Using Integration Controls

Service Broker Control

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.

Topics Included in This Section

Overview: Service Broker Control

Creating a New Service Broker Control

Setting Service Broker Properties

Service Broker Control Design Time Considerations

Service Broker Control Run-Time Considerations

Maintaining Service Broker Controls

Using Dynamic Binding

Notes on Service Broker Control Annotations

Notes on Service Broker Control Annotations

Overview: Service Broker Control

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 BEA Workshop for WebLogic Platform, or can be created using the Add function in the Controls section of the BEA Workshop for WebLogic Platform 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.

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.

Creating a New Service Broker Control

This topic describes how to create a new Service Broker control. To learn about Service Broker controls, see Overview: Service Broker Control.

You can create a Service Broker control in two different ways, which are described in the following sections:

Creating a New Service Broker Control Using the Control Wizard

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.

To create a new Service Broker control:

Note:

If the Data Palette view is not visible in BEA Workshop for WebLogic Platform, click WindowsShowViewData Palette from the menu bar.

Creating a Service Broker Control from a Business Process

You can create a Service Broker control from an existing business process.

Notes on XQueries

When you are using XQuery expression and the XQuery Builder, it is important to remember:

Setting Service Broker Properties

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:

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.

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, and for more information on XML Beans, see "Getting Started with XML Beans" in Handling XML with XML Beans.

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 WebLogic Integration Administration Console to perform dynamic binding. For more information on binding lookup values to dynamic properties using the WebLogic Integration Administration Console, see "Adding or Changing Dynamic Control Selectors" in Process Configuration in Using the WebLogic Integration Administration Console, which is available at the following URL:

http://download.oracle.com/docs/cd/E13214_01/wli/docs92/adminhelp/processconfig.html

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.

You can also use the Interface ControlContext for access to a control's properties at run time and for handling control events. 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.

Related Topics

Overview: Service Broker Control

Using Dynamic Binding

Service Broker Control Design Time Considerations

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:

Using a Service Broker Control in Stateless and Stateful Business Processes

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:

Using Service Broker Controls in Synchronous and Asynchronous Business Processes

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:

Using a Service Broker Control from the Parent Process

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.

Service Broker Control Location

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 Properties pane.

Note:

If the Properties pane is not visible in BEA Workshop for WebLogic Platform, choose WindowsShowViewProperties from the menu bar.

To view the location of the Service Broker control:

Service Broker Control Run-Time Considerations

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:

Run-Time Rules for Service Broker Controls in Stateless and Stateful Business Processes

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:

Run-Time Rules for Service Broker Controls in Synchronous and Asynchronous Business Processes

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:

Security

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 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 WebLogic Integration Administration Console, which is available at the following URL: http://download.oracle.com/docs/cd/E13214_01/wli/docs92/adminhelp/processconfig.html.

Maintaining Service Broker Controls

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.

Using Dynamic Binding

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 WebLogic Workshop while the administrator specifies look-up values using the 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.

How the Service Broker Control Uses Dynamic Binding

The following scenario shows how the Service Broker control uses dynamic binding. POService.jpd 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.

Components Used in Dynamic Binding

This topic describes the capabilities that provide dynamic binding to the quote service using the Service Broker control.

@jc:selector Tag

The method-level annotation, @jc: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:

    /** 
     * @jc:conversation phase="start"
     * @jc: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.

Built-In XQuery Functions

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 at http://download.oracle.com/docs/cd/E13214_01/wli/docs92/tpintro/index.html. To learn about adding or updating information in the TPM repository, see Trading Partner Management in Using The WebLogic Integration Administration Console at http://download.oracle.com/docs/cd/E13214_01/wli/docs92/adminhelp/tpm.html. The TPM control provides WebLogic Workshop 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 File

DynamicProperties.xml is an XML file managed through the 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 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 in Using The WebLogic Integration Administration Console at http://download.oracle.com/docs/cd/E13214_01/wli/docs81/manage/processconfig.html.

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 WebLogic Integration Administration Console allows an administrator to view and edit entries in the DynamicProperties.xml file.

Quote Processing Example

This section shows how dynamic controls and selectors can help to implement the quote processing scenario. The following figure 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.jpd uses a Service Broker control, QuoteProcessor.java, to call the quote service. Since the target is dynamically specified, the @jc: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 (@jc:selector).

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 WebLogic Integration Administration Console. The WebLogic Integration Administration Console allows an administrator to specify the following properties:

Notes on Service Broker Control Annotations

This section provides information on the Service Broker control specific behavior of the following annotations:

@com.bea.wli.common.ParameterXml

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 Properties pane.

@jc:conversation

The @jc:conversation annotation specifies the role that a control's methods or callbacks play in a conversation. For more information, see "@jc:conversation annotation" in Java Control Annotations.

When you generate a Service Broker control, do not edit the phase attribute of the @jc:conversation annotation. The @jc:conversation annotation is visible in the conversation section of the Property pane.

@jc:parameter xml

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.

@com.bea.wli.common.Protocol

The @com.bea.wli.common.Protocolannotation 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@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 @jc:protocol. This attribute is not supported for use with the Service Broker control. This attribute is visible in the protocol section of the Properties pane.