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

        /**
         * @jc:conversation phase="start"
         * @jc:selector xquery ::
         *     lookupTPMProperties($request/vendorID, $request/vendorID2) ::
         */
        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://edocs.bea.com/wli/docs81/tpintro/index.html. To learn about adding or updating information in the TPM repository, see Trading Partner Management in Managing WebLogic Integration Solutions at http://edocs.bea.com/wli/docs81/manage/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 JCX 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 Managing WebLogic Integration Solutions at http://edocs.bea.com/wli/docs81/manage/processconfig.html.

DynamicProperties.xml contains a sequence of <control> elements, one for each dynamic control JCX file. Each <control> element has a name attribute whose value is the fully-qualified Java class name of a JCX 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.jcx, 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 JCX 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);
        }

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

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

- Endpoint URI
- Protocol to use when making the call: http-soap, http-xml, jms-soap, jms-xml, form-get and form-post. The default is http-soap.

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.

- Any credentials needed to make the call:

- User name and password to invoke the remote service (base authentication)
- Certificate alias and password, if the remote service requires SSL with two-way authentication
- Certificate alias and password, if digital signature is required
- Keystore location, password and type, in case a client certificate is required