The Oracle Retail Integration Bus is difficult to test as a stand-alone sub-system. It is part infrastructure and part application, and needs to have the integrating application end-points for even a simple installation.
To aid in the initial installation and evaluation of RIB, a test harness has been developed and made available. The test harness is comprised of these components:
plsql-api-stub—An API simulator of the PL/SQL API applications, RMS, RFM, and RWMS.
javaee-api-stubs—An API simulator of the applications exposing JavaEE APIs, SIM, RPM, and AIP.
RDMT—The RIB Diagnostic and Monitoring Tool kit is a collection of command line tools, written in UNIX shell script along with supporting Java classes packaged in jar files.
Sample XML files—These samples conform to the message payloads (XSDs).
Message auditing—This is a feature that allows end-to-end auditing of a message as it passes through all RIB components.
Initially, installing and deploying RIB requires connecting to the Oracle Retail applications to verify that messages could flow end to end. RIB installation requires that end points exist and respond. To test it, the end points must be configured to publish or subscribe.
This test harness is completely independent of the applications, but uses the same RIB artifacts (payloads and Oracle Objects) as the actual applications. Additional tools and artifacts support the construction of test messages and the publication of these test messages.
The ability to initially install and deploy RIB has always been difficult because of the need to connect to the Oracle Retail applications to verify that messages could flow end-to-end. RIB installation requires that end-points exist and respond, and to test it requires that the end-points are configured to publish or subscribe.
The dependency on the application end-points can be not only a scheduling issue, but to produce messages for testing can require data seeding and coordination with the individual application teams.
RIB has several tools, including application API simulators that combine to provide a test harness that allows for RIB installation, configuration, and testing. These were developed to address the requirement for the full application to be present to validate a RIB installation as well as providing a tool for integration and system tests.
This check list covers all of the sequential steps required to create a stand-alone RIB Test Harness.
Task | Notes |
---|---|
Create the rib-home | Follow the guidelines in the Oracle Retail Integration Bus Installation Guide and the Oracle Retail Integration Bus Implementation Guide for prerequisites.
Do not invoke the installer yet. |
Install the javaee-api-stubs and plsql-api-stubs into the rib-home/tools-home. | Follow the instruction in the tools section. |
Install the pl/sql api stubs | Follow the instruction in the tools section. The plsql-api-stubs can simulate both RMS and RWMS from the same user, but if it is desired to test full flow including hospital, then install to two users. |
For the PL/SQL app subs install a set of Hospital Tables in the same user account. | See the Oracle Retail Integration Bus Installation Guide.
See note about two stubs. |
Deploy the javaee-api-stubs. | Follow the instruction in the tools section. |
Install RIB using the stubs as application end-points. | See the Oracle Retail Integration Bus Installation Guide. |
The plsql-api-stubs is an API simulator designed to act in the same manner as when 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 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 RIB directly interfaces with. These interfaces map calls to the common subsystem to output parameters or statuses.
The Stub Administration and Setup Application. A set of simple application function and a character based menu that allow 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 a 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 when the consume procedure is executed it will throw 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 APIs internally call the Java functions present in the classes and the PL/SQL OUT parameters are mapped with the Java return types.
So when 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 that uses the common subsystem tables to get messages as a CLOB. It then converts the CLOB to an Oracle Object and 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.
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 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 or getnxt API. |
read_metadata.sh | Wrapper script to call a Java utility that will read a PL/SQL application (RMS, RWMS) schema and create a metadata file as input to create the stubbed APIs. |
The following are /conf directory 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:
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 retail-public-payload-database-object-types. | retail-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 then the objects will be 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.
Note: Do not share the plsql-api-stubs schema with any other test-tools. |
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. |
Task | Notes |
---|---|
Extract the tar file.cd rib-app-builder/rib-home/tools-home
tar xvf PlsqlApiStubs15.0.0ForAll15.x.xApps_eng_ga.tar |
This will create the file folders and place the executables and configuration 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 retail-public-payload-database-object-types-<version>.jar into the scripts directory.
unzip retail-public-payload-database-object-types-<version>.jar |
|
Edit /conf/stubby.properties to point to the database url and user/password (see prerequisites).
vi stubby.properties |
# Database details
hostname= <host name> port= <port> sid=ora12c dbuseralias=rms15dbuseralias |
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 menu item or install.sh in the stubby base directory
cd rib-app-builder/rib-home/tools-home/ plsql-api-stubs ./install.sh Or ./stubbymenu.sh Then select the menu item to install. |
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 scripts files in the 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 can be ignored. Runs the load Java utility to load Java classes as objects in the configured user schema. All the RMS and RWMS packages are created in the configured user schema. The PLSQL stubby needs its own schema. It cannot share its tools with the other test tools. |
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. |
The installation is now complete, and the tool is ready to be used.
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 Enterprise Integration Guide and the operations guides for the RMS and RWMS applications.
Note: The database credentials setup must be complete before configuring the API. |
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. | 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 and respond to the prompts.
Prompts during configuration of a GETNXT and PUB_RETRY.
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 uploaded |
Enter Business Object ID to be returned. | Optional |
Do you want to enter Routing Information for the message? [Y/N]:N | |
Enter the Thread Value for the message. | |
Enter the number of times the message must be replicated. |
Prompts during configuration of a CONSUME.
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 with only be prompted if the status code is E. |
Enter Message Type the Consume should return [CRE,MOD,DEl] eq:ITEMCRE: |
The javaee-api-stubs is an API simulator designed to acts in the same manner as when 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 RIB: SIM, RPM, and AIP.
Complete the steps described below.
Task | Notes |
---|---|
Select a location for the javaee-api-stubs to reside. | Recommended location is in the rib-app-builder/rib-home tree structure:
rib-home/tools-home/javaee-api-stubs/rib-home/tools-home/ javaee-api-stubs |
Get the latest version of the javaee-api-stubs. | The javaee-api-stubs is packaged as a stand-alone tar. |
Create a database user that will own the javaee-api-stubs objects. | The user requires no special permissions.
CREATE USER <javaee stub user> PROFILE DEFAULT IDENTIFIED BY <plsql stub user> DEFAULT TABLESPACE USERS GRANT CONNECT TO <javaee stub user>; GRANT RESOURCE TO <javaee stub user>; |
Task | Notes |
---|---|
Determine the WebLogic instance to which to deploy the javaee-api-stubs-<version>.ear. | It is recommend 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. |
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 SIM subscribing families. |
Using RIB Application 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://javaeestubhost.example.com:<port>/javaee-api-stubs</url> <factory>weblogic.jndi.WLInitialContextFactory</factory>
<user-alias>sim_jndi_user-name-alias</user-alias>
</jndi>
</app>
|