Server-side mobile application development with IBM Worklight: Part 3. Integrate the IBM Worklight adapter with RESTful services

This is Part 3 of a multipart series that explains how to use IBM® Rational® Application Developer for WebSphere® Software and IBM® Worklight together to develop applications for mobile devices, including those that run Android, iOS, BlackBerry, and Microsoft Windows Metro operating systems. In this third article, Bhargav Perepa covers three key topics: Developing and testing a JPA-exposed RESTFul service application in Rational Application Developer for WebSphere, using that to create an application logic package as a library to use in mobile application development, and using Worklight Studio to develop and test a server-side mobile application component to use that library.

Bhargav Perepa (bvperepa@us.ibm.com), WebSphere Architect and IT Specialist, IBM Japan

Bhargav PerepaBhargav Perepa is a WebSphere architect and IT specialist in the IBM Federal Software Group in Washington DC area. Previously, he was a developer in the Austin WebSphere Development Lab and had Smalltalk and C++ development experience at IBM Chicago. Bhargav holds a master's degree in Computer Science from the Illinois Institute of Technology, Chicago, and a master's in business administration (MBA) from the University of Texas, Austin.



21 May 2013

Also available in Chinese

Introduction

By reading this article, you learn how to develop and test a JPA-exposed RESTful service application by using the IBM® Rational® Application Developer for WebSphere®, Version 8.5.1, developer workbench. Then you learn how to develop and test a mobile application that features a server-side adapter component that uses that application. IBM® Worklight supports development of server-side components that invoke business logic encapsulated in Java, web services, RESTful services, and Enterprise JavaBeans (EJB) components. It is part of the IBM MobileFirst mobile enterprise application development platform (see the Resources section for links to more information about both).


Use case architecture

This article uses the same use case that you developed previously, in Part 1. The entities Usecase and Usecases are generated from the underlying USECASES table of FIPSDB, IBM® DB2® database, by using Java Persistence API (JPA).

The use case implementation consists of eight distinct activities, broadly identified as these steps:

  1. Develop a JPA application using Rational Application Developer.
  2. Develop a JPA test client application using Rational Application Developer.
  3. Test the JPA server application using JPA test client application in Rational Application Developer.
  4. Expose the JPA server application using RESTful services application.
  5. Test the JPA RESTful services application by using a web browser.
  6. Develop a mobile application using Worklight Studio.
  7. Incorporate the JPA RESTful service application logic provided as a Java archive library in a mobile application.
  8. Test the mobile application using Worklight Studio, which also acts as an end-to-end testing of complete scenario.

Develop a JPA application using Rational Application Developer

The following steps outline the JPA application development using Rational Application Developer for WebSphere Version 8.5.1.

  1. Launch Rational Application Developer, and specify the location of the workspace on the file system:
    C:\temp\RADWS\Part3
  2. Open the Java Enterprise Edition (Java EE) perspective for Java application development, if it is not opened already (Window > Open Perspective > Other > Java EE), and then click OK.
  3. Create a new Java EE project:
    1. Select the New Dynamic Web Project creation wizard: File > New > Dynamic Web Project.
    2. Enter the Project name: WLUsecasesJPAProject
    3. Leave the defaults for the rest of the options.
    4. Click Next twice.
    5. On the Web Module page, check the Generate web.xml deployment descriptor option, and click Finish.
    6. If you are prompted to, close the Open Associated Perspective? dialog window by specifying Yes when you see the Yes or No option.

The Package Explorer of the Java EE perspective now shows the newly created Java EE project.

  1. Select JPA project facets:
    1. Select WLUsecasesJPAProject > Properties.
    2. Select Project Facets, and check JPA.
    3. Click Further configuration available.
    4. Select FIPSDB from the Connection drop-down menu.
    5. Select the radio button for Annotated classes must be listed in persistence.xml.
    6. Check Create mapping file (orm.xml).
    7. Accept the default value for the rest of the options.
    8. Click OK for Modify Faceted Project.
    9. Click Apply for Properties for WLUsecasesJPAProject.
  2. Select JAX-RS (RESTful web services) project facets:
    1. Select WLUsecasesJPAProject > Properties.
    2. Select Project Facets, and check JAX-RS (Rest Web Services).
    3. Accept the default values for all other options.
    4. Click OK for Modify Faceted Project.
    5. Click Apply for Properties for WLUsecasesJPAProject.
    6. Click OK for Properties for WLUsecasesJPAProject.
  3. Configure JPA database connectivity:
    1. Create the FIPSDB back-end database, and populate it with data. See the project files supplied in the Downloads section for data definition and data population.
    2. Select Window > Open Perspective > JPA to open JPA perspective.
    3. Select Data Source Explorer > FIPSDB (DB2 Alias) > Properties > Driver Properties > Test Connection (see Figure 1).
      Figure 1. JPA perspective, FIPSDB database connectivity properties
      Driver properties view plus ping succeeded message
    4. Select Data Source Explorer > FIPSDB (DB2 Alias) > Connect.
    5. Select Data Source Explorer > FIPSDB (DB2 for Linux, UNIX, and Windows V9.7) > FIPSDB > Schemas > DB2ADMIN > Tables > USECASES > Data > Return All Rows.
      Note:
      This option should return nine rows.
  4. Generate JPA entities from tables:
    1. Select WLUsecasesJPAProject > JPA Tools > Generate Entities from Tables.
    2. Select the USECASES table.
    3. Select Update class list in persistence.xml.
    4. Select Next and then Next again.
    5. On the Customize Default Entry Generation page, specify the package:
      com.worklight.customcode.entities
    6. Click Next.
    7. On the Customize Individual Entities page, specify the class name: Usecases
    8. Click FINISH.
  5. Configure JPA entities:
    1. Select WLUsecasesJPAProject > JPA Tools > Configure JPA Entities
    2. Check Available JPA Entities: Usecases.
    3. Select Update class list in persistence.xml, and click Next.
    4. Select Primary Key, check seqno, and click Next.
    5. Select Named Queries, and click the Default button.
    6. Select Concurrency Control., and specify the Collision Attribute:seqno: int
    7. Select Other. Check Add an equals and hashCode method if not present.
    8. Select Other. Check Convert Java Set objects to Java List objects.
    9. Select Other. Check Convert Java SQL Temporal Types to Java Util Temporal Types.
    10. Click FINISH.
  6. Configure the project for Java Database Connectivity (JDBC) deployment:
    1. Select WLUsecasesJPAProject > JPA Tools > Add JPA Manager Beans.
    2. Check Available JPA Entities: Usecases.
    3. Select Next.
    4. Review and accept the default options.
    5. Click Finish.
  7. Add JPA manager beans:
    1. Select WLUsecasesJPAProject > JPA Tools > Configure Project for JDBC Deployment.
    2. Review and accept default options.
    3. Click OK.
Usecases.java entity class
This is a JPA-generated Java class that represents a row in the FIPSDB DB2 database's USECASES table. This class contains a collection of constructor, GET, SET, hashCode, and equals methods.
 
UsecasesManager.java entity manager class
This is a JPA-generated Java class. For applications to manage related entity classes, JPA defines the concept of EntityManager. The EntityManager helps entity classes persist their states to the underlying relational database tables. A collection of related entity classes is called a persistence unit in JPA. An EntityManager instance in an application manages a persistence unit and uses the persistence.xml configuration file to create a programmatically accessible persistence context.
Listing 1. Contents of persistence.xml file
<?xml version="1.0" encoding="UTF-8"?>
<persistence version="2.0" xmlns="http://java.sun.com/xml/ns/persistence" 
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xsi:schemaLocation="http://java.sun.com/xml/ns/persistence 
http://java.sun.com/xml/ns/persistence/persistence_2_0.xsd">
<persistence-unit name="WLUsecasesJPAProject">
<jta-data-source>java:comp/env/FIPSDB</jta-data-source>
<class>com.worklight.customcode.entities.Usecases</class>
</persistence-unit>
</persistence>

EntityManager tracks all state changes taking place in all entity classes within a persistence context in an application. It then synchronizes the changes to persistence store (DB2 FIPSDB USECASES table).

Develop a JPA test client application using Rational Application Developer

Use the following steps as a guide to JPA test client application development using Rational Application Developer for WebSphere Version 8.5.1.

  1. Create a new Java test client project:
    1. Select File > New > Java Project.
    2. Enter Project name: WLUsecasesJPATestClientProject
    3. Select Next .
    4. Select the Source tab to select the default output folder:
      WLUsecasesJPATestClientProject/src
    5. Click Finish.
  2. Create a META-INF folder under the src folder for this project:
    1. Select WLUsecasesJPATestClientProject > src > File > New > Folder.
    2. Specify the Folder name: META-INF
    3. Select Finish.
  3. Create a persistence.xml in the META-INF folder:
    1. Select WLUsecasesJPATestClientProject > src > META-INF > File > New > Other > XML > XML File > persistence.xml.
    2. Select Finish.
  4. Populate the persistence.xml file with configuration entries, and review the source file contents. Use the server project's persistence.xml file as a template to understand configuration entries.
  5. Configure the test client project's Java build path entries:
    1. Select WLUsecasesJPATestClientProject > Properties > Java Build Path > Projects Tab > Add > WLUsecasesJPAProject.
    2. Select WLUsecasesJPATestClientProject > Properties > Java Build Path > Libraries > Add Variable > ECLIPSE_HOME > Extend > runtimes > base_v85_stub > lib > j2ee.jar, and click OK.
    3. Select WLUsecasesJPATestClientProject > Properties > Java Build Path > Libraries > Add Variable > ECLIPSE_HOME > Extend > runtimes > base_v85_stub >plugins > com.ibm.ws.jpa.jar, and then click OK.
    4. Select WLUsecasesJPATestClientProject > Properties > Java Build Path > Libraries > Add Variable > ECLIPSE_HOME > Extend > runtimes > base_v85_stub > plugins > com.ibm.ws.prereq.commons-collections.jar > OK.
    5. Select WLUsecasesJPATestClientProject > Properties > Java Build Path > Libraries > Add External JARs, and then specify these Java archives:
      • C:\I\SQLLIB\java\db2jcc_license_cu.jar
      • C:\I\WAS\runtimes\com.ibm.ws.jpa.thinclient_8.5.0.jar
      • C:\I\SQLLIB\java\db2jcc4.jar
    6. Select OK.
  6. Create and implement a Java test client class:
    1. Select WLUsecasesJPATestClientProject > src > File > New > Java Class.
    2. Specify Package: com.worklight.customcode.test
    3. Specify Name: WLUsecasesJPATestClient
    4. Select Finish.

The WLUsecasesJPATestClient.java client class program creates an EntityManager, creates a set of queries, runs them, and returns the query result set.

  1. Review the Java source file contents for WLUsecasesJPATestClient.

Test the JPA server application using JPA test client application in Rational Application Developer

The following steps outline the testing of JPA server application with JPA test client application using Rational Application Developer for WebSphere Version 8.5.1.

  1. Deploy the JPA server application to WebSphere Application Server v8.5.0.2:
    1. Select Servers View > WebSphere Application Server v8.5 at localhost.
    2. Right-click and, from the context menu, select Add and Remove > WLUsecasesJPAProjectEAR, and then click Add >and Finish.
    3. Use the Servers view to confirm that the application is successfully running.
  2. Perform the JPA test client Run Configurations action:
    1. Enter the VM arguments string for WLUsecasesJPATestClientProject > src > WLUsecasesJPATestClient > Run > Run Configurations > Java Application > New > (x) = Arguments tab > VM arguments:
      -javaagent:C:/I/RAD/runtimes/base_v85_stub/plugins/com.ibm.ws.jpa.jar.
    2. Select Apply and then select Run.
    3. View the Console output to verify that the test run is successful, as shown in Figure 2.
Figure 2. Verify correct execution of JPA server application in the Console view
Results say 'EntityManager successfully created'

Expose the JPA server application as a RESTful services application

Next, you'll wrap the JPA server application that you just created as a RESTful services application. This involves adding a JAX-WS servlet to your JPA server application, creating RESTful services implementation logic in Java classes. and annotating the class file resources for RESTful API access. The following steps capture the details:

  1. Expose the JPA server application as a RESTful services application:
    1. Use the Web Application 3.0 Deployment Descriptor editor to open the web.xml file by selecting WLUsecasesJPAProject > WebContent > web.xml.
    2. Select Web Application (WLUsecasesJPAProject) > Servlet (JAX-RS Servlet) > Add > Initialization Parameter > OK. Be sure to save your changes: File > Save or Ctrl+S.
    3. Select Problems View > JSR-311, 2.3.2. The param-name should be the javax.ws.rs.Application warning message.
    4. Right-click Quick Fix and select Create a new JAX-RS Application subclass. Set the param-value in the web.xml file, and click Finish.
    5. Specify Package:com.worklight.customcode.jaxrs
    6. Specify Name: WLUsecasesJAXRSApplication
    7. Select Finish.
  2. Create a RESTful services implementation the Java classes.
    1. Select WLUsecasesJPAProject > src > New > Class.
    2. Specify Package:com.worklight.customcode.resources
    3. Specify Name:ErrorUtil.java
    4. Select Finish.
    5. Select WLUsecasesJPAProject > src > New > Class.
    6. Specify Package:com.worklight.customcode.resources
    7. Specify Name:UsecasesResource.java
    8. Select Finish.

Part of exposing JPA entity classes as JAX-RS resources involves adding UsecasesResource.class to a HashSet object. This is for the getClasses method to return a HashSet object with JAX-RS resources instantiated in the WLUsecasesJAXRSApplication.java source file.

ErrorUtil.java class
This an exception handling class that features logic for four methods. Two of the methods take a string message as input parameter and convert it to a JSON object or JSON array object. Two other methods take a string and a status object as input parameters and build a response object that contains a JSON object or JSON array object.
 
UsecasesResources.java
This class features the Path, GET, and Produce annotations.
 
Path annotation
This is used to define the URIs for the resources.
 
GET annotation
This is used to decorate a method that performs the safe, idempotent HTTP GET operation.
 
Produces annotation
This indicates which media type is returned by a method that is decorated with the GET annotation.

@Path("/usecases") maps to this URI:
http://host:port/WLUsecasesJPAProject/jaxrs/usecases

com.worklight.customcode.resources.UsecasesResource.getAllUsecases() method in UsecasesResource.java source responds to the HTTP GET request.

@Path("/seqno/{seqno}") maps to this URL: http://host:port/WLUsecasesJPAProject/jaxrs/usecases/seqno/{seqno}.

com.worklight.customcode.resources.UsecasesResource.getMyUsecasesBySeqno(int seqno) method in UsecasesResource.java source responds to HTTP GET request.

  1. Review and study the code.

Test the JPA RESTful services application using a web browser.

The following steps outline the testing of JPA RESTful services application by using a browser.

  1. Clean compile the project and republish the compiled project to server.
  2. Point the browser URL to: http://localhost:9080/WLUsecasesJPAProject/jaxrs/usecases (see Figure 3).
Figure 3. Verify correct execution of the RESTful service call, getAllUsecases()
Successful execution results of RESTful service call getAllUsecases()
  1. Use your browser to navigate to this URL (see Figure 4): http://localhost:9080/WLUsecasesJPAProject/jaxrs/usecases/seqno/{seqno}
Figure 4. Verify correct execution of the RESTful service call, getUsecase(8)
Successful execution results of RESTful service call getUsecase(8)

Create JPA RESTful services application logic package as a Java archive for mobile application use

The following steps outline the packaging of JPA RESTful services application in order for its logic to be usable in mobile application.

  1. Export the JPA application logic as a JAR file. Select File > Export > Jave > JAR file > Next > > WLUsecasesJPAProject > WebContent > WEB-INF > classes > com.
  2. Enter this as the name of file to export:
    JAR file: c:\temp\WLUsecasesJPAProjectUtil.jar
  3. Click Finish, and review the contents of the WLUsecasesJPAProjectUtil.jar file (see Figure 5).
Figure 5. Contents of the WLUsecasesJPAProjectUtil.jar file
Content structure of WLUsecasesJPAProjectUtil.jar archive file

Develop a mobile application by using Worklight Studio

Follow these steps to develop a mobile application by using IBM® Worklight Studio Version 5.0.6.1. The steps are applicable to earlier versions of the tool, with slight or no modifications. (The author tested the use case on the stated release.)

Create a new project

  1. Launch Worklight Studio, and specify this as the location of the workspace on file system:
    C:\temp\WRKLT\WSAdapterCall2JPARESTfulServices
  2. Create a new Worklight project by using the project creation wizard: File > New > Worklight Project.
  3. Specify the Worklight project name as HybridWLUsecasesJAXRSProject.
  4. Select the Worklight project template to be HybridApplication.
  5. Click Next.
  6. Specify the application name as HybridWLUsecasesJAXRSApp.
  7. Leave the rest of the default values on this screen, and click Finish.

Create a new Worklight adapter

  1. To launch the new Worklight adapter creation wizard, select WLHTTPAdapterCall2JavaProject > adapters > Worklight Adapter.
  2. Start the wizard by clicking New > Worklight Adapter.
  3. Select the Project name as HybridWLUsecasesJAXRSProject.
  4. Specify Adapter type as HTTP Adapter.
  5. Specify Adapter name as UsecasesJAXRSHTTPClientAdapter.
  6. Click Finish.
  7. Review the contents of UsecasesJAXRSHTTPClientAdapter.xml and UsecasesJAXRSHTTPClientAdapter-impl.js source files.

Figure 6 shows the completed implementation of the adapter logic in the editor. The adapter implements two methods in the JavaScript functions, and each of these functions call the JPA RESTful services application logic that you developed in previous steps. The JPA RESTful services application logic is made available to the mobile application in a Java archive library. The implementation demonstrates how to invoke JPA RESTful services application instance methods.

Figure 6. Worklight adapter implementation in the editor
Adapter function implementations in JavaScript

Start the Worklight server to deploy the adapter

To start the Worklight server, follow these steps:

  1. Select HybridWLUsecasesJAXRSProject.
  2. Click Start Worklight Server.
  3. Deploy the Worklight adapter to the Worklight server:
    1. Select HybridWLUsecasesJAXRSProject > adapters > UsecasesJAXRSHTTPClientAdapter.
    2. Select Run As > Deploy Worklight Adapter.

The Console view confirms the successful deployment of the Worklight adapter in Worklight Studio.

The Worklight admin console also shows successful deployment of the Worklight adapter. To verify, enter this URL in the Google Chrome browser (a preferred browser, given its support for web development):
http://localhost:8080/console

Incorporate the RESTful application logic in the mobile application

The following steps describe how to import the JPA RESTful services application library to use it in a mobile application that you are developing in Worklight Studio:

  1. Start the import wizard to import the Java archive library into your Worklight Studio workspace so that the mobile application can use the library imported when you deploy mobile application project to the Worklight server.
  2. Select HybridWLUsecasesJAXRSProject.
  3. Navigate to the server by selecting server > lib > import > File System > Next.
  4. Specify the Java application library to use in the mobile application.
  5. Select the .jar file to import from the file system:
    C:\temp\WLUsecasesJPAProjectUtil.jar
  6. Accept the default location to import the file into the workspace:
    HybridWLUsecasesJAXRSProject/server/lib
  7. Click Finish.

Figure 7 shows the completed Worklight application project, ready for testing.

Figure 7. Worklight application project is finished and ready for testing
Project Explorer contents of HybridWLUsecasesJAXRSProject

Test the mobile application by using Worklight Studio

The following steps guide you through end-to-end testing of the mobile application. The JPA RESTful services application logic is invoked from the adapter component of the mobile application.

Invoke the getNumOfUsecasesInstances static adapter method

  1. For the instance adapter method to test, select getUsecase(id).
  2. Select HybridWLUsecasesJAXRSProject > adapters > UsecasesJAXRSHTTPClientAdapter.
  3. Select Run As > Invoke Worklight Procedure.
  4. Specify the Project name: HybridWLUsecasesJAXRSProject
  5. Specify the Adapter name: UsecasesJAXRSHTTPClientAdapter
  6. Specify the Procedure name: getusecase
  7. Review the Signature: getUsecase(id)
  8. Specify Parameters (comma-separated): 8
  9. Click Apply and then Run.

Figure 8 shows the successful invocation of instance method getUsecase(8).

Figure 8. Results for getUsecase(8)
Screen shows details of results

Invoke the getAllUsecases() instance adapter method

  1. Select the getAllUsecases() instance adapter method to test.
  2. Select HybridWLUsecasesJAXRSProject > adapters > UsecasesJAXRSHTTPClientAdapter.
  3. Select Run As > Invoke Worklight Procedure.
  4. Select Project name:HybridWLUsecasesJAXRSProject.
  5. Select Adapter name: UsecasesJAXRSHTTPClientAdapter.
  6. Select Procedure name:getAllUsecases().
  7. Click Apply and then Run.

Figure 9 shows the successful invocation of this instance of the getAllUsecases() adapter method.

Figure 9. Results for getAllUsecases()
Screen shows results

Summary

Part 3 of this article series shows you how to use the Rational Application Developer for WebSphere Software workbench to accomplish several tasks:

  • Develop a set of server and client JPA applications
  • Test the JPA server application by using the JPA client application already developed
  • Expose the JPA application as a RESTful services application
  • Test the JPA RESTful services application
  • Package JPA RESTful services application logic to be used by a mobile application
  • Develop a mobile application with Worklight Studio, featuring a Worklight adapter that uses the JPA RESTful services application logic previously developed, and, finally
  • Test the mobile application, end-to-end.

See the Downloads section to download the sample files for this article.


Acknowledgments

The author gratefully acknowledges receiving review feedback, constructive suggestions, support, and productive teamwork from Sujatha Perepa and Roger Snook. Both work for IBM.


Download

DescriptionNameSize
Application sample, configuration, and log filesRAD_WL_ArticleBundle_03182013.zip11.7MB

Resources

Learn

Get products and technologies

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 Rational software on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Rational, Mobile development, DevOps
ArticleID=929978
ArticleTitle=Server-side mobile application development with IBM Worklight: Part 3. Integrate the IBM Worklight adapter with RESTful services
publish-date=05212013