10 Programmatically Managing SOA Composite Applications

This chapter describes the Facade API, which exposes operations and attributes such as composites, components, services, and references for programmatically managing SOA composite applications during runtime. The Facade API is part of Oracle SOA Suite's Infrastructure Management Java API.

This chapter includes the following topics:

Section 10.1, "Introduction to Programmatically Managing SOA Composite Applications"
Section 10.2, "Facade API Interfaces"
Section 10.3, "Facade API Examples"

10.1 Introduction to Programmatically Managing SOA Composite Applications

You can programmatically manage your SOA composite applications during runtime with the Facade API. The Facade API is part of Oracle SOA Suite's Infrastructure Management Java API. The Facade API exposes operations and attributes of composites, components, services, references and so on. The Facade 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 the top level entry point for most Facade APIs. The oracle.soa.management.facade.Locator interface exposes a method, createConnection, which returns a DirectConnection to a composite. You can use the LocatorFactory implementation to obtain the DirectConnection. For more information about the LocatorFactory and DirectConnection, see section "Introduction to the Direct Binding Invocation API" of Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite. The DirectConnection and DirectConnectionFactory (for creating direct binding connections) classes are in the oracle.soa.api.invocation package.

Partition management APIs are not exposed by the Locator. Instead, the top level entry point for partition management APIs is the ServerManager. You use the ServerManagerFactory implementation shown in Example 10-1 to create ServerManager objects for managing the SOA server.

Example 10-1 ServerManagerFactory

ServerManagerFactory smf = ServerManagerFactory.getInstance();
 Hashtable jndiProps = new Hashtable();

 jndiProps.put(Context.PROVIDER_URL, "server_JNDI_provider_url");
 jndiProps.put(Context.INITIAL_CONTEXT_FACTORY, "server_initial_context_factory_
classname");
 jndiProps.put(Context.SECURITY_PRINCIPAL, "jndi_user");
 jndiProps.put(Context.SECURITY_CREDENTIALS, "jndi_password");
 ServerManager sm = smf.createInstance(jndiProps);

For more information about the Facade 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 Facade API Interfaces

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

Table 10-1 Facade API Interfaces

Interface	Description
`ActivityInstance`	Retrieves the 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. Note: This interface has been deprecated.
`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 service 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 Facade 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 Facade API Examples

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

10.3.1 Retrieving the State of a Composite

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

Mode: 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).
State: 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).

Use oracle.soa.management.facade.Locator#getComposite(compositeDN) to get a reference to a composite of interest.

From the composite reference, you can query the mode and state using the following methods:

String getMode()
String getState()

10.3.2 Finding Composite and Component Instances

You can find composite and component instances with the Facade API.

Use the Locator interface to find a Composite (locator.lookupComposite(compositeDN)). If the composite has not yet been invoked, there are no instances.

You can then find its instances and get related information (for example, the instance ID, which components were executed, and so on).

Example 10-2 provides details.

Example 10-2 Finding Composite and Component Instances

Composite composite = locator.lookupComposite("default/OrderBookingComposite!1.0");
 
// The context is already the composite, so there is no need to set the DN as a filter criterion
CompositeInstanceFilter filter = new CompositeInstanceFilter();
filter.setMinCreationDate(new java.util.Date((System.currentTimeMillis() - 20000)));
 
// Get composite instances by filter
List compositeInstances = composite.getInstances(filter);
 
// for each of the returned composite instances..
for (CompositeInstance instance : compositeInstances) {
    long   instanceId = instance.getId();
    Date   created    = instance.getCreationDate();
    String state      = instance.getState();
 
    // Configure a component instance filter
    ComponentInstanceFilter cInstanceFilter =
                         new ComponentInstanceFilter ();
 
    // Get the child component instances
    List componentInstances =
        instance.getChildComponentInstances(cInstanceFilter);
 
    for (ComponentInstance compInstance : componentInstances) {
        String compName       = compInstance.getComponentName();
        long   compInstanceId = compInstance.getId();
        String type           = compInstance.getServiceEngine().getEngineType();
 
        // State values correspond to constants defined by the ComponentInstance interface
        int state = compInstance.getState();
    }
 
    // Retrieve composite sensors
    List sensorData = instance.getSensorData();
}