Oracle® Retail Integration Bus Support Tools Guide Release 16.0.023 E89678-01 |
|
Previous |
Next |
This chapter discusses the RIB API simulators.
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.
Table 2-1 Prerequisite Tasks
Task | Notes |
---|---|
Install WebLogic server 12.2.1.2 and create an instance. |
This instance is used to deploy the javaee-api-stubs. |
Install the Oracle12c 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 (JavaEeApiStubs16.0.023ForAll16.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-<version>.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-<version>.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-<version>.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.
|
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.
|
|
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. The user supplied for sim_jndi_user-name-alias - the javaee-api-stubs user - must belong to the IntegrationGroup. To configure Users and Groups, log in to WebLogic Console and select Security Realms > myRealm > Users and Groups. If a group named "IntegrationGroup" does not exist, you must create one. Add the javaee-api-stubs user to the IntegrationGroup. |
<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> |
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.
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.
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 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 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.
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 Shell Scripts
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. |
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. |
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-<version>.jar 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.8 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 PlsqlApiStubs16.0.023ForAll16.x.xApps_eng_ga.tar |
This will create the file folders and place the executables and config files. In rib-home/tools-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-<version>.jar into the scripts directory. unzip rib-public-payload-database-object-types-<version>.jar |
|
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=ora12c dbuseralias=rms15dbuseralias, name should be unique |
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. |
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-<version>.jar. 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: |