10 Implementation Guidelines For Restful web services

This chapter provides a set of implementation notes that may be helpful when implementing the Oracle Retail Service-Oriented Architecture Enabler (RSE) tool. The information included here is intended to provide guidance on the following topics:

• PL/SQL Provider Service

• Java EE Service Provider

• Deploying the Web service

• Creating a JDBC Data Source

Important Note About this Chapter

The implementation notes in this chapter are intended to provide some guidance in the development and deployment of the Web service layer. This information does not take into account the implementation of the business logic required to complete the application API layer.

The RSE tool and approaches described in this section are complex. A high level of skill and knowledge of the product is required to complete these implementation tasks. Also required is technology specific development of application APIs and the business logic that is needed to complete it.

Any issues that may arise with development tools, development environments, custom APIs, or custom message flows are the responsibility of the customer and not Oracle Retail.

PL/SQL Provider Service Implementation Notes

The distribution (.zip) file includes an .ear file that contains all the generated code for the service; it is ready to be deploy to the application server. The business logic can be implemented in PL/SQL packages in Oracle. The distribution contains the specification and body scripts for the packages called by the deployed service.

To complete implementation, follow these steps:

Note: See Important Note About this Chapter.

1. Create the PL/SQL service provider distribution file using the RSE tool. The output of this process is the .zip file.

   
   

   Note: See Chapter 4, "User Interface Usage".

   
   

2. Extract the <service_name>ProviderImplSpec.sql and <service_name>ProviderImplBody.sql files from the distribution zip file.

   These files are modified to provide a PL/SQL implementation for the service.

3. Extract the <appname>-service.ear file from the distribution zip file. This file is the generated Web service that is deployed.

4. Create the JDBC data source.

   
   

   Note: See Chapter 10, "Creating a JDBC Data Source in Glassfish Server".

   
   

5. If not already deployed, deploy the Oracle Objects to the appropriate database user.

   
   

   Note: See the Oracle Retail Functional Artifact Generator Guide.

   
   

6. Modify the PL/SQL body file for the business logic implementation. The <service_name>ProviderImplBody.sql file contains comments about where to implement logic for each method on the service.

7. Install the modified PL/SQL packages to the database. They are called by the Web service methods.

8. Deploy the <appname>-rest-service.ear file to the Oracle Glassfish Server.

Java EE Service Provider Implementation Notes

The RSE tool creates the appropriate provider restful resources as well as a skeleton implementation layer where the developer implements business logic. All of this is packaged inside the provider distribution archive file.

The Java EE Provider distribution file provides a sample deployable application and all the libraries that can be used to create Web services using retail payloads. The distribution file follows the naming convention of <appname>_JavaEEServiceProvider.zip. For example, the distribution file for the RMS application is named rms_JavaEEServiceProvider.zip. The <rms> prefix must be replaced with the name of any other application being developed.

The Web services generated by the RSE tool can be implemented and deployed in a number of ways. This section includes three implementation use cases for reference.

Note: See the section, Important Note About this Chapter.

Use Case 1: Complete the Generator Provided Stub Code Implementation

1. Generate the distribution file using the RSE tool.

2. Extract the <appname>-service-ejb-impl-src.jar file from the zip file.

3. Extract the <appname>-rest-service.ear file from the zip file.

4. Add business logic code where indicated in the Impl java files.

5. Use the java jar command to re-build the <appname>-service-ejb-impl.jar file.

6. Use the jar command to update .ear file with the new implementation jar.

7. Deploy the .ear file to the server.

Use Case 2: Provide a Custom impl jar to the RSE Tool

1. Create custom java classes that implement the <service_name>ServiceProvider interfaces contained in the <appname>-service-provider.jar file.

2. Extract the ServiceProviderImplLookupFactory.properties file from the .ear file.

3. Modify the properties file to point to your implementation classes for the services.

4. Use the jar command to create a jar containing your implementation classes, as well as the modified properties file.

5. Run the RSE tool again and provide the new custom implementation jar file.

6. Extract and deploy the generated .ear file to the server.

Use Case 3: Package the Generated Service Classes in an Existing Application

1. Generate the distribution file using the RSE tool.

2. The service interfaces are provided in the <appname>-service-provider.jar file in the distribution file. This jar file should be included in the application classpath.

3. Source code of sample implementations for the service interfaces are provided in the <appname>-service-ejb-impl-src.jar file in the distribution file. (If application developers want to use the same classes in their application, they can extract the java files from the jar file and include those in application source code. They also can add their own business logic in the method implementations. If they decide to write their own implementations, they should make sure that the appropriate service interfaces are implemented.)

4. After writing the Web service implementations, the java files should be compiled. The class files can be included in a new jar file or in the same jar file used for the rest of the classes of the application.

5. Modify the ServiceProviderImplLookupFactory.properties file to include appropriate class names of service implementations and include it in application classpath. A recommended approach is to include the properties file in the jar file that contains the service implementation classes.

6. Make sure that the following jar files are included in the application ear file:

   • <appname>-service-provider.jar

   • Jar file containing the service implementation classes

   • jersey-client.jar

   • jersey-core.jar

   • jersey-json.jar

   • rms-service-util.jar

   • retail-public-payload-java-beans-base.jar

   • retail-public-payload-java-beans.jar

   • retail-soa-enabler.jar

7. Include web-module in the application.xml of the application. The module name should be same as the name of <appname>-rest-service.war file.

8. The .ear file is ready for deployment on the server.

Deploying the Web Service

Below are the steps for installing the <service-name>.ear on glassfish server:

1. Download and install Glassfish 3.1.1 server.

2. After installing, go to the glassfish-3.1.1/bin folder and run the below command:

   ./asadmin start-domain -v domain1

3. Access the admin console at URL: http://<host>:4848/

4. For creating an Oracle datasource in glassfish, copy ojdbc6.jar to the path $GLASSFISH_HOME/domains/domain1/lib/ext folder.

5. Stop and start the server again.

   Steps for creating a datasource are listed in the section Creating a JDBC Data Source in Glassfish Server.

6. After creating data source, access the Applications page

7. Click Deploy.

8. Browse the <appname>-rest-service.ear file to deploy and click OK.

   The deployed application is listed on the Applications page.

9. The URL to test a web service is like this: http://<host>:8080/rms-rest-service/SupplierResource/4/5.

10. In the above example, "rms-rest-service" is the context of web application in ear file, SupplierResource is the name of service, and the numbers are values supplied for path parameters for the web service.

    The above URL makes a call to the GET method of the web service.

11. For testing all other operations you can install SOAP-UI. And provide the URL of the WADL to create test cases. A sample URL of the WADL is http://<host>:8080/rms-rest-service/application.wadl

12. It will show all the operations that are available for a web service. You can enter request xml and execute the web service method.

Creating a JDBC Data Source in Glassfish Server

To create a JDBC Data Source in Glassfish Server, follow these steps:

1. Select Resources > JDBC > JDBC Connection Pools.

2. Click New.

3. In the Pool Namefield, enter OraclePool.

4. Select Resource Type as javax.sql.DataSource.

5. Select driver vendor as Oracle.

6. In Additional Properties section, enter the following details:

   • user: <database user name>

   • DatabaseName: <sid>

   • password: <database password>

   • URL: jdbc:oracle:thin:@<host>:<port>:<sid>

7. Save the connection pool.

8. Select Resources > JDBC > JDBC Resources.

9. Click New.

10. Enter JNDI Name: jdbc/RetailWebServiceDs

11. Select Pool Name as the one that was just created.

12. Click OK.

13. After saving the changes, restart the server.