2 RIB API Simulators

This chapter discusses the RIB API simulators.

Java API Simulator

The javaee-api-stubs is an API simulator designed to act in the same manner as when the RIB is connected to the actual application, but at the same time, have means to process specific status and other parameters from a stubbed application. This set of tools is designed to emulate those applications exposing Java EE APIs to the RIB: SIM, RPM, AIP, and OMS.

Architecture and Design

Installation

Table 2-1 Prerequisite Tasks

Task	Notes
Install WebLogic server 10.3.6 and create an instance.	This instance is used to deploy the javaee-api-stubs.
Install the Oracle11g database.	The installation creates the data source that refers to this database.
Select a location for the javaee-api-stubs to reside.	Recommended location is in the rib-app-builder/rib-home tree structure: rib-app-builder/rib-home/tools-home/ javaee-api-stubs
Get the latest version of the javaee-api-stubs (JavaEeApiStubs14.0.0ForAll14.x.xApps_eng_ga.tar) from RIB wiki.	The javaee-api-stub is packaged as a stand-alone tar.
Extract the tar file to locate the installable.	javaee-api-stub.ear resides in the extracted folder.
Create a database user that owns the javaee-api-stubs objects.	The user requires no special permissions. CREATE USER <javaee stub user> PROFILE DEFAULT IDENTIFIED BY <javaee stub password> DEFAULT TABLESPACE USERS TEMPORARY TABLESPACE TEMP; GRANT CONNECT TO <javaee stub user>; GRANT RESOURCE TO <javaee stub user>;

Table 2-2 Installation

Task	Notes
Determine the WebLogic instance to which to deploy the javaee-api-stubs.ear.	It is recommended but not required that an instance separate from the rib-<app> instance is used.
Using the WebLogic console, select the WebLogic instance and then deploy javaee-api-stubs-.ear.	See WebLogic deployment documentation for more details on how to deploy a Java EE application.
Using the WebLogic console, configure the database resources for the javaee-api-stubs JDBC resources. Log in to the WebLogic admin console Navigate to the Data Sources screen using Services > JDBC > Data Sources menu. Click New. Enter the following values in the respective fields. Name: javaee-api-stubs-non-xa-managed-datasource JNDI Name: jdbc/OracleRibDsNonXA Database Type: Oracle Database Driver: Oracle's Driver(Thin) Click Next. Uncheck Supports Global Transactions. Define connection properties for the database user in question. Verify the configuration by clicking Test Configuration. Do not proceed if the test fails. Ensure that the configuration is accurate. Select target as the server that would host javaee-stubby (for example, javaee-stubby-instance). Click Finish.	See WebLogic documentation for details.
Create one more data source named javaee-api-stubs-xa-managed-datasource. Navigate to the Data Sources screen using Services > JDBC > Data Sources menu. Click New. Enter the following values in the respective fields. Name: javaee-api-stubs- -xa-managed-datasource JNDI Name: jdbc/OracleRibDs Database Type: Oracle Database Driver: Oracle's Driver(Thin) Click Next for Transaction Properties. Make sure Supports Global Transactions is checked. Define connection properties for the database user in question. Verify the configuration by clicking Test Configuration. Do not proceed if the test fails. Ensure that the configuration is accurate. Select target as the server that would host javaee-stubby (for example, javaee-stubby-instance). Click Finish. Verify that both data sources are listed on Services > JDBC > Data Sources screen.
Install Hospital tables	See the Oracle Retail Integration Bus Installation Guide.

Table 2-3 Configuration of the rib-<app> to use Injection Stubs

Task	Notes
Decide which rib-<app> to configure for.	The stubbed implementation has been written to insert the payload to a database once inject has been called. Injectors.xml has been configured to include all the RPM, SIM subscribing families.
Using RIB App Builder or the RIB Installer configure and deploy the rib-app using the jndi information of the javaee-api-stubs in place of the app.	<app id="sim" type="javaee-app"> <jndi> <url>t3://ribhost.example.com:18022/javaee-api-stubs</url> <factory>weblogic.jndi.WLInitialContextFactory</factory> <user-alias>sim_jndi_user-name-alias</user-alias> </jndi> </app>

Operation

javaee-api-stubs application can be used to publish a message to the RIB integration environment.

Populate the following fields:

Table 2-4 RMI Properties

User Name	Mandatory Field	The user name used to connect to WebLogic server.
Password	Mandatory Field	The password used to connect to WebLogic server.
URL	Mandatory Field	t3://host:port/applicationName

Table 2-5 RIB Message Data

Message Family	Mandatory Field	The family of the message that is to be published.
Message Type	Mandatory Field	The message type of the message that is to be published.
Business Object ID	Optional	Numeric ID.
Message Data	Mandatory Field	Payload data.

The RIB app publishing adapter submits the message to be published.

PL/SQL API Simulator

The plsql-api-stubs is an API simulator designed to acts in the same manner as when the RIB is connected to the actual application, but at the same time, have means to process specific status and other parameters from a "stubbed" application. This set of tools is designed to emulate those applications exposing PL/SQL APIs to the RIB: RMS, RFM, and RWMS.

Architecture and Design

The tool set contains three main subsystems:

• A common set of PL/SQL packages, stored procedures and database tables. These are used by the other subsystems.

• A thin API-specific set of packages and stored procedures that the RIB directly interfaces with. These interfaces map calls to the common subsystem to output parameters or statuses.

• The Stub Admin and Setup Application. A set of simple application functions and a character based menu that allows installation and set up of specific behaviors for a specific API.

The Common Subsystem

The purpose of the common subsystem is to provide a standard means of implementing specific behavior by an API. The stubbed APIs simulate a real application by using the common subsystem which will be loaded during the installation through JDBC calls to the database. It is comprised of a group of tables, sequences and other database objects created for each stubbed API.

There is a set of tables and sequences created for each GETNXT procedure. These tables are generated with the OUT and IN/OUT parameters of the GETNXT procedure as the fields. The user is prompted to enter data into these tables when he is trying to test for a particular API.

For example:

If there is a GETNXT procedure in a package called RMSMFM_ORDER, then the common subsystem for this procedure would be a table RMSMFM_ORDER_GE_TBL and sequence called RMSMFM_ORDER_GE_SEQ created in the database.

For each PUB_RETRY Procedure in the API, a set of tables and sequences are created the same as GETNXT, except that the names of tables and sequences have PU instead of GE

For a CONSUME API, there is a table called RIB_CONSUME created with the O_STATUS_CODE, O_ERROR_MESSAGE and EXCEPTION_TO_THROW as the fields. If the user needs the CONSUME to throw a specific type of exception, then the exception can be uploaded into the RIB_CONSUME table, so that when the consume procedure is executed it throws the specified exception type.

The Thin API layer

The API subsystem consists of packages and stored procedures that have the exact same signature as those found within the real application. This layer queries the appropriate common subsystem tables, sequences and other database objects to get the appropriate out parameters. These are then mapped to the API specific parameters of the stubbed application API.

The implementation of the stubbed API is written as Java classes and loaded into the database during installation. The PL/SQL stubbed APIs are implemented in a way that these API internally call the Java functions present in the classes and the PL/SQL OUT parameters are then mapped with the Java return types.

So when the RIB calls the GETNXT stubbed API as it normally calls the GETNXT API of a real application, the stubbed API internally calls the Java class which uses the common subsystem tables to get messages as a CLOB, it then converts the CLOB to an Oracle Object and then maps it with the PL/SQL OUT parameters and returns.

The Stub Admin and Setup Functions

These are a set of simple application functions written in Java and wrapped by shell scripts and a character based menu that allow installation and set up of specific behaviors for a specific API.

Table 2-6 The Stub Admin and Setup Functions

Shell Script	Description
stubbymenu.sh	Simple character based menu that calls the wrapper scripts.
install.sh	Wrapper script that calls the Java classes to install the RIB Objects and stubby Java classes dynamically created from the metadata into the database (see stubby.properties).
configure_api.sh	Wrapper script that calls the Java classes to set up the behavior and messages of a given CONSUME, PUB_RETRY, or GETNXT API.
read_metadata.sh	Wrapper script to call a Java utility that will read a PL/SQL application (RMS, RFM, RWMS) schema and create a metadata file as input to create the stubbed APIs.

Configuration Files

The following are /conf directory files:

Table 2-7 Configuration Files

Configuration File	Description
stubby.properties	Primary configuration file. Contains database url info and the metadata scripts to load.
commons-logging.properties	Apache logging conf
simplelog.properties	Apache logging conf
SqlToJavaMapper.java	generated from the storedproceduremetadatxml specified in the Stubby.properties file. Note: Do not edit.
StoredProcedureMetaData_RWMS.xml	Note: Do not edit.
StoredProcedureMetaData_RMS.xml	Note: Do not edit.

Installation

Complete the following steps:

Table 2-8 Prerequisite Tasks

Task	Notes
Select a location for the plsql-api-stubs to reside.	Recommended location is in the rib-app-builder/rib-home tree structure: rib-app-builder/rib-home/tools-home
Get the latest version of the plsql-api-stubs.	The plsql-api-stubs is packaged as a stand-alone tar.
Get the latest version of the rib-public-payload-database-object-types.	rib-public-payload-database-object-types.zip is packaged with the RibFuncArtifacts and should be extracted from there. If this installation is in rib-home, the objects is located in the rib-home/download-home/rib-func-artifacts.
Create a database user that will own the plsql-api-stubs schema and the objects.	The user requires no special permissions. CREATE USER <plsql stub user> PROFILE "DEFAULT" IDENTIFIED BY <plsql stub password> DEFAULT TABLESPACE "USERS" TEMPORARY TABLESPACE "TEMP"; GRANT "CONNECT" TO <plsql stub user>; GRANT "RESOURCE" TO <plsql stub user>;
This version requires a path to jdk1.7 for compiling Java stored procedures.	Be prepared to specify the path when prompted.

Table 2-9 Installation

Task	Notes
Extract the tar file. cd rib-app-builder/rib-home/tools-home tar xvf PlsqlApiStubs14.0.0ForAll14.x.xApps_eng_ga.tar	This will create the file folders and place the executables and config files. In rib-home/tool-home there is a directory already. It is a placeholder and this will over write it.
Place the database objects file in the scripts subdirectory
Extract the rib-public-payload-database-object-types.zip into the scripts directory. unzip rib-public-payload-database-object-types.zip
Edit /conf/stubby.properties to point to the database hostname, port, sid, and alias (see prerequisites). vi stubby.properties	# Database details hostname=linux1 port=1521 sid=ora10g username=<plsql stub user> password=<plsql stub password>
Base Script File names	This is where the selection of either RMS or RWMS objects is made. There can be only one per installation.
Execute the installation using install.sh in the stubby base directory cd rib-app-builder/rib-home/tools-home/ plsql-api-stubs ./stubbymenu.sh	The installation performs these actions: Runs a cleanup that will remove any existing RIB related tables, sequences, packages and types installed in the configured user schema. Runs all the script files in the scripts sub-directory. Runs a drop Java utility to remove any existing classes in the configured user schema. Note: The warnings generated by the drop Java utility can be ignored. Runs the load Java utility to load Java classes as objects in the configured user schema. All the RMS or RWMS packages are created in the configured user schema.
Select option [1] Database Credentials SetUp from the Stubby menu.
Enter database user and password at the prompts
Select option [2] Installation
Install Hospital tables	See the Oracle Retail Integration Bus Installation Guide.
Enter the complete path for jdk1.7:	This version of stubby and the RDBMS require jdk1.7 for compiling Java stored procedures.

Operation

The next step in using the tool set is to configure the desired behavior of the APIs under test. Use of the tool requires that the user understand the APIs involved at enough detail to understand and answer several prompts during the configuration process. See the Oracle Retail Integration Bus Integration Guide and the operations guides for the RMS and RWMS applications.

Table 2-10 Prerequisites

Task	Notes
Create a sub-directory for the test messages to configure the API to use. These can be any location on the same host where the tool user has permissions to read.	The RIB ships with sample xml files for each message family. These are packaged with RDMT and are located under the testmsg subdirectory in the rdmt directory. retail-public-payload-xml-samples.zip. These should be used as a basis for testing and modified to suit the test cases.
Understand and know which API and its type to configure. For example: API Type: GETNXT API Package name: RMSMFM_ITEMS Message Type: ITEMCRE	API Types supported: GETNXT CONSUME PUB_RETRY

Execute the configure_api.sh script or select the menu item (Configure API) and respond to the prompts.

Prompts during configuration of a GETNXT and PUB_RETRY.

Table 2-11 Configuration Prompts

Prompt	Notes
Status Code the GETNXT API should return: S for Success, H for hospital, N for no message, and E for exception	Case sensitive
Enter Error Message to be returned (to be entered only for H or E status codes).
Enter data for O_MESSAGE	The complete file path of the message to upload.
Enter Business Object ID to be returned.	Optional
Enter the Routing Information, if applicable for your message type.
Enter the Thread Value for the message.
Enter the number of times the message must be replicated.

Prompts during configuration of a CONSUME.

Table 2-12 CONSUME Configuration Prompts

Prompt	Notes
Enter Status Code the Consume should return [S-Success]/[E-Error]
Enter the Exception to be Thrown eg:nullpointerexception: Enter the Exception Message to be Thrown.	The Exception_To_Throw and Error Message are only prompted if the status code is E.
Enter Message Type the Consume should return [CRE,MOD,DEl] eg:ITEMCRE: