| Oracle® Retail Integration Bus Operations Guide Release 13.0.1 |
|
 Previous |
 Next |
The RIB Application Builder and its directories and content are not a temporary staging structure. The directory structure and the tools must be in a permanent location and treated as a core application home. The location of the rib-app-builder is a key implementation decision.
The RIB installation process builds and executes out of rib-home. The RIB installer gathers all of the information that these tools require, constructs the key xml file (rib-deployment-env-info.xml), and then performs the installation, assembly, configuration, and deployment by invoking, as appropriate, a given task. Therefore, for most RIB software life cycle activities, the RIB installer should be used instead of the command line tools.
The rib-<app> application configuration and installation process follows the RIB lifecycle phases. Each of the lifecycle phases can be managed by a certain role. To support the separation of roles and responsibilities and to clearly define these phases the RIB has adopted a specific directory structure. The tools required for each of these roles are provided within this directory structure.
This directory structure supports access permissions to different tools that are managed according to the site-specific business requirements. For example; a sysadmin can be given access permissions to all the tools while a ribadmin or appadmin can be provided access to only certain operation tools.
The RIB App Builder directory structure is fixed and is created by the RIB kernel tar file; RibKernel<release>ForAll<release>Apps_eng_ga.tar.
The rib-home is a controlled structure and there are very specific rules for using the tools and the key files with in it. A key rule is that the tools scan and check versions of all files within rib-home (except for tools-home). The processes do not allow files to have the same name with only an additional extension.
NOT ALLOWED: rib-rms.properties.bak
Example 2-1
rib-home
rib-installer.sh -- this is the RIB GUI Installer
.retail-installer -- this directory contains the RIB GUI installer file
application-assembly-home
bin
rib-app-compiler.sh
conf
log
rib-aip
rib-func-artifacts
rib-func-artifact.war
rib-private-tafr-business-impl.jar
rib-public-payload-database-object-types.zip
rib-public-payload-database-xml-library.zip
rib-public-payload-java-beans.jar
rib-public-payload-xml-samples.zip
rib-rms
rib-<app>-adapters-resources.properties
rib-<app>-adapters.xml
rib-<app>-plsql-api.xml
rib-<app>.properties
rib-rpm
rib-rwms
rib-sim
rib-tafr
deployment-home
bin
rib-app-deployer.sh
conf
rib-deployment-env-info.xml
log
download-home
all-rib-apps
all-rib-defect-fixes
bin
check-version-and-unpack.sh
log
rib-func-artifacts
integration-lib
internal-build
third-party
maintenance-home
bin
check-version-and-apply-defect-fix.sh
inventory-management.sh
history-repository
rib-inventory-info.xml
log
operation-home
bin
rib-adapter-controller.sh
log
tools-home
javaee-api-stubs
plsql-api-stubs
rdmt
rib-func-artifact-gen
riha
All RIB Application Builder tools use the rib-deployment-env-info.xml as the source of all values.
Each tool that has a log directory where the execution log is maintained (for example, rib-app-builder.compiler.log). These logs are maintained by log4j and the log4j.xml that is in rib-home. Do not edit this log4j.xml. It is set for DEBUG when the tools are executed by command line. When the RIB installer is used, it displays the logging at the console level as INFO, but the tools themselves write the logs at DEBUG.
The rib-app-builder tools will automatically generate a backup when a patch is installed. Additionally, it is recommended that each site develop a backup plan that includes a regular backup at the file system level of the rib-app-builder directory structure.
The rib-complier is the tool that drives the rib-<app>.ear creation process. It performs validation of the input xml files. There are four xml files are used to build the rib-<app>.ear. These input files are:
rib-<app>-adapters.xml,
rib-integration-flows.xml,
rib-application-assembly-info.xml
rib-deployment-env-info.xml.
The compiler tool generates the rib-<app> specific application level configuration files, and then collects all of the generated files and packages them to create a deployable rib-<app>.ear file.
This tool works against all applications in-scope in the rib-deployment-env-info.xml file.
This tool performs operations related to deploying the RIB components. It takes a command line set of arguments and values for each function. All functions are driven by the contents of the rib-deployment-env-info.xml.
Table 2-1 Command Line Options to rib-app-deployer
| Command Line Option | Description |
|---|---|
|
-prepare-jms |
Prepares the JMS server with RIB JMS topics using the information in rib-deployment-env-info.xml. The JMS server must be running. See Chapter 6, "JMS Provider Management" later in this guide. |
|
-deploy-rib-func-artifact-war |
Deploys the rib-func-artifact.war to the Java EE application server defined in rib-deployment-env-info.xml. The Java EE server must be running. |
|
-deploy-rib-app-ear rib-<app> |
Deploys the rib-<app>.ear to the Java EE application server defined in rib-deployment-env-info.xml. The Java EE server must be running. |
|
-update-remote-rib-app-config-files rib-<app> |
Updates the rib-<app> application level configuration files in the remote server where rib-<app>.ear is or will be deployed. The remote server information is defined in rib-deployment-env-info.xml. The Java EE server must be running. |
|
-undeploy-rib-func-artifact-war |
Undeploys the rib-func-artifact.war from the Java EE application server defined in rib-deployment-env-info.xml. The Java EE server must be running. |
|
-undeploy-rib-app-ear rib-<app> |
Undeploys the rib-<app> from the Java EE application server defined in rib-deployment-env-info.xml. The Java EE server must be running. |
This tool will verify the version compatibility between the RIB paks and extract the files if they are compatible. The extracted files are moved to the appropriate directories under the rib-home.
The version compatibility between RibKernel, RibFuncArtifact and RIBPaks is determined based on the naming conventions used in the tar files and the information that is present in the MANIFEST.mf file inside the kernel tar file.
The RIB infrastructure kernel, RIB functional Pak and RIB functional artifacts version naming convention should be same. All should have same number of major and minor versions.
How Verifications work:
The tool gets the version of the Rib kernel from the MANIFEST.MF file of the RIB kernel tar file. This is the RibKernel<RIB_MAJOR_VERSION>ForAll<RETAIL_APP_VERSION>Apps_eng_ga.tar.
The tool reads the functional artifact file from rib-home/download-home/ rib-func-artifacts.
The tool reads the list of all the RIB application packs from the -home/download-home/all-rib-apps directory is read.
The tool makes use of the naming convention to check if the kernel version is the same as the functional artifact version. If the version is compatible, the tar file is un-tar'd into the rib-home/application-assembly/ rib-func-artifacts directory.
The tool makes use of the naming convention to check if the kernel version is the same as the application packs. If the version is compatible, the tar file is un-tar'd into the rib-home/application-assembly/rib-<app> directory.
The RIB has been designed to centrally manage and track the application of defects. The check-version-and-apply-defect-fix tool is responsible for that activity.
All RIB defects come in the form of a zip file (for example, RIB13_HPQC1789.zip). The zip file always contains a README.txt file in the format below.
-----------------------------------------------------------
Product : Oracle Retail Integration Bus
Version # : 13.0.x
Defect # : 1789
Date : 02/27/2008
-----------------------------------------------------------
Defects Fixed by this patch:
-------------------------
Resolution:
-----------
Files included:
---------------
Defect Fix Install Instructions:--------------------------------
The README.txt file contains the specific instructions on the application of the defect. It is always applied to the rib-home and deployed from there. Depending on the type of defect it may be necessary to migrate a jar to one of the Oracle Retail applications into the appropriate directories.
All defects are applied to rib-home in the same manner.
Drop the Defect.zip into /rib-home/download-home/all-rib-defect-fixes directory.
Run the check-version-and-apply-defect-fix.sh from the /rib-home/maintenance-home/bin directory.
Run the rib-home/application-assembly-home/bin/rib-app-compiler.sh script from the rib-home/application-assembly-home/bin directory.
Run the rib-home/deployment-home/bin/rib-app-deployer.sh script from rib-home/deployment-home/bin directory to the appropriate rib-<app>s.
The tool check-version-and-apply-defect-fix.sh will perform version compatibility checks and will update the RIB inventory xml file.
The RIB jars and xml files in rib-home are tracked through an xml file called rib-inventory-info.xml located in the rib-home/maintenance-home/history-repository/ directory. This file is initially created when the RIB installer, or user, executes the check-version-and-unpack tool the first time to extract the RIB application packs and the functional artifacts. Thereafter this file is updated and tracks the file change history of the jars and xml files in the rib-home system.
Table 2-2 Command Line Options to inventory-management
| Command Line Option | Description |
|---|---|
|
-update-current-inventory |
Scans the rib-home file system and updates the inventory database. |
|
-generate-file-change-history-report |
Generates a report of how the files in the rib-home file system have changed over time. |
|
-generate-defect-fix-applied-report |
Generates a report of what defect fixes have been applied to rib-home on this system. |
|
-generate-defect-fix-detail <defect-fix-id> |
Displays the long defect resolution description for a given defect fix id. |
The rib-adapter-controller a set of tools that perform RIB adapter control functions such as start/stop and subscriber check, The command line options and usage are summarized here. See the section, "RIB Components Start and Stop", in this manual.
Starts all adapters in a message flow for a given family or family list (comma separated list without any space)
start integation-message-flows <family-name-list>[no-subscriber-check]
Description:
For a given family, it identifies all message flow ids that this family directly or indirectly participates in.
Using the message flow ids defined in the rib-integration-flows.xml, it connects to all application servers where the respective rib-apps are deployed.
It starts the adapters in the order as defined in the message flows.
It checks if durable subscribers exist before starting an adapter.
It ignores all rib apps that are not in scope.
Examples:
rib-adapter-controller.sh start integation-message-flows Alloc rib-adapter-controller.sh start integation-message-flows Alloc,Order
Stops all adapters in a message flow for a given family or family list (comma separated list without any space).
stop integation-message-flows <family-name-list>
Description:
For a given family it identifies all message flow ids that this family directly or indirectly participates in.
Using the message flow ids in the rib-integration-flows.xml, it connects to all application servers where the respective rib-apps are deployed.
It stops the adapters in the order as defined in the message flows.
It ignores all rib apps that are not in scope.
Examples:
rib-adapter-controller.sh stop integation-message-flows Alloc rib-adapter-controller.sh stop integation-message-flows Alloc,Order
Stops all adapters in a message flow for a given family or family list (comma separated list without any space).
list integation-message-flows <family-name-list>
Description:
It will display all message node ids for all message flows that are part of the given family.
It lists the adapters in the order as defined in the message flows.
It ignores all rib apps that are not in scope.
Examples:
rib-adapter-controller.sh list integation-message-flows Alloc rib-adapter-controller.sh list integation-message-flows Alloc,Order
Starts all adapters by type given a rib-app or rib-app-list (comma separated list without any space).
start rib-app-adapters-by-type <sub,tafr,pub,hosp_retry,all><rib-app-list> [no-subscriber-check]
Description:
For every adapter type specified in the input it collects the adapter instances from the given rib-app-list.
It reorders the input adapter types to start in the correct order.
It connects to the respective applications servers where rib-apps are deployed.
It starts the sub adapters first in all rib-apps, and then it moves on to start all the tafr adapters in all rib-apps and so on.
It checks if durable subscribers exist before starting an adapter.
It ignores all rib apps that are not in scope.
Examples:
rib-adapter-controller.sh start rib-app-adapters-by-type sub,tafr rib-rms rib-adapter-controller.sh start rib-app-adapters-by-type pub,sub rib-rms,rib-sim rib-adapter-controller.sh start rib-app-adapters-by-type all rib-rms,rib-sim
Stops all adapters by type given a rib-app or rib-app-list (comma separated list without any space).
stop rib-app-adapters-by-type <sub,tafr,pub,hosp_retry,all><rib-app-list>
Description:
For every adapter type specified in the input it collects the adapter instances from the given rib-app-list.
It connects to the respective applications servers where rib-apps are deployed.
It stops the first adapter type first in all rib-apps, and then it moves on to stop the second adapter types in all rib-apps and so on.
It ignores all rib apps that are not in scope.
Examples:
rib-adapter-controller.sh stop rib-app-adapters-by-type sub,tafr rib-rms,rib-sim rib-adapter-controller.sh stop rib-app-adapters-by-type pub,sub rib-adapter-controller.sh stop rib-app-adapters-by-type all rib-rms,rib-sim
Starts individual adapter instances. Adapter instance must be fully qualified as "rib-<app>.<Family>_<type>_<n>". A comma separated list of adapter instances names can also be provided.
start rib-app-adapter-instance <rib-app.Family_type_1-list>[no-subscriber-check]
Description:
Checks if durable subscribers exist before starting an adapter.
Starts the adapter instance.
Examples:
rib-adapter-controller.sh start rib-app-adapter-instance rib-rms.Alloc_pub_1 rib-adapter-controller.sh start rib-app-adapter-instance rib-rms.Alloc_pub_1,rib-sim.ASNIn_sub_1
Stops individual adapter instances. Adapter instances must be fully qualified as "rib-<app>.<Family>_<type>_<n>". A comma separated list of adapter instances names can also be provided.
stop rib-app-adapter-instance <rib-app.Family_type_1-list>
Description:
Stops the adapter instance.
Examples:
rib-adapter-controller.sh stop rib-app-adapter-instance rib-rms.Alloc_pub_1 rib-adapter-controller.sh stop rib-app-adapter-instance rib-rms.Alloc_pub_1,rib-sim.ASNIn_sub_1
Tests if durable subscriber exist for topics associated with a given adapter class def. Adapter class def must be fully qualified as "rib-<app>.<Family>_<type>". A comma separated list of adapter class def names can also be provided.
test durable-subscriber-exist-for-adapter-class-def <rib-app.Family_type-list>
Description:
Finds out the topic names the input rib app adapter class def publishes to.
For each topic it publishes to, it checks to see if there is a durable subscriber registered.
Examples:
rib-adapter-controller.sh test durable-subscriber-exist-for-adapter-class-def rib-rms.Alloc_pub rib-adapter-controller.sh test durable-subscriber-exist-for-adapter-class-def rib-rms.Alloc_pub,rib-tafr.ASNOutToASNOutAT_tafr
Tests if durable subscriber exist for all publishing topics associated with a given rib-app or rib-app-list (comma separated list without any spaces).
test durable-subscriber-exist-for-rib-app <rib-app-list>
Description:
Finds out all adapter instances that publish to a topic name for the given rib-app-list.
For each topic it publishes to, it checks to see if there is a durable subscriber registered.
Examples:
rib-adapter-controller.sh test durable-subscriber-exist-for-rib-app rib-rms rib-adapter-controller.sh test durable-subscriber-exist-for-rib-app rib-rms,rib-sim
Lists all adapter instance for a given rib-app or rib-app-list (comma separated list without any spaces).
list rib-app-adapters <rib-app-list>
Description:
Lists all adapters that are part of the rib-app.
Examples:
rib-adapter-controller.sh list rib-app-adapters rib-rms rib-adapter-controller.sh list rib-app-adapters rib-rms,rib-sim
Messages (business objects) that flow between the retail applications are XML messages. RIB XML message definitions are defined statically through XML schemas. The RIB works with multiple technologies (Java EE, PL/SQL) and so has different ways of representing the same functional RIB XML message structure in different technologies. To make it easier to maintain the various RIB functional artifacts, the RIB uses a code generator.
Each RIB message family and type combination maps to one and only one RIB functional message definition. One RIB functional message definition can map to one or more than one family/type combination within the same family.
The RIB functional artifacts are different representations of the same message structure/definition in different technologies (Java EE, PL/SQL). Depending upon the retail application's technology, RIB uses that appropriate artifacts, converting one from the other as needed. Following are the RIB functional object definitions.
The RIB Artifacts Generator is a collection of tools designed to create the various RIB artifacts from an XML Schema (XSD).
The functional XML message structure is a contract between the integrating retail applications and is defined by the RIB XML schemas. All the other RIB artifacts are generated from the XML schemas. RIB XML schemas are the inputs required by the artifact generators.
The Java EE Oracle Retail applications interface with the RIB through Castor Java Payloads. The RIB Castor Payloads are the java bean representation of the RIB XML message definition and are used by the JavaEE applications to create the business object and publish them to the other integrating retail applications through the RIB. The RIB Castor Payloads are generated from the RIB XML schema files.
The RIB Artifact Generator is packaged and shipped with the other RIB tools and must be installed and configured.
The rib-app-builder tool needs to be installed before performing this install. The tool will not work without this; all the paths that the tool refers to are relative to the rib-app-builder tool.
Download the tool tar file.
Place the file in the rib-home/tools-home directory (e.g. Rib1301ForAll13xxApps/rib-home/tools-home).
Untar the file using the following command:
tar -xvf ArtifactGenerator13.0.1ForAll13.x.xApps_eng_ga.tar
This will place the tools into the following directory:
rib-home/tools-home/rib-func-artifact-gen
Installation is now complete.
Run the following command from the rib-home/tools-home/rib-func-artifact-gen directory. This prints the usage for the tool.
rib-home/tools-home/rib-func-artifact-gen/rib-artifact-generator.sh
Usage: Func Artifact Generator
-h,--help print this message -i,--inDir <arg> input xsd directory -o,--outDir <arg> output artifact directory -ot,--outputType <arg> generated artifact type<java|sql|xml>
Example: java com.oracle.rib.artifacts.generator.cairo.Main --inDir rib-public-xsd/src/payload/xsd --outDir rib-public-payload-java-beans/src --outputType java
Example: java com.oracle.rib.artifacts.generator.cairo.Main --inDir rib-public-xsd/src/payload/xsd --outDir rib-public-payload-java-beans/src --outputType sql
Example: java com.oracle.rib.artifacts.generator.cairo.Main --inDir rib-public-xsd/src/payload/xsd --outDir rib-public-payload-java-beans/src --outputType xml
| Parameter | Explanation | Description |
|---|---|---|
|
-i, --inDir |
Input XSD Dir |
This is the location of the XSD directory; all XSDs whose artifacts are being generated should be placed in the following directory. |
|
-o, --outDir |
Output Artifact Dir |
The artifacts will be generated in the following directory. |
|
-ot, --outputType |
Type of artifact being generated |
Valid values are java, sql or xml. Java refers to Castor Java objects, sql refers to Oracle Objects, and xml refers to Sample XML files. |
|
Note: All the schemas (XSDs) built should conform to the Meta schema IntegrationMetaSchema.xsd. The artifact generator tools check if the schema is valid before generating any artifacts. If the schema is not compliant with the IntegrationXmlMetaSchema, then the artifact generator fails. This file can be found in the conf directory of rib-home/tools-home/rib-func-artifact-gen directory. |
Run the following command to generate castor objects:
<RIB_HOME>/ tools-home/rib-func-artifact-gen/rib-artifact-generator.sh --inDir <xsd-dir> --outDir <art-dir> --outType java
