Orbeon Forms User Guide

Delegation Processor

1. Introduction

The Delegation processor allows calling services implemented as:

  • A JavaBean
  • An EJB
  • A Web service

The main benefit of the Delegation processor is that you do not need to implement your own XML processor in Java to call services.

2. Inputs and Outputs

Type Name Purpose Mandatory
Input interface

The interface input declares services that you can then call in the call input. You define one or more service identifiers and map those to a given JavaBean, EJB or Web service. You also need to provide information that the delegation processor needs to call the service: for instance a JNDI name for an EJB or a class name for a JavaBean.

The interface input is the only document with information specific to the service type (EJB, Web service or JavaBean). This means that if, at some point, a service is moved from, say, a JavaBean to an EJB, ohly the interface has to be modified, but not the call input.

Yes
Input call
  • The call input contains an XML document which is a template containing <delegation:execute> elements.
  • The <delegation:execute> element must be in the http://orbeon.org/oxf/xml/delegation namespace. The delegation prefix is usually mapped to this namespace.
  • Each <delegation:execute> element specifies a service to be called and the parameters to be sent to that service.
  • For calls to JavaBeans and EJBs in particular, it is important that the resulting document be a well-formed XML document. In particular, the resulting document must have a root element. In this case, always be sure that your call input contains at least one root element around <delegation:execute> elements.
Yes
Output data The data output produces a document based on the call input where the <delegation:execute> elements have been replaced with the value returned by the service. Yes

3. Calling a JavaBean

This is an example of using the Delegation processor to call a JavaBean:

<p:processor name="oxf:delegation"><p:input name="interface"><config><service id="my-service" type="javabean" class="MyClass"/></config></p:input><p:input name="call"><result><delegation:execute service="my-service" operation="myMethod"><param1 xsi:type="xs:string">param1</param1></delegation:execute></result></p:input><p:output name="data" id="result"/></p:processor>

  • The interface input declares the JavaBean to call:

    • The value of the type attribute must be set to javabean.
    • The class attribute references the Java class to instanciate.

  • The call input defines the method to call and the parameters to pass:

    • The service attribute references the service id declared in the interface input.
    • Each child element of <delegation:execute> corresponds to a parameter of the method to be called, in the order they appear in the method signature. The value in the xsi:type attribute must match the parameter type. The content of the element is the value passed to the Java method.
      • Note
      Note: the only two supported types are: xs:string and xs:double.

4. Calling an EJB

This is an example of using the Delegation processor to call an EJB:

<p:processor name="oxf:delegation"><p:input name="interface"><config><service id="creditcard-validation" type="stateless-ejb" uri="java:comp/env/ejb/creditcard-validation"/></config></p:input><p:input name="call"><delegation:execute service="creditcard-validation" operation="validate"><number xsi:type="xs:string">1234123412341234</number><type xsi:type="xs:string">visa</type></delegation:execute></p:input><p:output name="data" id="result"/></p:processor>

  • The interface input declares the EJB that will be called:

    • The value of the type attribute must be set to stateless-ejb.
    • The uri attribute references the JNDI name of the EJB.

  • The call input defines the method to be called and the parameters:

    • The service attribute references the service id declared in the interface input.
    • Each child element of <delegation:execute> corresponds to an attribute of the method to be called. The name of each element must match the attribute name, and the value in the xsi:type attribute must match the attribute type. The content of the element is the value passed to the EJB method.

5. Calling a Web Service

5.1. Example: RPC-Style

<p:processor name="oxf:delegation"><p:input name="interface"><config><service id="quotes" type="webservice" style="rpc" endpoint="http://www.scdi.org/~avernet/webservice/"><operation nsuri="urn:avernet" name="getRandomQuote" encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"/></service></config></p:input><p:input name="call"><delegation:execute service="quotes" operation="getRandomQuote"/></p:input><p:output name="data" id="result"/></p:processor>

5.2. Example: Document-Style

<p:processor name="oxf:delegation"><p:input name="interface"><config><service id="stock-quote" type="webservice" style="document" endpoint="http://ws.cdyne.com/delayedstockquote/delayedstockquote.asmx"><operation name="get-quote" soap-action="http://ws.cdyne.com/GetQuote"/></service></config></p:input><p:input name="call"><delegation:execute service="stock-quote" operation="get-quote" xsl:version="2.0"><m:GetQuote><m:StockSymbol>IBM</m:StockSymbol><m:LicenseKey>0</m:LicenseKey></m:GetQuote></delegation:execute></p:input><p:output name="data" id="result"/></p:processor>

5.3. Usage

  • The interface input declares the Web service to be called:

    • Valid values for the style attribute are rpc and document. The default value if the attribute is missing is rpc.
    • The id (referenced when Web service is called in the call input) and endpoint (the SOAP endpoint) attributes are mandatory.
    • Declaring the Web service operations is optional for document-style services. You only need to do so if you want to specify a SOAP action for a given operation.
    • Optionally you can declare for each operation the encoding style (encodingStyle attribute) and SOAP action (soap-action attribute).
    • Optionally you can declare what part of the SOAP result document is returned by specifying an XPath expression in the optional select attribute on the operation element. If you don't specify an expression, by default when the style is RPC the content of the first child element under the SOAP body is returned, and when the style is document the content of the SOAP body is returned.
    • By default, if the web service returns a SOAP fault, the delegation processor throws an exception. If you set the return-fault attribute on the <service> element to true, then the SOAP fault document is returned.

  • In the call input:

    • The XML fragment you specify in the execute element is sent as is, and you are responsible of making sure that it is valid according to the encoding style.
    • Referencing a specific operation in the operation attribute is mandatory for RPC-style services, and is optional for document-style services (you only want to do so if you declared specific information about the operation in the interface input).
    • The optional timeout attribute on the execute element specifies a connection timeout in milliseconds. The value must be a non-negative integer, with the value 0 meaning no timeout. If not specified, the timeout value is the default timeout of the underlying web service implementation.