Android DOL Data SDK Sample

Overview

This sample will provide the steps to create a simple Android application that can consume DOL Data. Following these steps in order will allow your application to operate correctly. Download this project | Download project for Service Operation.

This solution was built using:

Eclipse JEE Helio SR2 windows 32
JDK
Android SDK
ADT plug-in. You can install it using the Eclipse IDE(Help Menu=> Install New Software).

Download Android SDK

Installation instructions are provided in detail here to setup an android development environment. After installation it is important to follow the steps for installing ADT plug-in and additional components.
^*note: Save the SDK in a location where there are no spaces in the directory path. The Android emulator may behave incorrectly if this path has spaces.

Create a New Project

For this sample we are going to create a new Android application that will consume and list Agency data.

Start by creating a new workspace or selecting a workspace of your choice.

Select Workspace and Select the installation location of your android SDK

For new workspaces Click Window > Preferences a window will be displayed, at this time select Android. Select the installation location of your android SDK.

Workspace Setup

Then open a new project by Clicking File > New Android Project.

You will need to provide information in order to proceed.

Choose a project name; this will be display as the root item in your project.
Choose a Build Target; this will determine what components will be available to your application. It will also set a list of minimum requirements for the android device.
Choose an Application Name; this will be used through your application and resources.
Choose a Package name; this is where Eclipse will set you Java Package for this application.
Finally, choose the Activity name; this is the main entry form for the Android application.

For this project Android 2.2 platform has been used to cover a wider target.

Choose Project Name,BuildTarget,Applciation name and package Name

Add SDK to Project

All requests require account credentials to be submitted along with the request. This SDK contains a few classes needed to process service requests. This package needs to be imported into your project.

Add SDK package to Project

Import the Android_DOLDataSDK into your project using the General > File System option.

Import SDK by selecting File system

Choose the root path and click ok.

Choose root

Locate the Dataset Path

Each Dataset has a Dataset Location path that gives the URL that will be needed to reach the Dataset on the API. For this sample please see the one circled in red.For the standard DOL Agency dataset sample please use http://api.dol.gov/V1/DOLAgency

Locate Dataset Location path from Dataset

For the DOL Service Operation sample please use http://api.dol.gov/V1/SummerJobs

Locate Dataset Location path from Dataset, for Summer Job Plus Sample please use http://api.dol.gov/V1/SummerJobs

Define the User Interface

Add a new Layout to your project by navigating to res > layout folder and click the right mouse button to get a menu. Select New then select Android XML File. In this window you choose the following options.

File name - the name of the file, for this project, we will use list_item for the name. This name will be reference later in the code and is case sensitive.
Resource Type - We are going to create a new Layout to display our results.
Root Element - We are going to choose a TextView to be our root element to display.

Configure Xml to define the user interface

Adding a few lines to this file in the XML view will allow us to customize its appearance.

Configure Xml to Add grid screen

Implementing the DOL Data Request

The DOLDataAPI.java file handles the behavior of the layout form that we created earlier. This file is found under src > gov.dol.SDK.sample. The SDK classes need to be accessible from here so we add them with java import statements.

Import SDK package.

Additionally, we are going to add a few more utility classes that will help us provide functionality not found in the SDK.

Import Java package.

For DOL Service Operation (e.g. Summer Job Plus) please import additional json package to parse the json result text.

Import Json package
We will modify the basic DOLDataAPI Activity and use a ListActivity instead to handle multiple items. We also inherited functionality from the DOLDataRequestCallback interface to handle the results of the service call.

Implement onCreate,DOLDataRequestCallback and DOLDataErroCallback method

Adding implementation to the onCreate method will setup the request to the DOL Data service.

For DOL API dataset :

The String method variable represents the Dataset and the table portion of the Data location path.

-Format( Dateset/Table) i.e. "DOLAgency/Agencies", "FORMS/AgencyFormsTable", "FAQ/Topics", "FAQ/SubTopics".

^*Please Note: these paths are case sensitive, please refer to the corresponding Datasets for the correct formats.

Initiate DOLDataRequest object with a value request argument for DOL API dataset

For DOL service operation :

The String method variable represents the service method.

^*Please Note: Each String typed parameter of service request must be surrounded in quotes in order to work correctly. These quotes are then Url encoded and passed to the Service Operation.

Initiate DOLDataRequest object with a value request argument for DOL Service operation

Adding implementation to the DOLDataErrorCallback method will provide feedback for errors that occur during the request.

Implement error code in DOLDataErrorCallback method

For DOL API dataset :

Finally, adding implementation to the DOLDataResultsCallback method will provide access to the results in the form of List of Map objects.

Implement code to display serivce response in listview

For DOL service operation :

Finally, adding implementation to the DOLDataResultsCallback method will provide access to the results in the form of List of Map objects. Developer has to clean the json response text to get the clean json object from service response. SomeTime search result may have special charcter which cause to thrown an error during JSON serialization.

Implement code to display serivce response in listview

Configure Android Security

Android gives its users the ability to grant application access to features they choose. This requires our application to list the permissions this application needs in order for features to work correctly. This is done by adding the tag circled in red to the AndroidManifest.xml file. Configure SDK/Android Security permission to run application in internet

Configure Security

Secure logins are provided using the following code; we will need to modify both the ApiKey and the SharedSecret variable of this method to access DOL Data.
Add members to the DOLDataAPI ListActivity class within the DOLDataAPI.java file.

The ApiKey corresponds to the Token identifier in your token list.
The SharedSecret created during setup is the same value that is used in the DOLDataUtil class.

Configure Security, set value value for ApiKey and SharedSecret

Run the Application

In order to run this application the emulator debug settings and the emulator need to be set up. Press F11 or Run > Debug and a warning message will be displayed if an emulator has not been configured.

Press F11 to Run the Application

Continue to the next screen and add a new emulator.

Add a new emulatore

Give the emulator instance a name and configure the memory to your needs.

Give emulator instance a name and configure the memory

Later you can setup Debug properties for you application as needed.

For DOL API dataset :

Run the application and you should see a list of Agencies in the grid.

For DOL service operation :

Run the application and you should see a list of jobs in the grid.