This chapter provides an overview of the Facades API for programmatically managing SOA composite applications.
This chapter includes the following topics:
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 Console.
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.Table 9-1 provides an overview of the Facades API interfaces.
Table 9-1 Facades API Interfaces
| Interface | Description |
|---|---|
|
|
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. |
|
|
Retrieves details about asynchronous job types. |
|
|
Retrieves the results of asynchronous processes. |
|
|
Retrieves binding details such as URI, type, and subtype. |
|
|
Retrieves the binding type and the list of faults specified by the given fault filter. |
|
|
Retrieves business event details such as the consistency level, filter type, local name, namespace URI, and prefix. |
|
|
Retrieves component details such as distinguished name (DN); active, faulted, and total instances; deployment time; and so on. |
|
|
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). |
|
|
Retrieves composite details such as the distinguished name (DN); active, faulted, and total instances; deployment time; and so on. |
|
|
Retrieves the composite instance state (for example, successfully completed, faulted, running, and so on). |
|
|
Retrieves the event bridge type and the list of faults specified by the given fault filter. |
|
|
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. |
|
|
Provides action types such as aborting 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. |
|
|
Retrieves faults, errors, recoverable faults, nonrecoverable faults, and so on. |
|
|
Provides the fault recovery service engine. |
|
|
Retrieves the location of the imported resource and the import type. |
|
|
Retrieves the callback interface and interface properties. |
|
|
Exposes a method interface as an entry point for Facades API clients. |
|
|
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. |
|
|
Performs partitioning life cycle management tasks such as starting, stopping, activating, and retiring all the composites in a partition. |
|
|
Retrieves property details such as the default value, name, override attribute value of the property, property value source, and so on. |
|
|
Retrieves reference details such as the WSDL URL for the target service, properties for the reference, reference name, reference bindings, and so on. |
|
|
Retrieves the type of the binding. DN of the composite, composite instance ID, time of instance creation, and so on. |
|
|
Gets and creates partitions. |
|
|
Retrieves service details such as bindings, composite DN, interface type, name, multiplicity, and so on. |
|
|
Retrieves the list of deployed components in the service engine, engine type, and list of faults specified by the given fault filter. |
|
|
Retrieves service instance details such as the type of the binding. DN of the composite, composite instance ID, time of creation, and so on. |
|
|
Retrieves the default address URI, endpoint address URI, port, transport type, and so on. |
|
|
Retrieves the port name, port URI, service name, and so on. |
|
|
Retrieves the wire reference, wire service, source URI, and target URI. |
|
|
Retrieves the WSDL URL. |
This section provides several examples of using the Facades API to perform composite management.
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
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.*