The Service Broker control allows a business process to send requests to and receive callbacks from another business process, a Web service, or a Web service or business process defined in a WSDL file.
The Service Broker control lets you dynamically set control attributes. This allows you to reconfigure control attributes without having to redeploy the application.
For information on how to add control instances to business processes, see Using Controls in Business Processes.
The Service Broker control allows a business process to send requests to and receive callbacks from another business process, a Web service, or a remote Web service or business process. The Service Broker control is an extension of the Web Service control.
A remote Web service or business process is accessed using Web services and is described in a Web Services Description Language (WSDL) file. A WSDL file describes the methods and callbacks that a Web service implements, including method names, parameters, and return types. You can generate a WSDL file for any business process by right clicking on a Process.java file in the Package Explorer pane and choosing Generate WSDL File.
The first step in using a Service Broker control is creating a Control file. The Control can be automatically generated from a target service (Web service, business process, or WSDL file) using Oracle Workshop for WebLogic, or can be created using the Add function in the Controls section of the Oracle Workshop for WebLogic Data palette. The methods and callbacks on the Control file correspond to operations and callbacks of the target service. An instance of this Control file is used by a parent service to call the target service and can also be used to get callbacks from the target service. Service Broker control files can only have selector annotations on start methods for stateful target services, whereas they can have selector annotations on any method for stateless target services.
Note: | The parent process and the target process must both be configured to use the same protocol. Protocol matching and enabling is not handled automatically. |
To learn about creating a Service Broker control, see Creating a New Service Broker Control. For more information on Service Broker Control methods, see Interface ServiceBroker Control.
This topic describes how to create a new Service Broker control.
You can create a Service Broker control in two different ways, which are described in the following sections:
You can create a new Service Broker control and add it to your Web service or business process by using the Insert Control - Service Broker dialog.
Notes: | When creating a Service Broker control that references a business process (Process.java), the business process must be in the current Oracle Workshop for WebLogic application. |
Note: | If you are not in Design View, click the Design tab. |
To create a new Service Broker control:
Note: | If the Data Palette view is not visible in Oracle Workshop for WebLogic, click Windows > Show View > Data Palette from the menu bar. |
The Insert Control: ServiceBroker dialog appears.
If you invoked the Dynamic Selector query builder, perform the following steps to build and test a query:
TPM
to bind lookup values to properties in the TPM repository. Choose LookupControl to bind lookup values to dynamic properties specified in a domain-wide DynamicProperties.xml
file. You should only edit the DynamicProperties.xml
file to bind lookup values to dynamic properties if the domain is inactive. If the domain is active, it is recommended that you use the Oracle WebLogic Integration Administration Console to bind lookup values. For more information on binding lookup values to dynamic properties using the Oracle WebLogic Integration Administration Console, see “Adding or Changing Dynamic Control Selectors” in Process Configuration.
The Service Broker control is created and displayed in the Package Explorer pane. An instance of the control is also created and is added to the Data Palette.
You can create a Service Broker control from an existing business process.
The Dynamic Selector Generation (optional) dialog box is displayed (see Figure 14-1).
If you invoked the Dynamic Selector query builder, perform the following steps to build and test a query:
DynamicProperties.xml
file. You should only use LookupControl to bind lookup values to dynamic properties if the domain is inactive. If the domain is active, it is recommended that you use the Oracle WebLogic Integration Administration Console to bind lookup values. For more information on binding lookup values to dynamic properties using the Oracle WebLogic Integration Administration Console, see “Adding or Changing Dynamic Control Selectors” in Process Configuration.
MyProcess.java
, the generated Service Broker control file is named MyProcessSBControl.java
.Note: | Alternatively, you may create a Service Broker control file manually. For example, you may copy an existing Service Broker control file and modify the copy. |
When you are using XQuery expression and the XQuery Builder, it is important to remember:
The Service Broker control adds the capability of dynamically binding some properties of the control. Dynamic binding of properties can be achieved the following ways:
To retrieve the current properties settings, use the getProperties()
method. Note that this method does not return security-related settings such as username
/password
, keyAlias
/keyPassword
, and keyStoreLocation
/keyStorePassword
.
Starting with the method with the highest precedence, the hierarchy of property settings is:
com.bea.wli.common.control.Selector
annotation and the DynamicProperties.xml
filesetProperties()
method or other setter methods inherited from the Service control (setConversationID
, setEndPoint
, setOutputHeaders
, setPassword
, and setUsername
)
The ServiceBrokerControlProperties
type is an XML Beans class that is generated out of the corresponding schema element defined in DynamicProperties.xsd
. The DynamicProperties.xsd
file is located in the system folder of New Process Applications or in the system folder of the Schemas project.
Note: | The ServiceBrokerControlProperties document's "password" field and associated setPassword() method should contain the intended password alias, not the actual password. |
The setProperties()
method uses this XML Beans class to set properties on a control instance. A selector on a Service Broker control method returns an XML document that conforms to the ServiceBrokerControlProperties
element. The following sample shows how to programmatically set the endpoint property for the control. You add the bold code lines to the code generated when the control is created, overriding properties set using dynamic binding and static annotations:
import com.bea.wli.control.dynamicProperties.
ServiceBrokerControlPropertiesDocument;
import com.bea.wli.control.dynamicProperties.
ServiceBrokerControlPropertiesDocument.ServiceBrokerControlProperties;
ServiceBrokerControlPropertiesDocument props= null;
ServiceBrokerControlProperties sprops = null;
public void sBC8InvokeSetProperties() throws Exception
{
props = ServiceBrokerControlPropertiesDocument.Factory.newInstance();
sprops = props.addNewServiceBrokerControlProperties();
sprops.setEndpoint("http://localhost:7001/BVTAppWeb/ServiceBrokerControl
/SBC8DynPropHierarchyChild_2.jpd");
You construct the ServiceBrokerControlPropertiesDocument instance in the above section of code through a Data Transformation method or through XML Bean APIs. For more information on Data Transformations, see Guide to Data Transformation.
The following code provides a sample of a ServiceBrokerControlPropertiesDocument instance:
this.sbcp = ServiceBrokerControlPropertiesDocument.Factory.newInstance();
this.sbcp.addNewServiceBrokerControlProperties();
this.sbcp.getServiceBrokerControlProperties().setEndpoint("http://localhost:7001/");
Some control properties can be specified dynamically or in annotations (statically) on the control file. For example, the Service Broker control allows you to specify the http-url
of the target service in the @com.bea.wli.common.control.Location
annotation at the top of the control, or dynamically using the endpoint element in DynamicProperties.xml
. In all such cases, a dynamically bound value for the property takes precedence over the static annotation.
If the domain is active, it is recommended that you use the Oracle WebLogic Integration Administration Console to perform dynamic binding. For more information on binding lookup values to dynamic properties using the Oracle WebLogic Integration Administration Console, see “Adding or Changing Dynamic Control Selectors” in Process Configuration.
Dynamic properties can also be specified by calling setProperties
on the control, or by calling one of the setter methods, such as ServiceBrokerControl.setEndPoint()
. Properties specified in this way take precedence over properties bound by selectors or annotations.
Properties applied using selectors remained bound until one of the following conditions occurs:
ServiceControl.reset()
is overwritten by the Service Broker control to reset all dynamically set properties (in addition to all conversational states). Programmatically specified properties remain bound until reset()
is invoked.
Property values set by a developer who is using the control are stored as annotations on the control's declaration in a JWS, JSP, or Process.Java file, or as annotations on its interface, callback, or method declarations in a Control file.
This section outlines some of the issues you must consider when you are designing a Service Broker control for your business process. The issues covered in this section are:
The number of transactions contained in a business process determines whether the process is stateless or stateful. For more information, see Building Stateless and Stateful Processes. This section covers some of the issues you should consider when designing a Service Broker control for stateless and stateful business processes.
When designing your Service Broker control, adhere to the following rules:
Business processes can have both synchronous or asynchronous request methods. For more information, see Building Synchronous and Asynchronous Business Processes. This section covers some of the issues you should consider when designing a Service Broker control for synchronous and asynchronous business processes.
When designing your Service Broker control, remember:
The Service Broker control is typically used to call a subprocess from a parent business process. When the Service Broker control is invoked from the parent process, the control is invoked normally if the subprocess is in the same domain.
In cases where the parent process and subprocess are in different domains, or in the same domain but in different applications, and you want to use the Service Broker control for the parent process to communicate with the subprocess, you must create the Service Broker control in the subprocess domain or application, then manually copy it to the parent process domain or application, and then reference it as an existing control file.
Additionally, when the parent process and subprocess are in different applications, you will manually have to change the JMS and/or HTTP location of the location attribute.
When you create a Service Broker control, it is displayed in the Package Explorer pane and an instance of the control is added to the Data Palette. The location of the Service Broker control is displayed in the JPD Configuration pane.
Note: | If the JPD Configuration pane is not visible in Oracle Workshop for WebLogic, choose Windows > Show View > Properties from the menu bar. |
To view the location of the Service Broker control:
The Service Broker control is displayed in the Design view and the JPD Configuration pane displays the properties of the Service Broker control (see Figure 14-3).
The location of the Service Broker control is displayed in the location section of the JPD Configuration pane. The location can contain a HTTP and/or JMS attribute. The HTTP location is a true HTTP address and the JMS location is a JMS url.
This section outlines some of the run-time issues you must consider when you are invoking a Service Broker control in your business process.
The topics covered in this section are:
The number of transactions contained in a business process determines whether the process is stateless or stateful. For more information, see Building Stateless and Stateful Processes. This section covers some of the run-time issues you should consider when using a Service Broker control in stateless and stateful business processes.
The following rules govern the run-time operation of Service Broker controls in stateless and stateful business processes:
FORM-POST
and FORM-GET
requests.Business processes can have both synchronous or asynchronous request methods. For more information, see Building Synchronous and Asynchronous Business Processes. This section covers some of the run-time issues you should consider when using a Service Broker control in synchronous and asynchronous business processes.
The following rules govern the run-time operation of Service Broker controls in synchronous and asynchronous business processes:
com.bea.control.ServiceControlException
is generated.com.bea.control JwsContext
interface provides access to container services that support Web services (JWS files). For more information, see “com.bea.control JwsContext Interface” in
com.bea.control packages. The setUnderstoodInputHeaders()
method of the com.bea.control JwsContext
interface is not supported for asynchronous processes.The Service Broker control conforms to all standard security checks associated with JMS and WSDL. SSI is not supported. For more security information, see Security.
If you want to configure security settings for your Service Broker control, it is recommended that you use the Oracle WebLogic Integration Administration Console to configure these settings and do not set them on the process. For more information, see “Updating Security Policies” in Process Configuration in Using The Oracle WebLogic Integration Administration Console.
In general, Service Broker controls are utilized in situations where the parent process and subprocess are in the same application, or in situations where the parent process and subprocess are in different applications.
In both situations, if the Service Broker control is changed on the subprocess side of the transaction, you must regenerate the control on the parent side to insure that the control will operate normally. If the subprocess and parent process are in different applications, and the Service Broker control is changed in any way (i.e. request/response removed, etc.), backward compatibility may be compromised. If this happens, you must merge the Service Broker control on the subprocess side and repropagate the control back to the parent business process.
Note: | Much like the Service control, the Service Broker control can throw a ServiceControlException class when a SOAP fault occurs. To access this SOAP fault, use the JPD's JpdContext.ExceptionInfo interface to see if the offending cause is a ServiceControlException. For more information on the ServiceControlException class, see “ServiceControlException Class” in com.bea.control packages. For more information on the JpdContext.ExceptionInfo interface, see “JpdContext.ExceptionInfo Interface” in com.bea.jpd Package. |
In many cases, control attributes are statically defined using annotations. Some controls provide a Java API to dynamically change certain attributes. Dynamic controls, including the Service Broker and Process controls, provide the means to dynamically set control attributes. Attributes are determined at runtime using a combination of lookup rules and lookup values, a process called dynamic binding. Controls that support dynamic binding are called dynamic controls. The business process developer specifies lookup rules using Oracle Workshop for WebLogic while the administrator specifies look-up values using the Oracle WebLogic Integration Administration Console. This powerful feature means that control attributes can be completely decoupled from the application and can be reconfigured for a running application, without redeployment.
The following scenario shows how the Service Broker control uses dynamic binding. POService.java
needs to call an external service to obtain a quote on a specific item. Several vendors offer this service. The administrator needs to be able to access multiple implementations of the outside service without changing or redeploying POService.jpd
.
This topic describes the capabilities that provide dynamic binding to the quote service using the Service Broker control.
The method-level annotation, com.bea.wli.common.control.Selector, allows dynamic definition of certain properties of the control. The selector has an attribute, xquery
, which is an XQuery expression, as shown in the following example:
/**
* com.bea.wli.common.Conversation.Phase.Start
* com.bea.wli.common.control.Selector xquery ::
* lookupControlProperties($request/vendorID) ::
*/
public void requestQuote(PurchaseRequest request);
The value of the selector’s XQuery expression is an XML document with a schema that contains control property values. If you are accessing a TPM repository, the XQuery expression appears as follows:
/**
* @com.bea.wli.common.Conversion(value = com.bea.wli.common.Conversation.Phase.START)
* @com.bea.wli.common.control.Selector( xquery= "lookupControlProperties($request/vendorID)")
* public void requestQuote(PurchaseRequest request);
When invoking a method on the control, the system looks for a selector annotation. If one is present, the XQuery expression is evaluated, possibly binding arguments of the Java call to arguments of the XQuery expression. The result of the XQuery expression is a String value that defines dynamic properties for the control.
Two types of XQuery functions are supplied to help you write selector expressions: lookupControlProperties
and lookupTPMProperties
. The lookupControlProperties
function looks up values for dynamic properties specified in a domain-wide DynamicProperties.xml
file. The lookupTPMProperties
function looks up values from properties in the TPM (Trading Partner Management) repository.
To learn about the TPM repository, see Introducing Trading Partner Integration. To learn about adding or updating information in the TPM repository, see Trading Partner Management. The TPM control provides Oracle Workshop for WebLogic business processes and Web services with query (read-only) access to trading partner and service information stored in the TPM repository. To learn about the TPM control, see TPM Control.
If the selector expression uses the lookupControlProperties
function, the fully-qualified class name of the control together with the result of evaluating the selector are used as a lookup key into the DynamicProperties.xml
file. If a match is found, the dynamic properties are applied before making the call to the target service.
DynamicProperties.xml
is an XML file managed through the Oracle WebLogic Integration Administration Console. It contains mappings between values from the message payload (the lookup key) and corresponding control properties. It is a domain-wide file shared by all Oracle WebLogic Integration applications in the domain. This file allows you to administer dynamic properties without redeploying the application. The file is located in a subdirectory of the domain root named wliconfig
. To learn about managing dynamic selectors, see
Processes Configuration.
DynamicProperties.xml
contains a sequence of <control>
elements, one for each dynamic control control file. Each <control>
element has a name
attribute whose value is the fully-qualified Java class name of a control file. Nested inside the <control>
element is a sequence of <key>
elements which map string values that match the value of the parameter passed into the lookupControlProperties
within the caller’s selector to dynamic properties, as shown in the following example:
<DynamicProperties
xmlns="http://www.bea.com/wli/control/dynamicProperties">
<control name context-path="/sbcAppWeb"
controlType="ServiceBrokerControl">
<key value="QuoteCom">
<ServiceBrokerControlProperties>
<endpoint>http://www.quotecom.com/quotes/QuoteService</endpoint>
</ServiceBrokerControlProperties>
</key>
<key value="WebQuote">
<ServiceBrokerControlProperties>
<endpoint>http://www.webquote.com/quoteEngine/getQuote</endpoint>
</ServiceBrokerControlProperties>
</key>
</control context-path>
<control name context-path="quote.InternalQuote"
controlType="ProcessControl">
<key value="OurQuote">
<ProcessControlProperties>
<targetURI>http://acme/myApp/PublicProcess.jpd</targetURI>
</ProcessControlProperties>
</key>
</control context-path>
</DynamicProperties>
The Oracle WebLogic Integration Administration Console allows an administrator to view and edit entries in the DynamicProperties.xml
file.
This section shows how dynamic controls and selectors can help to implement the quote processing scenario. Figure 14-4 shows the components that participate in the dynamic binding:
To achieve the required dynamic binding to the target service, the business process defined in POService.java
uses a Service Broker control, QuoteProcessor.java
, to call the quote service. Since the target is dynamically specified, the com.bea.wli.common.control.Location
tag is not used. The Service Broker control is defined by the following control file:
import com.bea.control.ServiceBrokerControl;
import com.bea.control.ControlExtension;
import org.applications.PurchaseRequest;
import org.applications.PurchaseReply;
public interface QuoteProcessor
extends ServiceBrokerControl, ControlExtension
{
public interface Callback
{
public void infoReady (PurchaseReply reply);
}
/**
* @com.bea.wli.common.Conversion(value = com.bea.wli.common.Conversation.Phase.START)"
* @com.bea.wli.common.control.Selector( xquery= "lookupControlProperties($request/vendorID)")
public void requestQuote(PurchaseRequest request
}
At runtime, the control container needs to bind the proxy represented by the control to the proper implementation. This is driven by a selector XQuery expression tagged on the start method of the Service Broker control interface (com.bea.wli.common.control.Selector
).
Note: | For controls representing stateless components, each method can have a selector. For methods without selectors, the default location defined in the annotation is used. If the target location is not resolved after applying the selector, a runtime exception is raised. |
The selector returns an XML fragment that contains the dynamic properties of the control. For example:
<ServiceBrokerControlProperties>
<endpoint>
http://www.quotecom.com/quotes/QuoteService/endpointURI>
</endpoint>
<username>fred</username>
<password>@$%&*</password>
</ServiceBrokerControlProperties>
In this example, the selector uses a standard XQuery function called lookupControlProperties()
. This function looks up the control properties from the DynamicProperties.xml
file based on the key passed to it. In the example, the key is the vendor ID that is extracted from the payload. The result passed back by lookupControlProperties()
is a <ServiceBrokerControlProperties>
element.
The key-attribute mapping information used by lookupControlProperties()
is stored in the DynamicProperties.xml
file. The schema for the dynamic properties file can handle all the attributes that are valid for dynamic controls. You can define selectors when you create the control or by directly editing the control source code.
An administrator can define the mapping between the selector value and the implementation using the Oracle WebLogic Integration Administration Console. The Oracle WebLogic Integration Administration Console allows an administrator to specify the following properties:
Note: | The parent process and the target process must both be configured to use the same protocol. Protocol matching and enabling is not handled automatically. |
This section provides information on the Service Broker control specific behavior of the following annotations:
The @com.bea.wli.common.ParameterXml
annotation specifies that there should be a queue between the component’s implementation code and the message transport wire for the specified method or callback. For more information, see “@com.bea.wli.common.ParameterXml Annotation” in
Java Control Annotations.
When you generate a Service Broker control request method, do not edit any of the attributes of the @common:message-buffer
annotation. The @common:message-buffer
annotation is visible in the message-buffer section of the JPD Configuration pane.
The com.bea.wli.common.Conversation
annotation specifies the role that a control’s methods or callbacks play in a conversation. For more information, see “com.bea.wli.common.Conversation annotation
” in
Java Control Annotations.
When you generate a Service Broker control, do not edit the phase attribute of the com.bea.wli.common.Conversation
annotation. The com.bea.wli.common.Conversation
annotation is visible in the conversation section of the JPD Configuration pane.
The @jc:parameter-xml
annotation specifies characteristics for marshaling data between XML messages and the data provided to the parameters of a Web service operation. For more information, see “@jc:parameter-xml Annotation” in
Java Control Annotations.
It is recommended that you do not use this annotation when designing a Service Broker control.
The @com.bea.wli.common.Protocol
annotation specifies which protocols and message formats can be accepted by the Web service represented by a Web Service control, and by the operations on that Web service. For more information, see “@com.bea.wli.common.Protocol Annotation” in
Java Control Annotations.
If you use the Service Broker control to call properties, do not use the http-xml
attribute of com.bea.control.ServiceControl.JmsSoapProtocol
. This attribute is not supported for use with the Service Broker control. This attribute is visible in the protocol section of the JPD Configuration pane.