| Oracle® Retail Integration Bus Operations Guide Release 13.0.4 |
|
 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.
For example, rib-rms.properties.bak is not allowed.
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.
| 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 verifies the version compatibility between the RIB packs and extracts 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 pack and RIB functional artifacts version naming convention should be same. All should have the 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-tarred 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.
| 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"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 displays 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
The RIB Artifacts Generator is a collection of tools designed to create the various RIB artifacts from an XML Schema (XSD).
Messages (business objects) that flow between the retail applications are XML messages. RIB XML message definitions are defined statically through XML schemas. The integration infrastructure works with multiple technologies (Java EE, PL/SQL), so it has different ways of representing the same functional 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 on the retail application's technology, RIB uses the appropriate artifacts, converting one from the other as needed. Following are the RIB functional object definitions.
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.
JAXB is a standard Java SML binding technology. It provides the mechanism to convert SML instances to java objects—and java objects to SML instances—in a standardard way. The Java EE Web Service infrastructure internally uses JAXB to marshall and unmarshall the SOAP messages. For every payload XSD, the artifact generator generates the corresponding JAXB beans.
The RIB Artifact Generator can be installed and run in the following ways:
As a stand-alone application.
As an application inside rib-home.
This section describes the conditions under which installation can take place, including environment variables.
Be sure the JAVA_HOME environment variable is set for the user who performs the setup task: Run the command echo $JAVA_HOME and check that the JAVA_HOME is set to /usr/bin/java/jdk1.5.0_09. If it is not set correctly, run the following command to set the right path: export JAVA_HOME=/usr/bin/java/jdk1.5.0_09.
Determine the host and file system on which to create the Artifact Generator home directory (for example, mkdir ArtifactGeneratorStandalone).
Be sure the JAVA_HOME environment variable is set for the user who will perform the setup task: Run the command echo $JAVA_HOME and check that the JAVA_HOME is set to /usr/bin/java/jdk1.5.0_09. If it is not set correctly, run the following command to set the right path: export JAVA_HOME=/usr/bin/java/jdk1.5.0_09.
This section describes the steps required to install and set up the Artifact Generator tool.
Download and extract the Artifact Generator to the Artifact Generator home directory:
cd Artifact Generator Standalone
tar -xvf ArtifactGeneratorStandalone13.0.4ForAll13.x.x_eng_ga.tar
Make Groovy executable.
cd rib-func-artifact-gen
chmod 711 ./integration-lib/third-party/groovy/1.5.6/bin/groovy
Set Groovy path:
export GROOVY_HOME= pwd/integration-lib/third-party/groovy/1.5.6
Download RibFuncArtifactX.X.XForAllX.X.XApps_eng-ga and place it in ./base-func-artifacts. DO NOT untar it.
Execute the setup script.
$GROOVY_HOME/bin/groovy SetupWorkArea.groovy
Run the Artifact Generator to verify installation. All subdirectories and artifacts should be created without errors.
$GROOVY_HOME/bin/groovy GenArtifacts.groovy
|
Note: Upon completion of Step 6 above, installation is complete. All appropriate output subdirectors are available, and the input-xsds subdirectory contain the required schemas. |
Download and extract the Artifact Generator to the tools-home directory of rib-home:
cd ../rib-home/tools-home
tar -xvf ArtifactGeneratorStandalone13.0.4ForAll13.x.x_eng_ga.tar
Make Groovy executable.
cd rib-func-artifact-gen
chmod 711 ./integration-lib/third-party/groovy/1.5.6/bin/groovy
Set Groovy path:
export GROOVY_HOME= pwd/integration-lib/third-party/groovy/1.5.6
Execute the setup script.
$GROOVY_HOME/bin/groovy SetupWorkArea.groovy
Make Groovy executable.
cd ../rib-home
chmod 711 ./integration-lib/third-party/groovy/1.5.6/bin/groovy
Set Groovy path:
export GROOVY_HOME= pwd/integration-lib/third-party/groovy/1.5.6
Run the Artifact Generator to verify installation. All subdirectories and artifacts should be created without errors.
cd tools-home/ rib-func-artifact-gen
$GROOVY_HOME/bin/groovy GenArtifacts.groovy
|
Note: Upon completion of Step 7 above, installation is complete. All appropriate output subdirectors are available, and the input-xsds subdirectory contain the required schemas. |
The source for all Artifact Generator tools is defined by the XML schemas. All other artifacts are generated from XML schemas. As a result of installation, a directory structure is created to contain the libraries (integration.lib) and input artifacts (base-func-artifacts/rib-func-artifacts) required to generate all support output types. For example:
./base-func-artifacts |--------------- rib-func-artifactsretail-public-bo-java-beans.jarrib-custom-tafr-business-impl.jarrib-func-artifact.warrib-private-tafr-business-impl.jar rib-public-payload-database-object-types.ziprib-public-payload-database-xml-library.ziprib-public-payload-java-beans.jarrib-public-payload-xml-samples.zip
An output directory exists for each type of artifact produced. For example:
./output-database-object-types |----------- src |---- ASNInDesc.sql |----------- dist |---- rib-public-payload-database-object-types.zip
./output-jaxb-java-beans |----------- src |---- com/oracle/retail/integration/payload/asnindesc |----- ASNInDesc.java… ObjectFactory.java package-info.java |----------- dist |---- retail-public-bo-java-beans.jar
./output-castor-java-beans |----------- src//com/retek/rib/binding/payload |---- ASNInDescDescriptor.java ASNInDesc.java |----------- dist |---- rib-public-payload-java-beans.jar
./output-xml-samples |----------- src |---- ASNInDesc.xml |----------- dist |---- rib-public-payload-xml-samples.zip
All artifacts are generated by the same command:
$GROOVY_HOME/bin/groovy GenArtifacts.groovy
|
Note: All schemas should conform to the Meta schema, IntegrationMetaSchema.xsd. The artifact generator tools check the validity of the schema before generating any artifacts. If the schema is not compliant with the IntegrationXmlMetaSchema, the artifact generator fails. The error file can be found in the conf directory of the rib-func-artifact-gen directory. |
Edit the payload XSDs in ./input-xsd.
cd input-xsd
vi ASNInDesc.xsd (make changes)
Run the Artifact Generator.
$GROOVY_HOME/bin/groovy GenArtifacts.groovy
|
Note: Upon completion of Step 2 above, each generated artifact is in the appropriate ./output*/dist folder. |
The following HTML reports can be used to verify the successful installation of RIB hot fixes:
defect-fix-applied-report.html
file-change-history-report.html
defect-fix-detail-<defect-fix-id>.html
These reports are available at rib-home/maintenance-home/history-repository/HTML-Report.
|
 Copyright © 2010, Oracle and/or its affiliates. All rights reserved. Legal Notices |
|
