Develop an Android application with the InfoSphere Business Glossary REST API

IBM® InfoSphere® Business Glossary enables users to create, manage, and share an enterprise vocabulary and classification system. InfoSphere Business Glossary includes a REST API that makes glossary content easier to consume by enabling the development of custom applications based on particular needs. The API has been updated with every subsequent release of InfoSphere Business Glossary. This article provides step-by-step instructions on how to develop a dynamic Android application using the IBM InfoSphere Business Glossary REST API. The application enables users to find terms, examine the term's details and contact the steward using the native phone and email applications on the Android device. The goal is for InfoSphere Business Glossary customers to use the knowledge gained through building this sample application as inspiration for using the REST API to create their own custom applications.

Benny Halberstadt (bennyhal@il.ibm.com), Senior Architect, IBM

Author PhotoBenny Halberstadt is a Senior Architect for IBM InfoSphere Governance Tools. He has worked on InfoSphere Information Server and InfoSphere Business Glossary products for the past seven years. He has extensive development experience for IBM and other companies.



Nancy L. Navarro (nancyn@il.ibm.com), Advisory Information Developer, IBM

Author PhotoNancy Navarro is an Advisory Information Developer for IBM who has worked on InfoSphere Information Server and InfoSphere Business Glossary products for the past five years. She has extensive information development experience for IBM and other companies.



18 July 2013

Also available in Chinese Russian Vietnamese

Overview

IBM InfoSphere Business Glossary enables you to create, manage, and share an enterprise vocabulary and classification system. InfoSphere Business Glossary exposes rich functionality through an API that uses a REST (Representational State Transfer)-based service. REST is an open architectural style for designing Web services that allows developers with a basic understanding of Web 2.0 technologies to quickly build applications.

This article provides step-by-step instructions on how to build an Android application that uses the Business Glossary REST API to deliver the enterprise vocabulary to the Android environment. The sample application is a lightweight application that enables quick discovery and modification of a company's business vocabulary. The vocabulary is not stored on the Android device; instead, the REST API is used dynamically to access the business glossary content on demand.

The Business Glossary REST API is a supported part of IBM InfoSphere Information Server. The Android application that you can develop by following the steps in this article is based on the REST API and the Android operating system but is not officially supported as part of an IBM product. The sample application is written against InfoSphere Business Glossary version 9.1 and Android version 2.3.

You can also download the source and executable of our sample program from this article.


Prerequisites

This article is intended for software developers who have a basic understanding of XML, REST, and the Android operating system. To deploy the sample application you will need access to a device that runs the Android operating system. To develop the sample application, we used the Android Development Tools (ADT) plugin for the Eclipse IDE. The ADT and the Eclipse IDE is required for working with the sample code. See Resources for more information about the ADT.


Scenarios

Following are two sample scenarios that demonstrate how a mobile InfoSphere Business Glossary application might be used:

  • Lorraine, a sales executive on the way to a client, receives a business email which contains the phrase Account Accruement. She is not very familiar with this term, and needs to understand how it is specifically defined in her company. She uses the InfoSphere Business Glossary Android application to look up the term and study its context and definition.
  • Tom, a subject matter expert, is reviewing his company's business glossary on his Android device while waiting in the airport for his departure flight. He is surprised to see that the definition of the term Accounting Period is not accurate. He edits the term in real time to correct its definition.

The sample application used for this article supports the first scenario.

Figure 1 shows the sample Android application and how a user opened up the details view for the term Account Accruement.

Figure 1. Sample InfoSphere Business Glossary Android application
This figure shows a sample InfoSphere Business Glossary Android application view for the term Account Accruement.

The view shows the definition of the term, its status (Accepted, meaning that it is not merely a candidate for use or deprecated), the name of the term’s steward or person responsible for it, and its abbreviation. The steward name is a hyperlink; the user can click it to display detailed contact information.


The InfoSphere Business Glossary REST API

The Business Glossary REST API allows client applications to read and write business glossary content. REST was the technology chosen for the API because of several advantages it offers over other distributed technologies. Most importantly, it is lightweight and interoperable. The API exposes glossary content as resources. These resources are addressed by using URIs. The URIs are represented by XML documents that are defined by XML schemas residing on the server.

API resources

The resources that can be received by the Business Glossary REST API are divided into two major sets:

  • Entity Resource Set: This resource set contains detailed information about Business Glossary entities such as categories, terms, stewards, custom attributes, and additional assets. All of these entities are supported by the Read API. Categories, terms, and custom attribute are also supported by the Write API and its create, update, and delete capabilities.
  • Operational Resource Set: This resource set provides easy-to-use, generic operations for developing client applications, such as:
    • Autocomplete. Provides completion suggestions based on terms in the glossary, given a prefix.
    • Anywhere Search. Search algorithm similar to that used in IBM InfoSphere Business Glossary Anywhere.
    • Search. This operation enables a search of the glossary for a specific pattern. The user can control the searched features and classes and the ranking of the results.

The InfoSphere Business Glossary REST API documentation contains full descriptions of the resource sets. See Resources for information on obtaining the documentation.

API transactions

API transactions consist of an HTTP request and response. Different operations require different kinds of HTTP methods in the request. A combination of URI and HTTP method defines what operation will occur. The REST interface provides the following HTTP methods:

  • POST: create a resource
  • GET: read a resource
  • PUT: update a resource
  • DELETE: delete a resource

Invoking REST from Android

There are many ways of invoking a REST service from an Android application. Listing 1 shows sample code that provides a generic method for invoking a REST GET operation. The caller provides a URL and a DOM (Document Object Model) document object is returned. The connection details to the InfoSphere Business Glossary host server are obtained from the shared preferences of the Android application. The following code sample invokes a REST GET operation:

Listing 1. Invoking a REST GET operation
public ArrayList<Item> invokeRestAPI(String relativeUrl, XMLParser xmlParser) {
    Document document = invokeRestAPI(relativeUrl);
    return xmlParser.parse(document);
}
                
private Document invokeRestAPI(String relativeUrl) {
    SharedPreferences prefs = PreferenceManager.getDefaultSharedPreferences(fContext);
              
    String server = prefs.getString("server", "Server");
    String port = prefs.getString("port", "Port");
                
    HttpGet httpGet = new HttpGet("http://" + server + ":" + port + "/" + relativeUrl);
                
    try {
                
       HttpResponse response = getHttpClient().execute(httpGet, new BasicHttpContext());
       HttpEntity entity = response.getEntity();
       DocumentBuilderFactory builderFactory = DocumentBuilderFactory.newInstance();
       builderFactory.setNamespaceAware(true);
       DocumentBuilder builder = builderFactory.newDocumentBuilder();
       return builder.parse(entity.getContent());
                
     } catch (Exception e) {
       Log.e("error", e.getLocalizedMessage(), e);
       return null;
     }
                
}
                
private DefaultHttpClient getHttpClient() {
    if (fHttpClient == null) {
       SharedPreferences prefs = PreferenceManager.getDefaultSharedPreferences(fContext);
       String username = prefs.getString("username", "");
       String passw = prefs.getString("password", "");
       String server = prefs.getString("server", "");
       String port = prefs.getString("port", "");
                
       fHttpClient = new DefaultHttpClient();
       fHttpClient.getCredentialsProvider().setCredentials(
       new AuthScope(server, Integer.parseInt(port)),
       new UsernamePasswordCredentials(username, passw));
     }
     return fHttpClient;
}

The Android operating system enables an application to spawn a background thread. This can be used to invoke the REST call asynchronously. The user will then be able to use the application while the REST call is being processed.


Application design

The sample Android application is constructed from five Android activities. An Android activity is an action that the user can do, that is instantiated with the Android public class Activity.

The five activities are the following:

  1. Home
  2. Preferences
  3. Progress
  4. List Results
  5. Item

Figures 2 through 6 show screenshots of each activity as displayed on an Android device:

  1. The Home activity enables the user to initiate a search against the REST API.
    Figure 2. Home activity
    This figure shows the Home activity that enables a user to start a search against the RESP API.
  2. A Preferences activity lets the user provide the connection details of the InfoSphere Business Glossary server.
    Figure 3. Preferences activity
    This figure shows the Preferences activity that lets the user provide the connection details of the InfoSphere Business Glossary server
  3. A Progress activity is displayed while a REST call is being invoked.
    Figure 4. Progress activity
    This figure shows the Progress activity that is displayed while the REST call is invoked
  4. A List Results activity lets the user scroll through the search results.
    Figure 5. List Results activity
    This figure shows the List results activity that lets a user go through the results of the search
  5. An Item activity displays all of the details of a particular search result.
    Figure 6. Item activity
    This figure shows the Item activity that shows all details of a search result.

Activity flow

Figure 7 shows the sequence in which a user would navigate through different activities.

Figure 7. Activity flow
This figure shows the order or sequence that a user would go through activities.

On application start-up, the Home activity is displayed. Then, the following sequence of events occurs:

  1. The user navigates to the Preferences activity. This activity enables the user to set the connection details to the InfoSphere Business Glossary host server. The preferences persist on the Android device and will be used on future invocations of the application.
  2. The user navigates back to the Home activity.
  3. The user enters a search phrase in the edit box, and clicks the Search button. This starts the Progress activity, which processes the search request.
  4. Once the Progress activity has invoked the REST URL and parsed the resulting XML document, the List Results activity is displayed.
  5. The user can scroll through the list and select a specific glossary item. This navigates the user to the Progress activity, which processes the item request.
  6. Once the Progress Activity has invoked the REST URL and parsed the resulting XML document, the Item activity is displayed.
  7. The Item activity displays the details of the selected item. The user can examine the details. Optionally, the user can click a displayed link. This navigates the user to the Progress activity, which processes the item request. In this case, the link is the steward name.
  8. Once the Progress activity has invoked the REST URL and parsed the resulting XML document, the Item activity is displayed again.
  9. In this case, the Item activity displays contact information about the steward. The user can examine the details and click on the phone number of the steward. This navigates the user to the native phone application of the device.

Activity details

The following sections of this article describe each Android activity in the application.

Home activity

This is the main activity of the application. The REST API provides data about the glossary, including the glossary header, welcome text and counters for the different asset types. This information can be displayed to the user to provide some context and orientation.

The REST API provides three different types of search. In this sample application, the user is given the choice whether to invoke an auto-complete search or a regular search. An alternative approach would be to provide a single search button, where the search behavior depends on an application preference.

When the user presses the Search button, a Progress activity is activated.

The Home activity includes a Preference button, which navigates the user to the Preferences activity.

Preferences activity

This activity lets the user set the connections details to the server. This includes host name, port, user name and password. This information persists so that the connection details only need to be set the first time the application is used.

Progress activity

This activity is used to show a spinning wheel, while in a separate thread the REST API is invoked and the result is parsed. The Progress activity needs the following two objects:

  1. URL to invoke.
  2. The next activity to invoke after the parsing has completed.

The sample code shown in Listing 2 invokes the Progress activity.

Listing 2. Invoking the Progress activity
package com.bg.android.activity;

import java.util.ArrayList;

import android.app.Activity;
import android.content.Intent;
import android.os.AsyncTask;
import android.os.Bundle;
import android.util.Log;

import com.bg.android.R;
import com.bg.android.model.Item;
import com.bg.android.parser.XMLParser;

public class ProgressActivity extends Activity {

	private String fUrl;
	private Class<?> fNextActivity;

	@Override
	protected void onCreate(Bundle savedInstanceState) {
		super.onCreate(savedInstanceState);
		setContentView(R.layout.activity_item_progress);
		Intent intent = getIntent();
		fUrl = intent.getStringExtra("url");
		String nextActivity = intent.getStringExtra("nextActivity");

		try {
			fNextActivity = Class.forName(nextActivity);
		} catch (Exception e) {
			Log.e("error", e.getLocalizedMessage(), e);
		}

		new LongRunningInvoke().execute();

	}

	private class LongRunningInvoke extends AsyncTask<Void, Void, String> {

		ArrayList<Item> fResult;

		@Override
		protected String doInBackground(Void... params) {

			BgApp app = (BgApp) getApplicationContext();
			try {
				fResult = app.getHttpUtil().invokeRestAPI(
   fUrl,XMLParser.getParser(fUrl));
				return "SUCCESS";
			} catch (Exception e) {
				Log.e("error", e.getLocalizedMessage(), e);
				return e.getLocalizedMessage();
			}
		}

		protected void onPostExecute(String results) {
			if (fResult != null) {
				Intent intent = new Intent(getApplicationContext(), 
                     fNextActivity);
				intent.putExtra("list", fResult);
				startActivity(intent);
			} else {
				Intent intent = new Intent(getApplicationContext(), 
                MainActivity.class);
				intent.putExtra("toast", results);
				startActivity(intent);
			}
		}
	}

}

The activity invokes the given URL. When the REST call returns an XML document, the parser converts the documents to Java objects. The next activity is invoked and the objects returned by the parser are transferred to the activity. This mechanism is generic and is used for all the REST calls that the application invokes.

List Results activity

This activity is used to display a list of search results to the user. When the user selects an item in the list, it activates the Progress activity to fetch the details of the item using the REST API. After the details are received, the Item activity is invoked.

The sample code shown in Listing 3 invokes the List Results activity.

Listing 3. Invoking the List Results activity
package com.bg.android.activity;

import java.util.ArrayList;

import android.app.ListActivity;
import android.content.Intent;
import android.os.Bundle;
import android.os.Parcelable;
import android.view.View;
import android.widget.ListView;

import com.bg.android.model.Item;

public class ListResultsActivity extends ListActivity {

	@Override
	public void onCreate(Bundle savedInstanceState) {
            super.onCreate(savedInstanceState);

            ArrayList<Parcelable> list = getIntent().getParcelableArrayListExtra("list");

            setListAdapter(new ResultsArrayAdapter(this, list));
	}

	@Override
	protected void onListItemClick(ListView l, View v, int position, long id) {
            Item selectedValue = (Item) getListAdapter().getItem(position);		
            String url = selectedValue.getUri();

            Intent intent = new Intent(getApplicationContext(), ProgressActivity.class);
            intent.putExtra("url", url);
            intent.putExtra("nextActivity", ItemActivity.class.getName());
            startActivity(intent);
	}

}

Item activity

This activity displays the attributes of an item in the business glossary. Items can be terms, categories, information governance policies, information governance rules, or stewards. The activity gets a map of key-value pairs and displays them in a table-like structure. The item name and description are given special attention and are displayed more prominently at the top of the page.

The activity displays references as active hypertext links. For example:

  • A term that is a synonym to another term is a link that, when selected, displays the details of the synonym.
  • The reference to the steward is a link that, when selected, displays the details of the steward.
  • The phone number of the steward is turned into a link that invokes the native dialing application of the device.

By using the links, users can navigate the glossary, moving from a term to related terms, synonyms, parent category, steward, and so on.

Although our sample application does not include it, an application could also let the user edit the content of the page. Changes would be sent back to the InfoSphere Business Glossary server via a PUT request as an update to the item.


Conclusion

The IBM InfoSphere Business Glossary REST API provides you with the ability to expose glossary content through custom programs, including mobile applications. The Android example provided in this article provides a proof-of-concept that shows you how to bring the power of InfoSphere Business Glossary to mobile devices.


Acknowledgements

The authors would like to thank Michael Fankhauser, Gabi Nativ, Marc Haber, and Erel Sharf for reviews and contributions to this article.


Downloads

DescriptionNameSize
Source code for the sample applicationBGAndroidEclipseProject.zip544KB
The executable Android applicationMain.zip372KB

Resources

Learn

Get products and technologies

  • Build your next development project with IBM trial software, available for download directly from developerWorks.
  • Evaluate IBM products in the way that suits you best: Download a product trial, try a product online, use a product in a cloud environment, or spend a few hours in the SOA Sandbox learning how to implement Service Oriented Architecture efficiently.

Discuss

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into Information management on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Information Management, Mobile development
ArticleID=937360
ArticleTitle=Develop an Android application with the InfoSphere Business Glossary REST API
publish-date=07182013