Developing JAX-RS 1.1 RESTful Services in Rational Software Architect V8 for deployment to WebSphere Application Server V8

Enabling legacy applications for REST

Learn how to expose existing business functionality embedded in legacy applications as JAX-RS 1.1 RESTful services using WebSphere® Application Server V8.0 and Rational® Software Architect.

Tendai Chinoda (tendai@us.ibm.com), IT Specialist and Senior Software Engineer, IBM

Photo of Tendai ChinodaTendai Chinoda is an IBM Certified IT Specialist and Senior Software Engineer in IBM Software Services for WebSphere (ISSW). He provides consulting and enablement services to IBM customers for the WebSphere family of products. His expertise and interests include application architecture, design and development for cloud computing, Java EE, SOA, and web services.


developerWorks Contributing author
        level

Harry L. Hoots, III (hlhoots@us.ibm.com), IT Specialist, IBM China

Photo of Harry HootsHarry L. Hoots, III is an IT Specialist working on the IBM Account. He serves in senior roles and is a Web Services Development Lead on a major internal project. His expertise and interests include application architecture, design and development of Java EE, web services, and WebSphere MQ.



02 November 2011

Before you start

Learn what to expect from this tutorial, and how to get the most out of it.

About this tutorial

IBM® WebSphere® Application Server V8.0 provides support for simplified development of Representational State Transfer (REST) applications using Java™ API for RESTful Web Services (JAX-RS) 1.1. Rational® Software Architect (hereafter referred to as Software Architect) provides tooling to design, develop, test and package JAX-RS 1.1 REST applications for deployment to WebSphere Application Server V8 (hereafter referred to as Application Server). This tutorial provides a step-by-step walkthrough of the required development tasks in Software Architect and the additional steps for deployment to Application Server. You can download the solution set or perform the sequence of development tasks to create the solution on your own.

Objectives

Using a fictional business scenario, the objectives of this tutorial are to:

  • Demonstrate the tooling support in Software Architect V8 for development of JAX-RS 1.1 RESTful services
  • Demonstrate the use of the above pattern to expose existing business functionality embedded in legacy applications as JAX-RS 1.1 RESTful services that support both XML and JavaScript Object Notation (JSON) payloads
  • Demonstrate Application Server V8 support for Java EE 6 and deployment of Web Service implementations as JAX-RS 1.1 RESTful services
  • Provide an opportunity for practitioners to get hands-on experience developing JAX-RS 1.1 RESTful services in Software Architect V8 and deploying the solution to Application Server V8

Prerequisites

This tutorial is written for application programmers with intermediate to advanced skills. You should be familiar with using Rational Software Architect and understand REST applications.

System requirements

To run the examples in this tutorial, you need Rational Software Architect V8 and WebSphere Application Server V8.


Introduction

Business scenario

HTBanking Corporation currently controls all access to banking information via a legacy Java application hosted out of its main headquarters. Banking subsidiaries are required to submit manual documents and forms requesting account information when processing loan requests. Account Reps located at the HTBanking main office then process these requests using a Java Swing application hosted on their personal workstations.

Due to significant growth projections HTBanking Corporation's Strategic Business and IT teams have decided to expand the interfacing capabilities of their legacy system. The plan is to support the growth by enabling their subsidiaries to access and manipulate accounts via rich desktop and mobile user interfaces which leverage standards-based technologies such as Asynchronous JavaScript and XML (AJAX), REST Web Services, and Dojo. This expansion will allow for more efficient processing of loans as well as the ability for subsidiaries to offload the management of account information.

Technical solution

After careful review of implementation and deployment options for the expanded interfacing solution, the HTBanking IT Team decided on IBM® WebSphere® Application Server V8.0. Application Server provides support for simplified development of REST applications using the Java API for RESTful Web Services (JAX-RS) 1.1. In tandem the development teams will implement the solution using Rational® Software Architect which provides tooling to design, develop, test and package JAX-RS 1.1 REST applications for deployment to Application Server.

The design pattern and code artifacts used and delivered as part of the solution are shown in Figure 1.

Figure 1. Design pattern: Enabling legacy applications as REST Web Services using JAX- RS 1.1
Design Pattern: Enabling Legacy Applications as REST Web Services using JAX- RS 1.1

Implementing the solution

An overview of the sections in this tutorial and the steps for implementing the solution are:

OPTIONAL: If you are more inclined you can import the complete solution (extract the archive file JAXRS-RESTService_solution_devWorks.zip from the sample artifacts provided in the Download section of this tutorial and skip to Deploy the solution to the runtime test environment). However you must first configure a runtime environment as described in Configure the WebSphere Application Server V8 runtime environment.


Import the legacy application code and supporting services (XML and JSON Helpers)

This section outlines the steps to import the code supplied as part of the solution.

  1. Start Rational Software Architect V8.0 and create a new workspace.
  2. If prompted to configure your workspace with an existing Runtime Environment and Profile Setting, click Cancel (Figure 2).
    Figure 2. Configuring the WebSphere Application Server dialog
    Configuring the WebSphere Application Server Dialog
  3. To open the Java EE perspective select Window > Open Perspective > Other.
  4. Check the Show all check box, and then select Java EE and click OK.
  5. If prompted to Confirm Enablement of new capabilities, check the Always enable activities and don’t ask me again box and then click OK (Figure 3).
    Figure 3. Confirm Enablement dialog
    Confirm Enablement Dialog
  6. Download the devWorks_LegacyBankAppArtifacts.zip archive file provided in the Downloads section into a directory location of your choice. The following files are contained in the archive file:
    File Name Description
    JAXRS-RESTService_devWorks.zip Contains the Legacy Bank App, Legacy Wrapper Service Projects, and the RESTClient for verifying the solution. Files containing code and log snippets are in the TextFiles project.
    JAXRS-RESTService_solution_devWorks.zip Contains the completed solution ready for deployment to a WebSphere Application Server V8.0 Runtime Environment
  7. Select File > Import and in the Import dialog select General > Existing Projects Into Workspace and then click Next (Figure 4).
    Figure 4. Import: Select Import Type dialog
    Import: Select Import Type Dialog
  8. Click on Select archive file bullet and then click on Browse.
  9. Browse to the location of the extracted downloads, select the LegacyBankAppCode.zip file and then click Open.
  10. Verify all the required projects are located (Figure 5) and then click Finish.
    Figure 5. Import: Import Projects dialog
    Import: Import Projects Dialog

The projects and files imported into the workspace are shown in Figure 6 and consist of the following:

  • LegacyBankApp. Java project that contains the legacy bank application code
  • LegacyBankAppWrapperService. Java project that contains the Wrapper service which invokes the legacy bank application code. The JAX-RS framework will invoke methods on this class.
  • RESTClient/ Java project that contains a test client for verifying the solution.
Figure 6. Projects and files imported into workspace
Projects and files imported into workspace

This completes the steps required to import the legacy application code artifacts used by the legacy bank application’s JAX-RS 1.1 REST Service.


Configure the WebSphere Application Server V8.0 runtime environment

This section outlines the tasks required to configure a new WebSphere Application Server V8.0 to deploy the JAX-RS REST Service.

  1. In the Server view right click and select New > Server.
  2. In the Define a New Server dialog, select WebSphere Application Server v8.0 as the server type to be created.
  3. In the Server runtime environment field, select Create new runtime environment and then click Next (Figure 7).
    Figure 7. Create Server: Define a New Server dialog
    Create Server: Define a New Server Dialog
  4. In the Application Server Runtime Environment dialog, click Browse to navigate to the Installation Directory. Select the <installation_directory> for WebSphere Application Server V8.0 and then click Next (Figure 8).
    Figure 8. Create Server: Specify Server Runtime Environment
    Create Server: Specify Server Runtime Environment
  5. In the WebSphere Application Server Settings dialog, if you have an existing profile, you can select it from the Profile name pull down it or you can create a new one.
  6. To create a new profile click the Configure profiles link and follow the remaining steps (Figure 9).
    Figure 9. Create Server: Specify Server Settings
    Create Server: Specify Server Settings
  7. If prompted to Create a runtime environment, click Yes.
  8. In the Preferences window, expand Preferences > Server > WebSphere Application Server and click on Run Profile Management Tool (Figure 10).
    Figure 10. Create Server: Select Run Profile Management Tool
    Create Server: Select Run Profile Management Tool
  9. In WebSphere Customization Toolbox window click Create (Figure 11).
    Figure 11. Create Server: Create Profile
    Create Server: Create Profile
  10. In the Environment Selection dialog choose Application Server and click Next (Figure 12).
    Figure 12. Create Server: New Profile Environment Selection
    Create Server: New Profile Environment Selection
  11. In the Profile Creation Options dialog, select Advanced profile creation and click Next (Figure 13).
    Figure 13. Create Server: Profile Creation Options Dialog
    Create Server: Profile Creation Options dialog
  12. In the Optional Application Deployment dialog, ensure Deploy the admin console is checked, uncheck the Deploy default application and click Next (Figure 14).
    Figure 14. Create Server: Profile Application Deployment Dialog
    Create Server: Profile Application Deployment dialog
  13. In the Profile Name and Location dialog, enter a name for the profile (for example: devWorksProfile)
  14. Change the Profile directory to include the name of the application server and click Next (Figure 15)
    Figure 15. Create Server: Profile Name and Location
    Create Server: Profile Name and Location
  15. In the Node and Host Names dialog, enter appropriate values for Node name, Server name and Host name and then click Next (Figure 16).
    Figure 16. Create Server: Profile Node and Host Names dialog
    Create Server: Profile Node and Host Names Dialog
  16. In the Administrative Security dialog, check Enable administrative security and enter appropriate values for User name and Password and then click Next (Figure 17). NOTE: Remember this User name to access the Administrative Console and to start or stop the server from the command line.
    Figure 17. Create Server: Profile Administrative Security dialog
    Create Server: Profile Administrative Security Dialog
  17. In the Security Certificate (Part 1) dialog, leave all fields as default to create a new default personal certificate and root signing certificate and click Next (Figure 18).
    Figure 18. Create Server: Profile Security Certificate I dialog
    Create Server: Profile Security Certificate I Dialog
  18. In the Security Certificate (Part 2) dialog leave all fields as default to create a new default personal certificate and root signing certificate and click Next (Figure 19).
    Figure 19. Create Server: Profile Security Certificate II dialog
    Create Server: Profile Security Certificate II Dialog
  19. In the Port Values Assignments dialog, accept the default generated ports and click Next (Figure 20). Take note of the HTTP transport port as it will be need for the HTTP Client at a later stage in the tutorial.
    Figure 20. Create Server: Port Assignments
    Create Server: Port Assignments
  20. In the Window Service Definition dialog, uncheck Run the application sever process as a Windows service and click Next (Figure 21).
    Figure 21. Create Server: Server Windows Service dialog
    Create Server: Server Windows Service Dialog
  21. In the Web Server Definition dialog, leave all fields as default and click Next (Figure 22).
    Figure 22. Create Server: Web Server Definition dialog
    reate Server: Web Server Definition Dialog
  22. Review the Profile Creation Summary information and click Create (Figure 23).
    Figure 23. Create Server: Profile Creation Summary
    Create Server: Profile Creation Summary
  23. In the Profile Creation Complete dialog, uncheck Launch the First steps console and click Finish (Figure 24).
    Figure 24. Create Server: Profile Creation Complete dialog
    Create Server: Profile Creation Complete Dialog
  24. The newly created profile should now be visible in the WebSphere Customization Toolbox (Figure 25). Close the window to return to Rational Software Architect.
    Figure 25. Create Server: Updated Profile List
    Create Server: Updated Profile List
  25. In the Preferences window, expand Preferences > Server > WebSphere Application Server and click on the WebSphere Application Server V8.0 installed runtime to refresh the list of profiles. The new server should appear in the profile section. Click OK (Figure 26).
    Figure 26. Create Server: Updated Servers and Profiles View
    Create Server: Updated Servers and Profiles View
  26. In the WebSphere Application Server Settings dialog, select the newly created profile in the Profile name drop-down menu. Enter the User ID and Password and click Next (Figure 27).
    Figure 27. Create Server: Configure WebSphere Application Server Settings dialog
    Create Server: Configure WebSphere Application Server Settings Dialog
  27. In the Add Remove projects dialog, click Finish.

This completes the steps required to configure the WebSphere Application Server V8.0 runtime environment for deploying the legacy bank application’s JAX-RS 1.1 REST Service. In the Server view you should now see the newly created server in Stopped state.


Create the JAX-RS 1.1 REST service and Java EE modules

  1. In the Java EE perspective select File > New > Dynamic Web Project.
  2. In the Dynamic Web Project dialog, enter LegacyBankAppWeb as the project name.
  3. In the Target runtime drop-down menu, select WebSphere Application Server V8.0.
  4. In the Configuration drop-down menu, select IBM JAX-RS Configuration.
  5. In the EAR project name drop-down menu, enter LegacyBankAppEAR as the EAR Project to deploy the newly created Web Module and click Next (Figure 28).
    Figure 28. Dynamic Web Project Creation dialog
    Dynamic Web Project Creation Dialog
  6. In the Configure Project for Java Application dialog (Src Folder dialog), leave all fields as default and click Next (Figure 29).
    Figure 29. Dynamic Web Project Src Folder dialog
    Dynamic Web Project Src Folder dialog
  7. In the Web Module Settings dialog, check the Generate web.xml deployment descriptor box and click Next (Figure 30).
    Figure 30. Dynamic Web Project Module Settings
    Dynamic Web Project Module Settings
  8. In the JAX-RS Capabilities dialog, leave all fields as default and click Finish (Figure 31).
    Figure 31. Dynamic Web Project JAX-RS Settings dialog
    Dynamic Web Project JAX-RS Settings Dialog
  9. If prompted to Open the Associated Perspective (i.e. Web Perspective) click No.
  10. In the Enterprise Explorer View, expand the LegacyBankAppEAR project, right click on the LegacyBankAppEAR > LegacyBankAppEAR > Utility JARs and select Modify.
  11. In the Properties for LegacyBankAppEAR window, click on Deployment Assembly and in the EAR Module Assembly pane, click Add (Figure 32).
    Figure 32. EAR Module Deployment Assembly
    EAR Module Deployment Assembly
  12. In the Select Assembly Directive Type dialog, select Project and click Next (Figure 33).
    Figure 33. EAR Module Deployment Assembly: Select Assembly Directive dialog
    EAR Module Deployment Assembly: Select Assembly Directive Dialog
  13. In the Select Project to include dialog, select LegacyBankAppWrapperService project and while pressing the CTRL Key also select the LegacyBankApp project and click Finish (Figure 34).
    Figure 34. EAR Module Deployment Assembly: Select Projects dialog
    EAR Module Deployment Assembly: Select Projects Dialog
  14. Confirm that the LegacyBankAppWrapperService and LegacyBankApp project appear in the EAR Module Assembly pane and click OK (Figure 35).
    Figure 35. EAR Module Deployment Assembly: Utility Projects and Packaging
    EAR Module Deployment Assembly: Utility Projects and Packaging
  15. In the Enterprise Explorer view, confirm that the Utility JARs have been added to the EAR file as shown in Figure 36.
    Figure 36. LegacyBankAppEAR Utility JARs
    LegacyBankAppEAR Utility JARs
  16. In the Enterprise Explorer view, right click on the LegacyBankAppWeb project and select Build Path > Configure Build Path….
  17. In the Properties for LegacyBankAppWeb window, click on Projects tab and then click on Add (Figure 37).
    Figure 37. LegacyBankAppWeb Java Build Path
    LegacyBankAppWeb Java Build Path
  18. In the Required Project Selection dialog, select the LegacyBankAppWrapperService project and click OK (Figure 38).
    Figure 38. LegacyBankAppWeb Java Build Path Select Projects dialog
    LegacyBankAppWeb Java Build Path Select Projects Dialog
  19. The Java Build Path should now include the LegacyBankAppWrapperService project as shown in Figure 39.
    Figure 39. LegacyBankAppWeb Updated Java Build Path
    LegacyBankAppWeb Updated Java Build Path

This completes the steps required to create the associated artifacts and Java EE Modules for the legacy bank application’s JAX-RS 1.1 REST Service.


Implement the JAX-RS 1.1 application configuration and resource classes

  1. In the Enterprise Explorer, right click on the LegacyBankAppWeb > Java Resources > src folder and select New > Class.
  2. In the Package field enter com.ibm.wrapper.bankapp.rest.resources as the package name.
  3. In the Name field enter CustomerAccountResource as the class name and then click Finish (Figure 40).
    Figure 40. Create JAX-RS resource class
    Create JAX-RS Resource Class
  4. Right click on the LegacyBankAppWeb > Java Resources > src > com.ibm.wrapper.bankapp.rest.resources package and select New > Class.
  5. In the Name field enter CustomerAccountApplication as the class name.
  6. In the Superclass field enter javax.ws.rs.core.Application as the Superclass and then click Finish (Figure 41).
    Figure 41. Create JAX-RS application configuration class
    reate JAX-RS Application Configuration Class
  7. In the Enterprise Explorer view, expand the LegacyBankAppWeb > Java Resources > src > com.ibm.wrapper.bankapp.rest.resources package.
  8. Right click on the CustomerAccountApplication class and select Open.
  9. Open the TextFiles > CodeSnippets.txt file and copy in the code from the === CustomerAccountApplication === section into the CustomerAccountApplication class (Figure 42).
    Figure 42. JAX-RS CustomerAccountApplication code
    JAX-RS CustomerAccountApplication Code
  10. Click on File > Save.
  11. In the Enterprise Explorer view, expand the LegacyBankAppWeb > Java Resources > src > com.ibm.wrapper.bankapp.rest.resources package.
  12. Right click on the CustomerAccountResource class and select Open.
  13. Open the TextFiles > CodeSnippets.txt file and copy in the code from the === CustomerAccountResource === section into the CustomerAccountResource class (Figure 43).
    Figure 43. JAX-RS CustomerAccountResource code
    JAX-RS CustomerAccountResource Code
  14. Click File > Save.

This completes the steps required to create and implement JAX-RS code artifacts for the legacy bank application’s JAX-RS 1.1 REST Service.


Modify the Web module deployment descriptors

  1. In the Enterprise Explorer, expand the LegacyBankAppWeb and navigate to LegacyBankAppWeb > WebContent > WEB-INF.
  2. Right click the web.xml file and click Open.
  3. In the Web Application 3.0 Deployment Descriptor Editor, click on the Design Tab.
  4. Select Web Application (LegacyBankAppWeb) > Servlet (JAX-RS Servlet) and click Add (Figure 44).
    Figure 44. LegacyBankAppWeb Deployment Descriptor
    LegacyBankAppWeb Deployment Descriptor
  5. In the Add Item to Servlet dialog, select Initialization Parameter and click OK (Figure 45).
    Figure 45. LegacyBankAppWeb Deployment Descriptor Add Item dialog
    LegacyBankAppWeb Deployment Descriptor Add Item Dialog
  6. In the Design Tab’s Details section for the newly added servlet initialization parameter, enter the following in the name and value fields (Figure 46): Name*: javax.ws.rs.ApplicationValue*: com.ibm.wrapper.bankapp.rest.resources.CustomerAccountApplication
    Figure 46. LegacyBankAppWeb Deployment Descriptor with initialization parameter
    LegacyBankAppWeb Deployment Descriptor with initialization Parameter
  7. Save changes to the Web Deployment Descriptor and close the editor.

This completes the steps required to modify the Web Module deployment descriptors for the legacy bank application’s JAX-RS 1.1 REST Service. The solution is now ready to be deployed to the WebSphere Application Server V8.0 runtime environment.


Deploy the solution to the runtime test environment

  1. In the Server View, right click on the server and select Add and Remove.
  2. Select the LegacyBankAppEAR and click Add (Figure 47).
    Figure 47. Add LegacyBankAppEAR to the server
    Add LegacyBankAppEAR to the Server
  3. Click Finish (Figure 48).
    Figure 48. LegacyBankAppEAR deployed to server
    LegacyBankAppEAR Deployed to Server
  4. In the Server View, right click the server and click Start.

This completes the steps required to deploy the legacy bank application’s JAX-RS 1.1 REST Service to a WebSphere Application Server runtime environment configured in Software Architect.


Verify the solution with REST HTTP client

  1. Expand RESTClient > src > com.ibm.simple.bankapp.client. Right click RESTHTTPClient.java and select Open (Figure 49).
    Figure 49. Select and Open RESTHTTPClient for editing
    Select and Open RESTHTTPClient for Editing
  2. Update the String variable “port” with the port number for your Application Server runtime (Figure 50).
    Figure 50. RESTHTTPClient code update
    RESTHTTPClient Code Update
  3. Right click RESTHTTPClient.java and select Run As > Java Application (Figure 51).
    Figure 51. Launch RESTHTTPClient
    Launch RESTHTTPClient
  4. The output from the test client is shown in the file TextFiles > RESTHTTPClientOutput.txt under downloads. NOTE: Server Side code will throw an Application Exception that Account does not exist when the test client verifies that an account has been deleted (see TextFiles > ServerRuntimeOutput.txt)
  5. When testing and validation is complete, in the Server View right click Server > Stop.

This completes the steps required to verify the successful deployment of the legacy bank application’s JAX-RS 1.1 REST Service to a WebSphere Application Server runtime environment configured in Software Architect.


Download

DescriptionNameSize
Sample artifacts for this tutorialdevWorks_LegacyBankAppArtifacts.zip4.82MB

Resources

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 WebSphere on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=WebSphere, Java technology
ArticleID=764302
ArticleTitle=Developing JAX-RS 1.1 RESTful Services in Rational Software Architect V8 for deployment to WebSphere Application Server V8
publish-date=11022011