Skip Headers
Oracle® Fusion Middleware Administrator's Guide for Oracle SOA Suite and Oracle Business Process Management Suite
11g Release 1 (11.1.1.4.0)

Part Number E10226-07
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Master Index
Master Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
View PDF

10 Programmatically Managing SOA Composite Applications

This chapter provides an overview of the Facades API for programmatically managing SOA composite applications.

This chapter includes the following topics:

10.1 Introduction to Programmatically Managing SOA Composite Applications

You can programmatically manage your SOA composite applications during runtime with the Facades API. The Facades API is part of Oracle SOA Suite's Infrastructure Management Java API. The Facades API exposes operations and attributes of composites, components, services, references and so on. The Facades API provides an alternative to managing composites with Oracle Enterprise Manager Fusion Middleware Control.

The oracle.soa.management.facade.Locator interface exposes a method interface as an entry point for Facades API clients.

For more information about the Facades API, see Oracle Fusion Middleware Infrastructure Management Java API Reference for Oracle SOA Suite.

Note:

The Infrastructure Management Java API also includes the direct binding invocation API for inbound invocation of SOA composite applications and outbound invocations of Oracle Service Bus (OSB) or another SOA composite application. For information on using the direct binding invocation API, see Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite.

10.2 Facades API Interfaces

Table 10-1 provides an overview of the Facades API interfaces.

Table 10-1 Facades API Interfaces

Interface Description

ActivityInstance

Retrieves the instance ID (key) of the instance to which this activity belongs, the component name, the creation date of the activity, the expiration date of the current activity, and so on.

AsynchronousJob

Retrieves details about asynchronous job types.

AsynchronousResult

Retrieves the results of asynchronous processes.

Binding

Retrieves binding details such as URI, type, and subtype.

BindingComponent

Retrieves the binding type and the list of faults specified by the given fault filter.

BusinessEventInfo

Retrieves business event details such as the consistency level, filter type, local name, namespace URI, and prefix.

Component

Retrieves component details such as distinguished name (DN); active, faulted, and total instances; deployment time; and so on.

ComponentInstance

Retrieves component instance details such as the audit trail, component instance state (for example, successfully completed, faulted, or running), conversation ID, creation date, and so on).

Composite

Retrieves composite details such as the distinguished name (DN); active, faulted, and total instances; deployment time; and so on.

CompositeInstance

Retrieves the composite instance state (for example, successfully completed, faulted, running, and so on).

EventBridge

Retrieves the event bridge type and the list of faults specified by the given fault filter.

Fault

Retrieves fault details such as the binding type if the fault occurred in a binding component, the component instance ID, the name of the component in which the fault occurred, the time at which the fault was generated, the engine type if the fault occurred in a service engine, and so on.

FaultRecoveryActionTypeConstants

Provides action types such as terminating instances, marking a faulted activity as complete, storing the rejected message in a file, marking a faulted activity to be recovered, retrying an activity, and so on.

FaultRecoveryResult

Retrieves faults, errors, recoverable faults, nonrecoverable faults, and so on.

FaultRecoveryServiceEngine

Provides the fault recovery service engine.

ImportInfo

Retrieves the location of the imported resource and the import type.

InterfaceType

Retrieves the callback interface and interface properties.

Locator

Exposes a method interface as an entry point for Facades API clients.

Message

Retrieves message details such as the component name, composite DN, content of the message, conversation ID, message storage location, message recoverable state, and so on.

Partition

Performs partitioning lifecycle management tasks such as starting, stopping, activating, and retiring all the composites in a partition.

Property

Retrieves property details such as the default value, name, override attribute value of the property, property value source, and so on.

Reference

Retrieves reference details such as the WSDL URL for the target service, properties for the reference, reference name, reference bindings, and so on.

ReferenceInstance

Retrieves the type of the binding. DN of the composite, composite instance ID, time of instance creation, and so on.

ServerManager

Gets and creates partitions.

Service

Retrieves service details such as bindings, composite DN, interface type, name, multiplicity, and so on.

ServiceEngine

Retrieves the list of deployed components in the service engine, engine type, and list of faults specified by the given fault filter.

ServiceInstance

Retrieves service instance details such as the type of the binding. DN of the composite, composite instance ID, time of creation, and so on.

WebServiceBinding

Retrieves the default address URI, endpoint address URI, port, transport type, and so on.

WebServiceBindingPort

Retrieves the port name, port URI, service name, and so on.

WireInfo

Retrieves the wire reference, wire service, source URI, and target URI.

WSDLInterfaceBinding

Retrieves the WSDL URL.


10.3 Facades API Examples

This section provides several examples of using the Facades API to perform composite management.

10.3.1 Retrieving the State of a Composite

You can retrieve the state of a composite with the Facades API.

There are two parts to the state of a composite:

  • active | retired:

    This setting decides whether new instances can be created (active) or old ones are allowed to finish without new ones being allowed to be created (retired). This is referred to as composite mode.

  • on | off:

    This setting is the composite state and overrides the active or retired composite modes in either allowing call access (invoke/callback) to the composite revision (on) or not allowing call access (off). This is referred to as composite state.

From oracle.soa.management.facade.Locator, use the following code:

getComposite(CompositeDN)

This gets you to the composite (an implementation of oracle.soa.management.facade.Composite).

To retrieve the mode and the state, use the API and the implementation:

System.out.println("Mode: " + composite.getMode() + " state: " + 

   ((oracle.soa.management.internal.facade.CompositeImpl)composite).getState());

This action returns data similar to the following:

Mode: active state: on

10.3.2 Finding Instances

You can find instances with the Facades API.

Use the Locator interface to find a Composite (locator.lookupComposite(compositeDN);), and invoke it through a DeliveryService.

Then use the API to find its instances and get information (for example, the instance ID, which components were executed, and so on)

Composite composite = 
                locator.lookupComposite("default/OrderBookingComposite!1.0");
        /*
         * retrieve instances, we are already on a composite, no need to set the
         * DN
         */
        CompositeInstanceFilter filter = new CompositeInstanceFilter();
            filter.setMinCreationDate(
                new java.util.Date((System.currentTimeMillis() - 20000)));
// get composite instances by filter ..
List obInstances = composite.getInstances(filter);
// for each of the returned composite instances..
for (CompositeInstance instance : obInstances)
{
System.out.println(" DN: " + instance.getCompositeDN() +
"Instance: " + instance.getId() +
" creation-date: " + instance.getCreationDate() +
" state (" + instance.getState() + "): " +
getStateAsString(instance.getState()));

// setup a component filter
ComponentInstanceFilter cInstanceFilter =
new ComponentInstanceFilter ();

// get child component instances ..
List childComponentInstances =
instance.getChildComponentInstances(cInstanceFilter);

// for each child component instance (e.g. a bpel process)
for (ComponentInstance cInstance : childComponentInstances)
{
System.out.println(" -> componentinstance: " +
cInstance.getComponentName() + " type: " +
cInstance.getServiceEngine().getEngineType()+
" state: " +
getStateAsString(cInstance.getState()));
}

// retrieve composite sensors
List sensorData = instance.getSensorData();
for (SensorData data : sensorData)
{
System.out.println(" -> Sensor: " + data.getSensor().getName() +
" data: " + data.getData());}
}

To make the composite and component states readable, use the following conversion method:

private String getStateAsString (int state) 
    {
        // note that this is dependent on wheter the composite state is 
        // captured or not

        if (state == CompositeInstance.STATE_COMPLETED_SUCCESSFULLY)
            return ("success");
        else if (state == CompositeInstance.STATE_FAULTED)
            return ("faulted");
        else if (state == CompositeInstance.STATE_RECOVERY_REQUIRED)
            return ("recovery required");
        else if (state == CompositeInstance.STATE_RUNNING)
            return ("running");
        else if (state == CompositeInstance.STATE_STALE)
            return ("stale");
        else 
            return ("unknown");
    }

For example, this code when executed against the Fusion Order Demo BamOrderBookingComposite, returns the following data:

DN: default/BamOrderBookingComposite!1.0Instance: 40103 creation-date: Thu Jul 30
 12:31:24 PDT 2009 state (-1): unknown
  -> componentinstance: EvaluatePreferredSupplierRule type: decision state:
 success
  -> componentinstance: FulfillOrder type: mediator state: success
  -> componentinstance: InternalWarehouseService type: bpel state: unknown
  -> componentinstance: OrderProcessor type: bpel state: unknown
  -> componentinstance: RequiresApprovalRule type: decision state: success
  -> componentinstance: PartnerSupplierMediator type: mediator state: success
 -> Sensor: CreditCardAuthResultSensor data: APPROVED
 -> Sensor: OrderBookingCompositeProcessorResult data: 900
 -> Sensor: OrderProcessingStart data: Order 900

If you do not want to start searching for the APIs and packages, all classes used are in the following:

  • oracle.fabric.common.*

  • oracle.soa.management.facade.*

  • oracle.soa.management.util.*