| Oracle® Fusion Applications Developer's Guide 11g Release 5 (11.1.5) Part Number E15524-10 |
|
|
PDF · Mobi · ePub |
| Oracle® Fusion Applications Developer's Guide 11g Release 5 (11.1.5) Part Number E15524-10 |
|
|
PDF · Mobi · ePub |
This chapter describes what a user action or other activity in an Oracle ADF web application needs to do to invoke a SOA composite. The invocation is asynchronous and does not require a response. Inside the SOA composite, an Oracle Mediator component can provide routing and transformation, a BPEL component can provide business process orchestration, a human task service can provide workflows, and a decision service can provide complex business rules based decision making.
When to implement: A user action or other activity in an Oracle ADF web application needs to invoke a SOA composite. The invocation is asynchronous and does not require a response. Inside the SOA composite, an Oracle Mediator component can provide routing and transformation, a BPEL component can provide business process orchestration, a human task service can provide workflows, and a decision service can provide complex business rules based decision making.
Design Pattern Summary: A business component in the ADF Business Components Framework publishes a business event to execute a SOA composite application. The SOA composite application subscribes to the event using the Oracle Mediator component, and from there it can be routed to any other service component, such as BPEL.
Involved components:
Oracle ADF web application that includes ADF Business Components.
SOA composite application that includes an Oracle Mediator service component and an additional service component to which the event can be routed (such as a BPEL process service component).
Oracle Fusion applications initiate business processes in response to user actions. Oracle ADF provides a change notification framework that is triggered at the end of a transaction involving ADF Business Components. This notification can be declaratively configured to raise business events that conform to an Event Description Language (EDL) definition. When an event is raised, it is published on the Event Delivery Network (EDN). For more information about the EDN, see the chapter "Using Business Events and the Event Delivery Network" in the Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite.
Process flows are implemented using a BPEL process service component as a bridge from EDN to the BPEL process. Because the events raised by the ADF Business Components are not a native BPEL construct, you use a mediator service component to subscribe to the event and to then invoke the BPEL process service component. The mediator service component acts as a binding between the EDN and the BPEL process service component. Whenever the event is raised by ADF Business Components (whether through a GUI action or programatically), the BPEL process service component is invoked. Figure 32-1 illustrates how these work together.
This approach is recommended for the following reasons:
Validation logic can be consolidated in the entity object.
Multiple user interfaces can invoke the reusable entity object that produces the events.
Event subscription can be modeled on the mediator service component and not hard wired into the UI.
The producer of the event (in this case, ADF Business Components) does not need to know who the downstream consumers of the event are. If needed, the SOA back-end service can change, without needing to change anything in the Oracle ADF web application. Decoupling the Oracle ADF and SOA application lifecycles makes development more manageable.
Events raised by ADF Business Components are asynchronous with no return value. The event infrastructure leverages the WLS JMS provider, so any unconsumed events can be de-queued by the SOA platform at some later time if the platform isn't running, assuming the JMS implementation leverages Oracle Advanced Queuing. For information about integrating Oracle Advanced Queuing with Oracle BPEL Process Manager or Oracle Mediator, see the chapter "Oracle JCA Adapter for AQ" in the Oracle Fusion Middleware User's Guide for Technology Adapters.
Instead of using ADF Business Components, and the change notification publisher in entity objects to invoke a BPEL service component, you could use one of the following approaches. These development approaches should be used only when the recommended approach cannot be implemented.
WARNING:
The following approaches should not be used:
A web services data control created using a SOAP web service on the composite to create the view in the web application.
A custom Java class in the web application using SOAP.
A direct API call, or some other means to access the SOA composite.
A web application built using ADF Business Components and Oracle ADF Faces allows users to register bugs found in software. An ADF Business Components entity object is used to create a bug, and contains an event whose payload is the attribute values for the created bug. The event is configured to be raised whenever the Create operation is called on the entity object.
A mediator service component subscribes to the event and accepts the event payload. A routing rule is configured for the mediator service component that routes the payload for the event to a BPEL process service component. This component then sends an email that contains the information from the payload to the bug's creator.
There are some cases in which one might need to propagate the end user ID of the event raiser across the invoked services for auditing purposes. It is recommended to propagate this information in the event payload. When raising events for CUD operations (create, update, delete), include the last_updated_by history column in the event definition. As this column exists in every Oracle Fusion Applications table, the user raising the event will always be propagated.
The sample code for this use case can be downloaded from Oracle SOA Suite samples.
To initiate a BPEL process service component from a web application, you first need to create the web application using ADF Business Components and Oracle ADF Faces. You then create a SOA composite application that contains a mediator service component to pass the event payload created by ADF Business Components, and execute a BPEL process service component.
To invoke a BPEL process service component from an Oracle ADF web application:
In the Oracle ADF web application, define an event on an entity object.
For more information on creating events on entity objects, see the chapter "Creating a Business Domain Layer Using Entity Objects" in the Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework (Oracle Fusion Applications Edition). For more information about using business events, see the chapter "Using Business Events and the Event Delivery Network" in the Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite.
When you create the event, ensure the following:
Include attributes as needed for the payload.
Set the event point to be the database operation (create, update, delete) that will raise the event. You can also create any conditions needed to determine when the event should be raised.
Note:
Event points can only be associated with Data Manipulation Language (DML) operations.
Personally identifiable information (PII) is any piece of information that can be used to uniquely identify a person. PII is sensitive and must be protected from potential misuse.
When data is included in events or a BPEL flow, it is potentially exposed. While the transport may be encrypted on the SOA side, the data is not. The data in events, payload and BPEL variables is not secured by the security restrictions for business objects. Consider what data is to be exposed in the payload so as to prevent unauthorized access.
Defining an event generates an Event Definition Language (.edl) file and XML schema definition (.xsd). The EDL file contains all event definitions for the entity and the XSD file defines the contents of an event's payload, in addition to other objects needed by the BPEL process service component. These files together define the contract between the Oracle ADF application and the SOA composite application, as for a particular event, they identify the elements the SOA composite expects. Both these files are placed in the events directory for the project, and can be found in the Application Navigator as children to the associated entity object.
In the example bug application, the BugReport entity object contains the BugCreated event. This event carries all the attributes on the entity object as its payload, and is published using the create operation as its event point.
Create the page in the view that will invoke the operation defined as the event point for the event (for example, through a command button bound to the commit operation or through the implicit call to the commit operation as a task flow return activity).
In the example bug application, this is a UI command component bound to the Commit operation on the BugReport entity object. Because this operation commits the data to the database, and the Commit operation's corresponding DML operation (create) is used to sync the ADF Business Components cache with the database, the ADF Business Components framework raises the event.
For more information about creating the view, see "Part IV: Creating a Databound Web User Interface" in Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework (Oracle Fusion Applications Edition).
For verification purposes, you can either run the Oracle ADF web application from the Integrated Oracle WebLogic Server container included with Oracle JDeveloper, or you can deploy the Oracle ADF web application to a standalone container. This step includes procedures for running the Oracle ADF web application within the embedded container and the SOA composite on a standalone Oracle WebLogic Server container. See Step 4 for procedures on deploying to a standalone container.
Make sure that EDN data sources have been configured. Using Oracle WebLogic Server Administration Console, verify that EDNDataSource and EDNLocalTxDataSource have been configured.
Note:
Oracle ADF and SOA data sources for EDN must point to the same schema. The EDN schema cannot be shared by more than one SOA runtime environment (such as outside a cluster).
Navigate to Domain Configurations > Services > JDBC > Data Sources to verify the existence of EDN data sources.
If the EDN data sources have not been configured, create new EDN data sources. Select EDNDataSource and click New. Enter the following details:
Name: EDNDataSource
JNDI Name: jdbc/EDNDataSource
Database Type: Oracle and Database Driver > Oracle Thin Driver XA: Versions 9.0.1.9.2.0.10.11.
Driver Class Name: oracle.jdbc.xa.client.OracleXADataSource.
Click Next. In the next window, uncheck Supports Global Transactions.
Click Next and configure the following:
Database Name: DB_NAME_FUSION_EDN
Host Name/Port: Enter the host name and port for server running the FUSION_EDN database
Database User Name/Password: Enter a username and password.
Test the data source. Set as DefaultServer and click Finish.
Define EDNLocalTxDataSource as above, but use EDNLocalTxDataSource for the data source and jdbc/EDNLocalTxDataSource for the JNDI name.
Map the data source in the web.xml and weblogic.xml files associated with the event publishing application. Add the lines shown in Example 32-1to the WEB-INF/web.xml file.
Create an XML file called weblogic.xml with the following contents, and save it in the WEB-INF directory. This maps the global JMS resources to local JNDI names. The names in this file are the defaults expected by the remote connection factory, so you do not need to specify them. An example is shown in Example 32-2.
Example 32-2 Mapping Global JMS Resources to Local JNDI Names
<?xml version="1.0"?>
<resource-description>
<res-ref-name>jdbc/EDNLocalTxDataSource</res-ref-name>
<jndi-name>jdbc/EDNLocalTxDataSource</jndi-name>
</resource-description>
<resource-description>
<res-ref-name>jdbc/EDNDataSource</res-ref-name>
<jndi-name>jdbc/EDNDataSource</jndi-name>
</resource-description>
Add event-related SOA runtime libraries, specifically ADF Business Components uses Event Publishing APIs bundled in fabric-runtime.jar. Add a library reference to oracle.soa.workflow.wc in order to include the event publishing APIs bundled in the relevant JAR files.
Add the code shown in Example 32-3 to the weblogic-application.xml file.
In Oracle JDeveloper, create a SOA composite application project and add a mediator service component.
For detailed procedures on creating SOA composite application projects, see the chapters "Developing SOA Composite Applications with Oracle SOA Suite" and "Getting Started with Oracle Mediator" in the Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite.
When you create the project, ensure the following:
You choose to create a mediator service component on completion.
Before configuring the mediator service component, manually copy the EDL and XSD files created in Step 1 to the SOA composite application project's source path.
Open the MPLAN file for the mediator service component and create a new subscription that points to the EDL file moved into the source path. This means the mediator service component will now be subscribed to that event.
In the following example application, a mediator service component named BugCreatedRouter is subscribed to the BugCreated event, as shown in Figure 32-2.
Create the BPEL process service component.
For detailed procedures, see the chapter "Getting Started with Oracle BPEL Process Manager" in the Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite.
When you create the component, ensure the following:
Use the Create BPEL Process dialog to configure the payload. Use the Input Element finder icon to select the payload from the schema created for the event.
In the example application, the input element would be the BugCreatedInfo payload under the BugReport.xsd node, as shown in Figure 32-3.
You create an activity that accepts the payload from the input element as its input parameters. In the sample application, an email activity is created that takes various input parameters from the payload as assigns them to the email's parameters.
In the mediator service component, add a routing rule and configure it so that it invokes the BPEL process service and contains a subscription to the ADF Business Components event. Ensure the following:
You select the initiate operation on the client of the BPEL process service component as the target service, as shown in Figure 32-4.
Optionally, use the Transformation map to map the mediator service component's schema to the input schema of the BPEL process service component. However, this should not be necessary, as you should be using the same schema for both.
Deploy the SOA composite application to the SOA infrastructure. For details, see the chapter "Deploying SOA Composite Applications" in the Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite.
Use Oracle Enterprise Manager Fusion Middleware Control Console to view the SOA composite application to ensure it was properly deployed. For more information about using Oracle Enterprise Manager Fusion Middleware Control Console, see the chapter "Deploying SOA Composite Applications" in the Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite.
Following are alternative approaches to the use case pattern:
Section 32.5.1, "Using the Java Event API to Publish Events"
Section 32.5.2, "Using a JAX-WS Proxy to Invoke a Synchronous BPEL Process"
You can programmatically raise events following an ADF Business Components CUD operation using the publishEvent API.
Before you begin:
In Oracle WebLogic Server Console, set up EDN data sources as described in Section 32.4, "How to Initiate a BPEL Process Service Component from an Oracle ADF Web Application."
Add a library reference to oracle.soa.workflow.wc.
To publish events using the Java event API:
Import the required libraries into your application as shown in Example 32-4.
Example 32-4 Importing Files into Your Application
import javax.xml.namespace.QName; import oracle.fabric.blocks.event.BusinessEventConnection; import oracle.fabric.blocks.event.BusinessEventConnectionFactory; import oracle.fabric.common.BusinessEvent; import oracle.integration.platform.blocks.event.BusinessEventBuilder; import oracle.integration.platform.blocks.event.BusinessEventConnectionFactorySupport; import oracle.xml.parser.v2.XMLDocument; import org.w3c.dom.Element; import oracle.jbo.server.TransactionEvent; import oracle.jbo.server.JTATransactionHandler;
Publish events as required. An example is shown in Example 32-5.
Example 32-5 Publishing Events Using the Java Event API
private final String eventName = "CreateExpenseReport";
private final String eventNamespace = "/oracle/apps/ta/model/events/edl/ExpenseReportEO";
private final String schemaNamespace = "/oracle/apps/ta/model/events/schema/ExpenseReportEO";
private BusinessEventConnectionFactory cf = null;
private BusinessEventConnection conn = null;
public void eventSetup()
{
// Get event connection. Set to true for debugging only.
BusinessEventConnectionFactory cf =
BusinessEventConnectionFactorySupport.findRelevantBusinessEventConnectionFactory(false);
BusinessEventConnection conn = cf.createBusinessEventConnection();
}
private XMLDocument getXMLPayload() {
Element masterElem, childElem1, childElem2;
XMLDocument document = new XMLDocument();
masterElem = document.createElementNS(schemaNamespace, "CreateExpenseReportInfo");
document.appendChild(masterElem);
childElem1 = document.createElementNS(schemaNamespace, "Id");
masterElem.appendChild(childElem1);
childElem2 = document.createElementNS(schemaNamespace, "newValue");
childElem2.setAttribute("value", ((BigDecimal) this.getAttribute("Id")).toString());
childElem1.appendChild(childElem2);
return document;
}
public void beforeCommit(BusinessEventConnection conn , TransactionEvent e) {
// Determine whether this is a JTA transaction.
if (this.getDBTransaction() != null &&
this.getDBTransaction().getTransactionHandler() instanceof
JTATransactionHandler) {
// Determine whether the row is newly created.
if (this.getEntityState() == STATUS_NEW) {
try {
// Build the event.
BusinessEventBuilder builder = BusinessEventBuilder.newInstance();
// Specify the event name and namespace. In this example,
// they are constants: eventNamespace and eventName.
builder.setEventName(new QName(eventNamespace, eventName));
// Specify the event payload. In this example, the custom
// method getXMLPayload constructs the payload.
builder.setBody(getXMLPayload().getDocumentElement());
BusinessEvent event = builder.createEvent();
// Publish the event.
conn.publishEvent(event, 5);
conn.close();
// For debugging and testing purposes, print the result.
System.out.println("Event was sent sucessfully");
} catch (Exception exp) {
System.out.println("Failed sending event: " + exp.getMessage());
exp.printStackTrace();
}
}
}
super.beforeCommit(e);
}
Another way to invoke a SOA composite as a web service from an Oracle ADF web application is to use a JAX-WS proxy.
Use this pattern only for synchronously invoking BPEL processes where the calling application waits for a response. As such, any BPEL processes called using this pattern must be synchronous and brief so as to avoid any time out issues.
Caution:
Do not use this pattern for a long running or asynchronous BPEL process.
Make sure that synchronous services return immediately. Synchronous services should be simple input/output payloads.
Do not use multi-record or N record services in which processing time varies from seconds to minutes or longer.
For more information about this approach, see the chapter "Integrating Web Services Into an Oracle Fusion Web Application" in Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework (Oracle Fusion Applications Edition).
In this pattern, SOA composite services are exposed as web services. You generate a JAX-WS proxy client to invoke the SOA composite exposed as a web service from your ADF Business Components application module.
You use the web services wizard to generate a web service proxy, and then call the web service using method calls.
An indirection for the web service proxy node enables retrieving the location of the web service WSDL, username and password from connections.xml. To use the indirection, access the proxy via oracle.adf.model.connections.webservice.WebServiceConnection.
An example is shown in Example 32-6.
Example 32-6 Using WebServiceConnection
WebServiceConnection wsc =
(WebServiceConnection)ADFContext.getCurrent().getConnectionsContext().lookup(connectionName);
Hello hello = wsc.getJaxWSPort(Hello.class);
Use the username or SAML token policies for identity propagation and security. For more information, see Chapter 50, "Securing Web Services Use Cases."
To secure this pattern, it is recommended that you secure the Oracle ADF web application. For more information about securing the pattern, see Chapter 50, "Securing Web Services Use Cases."
To make the mediator run as an event publisher:
Open the composite.xml file for the SOA composite application and manually add the runAsRoles="$publisher"' attribute to the composite subscriptions. Example 32-7 shows the composite subscription for the sample application.
Example 32-7 runAsRoles Attribute in a Composite Subscription
<component name="BugReportMediator">
<implementation.mediator src="BugReportMediator.mplan" />
<business-events>
<subscribe xmlns:sub1="/model/events/edl/BugReport"
name="sub1:bugCreated"
consistency="oneAndOnlyOne"
runAsRoles="$publisher"/>
</business-events>
</component>
Note:
Currently, the only option for runAsRoles is $publisher.
To validate the subject propagation in the SOA composite application, add the following code as shown in Example 32-8 to the BPEL file for the BPEL process flow:
Example 32-8 Using bplex:exec to Print Out Subject Information
<bpelx:exec language="java" version="1.5">
<![CDATA[
javax.security.auth.Subject
subject = javax.security.auth.Subject.getSubject
( java.security.AccessController.getContext());
System.out.println("\n\n\n\n\n\n\n");
System.out.println ("######*****----->
subject: " + subject.toString());
System.out.println("\n\n\n\n\n\n\n");
]]>
</bpelx:exec>
Events enable event-driven applications and are not related to OWSM. Therefore, OWSM policies do not apply to events.
Events raised by Oracle ADF web applications automatically propagate the event's publisher ID in the event header. No action is required to perform identity propagation. The publisher's ID corresponds to the end-user authenticated in the application.
You can verify the deployment by testing the Oracle ADF web application. Alternatively, you can send EDN events at the command line to verify event-raising functionality.
To properly verify this design pattern, you should test the Oracle ADF web application and enable logging, use Oracle Enterprise Manager Fusion Middleware Control Console to verify the process instance creation, and check the SOA logs.
To verify this design pattern:
Test your Oracle ADF web application using various testing and debugging methods described in the chapter "Testing and Debugging ADF Components" in the Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework (Oracle Fusion Applications Edition). Be sure to enable ADF Business Components runtime logging by setting the Java VM parameter in the run/debug profile to jbo.debugoutput=console. Doing so logs the event and its payload in the JDeveloper log console.
Run the Oracle ADF web application and invoke the method that raises the event.
View the ADF Business Components runtime log in the JDeveloper log console to view the event and payload.
Use Fusion Middleware Control Console for tracking composite instances and for a variety of debugging, monitoring and testing functions.
Launch Fusion Middleware Control Console using the following URL:
http://<hostname>:<port number>/em
Open Fusion Middleware Control Console to verify the process instance has been created. Use the Audit tab to verify that the payload is correct.
You can test EDN functionality using SendEvent and edn.debug.event-connection at the command line.
SendEvent is a command line utility for sending an event to a database-based Oracle Event Delivery Network instance. SendEvent can send an empty event (of a given queue name) or an entire event from a file. Running the command displays a list of command line options.
Some examples are shown in Example 32-9 and Example 32-10.
In Example 32-9, an empty event with namespace uuid:1111 and local name MyEvent is sent to the event bus.
Example 32-9 Sending an Empty Event
oracle.integration.platform.blocks.event.SendEvent -dbconn host.companyname.com:1521:SID -dbuser user -dbpass password -eventName {uuid:1111}MyEvent
In Example 32-10, the event contained in the file AnEvent.xml is sent to EDN.
You can use BusinessEventConnectionFactorySupport in your Oracle ADF web application to test your event publishing code. Rather than sending an event to a queue, you can configure your Oracle ADF web application to print the event information to the log using BusinessEventConnectionFactorySupport.
To do so, set the system property edn.debug.event-connection to true when running your application. When the application sends an event, the information for that event is logged, including the event body in its entirety. This enables you to see the events that will be sent to EDN when the application runs on a SOA server.
The log name is oracle.integration.platform.blocks.event.debug, but in most configurations the information prints to stdout by default.
To set the system property:
When Oracle WebLogic Server starts up, add the system property shown in Example 32-11 to the JAVA_OPTIONS environment variable.
To access the EDN database log:
You can use the EDN database log shown in Example 32-12 for diagnostic purposes.
Following are tips that may help resolve common issues that arise when developing or running this use case.
If deployment of the SOA composite application fails, then verify the following:
The location element in the EDL file located in the directory is relative to the directory that contains the EDL file.
If you get an invalid XPath expression exception, use a static value instead of a value from the payload.
Before you implement these design patterns, you should be aware of the following:
If you change the event name or event payload, the mediator will not respond to the raising of the event. If you need to make changes, you should create a new event. During development, you need to change the mediator (if the name of the event changes) and/or the BPEL process being invoked (if the payload changes).
Following are known issues:
You must add a library reference to oracle.soa.workflow.wc in order to raise events successfully.
You can only specify $publisher as the runAsRole for an event subscription.
|
 Copyright © 2011, 2013, Oracle and/or its affiliates. All rights reserved. Legal Notices |
|