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 "Pre-Implementation Considerations" in the Oracle RIB Integration Bus Implementation Guide.

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.

The following is not allowed: rib-rms.properties.bak

Directory Structure and Key Files

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
               setup-security-credential.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.

Surrounding text describes RIB%20Config%20Tools%20perspectives.png.

Logging

Logging is done for each tool with 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 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 automatically generate a backup when a patch is installed. It is recommended that each site develop a backup plan to include a regular backup at the file system level of the rib-app-builder directory structure.

rib-app-compiler

The rib-compiler is a tool that drives the rib-<app>.ear creation process. It performs validation of the input XML files. The following XML files are used to build the rib-<app>.ear.

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, collects the generated files, and packages them to create a deployable rib-<app>.ear file.

This tool works with all applications in scope in the rib-deployment-env-info.xml file.

Command Line Option	Description
-setup-security-credential	This argument must be used when running the rib-app-compiler for the first time. It prompts the user to enter user names and passwords required to install RIB components. It stores the details as credentials in a wallet file inside the rib-home/deployement-home/conf/security/ directory. The credentials are retrieved and used by the deployer when installing RIB components.

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.

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 7, "JMS Provider Management."
-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 verifies the version compatibility between the RIB paks and extract the files. 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 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 the same. All should have the same number of major and minor versions.

For verification, the tool does the following:

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.
Reads the functional artifact file from rib-home/download-home/ rib-func-artifacts.
Reads the list of all the RIB application packs from the -home/download-home/all-rib-apps directory.
Uses 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.
Uses 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.2.x
    Defect #    : 1789
    Date                 : 02/27/2010
-----------------------------------------------------------

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.

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.

setup-security-credential

The user names and passwords required to install RIB components are stored as security credentials in a wallet file located in the rib-home/deployment-home/conf/security/ directory. The file is initially created when the RIB installer, or user, executes the rib-app-compiler tool with the setup-security-credential argument the first time and enters all the user names and passwords required for installing RIB components. Thereafter, this file can be modified using the setup-security-credential script located in rib-home/maintenance-home/bin directory. After updating existing credentials, the user must run the rib-app-compiler tool again and redeploy the rib apps to use the new credentials.

Command Line Option	Description
-setup-aq-credential <aq-id>	Updates the security credential for the AQ JMS Server ID specified in rib-deployment-env-info.xml
-setup-weblogic-credential<wls-id>	Updates security credential for the specified WebLogic instance.
-setup-admin-gui-credential rib-<app>	Updates security credential for the RIB Admin GUI user for the specified RIB App.
-setup-error-hospital-credential rib-<app>	Updates security credential for the error hospital database user for the specified RIB App.
-setup-app-database-credential rib-<app>	Updates security credential for the application database for the specified RIB App.
-setup-jndi-credential rib-<app>	Updates security credential for the remote JNDI for the specified RIB App.

Hot Fix Installation Reports

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.

Sample: file-change-history-report

Surrounding text describes file_change_history_report.png.

Sample: defect-fix-detail-<defect-fix-id>

Surrounding text describes defect_fix_applied_report.png.

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 "RIB Components Start and Stop."

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 in which this family directly or indirectly participates.
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 in which this family directly or indirectly participates.
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

List Flow

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

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

RIB Deployment Configuration File Editor

The RIB Deployment Configuration File Editor is an application used to configure the rib-deployment-env-info.xml file, following installation. The editor tool simplifies user interaction with the XML file by hiding the raw text form of XML. It provides a user interface for adding, removing, and rearranging the elements of the RIB configuration.

Note:

See the "RIB App Builder Tools" in this chapter and "rib-deployment-env-info.xml" in Chapter 3, "Backend System Administration and Logging."

The tool is located in the RDMT package and installed with RDMT in the <rib-home>/tools-home/RDMT directory. It is available as a menu selection from the ribadmin sub menu. See Chapter 9, "Diagnostic and Monitoring Tools."

Note:

The editor is a GUI application. To execute it on a host other than the one on which RDMT is installed, use an X server, such as Exceed, and set the DISPLAY environment.

Important Installation Warning

All rib-app-builder tools use the rib-deployment-env-info.xml as the single source of truth about the deployment configuration. See "RIB Deployment Configuration File Editor" in Chapter 3, "Backend System Administration and Logging."

All tools use the values in this file. Editing the file directly affects the compilation, configuration, and deployment of the rib-apps. Use extreme caution and understand the ramification of the values being manipulated.

Note:

See the Oracle RIB Integration Bus Implementation Guide.

Before editing the source file in rib-home, make a backup of the file and place it securely outside of rib-home. Do not create a backup in the rib-home.

Key Rule

The rib-app-builder 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.

Editor Usage

The following is an illustration of the editor interface.

Note:

See the online help provided in the tool for additional details.

Surrounding text describes file_editor.png.

The RIB Deployment Configuration File Editor allows users to do the following:

Add, delete and move applications.
Add, delete and move WebLogic instances.

Add and delete Application Server instances.
Configure JMS servers.

To edit files using the editor, do the following:

Select File from the menu bar. Click Open.
Navigate to the directory containing rib-deployment-env-info.xml.
Select the file and open it.
Complete the required task (for example, add, delete, or move).
Save the file using the File menu.