Overview  Package  Class  Tree  Deprecated  Index  Help 
 PREV   NEXT FRAMES    NO FRAMES    

Java Toolbox Oracle Fusion Middleware Utilities Module - API Documentation

Java Toolbox Module to provide utilities and functions that can be used with Oracle Fusion Middleware.

See:
          Description

Packages
toolbox.oracle.fault.management Provides implementations of the oracle provided oracle.integration.platform.faultpolicy.IFaultRecoveryJavaClass interface to extend the default fault management capabilities of Oracle SOA Suite.
toolbox.oracle.fault.management.client Provides interfaces and classes to test FaultDistributionService implementations and output templates.
toolbox.oracle.fault.management.services Provides common interfaces and classes to build custom fault distribution implementations.
toolbox.oracle.osb.config Provides an API for importing and exporting projects, folders and resources to and from Oracle Service Bus.
toolbox.oracle.osb.config.client Provides a command line client to invoke the OSBConfigUtil class.
toolbox.oracle.siebel.session Provides an API to manage stateless Oracle Siebel authentication tokens.
toolbox.oracle.siebel.session.beans Provides simple Java Bean style classes to store siebel session tokens.
toolbox.oracle.siebel.session.client Provides a test client to facilitate simple testing against live Siebel environments.
toolbox.oracle.siebel.session.services Provides a high level service style API to simplify the use of stateless Oracle Siebel authentication tokens.
toolbox.oracle.siebel.session.services.support Support classes required by the service API.
toolbox.oracle.xpath.ext Provides XPath extension functions that can be used with the Oracle XSLT Mapper and the Oracle BPEL and Oracle Mediator service engines.
toolbox.oracle.xpath.ext.helper Provides classes that support various XPath function implementations.

 

Java Toolbox Module to provide utilities and functions that can be used with Oracle Fusion Middleware.

Technical Reference

The functionality provided by this module is currently divided into following:

General Requirements and Instructions

This section document the general requirements that must be met to use either of the functional areas.

Software Requirements

NOTE: This document assumes that Oracle SOA Suite, Oracle OSB and JDeveloper are installed and configured correctly.

Additional Software Requirements

The following provides the additional software required by the Fault Management and Siebel Authentication Token functionality of this module:

Sofware (The Java Toolbox Installation Guide provides download locations for all the software listed here):

Environment Variables: The following is an example of my current Unix environment configuration: 
      TOOLBOX_HOME=/opt/frameworks/toolbox
      TOOLBOX_FM_HOME=/opt/misc/freemarker
      TOOLBOX_CXF_HOME=/opt/asf/cxf27
      TOOLBOX_XMLBEANS_HOME=/opt/asf/xmlbeans
      TOOLBOX_COMMONS_HTTPCLIENT_HOME=/opt/asf/commons-httpclient
      TOOLBOX_COMMONS_LOGGING_HOME=/opt/asf/commons-logging
      TOOLBOX_COMMONS_CODEC_HOME=/opt/asf/commons-codec

Installation Instructions

The following is an example of my current Unix installation: 
      toolbox distribution:
      /opt/frameworks/toolbox
  
      module distribution:
      /opt/frameworks/tbmodules/toolbox_oracle_fmw_util
At this stage nothing more is required from an installation perspective. Configuration details specific to each functional area will be discussed later.

XPath Extension Functions

All XPath extension functions are implemented in the toolbox.oracle.xpath.ext package. Instructions for configuring and using the functions in design time an run time is provided in the package summary document.

Fault Management

The primary goal of the fault management functionality provided by this module is to promote the visibility of faults that occur during message processing in Oracle SOA Suite Composites.

Oracle SOA Suite provides a very comprehensive policy based Fault Management Framework that make it possible to declaratively handle business and technical faults in a consistent way. This goes a long way towards protecting solution implementations from coding for exceptional cases such as unplanned system outages.

The links below provide more information about the Oracle SOA Suite Fault Management Framework when used in conjunction with specific service engines:

What the Oracle framework does not provide is a mechanism to make the occurrence of a fault visible to a broader audience during the recovery process (unless you would like to sit and stare at the Enterprise Manager Console all day). This module augments the out of the box functionality provided by Oracle SOA Suite by providing an extensible fault distribution capability.

The fault distribution functionality is implemented in the following API packages:

Let's walk through an example to demonstrate what can be achieved with the FaultDistributionHandler and a FaultDistributionService implementation when incorporated into an Oracle Fault Policy that is attached to a Composite.

The image below shows the interaction between the Composite, the Oracle Fault Management Framework and the Fault Distribution components of this module:

The following describes the possible flow of a fault through the Oracle Fault Management Framework when configured to use the the Fault Distribution components of this module (Use the image above as reference):

  1. A fault occurs in the Composite and is intercepted by the Oracle Fault Management Framework.

  2. The Oracle Fault Policy evaluates the fault against the set of policy conditions.

  3. If the fault can be retried the policy directs the fault to the Toolbox Retry Notify Action i.e it invokes the handleFault() method of the FaultDistributionHandler instance.

  4. The Retry Notify Action performs two steps. 1) Invokes the FaultDistributionService and 2) directs the fault to the Oracle Retry Action.

    The FaultDistributionService formats the fault data and distributes it to the target system where end users can be made aware of the fault and take further action.

    The Oracle Retry Action starts the automated recovery process based on the configured retry parameters.


  5. If the Oracle Retry Action succeeds at any point, the policy directs the fault back to the Toolbox Retry Notify Action. But this time the handleRetrySuccess() method of the FaultDistributionHandler instance is invoked.

    At this point the Retry Notify Action invokes the FaultDistributionService again, which in turn formats the fault data and distributes it to the target system where end users can be made aware that the fault had been recovered successfully.


  6. If the Oracle Retry Action fails to recover the fault, the policy directs the fault to the Toolbox Manual Notify Action i.e it invokes the handleFault() method of the FaultDistributionHandler instance.

  7. The Manual Notify Action performs two steps. 1) Invokes the FaultDistributionService and 2) directs the fault to the Oracle Human Intervention Action.

    The FaultDistributionService formats the fault data and distributes it to the target system where end users can be made aware that a fault occurred that cannot be recovered without intervention.

    The Oracle Human Intervention Action marks the fault for manual recovery.


  8. If the initial fault cannot be retried, the policy directs the fault to the Toolbox Manual Notify Action and the steps described in point 7 above is repeated.

  9. If the fault cannot be handled by any policy action, it is directed back to the Composite using the Oracle Rethrow Fault Action.

Installation and Configuration

Additional installation and configuration steps are required before we can start making use of the fault management functionality provided by the module.

Testing Note 

         It is possible to test output templates in design time before 
         deployment to SOA Suite. To facilitate testing you must complete all 
         the configuration steps in this section, excluding the 
         SOA Suite Run Time Configuration, in the design time 
         environment.

Installation

Complete section 1 and 2 of the Java Toolbox Installation Guide with the software requirements and environment variables as documented in the Additional Software Requirements section of this document.

Configuration

NOTE:I have employed absolute paths in this section to simplify the instructions. Adjust this to fit your own environment.

All FaultDistributionService implementations are developed as Java Toolbox Services and require the following configuration files and Java System Properties to load successfully:

And finally. The FaultDistributionService implementations try to locate output templates in one of two directories. The first directory is located in the module distribution directory at etc/templates, the second directory is configurable using the toolbox_ora_fmw_util_fds_template_dir configuration property in the /opt/local/etc/toolbox_apps.properties file that was created earlier.

Create a directory in a suitable location for the purpose of storing your own output templates and update the configuration property accordingly.

SOA Suite Run Time Configuration

We have to ensure that the Oracle SOA Suite run time is able to load all the relevent Java classes. These instructions assume that Oracle SOA Suite is hosted on Oracle WebLogic Server and that the following holds true:

Perform the following from a command shell to make the fault management classes available to the Oracle SOA Suite run time.

Implementation

This section will cover the basic steps required to implement the fault distribution components of this module in your own SOA Suite projects.

The following provides the high level steps required to complete implementation:

  1. Decide which FaultDistributionService implementation you are going to use to distribute faults. At present the module only provides an HTTP based implementation.

  2. Create an Oracle Fault Policy to cater for all faults you want the Oracle Fault Management Framework to handle. An example Fault Policy, that implements the fault flow we discussed earlier, is available in the share/oracle_policies directory of the module distribution.

  3. Create an output template to transform the fault data into the format expected by the target system i.e the system on the other end of the FaultDistributionService. An example template is provided in the etc/templates directory of the module distribution. This template also provides insight into available fault information. Remember to place your own templates in the custom template directory you configured earlier.

  4. Test your output template using the tools provided in the bin directory of the module distribution.

    The following is an example of how to execute a test with the default test data and template provided with the module:

    Update the /opt/local/etc/toolbox_apps.properties with the name of your own output template and execute the fault_dist_client.sh script again. You should see the output from your own template.

  5. At this stage you can also inject the fault information directly into the target system. Update the HTTP properties in the /opt/local/etc/toolbox_apps.properties to reflect your own environment and execute the fault_dist_client.sh script. The fault information should show up in the target system.

  6. You should now be ready to implement your output template and Fault Policy on the run time environment by completing the following steps:

Authentication Token Pool for Oracle Siebel

The token pool implementation provided, is based on the algorithm documented in Oracle Support Article[ID 795552.1]. This implementation also adds support for time based token expiration in addition to the simple counter based approach documented by Oracle.

The problem as described in the Oracle Support Article[ID 795552.1]: 

             "When a middleware is used to send a high number of concurrent web 
             service requests to siebel under the same USER_ID, the usual log 
             in - process single request - logout model is too expensive.

             If using database authentication, contention may occur while 
             logging in at the database and eventually requests are serviced 
             in delay or even rejectd.

             This article suggests the use of Siebel Authorization Stateless 
             Session Management to reduce the impact of the log in process by 
             sending one log in request, followed by several SOAP requests to 
             process data and finally one log off request.

             This shall drive improved performance and prevent requests from 
             being rejected."

More information about Oracle Siebel authentication tokens can be obtained from About Siebel Authentication and Session Management SOAP Headers.

The token pool functionality provided by this module provides a reusable API and service to pool and manage Oracle Siebel authentication tokens.

Installation and Configuration

Installation

Complete section 1 and 2 of the Java Toolbox Installation Guide with the software requirements and environment variables as documented in the Additional Software Requirements section of this document.

Configuration

NOTE:I have employed absolute paths in this section to simplify the instructions. Adjust this to fit your own environment.

The SiebelSessionTokenService is implementated as as Java Toolbox Service and require the following configuration files and Java System Properties to load successfully:

Token Pool Configuration

This section provides information on configuring Token Pool instances to facilitate authentication against Oracle Siebel. The pool configuration is stored in an XML configuration file. An example can be found in the etc/siebel_session_env.xml file in the module distribution.

The configuration document is structured around two top level XML elements:

1. SiebelConfig
Each SiebelConfig element instance contains the configuration required to establish an authentication token against Oracle Siebel. The following table provides a description of the element:

Element (E)/Attribute (A) Description Property (toolbox_apps.properties)
name (A) A name to uniquely identify this SiebelConfig element inside the configuration document N/A
Protocol (E) The protocol that must be used to communicate to Oracle Siebel. Valid values: http | https N/A
Host (E) The name of Oracle Siebel SWE host. toolbox_ora_fmw_util_sbl_host
Port (E) The port number where Oracle Siebel SWE accepts connections. toolbox_ora_fmw_util_sbl_port
Uri (E) A valid URI to access Oracle Siebel SWE. This will typically be something like /eai_enu/start.swe?SWEExtSource=WebService&SWEExtCmd=Execute&WSSOAP=1 toolbox_ora_fmw_util_sbl_uri
ContentType (E) The content header that must be used. Default: text/xml;charset=UTF-8 N/A
SOAPAction (E) The value of the SOAPAction header. toolbox_ora_fmw_util_sbl_soap_action
Namespace (E) The XML namespace of the Oracle Siebel authentication header. Default: http://siebel.com/webservices N/A
HeaderElement (E) The name of the XML header elemen that contains the authentication token value. Default: SessionToken N/A
CreateEnvelope (E) A SOAP envelope that must be sent to Oracle Siebel to establish the authentication token. Ask your Siebel representative for a lightweight web service call that can be performed. N/A
DestroyEnvelope (E) A SOAP envelope that must be sent to Oracle Siebel to destroy a specific authentication token. N/A

2. ResourcePool
Each ResourcePool element instance defines a single pool of Oracle Siebel authentication tokens. Each ResourcePool element must be associated with one SiebelConfig element using ConfigName element. The following table provides a description of the element:

Element (E)/Attribute (A) Description
name (A) A name to uniquely identify this ResourcePool element inside the configuration document. This is also the value that must be used from the API/service to indicate which pool must be used to obtain a token.
MaxSize (E) The maximum number of tokens this pool is allowed to token.
InitialSize (E) The initial number of tokens that must be create when this pool is first accessed.
Custom/ConfigName (E) The name of a SiebelConfig element instance that must be used to establish a connection to Oracle Siebel.
Custom/Delay (E) The delay in milliseconds that must be applied before a newly created token can be made available to a client.
Custom/TokenCounterMax (E) The maximum number of times a specific token can be used before it is destroyed an recreated.
Custom/TimeToLive (E) The duration (in seconds) that this token will remain valid before being destroyed and recreated.

NOTE: These two elements can be repeated any number of times to establish multiple pools to a single or multiple Siebel environments using different user/password combinations.
NOTE: You can control the location of your own siebel_session_env.xml configuration file using the toolbox_ora_fmw_util_sbl_conf_home configuration property in the toolbox_apps.properties file.

Deployment

This section provides the steps required to deploy and use the token pool functionality. Two deployment options currently exist:

WebLogic Deployment

This section provides the steps required to deploy the web service component to Oracle WebLogic Server.

NOTE:Restart WebLogic Server, if you haven't done so, to ensure the new JAVA_OPTIONS environment variable is available.

Use the following steps to deploy the toolbox_siebel_session_service_app.ear archive to WebLogic Server:

  1. Prepare the relevant WebLogic Shared Libraries by doing the following: 
               cd $TOOLBOX_HOME/share/weblogic
           ant toolbox-core toolbox-apache-commons cxf26
  2. Deploy the 3 WAR files in the $TOOLBOX_HOME/share/weblogic/dist directory as LIBRARIES to WebLogic Server.
  3. Extract the toolbox_siebel_session_service_app.ear in a directory of your choice e.g: 
               cd /u02/app/oracle/admin/applications
           mkdir toolbox_siebel_session_service_app
           cd toolbox_siebel_session_service_app
           jar xfv <module distribution>/war/toolbox_siebel_session_service_app.ear
  4. Deploy the toolbox_siebel_session_service_app open directory as an APPLICATION to WebLogic Server.
The WSDL document for the web service should be available at: http://<server>:<port>/toolbox_siebel_session_service/ws/SiebelSessionTokenService?wsdl

Oracle SOA Suite Runtime Deployment

This section provides the steps required to deploy the token functionality to the soa-infra application to enable use of the API from an embedded Java activity.

We have to ensure that the Oracle SOA Suite run time is able to load all the relevent Java classes. These instructions assume that Oracle SOA Suite is hosted on Oracle WebLogic Server and that the following holds true:

Perform the following from a command shell to make the token pool classes available to the Oracle SOA Suite run time.

Oracle Service Bus Configuration Utility

The Oracle Service Bus (OSB) Console provides an intuitvie and powerful interface to manage messaging and mediation resources. In larger projects the movement of the configuration data between environments can become a tedious and error prone task. In these larger projects, programmatic or scripted interfaces provide a more consistent and repeatable mechanism to manage the movement of configuration data between environments.

This configuration utility provides a number of interfaces to import, export and customise OSB configuration data as it moves through the software development lifecycle.

Instructions for setting up and using the utility is provided in the utility's API package summary.

 Overview  Package  Class  Tree  Deprecated  Index  Help 
 PREV   NEXT FRAMES    NO FRAMES