| Oracle® Retail Integration Bus Operations Guide Release 13.0.4 |
|
 Previous |
 Next |
The RIB 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 install.
To aid in the initial install and evaluation of the RIB, a test harness has been developed and made available. The test harness is comprised of the these components:
plsql-api-stubs - An API simulator of the PL/SQL API applications: RMS and RWMS.
javaee-api-stubs - An API simulator of those 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 of RIB 13 that allows the end-to-end auditing of a message as it passes through all of the RIB components.
The ability to initially install and deploy the 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. The RIB install requires that end-points exist and respond, and to test it requires that the end-points are 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.
|
Note: See "RIB Test Harness" in this chapter.See Chapter 8, "Diagnostic and Monitoring Tools." See "RIB Logging" in Chapter 3. |
The ability to initially install and deploy the 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. The RIB install 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 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 the installation, configuration, and testing of the RIB. These were developed to address the requirement for the full application to be present to validate a RIB installation as well as a providing a tool for integration and system tests.
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.
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 Implementation Guide and the Oracle Retail Integration Bus Installation Guide for the 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 the 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 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 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 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 sequence called RMSMFM_ORDER_GE_SEQ created in the data base.
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 execute 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 API internally call the java functions present in the classes then the PL/SQL OUT parameters are 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 CLOBs, 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.
| 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 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. |
/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 storedproceduremetadat.xml specified in the Stubby.properties file.
Do not edit. |
| StoredProcedureMetaData_RWMS.xml | Do not edit. |
| StoredProcedureMetaData_RMS.xml | Do not edit. |
| 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 (for example, PlsqlApiStubs13.0.4ForAll13.x.xApps_eng_ga.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. (for example, RibFuncArtifact13.0.4ForAll13.0.4Apps_eng_ga.tar) and should be extracted from there.
If this install 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. | The user requires no special permissions.
CREATE USER "PLSQLSTUB" PROFILE "DEFAULT" IDENTIFIED BY " PLSQLSTUB " DEFAULT TABLESPACE "USERS" TEMPORARY TABLESPACE "TEMP" GRANT "CONNECT" TO " PLSQLSTUB " GRANT "RESOURCE" TO " PLSQLSTUB " |
| This version requires a path to jdk1.5 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 PlsqlApiStubs13.0.4ForAll13.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 url and user/password (see prerequisites).
vi stubby.properties |
# Database details
hostname=linux1 port=1521 sid=ora10g username=plsqlstub password=plsqlstub |
| Base Script File names | This is where the selection of either RMS or RWMS objects is made. Only one per installation. |
| Execute the install. 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 install 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 udt 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. |
| Install Hospital tables | See the Oracle Retail Integration Bus Installation Guide. |
| Enter the complete path for jdk1.5: | This version of stubby and the RDBMS requires jdk1.5 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 Integration Bus Integration Guide and the application operations guide for Oracle Retail Merchandising System and Oracle Retail Warehouse Management System.
| 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.
rib-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 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 (Give the complete file name): | The complete file path of the message to uploaded. |
| Enter Business Object ID to be returned (Optional): | |
| Do want to enter Routing Information for the message?[Y/N]:N | |
| Enter the Thread Value for the message: | |
| Enter the No. of times the message needs to 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 is prompted only 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 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 JavaEE APIs to the RIB; SIM, RPM and AIP.
| 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-app-builder/rib-home/tools-home/ javaee-api-stubs |
| Get the latest version of the plsql-api-stubs. | The plsql-api-stubs is packaged as a stand-alone tar (for example, JavaEeApiStubs13.0.4ForAll13.x.xApps_eng_ga.tar). |
| Create a database user that will own the javaee-api-stubs objects. | The user requires no special permissions.
CREATE USER JAVAEESTUB PROFILE DEFAULT IDENTIFIED BY STUBBY DEFAULT TABLESPACE USERS TEMPORARY TABLESPACE TEMP GRANT CONNECT TO JAVAEESTUB GRANT RESOURCE TO JAVAEESTUB |
| Task | Notes |
|---|---|
| Decide which OC4J instance to deploy the javaee-api-stubs.ear to. | It is recommend but not required that a separate instance be used from the rib-<app> instance. |
| Using the OAS console, select the oc4j instance and then deploy javaee-api-stubs-.ear. | Refer OAS deployment document for more details on how to deploy a Java EE application. |
| Verify install | Check logs in
$ORACLE_HOME/j2ee/<instance_name>/log/<instance_name_group_name>/oc4j/log.xml |
Using the OAS console, configure the database resources for the javaee-api-stubs JDBC resources.
|
Refer to the OAS document for more details. |
| On the JDBC Resources line select Go to Task. | Select javaee-api-stubs-db-connection-pool-non-xa
Update database credentials to the javaee-api-stubs user created in the prereqs. Select javaee-api-stubs-db-connection-pool Update database credentials to the javaee-api-stubs user created in the prereqs. |
| Test Connections | Select Test Connection and verify. |
| 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 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. |
<jndi>
<url>opmn:ormi://linux1:rib-javaeestub-oc4j-instance/javaee-api-stubs</url>
<factory>oracle.j2ee.rmi.RMIInitialContextFactory</factory>
<user>oc4jadmin</user>
<password>welcome1</password>
</jndi>
</app>
|
|
 Copyright © 2010, Oracle and/or its affiliates. All rights reserved. Legal Notices |
|
