11 Implementation Guidelines

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 Consumer using Web Service Call-Out Utility Implementation Notes

To set up the Web service consumer side proxies, complete the following steps:

The Oracle database needs to get configured so that it can make WebService calls. This setup proce-dure requires sysdba permissions. The operating system commands must be executed by the OS us-er that owns Oracle Database installation, or has proper read/write/execute permission to Oracle Database installation folders.

Install Oracle JVM Web Services Call-Out Utility

Oracle JVM Web Services Call-Out Utility allows Oracle Database to make WebService calls. Installing WebService Call-Out utility prepares and configures the Oracle database to be able to make network calls out of the database.

Verify environment variables and export if needed

1. Login to linux box as the user that has installed Oracle 12.2.0.1 database.

2. env | grep ORACLE

   ORACLE_BASE=/u00/oracle

   ORACLE_HOME=/u00/oracle/product/12.2.0.1

   ORACLE_SID=sqlnet

3. export JAVA_HOME=$ORACLE_HOME/jdk

4. export PATH=$ORACLE_HOME/bin:$PATH

5. export PATH=$JAVA_HOME/bin:$PATH

6. which java

7. java -version

   
   

   Note: Verify all your variables are pointing to right locations.

   
   

Create OJVMWCU_INSTALL User

1. Login to sqlplus as sys dba.

   sqlplus sys/<password>@<DB_SERVICE_NAME> as sysdba

2. Create a user with exact name as OJVMWCU_INSTALL in DB.

   create user OJVMWCU_INSTALL identified by <OJVMWCU_INSTALL_PASSWORD>;

   
   

   Note: Oracle documentation states that the name cannot be different, it must be OJVMWCU_INSTALL

   
   

Install OJVMWCU

Install OJVMWCU using the oracle database provided install script(install_ojvmwcu.sql). Note down the password, it is recommended to keep the password same as sys users and application code will never need this password. Execute the following commands.

1. cd <ORACLE_HOME>/javavm/ojvmwcu/install

2. sqlplus sys/<SYS_PASSWORD>@<DB_SERVICE_NAME> as sysdba

3. SQL> @install_ojvmwcu.sql

   Enter value for 1: <OJVMWCU_INSTALL_PASSWORD>
    
   Package created.
    
   old  24:   execute immediate 'create user ' || install_schema || ' identified by &1';
   new  24:   execute immediate 'create user ' || install_schema || ' identified by password';
    
   Package body created.
    
   WCU: Configuring ojvmwcu
    
   Call completed.
    
   drop role ojvmwcu
   create role ojvmwcu
   grant ojvmwcu to SYS
    
   Call completed.
    
   WCU: Done Configuring ojvmwcu
    
   Call completed.
    
    
   Package created.
    
    
   Package body created.
    
   WCU: Loading Jersey jars
    
   Call completed.
    
   WCU: Loading - ojvmwcu-security.jar
   WCU: Loading - jersey-guava-2.22.1.jar
   WCU: Loading - javax.inject-2.4.0-b31.jar
   WCU: Loading - hk2-utils-2.4.0-b31.jar
   WCU: Loading - org.osgi.core-4.2.0.jar
   WCU: Loading - osgi-resource-locator-1.0.1.jar
   WCU: Loading - oracle-hk2.jar
   WCU: Loading - asm-debug-all-5.0.4.jar
   WCU: Loading - oracle-jaxrs-ri.jar
   WCU: Loading - javassist-3.18.1-GA.jar
   WCU: Loading - aopalliance-repackaged-2.4.0-b31.jar
    
   Call completed.
   WCU: Done Loading Jersey jars
   Call completed.
   SQL> 
   

   Make sure you get successful output before proceeding.

   
   

   Note: You must create the OJVMWCU_INSTALL schema before running the install_ojvmwcu.sql script. The install_ojvmwcu.sql script checks whether the OJVMWCU_INSTALL schema is present in the database or not. If not, then it displays a message that the schema is not present and stops running. The OJVMWCU_INSTALL schema is created only for using the Oracle JVM Web Services Call-Out Utility and should not be used for any other purpose.

   
   

Create the user that will call WebServices from the Database

1. sqlplus sys/<SYS_PASSWORD>@<DB_SERVICE_NAME> as sysdba

2. create user <WEB_SERVICE_CALLER_USER> identified by <WEB_SERVICE_CALLER_PASSWORD>;

3. GRANT CREATE SESSION TO <WEB_SERVICE_CALLER_USER>;

4. GRANT DBA TO <WEB_SERVICE_CALLER_USER>;

5. grant OJVMWCU to <WEB_SERVICE_CALLER_USER>;

6. SELECT * FROM DBA_ROLES;

   
   

   Note: Make sure <WEB_SERVICE_CALLER_USER> has role OJVMWCU: SELECT * FROM DBA_ROLE_PRIVS WHERE GRANTEE = 'WEB_SERVICE_CALLER _ USER';

   
   

Grant permission and create synonyms

Permissions and synonyms are created from user schema to ojvmwcu_install schema.

1. cd <ORACLE_HOME>/javavm/ojvmwcu/install

2. sqlplus sys/<SYS_PASSWORD>@<DB_SERVICE_NAME> as sysdba

3. SQL>@export_ojvmwcu_classes.sql <WEB_SERVICE_CALLER_USER>;

Check for invalids in both ojvmwcu_install and <WEB_SERVICE_CALLER_USER> schema:

SELECT count(*) "invalid" FROM user_objects WHERE status <> 'VALID';

If invalids are found, fix them.

Grant permission to the user

Give the java classes various permission. Execute the dbms_java.grant_permission() call from sqlplus.

1. sqlplus sys/<SYS_PASSWORD>@<DB_SERVICE_NAME> as sysdba

2. call dbms_java.grant_permission( '<WEB_SERVICE_CALLER_USER>', 'SYS:java.util.PropertyPermission', 'com.sun.xml.ws.transport.http.client.HttpTransportPipe.dump', 'write' );

3. call dbms_java.grant_permission( '<WEB_SERVICE_CALLER_USER>', 'SYS:java.util.PropertyPermission', 'com.sun.xml.internal.ws.transport.http.client.HttpTransportPipe.dump', 'write' );

4. call dbms_java.grant_permission( '<WEB_SERVICE_CALLER_USER>', 'SYS:java.util.PropertyPermission', 'com.sun.xml.ws.transport.http.HttpAdapter.dump', 'write' );

5. call dbms_java.grant_permission( '<WEB_SERVICE_CALLER_USER>', 'SYS:java.util.PropertyPermission', 'com.sun.xml.internal.ws.transport.http.HttpAdapter.dump', 'write' );

6. call dbms_java.grant_permission( '<WEB_SERVICE_CALLER_USER>', 'SYS:java.lang.reflect.ReflectPermission', 'suppressAccessChecks', '' );

7. call dbms_java.grant_permission( '<WEB_SERVICE_CALLER_USER>', 'SYS:java.io.FilePermission', '/u00/oracle/product/12.2.0.1/basename', 'read' )

   
   

   Note: This step assumes ORACLE_HOME=/u00/oracle/product/12.2.0.1

   
   

8. call dbms_java.grant_permission( '<WEB_SERVICE_CALLER_USER>', 'SYS:java.lang.RuntimePermission', 'accessClassInPack-age.com.sun.xml.internal.bind.v2.model.annotation', '' )

9. call dbms_java.grant_permission( '<WEB_SERVICE_CALLER_USER>','SYS:java.util.logging.LoggingPermission', 'control', '');

10. call dbms_java.grant_permission('<WEB_SERVICE_CALLER_USER>', 'SYS:oracle.aurora.rdbms.HandlePermission', 'HandleInputStream. <WEB_SERVICE_CALLER_USER>:com.sun.xml.internal.bind.v2.runtime.reflect.opt.FieldAccessor_Ref', 'read' );

    
    

    Note: You can do the following as well, but with PlsqlServiceConsumerImpl_grant.sql SQL>@<INSTALL_DIR>/PlsqlServiceConsumerImpl_grant.sql

    
    

Load RBO Oracle Objects into the database

The PLSQL Retail Business Objects(RBOs) are reused in the service consumer. The RBOs needs to be installed so the user <WEB_SERVICE_CALLER_USER> have access to it.

Note: If PLSQL RBOs are already installed for <WEB_SERVICE_CALLER_USER> user then skip this step.

All ROB sql files are available inside re-tail-public-payload-database-object-types-<CURRENT_VERSION>.jar

1. Unzip the file retail-public-payload-database-object-types-<CURRENT_VERSION>.jar

2. cd to the folder that has the *.sql files.

3. sqlplus <WEB_SERVICE_CALLER_USER>/<WEB_SERVICE_CALLER_PASSWORD>@<DB_SERVICE_NAME>

4. Run the SQL file InstallAndCompileAllRibOracleObjects.sql from sqlplus.

   
   

   Note: Make sure there are no invalid objects.

   
   

Create activity logging table

The WebService consumer logs all major activity in a table called service_log_entries to make it easier to debug. Create the table in <WEB_SERVICE_CALLER_USER> user.

1. sqlplus <WEB_SERVICE_CALLER_USER>/<WEB_SERVICE_CALLER_PASSWORD>@<DB_SERVICE_NAME>

2. SQL>@<INSTALL_DIR>/service_log_enteries.sql

   
   

   Note: Verify that the table got created properly.

   
   

Load WebService java code into database

The consumer zip file generated using RSE includes the jar files which need to be loaded into the da-tabase. Following is the list of jars that need to be loaded:

1. <WebServiceName>ServiceConsumer.jar

2. <WebServiceName>ServiceConsumerPlsqlImpl.jar

3. oo-jaxb-bo-converter-<CURRENT_VERSION>.jar

4. retail-public-webservice-consumer-util-<CURRENT_VERSION>.jar

5. retail-private-plsql-webservice-consumer-<CURRENT_VERSION>.jar

6. retail-public-payload-database-object-types-<CURRENT_VERSION>.jar

7. retail-public-payload-java-beans-<CURRENT_VERSION>.jar

8. retail-public-payload-java-beans-base-<CURRENT_VERSION>.jar

Run loadjava oracle database utility to load the java code into the database. loadjava should be executed by the oracle db user that has permission to Oracle database install folders.

loadjava -thin -verbose -resolve -force -user <WEB_SERVICE_CALLER_USER>/<WEB_SERVICE_CALLER_PASSWORD>@<DB_HOST_NAME>:<DB_PORT>/<DB_SERVICE_NAME>   
<INSTALL_DIR>/retail-public-payload-java-beans-base-<CURRENT_VERSION>.jar
<INSTALL_DIR>/retail-public-payload-java-beans-<CURRENT_VERSION>.jar
<INSTALL_DIR>/oo-jaxb-bo-converter-<CURRENT_VERSION>.jar
<INSTALL_DIR>/retail-public-webservice-consumer-util-<CURRENT_VERSION>.jar
<INSTALL_DIR>/retail-private-plsql-webservice-consumer-<CURRENT_VERSION>.jar
<INSTALL_DIR>/<WebServiceName>ServiceConsumer.jar
<INSTALL_DIR>/<WebServiceName>ServiceConsumerPlsqlImpl.jar

Check for invalids in <WEB_SERVICE_CALLER_USER> schema. If invalids are found, fix them:

SELECT count(*) "invalid" FROM user_objects WHERE status <> 'VALID';

Load WebService plsql code into database

Run the <WebServiceName>ServiceConsumerPlsqlImpl_create.sql in the same(<WEB_SERVICE_CALLER_USER>) schema where consumer code will be running. This sql file contains the PLSQL package which are used for invoking the web service. The service consumer package name follows the naming convention <WebServiceName>_SC. For example, if the web ser-vice name is GlAccountValidation, then the packages created by this script will be GlAc-countValidation_SC.

1. sqlplus <WEB_SERVICE_CALLER_USER>/<WEB_SERVICE_CALLER_PASSWORD>@<DB_SERVICE_NAME>

2. SQL>@<INSTALL_DIR>/<WebServiceName>ServiceConsumerPlsqlImpl_create.sql

PL/SQL Provider Service Implementation Notes

The distribution (.zip) file includes a .ear file that contains all the generated code for the service; it is ready to be deployed 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 5, "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.

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 WebLogic Application 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

   • retail-public-payload-java-beans-base-<version>.jar

   • retail-public-payload-java-beans-<version>.jar

   • retail-soa-enabler-<version>.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 WebLogic:

1. Create managed server on Weblogic for REST deployment.

2. Make sure that the managed server is up and running.

3. Create datasource as listed in the section

   Creating a JDBC Data Source in WebLogic.

4. After creating data source, navigate to Deployments Page.

5. Click "Lock and Edit" located on the right side pane.

6. Click Install. Browse the <appname>-rest-service.ear file to deploy and click

   OK.

   Use managed server created above to deploy.The deployed application is listed under Deployments and should be in Active State.

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

8. 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.

9. 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

10. 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 WebLogic

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

1. Select Data Sources from Home Page.

2. Click Lock & Edit located in the right pane.

3. Click New and select Generic Data Source from pop down.

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

5. Enter Name as, RetailWebServiceDs.

6. Enter JNDI Name as, jdbc/RetailWebServiceDs and Click Next.

7. Select Database Driver as, "Oracle's Driver(Thin) for Service connection; Versions:Any.

8. Click Next button. Uncheck the option for "Supports Global Transcations" and click Next.

9. In Connection Properties section, enter the following details:

   • DatabaseName: <sid>

   • Host Name: <host name>

   • Port: <port number>

   • password: <database password>

   • Confirm Password: <Same database password as above>

10. Click Next.

11. Click the Test Configuration button.

12. After Connection test succeeded, Click Next.

13. Select Managed server that is created for REST service deployment.

14. Click Finish.