2 Application Builder

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.

Note:

See RIB Implementation Guide - Pre-Implementation Considerations

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.

RIB Application Builder Directory Structure

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

Directory Structure and Key Files

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.xmlrib-<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            bincheck-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

RIB App Builder Tools

All RIB Application Builder tools use the rib-deployment-env-info.xml as the source of all values.

Logging

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.

Backup and Archive of Key Files

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.

rib-app-compiler

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.

rib-app-deployer

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.

Check-version-and-unpack

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.

check-version-and-apply-defect-fix

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.

inventory-management

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.

rib-adapter-controller

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.

Start Flow

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

Stop Flow

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

Start Adapters By Type

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

Stop Adapters by Type

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

Start Adapter

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

Stop Adapter

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

Test Durable Subscriber for Adapter

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

Test Durable Subscriber for RIB App

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

List RIB App Adapters

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