11 Programmatically Managing SOA Composite Applications with the Facade API

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 sections:

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

11.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 11-1 to create ServerManager objects for managing the SOA server.

Example 11-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.

11.1.1 Security Credentials Required when Creating the Locator Object

Starting with 11g Release 1 (11.1.1.7), you must set the subject credential or have a valid subject established in the invocation context when creating the locator object. Example 11-2 shows how to create a locator object.

Example 11-2 Security Credentials for Creating the Locator Object

Hashtable<String, String> jndiProps = new Hashtable<String, String>();
jndiProps.put(Context.INITIAL_CONTEXT_FACTORY,initialContextFactory);
jndiProps.put(Context.PROVIDER_URL, providerURL);
jndiProps.put(Context.SECURITY_PRINCIPAL, principal);
jndiProps.put(Context.SECURITY_CREDENTIALS, creds);
Locator locator = LocatorFactory.createLocator(jndiProps);

If you do not specify the user credentials with jndiProps.put, a locator object is created, but when this object is used to invoke a method in the locator, a runtime exception is displayed because the caller does not have enough permissions to call the method:

Exception in thread "Main Thread" java.lang.RuntimeException

11.2 Facade API Interfaces

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

Table 11-1 Facade API Interfaces

Interface Description

AsynchronousJob

Retrieves details about asynchronous job types.

Note: This interface has been deprecated.

AsynchronousResult

Retrieves the results of asynchronous processes.

B2BBinding

Retrieves B2B binding details such as type and document reference.

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).

ComponentInstanceMigrationReport

Provides information about the feasibility of component instance migration for a specific candidate component instance.

ComponentInstanceMigrationResult

Provides information about the result of an attempt to migrate a specific component instance.

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).

CompositeInstanceMigrationReport

Provides information about the feasibility of composite instance migration for a specific candidate composite instance.

CompositeInstanceMigrationResult

Provides information about the result of an attempt to migrate a specific composite instance.

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.

InstanceMigrationContext

Provides instance migration context data.

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.

MigrationPlan

Provides details for handling supported incompatibilities during instance migration attempts.

MigrationReport

Provides details about a proposed composite instance migration attempt.

MigrationResult

Provides details about an instance migration attempt.

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.


11.3 Facade API Examples

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

11.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, which allows 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()

11.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 11-3 provides details.

Example 11-3 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();
}