Using Multiple Regions

You can use multiple regions by having the client code send the optional SOAP header element, Router, in the SOAP request. If the Router element is present in the header, Process Engine Web Services uses the specified value as the connection point for the request. If the Router element is not present, the default connection point (PEWSConnectionPoint) is used.

The Router element has the following format for a fully qualified connection point URL:


   connection_point_name

For example:


    <Router xmlns="http://www.filenet.com/ns/fnpe/2004/06/ws/schema">connectionPoint2</Router>

You can specify only the connection point name when you use a simple connection point URL.

Examples

The following examples are for IBM® WebSphere® Studio and the Microsoft .NET framework. For useful information for other toolkits, see Other Toolkits Supporting JAX-RPC.

WebSphere Studio

To create custom SOAP headers, you need to install a handler class that extends the JAX-RPC handler (javax.xml.rpc.handler.*). Here is a working example:


import javax.xml.namespace.QName;
import javax.xml.rpc.JAXRPCException;
import javax.xml.rpc.handler.soap.SOAPMessageContext;
import javax.xml.rpc.handler.*;
import javax.xml.rpc.soap.SOAPFaultException;
import javax.xml.soap.Name;
import javax.xml.soap.SOAPElement;
import javax.xml.soap.SOAPEnvelope;
import javax.xml.soap.SOAPHeaderElement;
import javax.xml.soap.SOAPFactory;
import javax.xml.soap.SOAPHeader;

import java.util.Map;

public class ClientHandler extends GenericHandler{
    public static final QName AUTH_HEADER = new QName("http://schemas.xmlsoap.org/ws/2002/12/secext", "Security");
    public static final QName USERNAME_TOKEN = new QName("http://schemas.xmlsoap.org/ws/2002/12/secext", "UsernameToken");
    public static final QName USER_NAME = new QName("http://schemas.xmlsoap.org/ws/2002/12/secext", "Username");
    public static final QName PASSWORD = new QName("http://schemas.xmlsoap.org/ws/2002/12/secext", "Password");
    public static final QName ROUTER = new QName("http://www.filenet.com/ns/fnpe/2004/06/ws/schema", "Router");
    
    public static final String USER_NAME_KEY = "user";
    public static final String PASSWORD_KEY  = "password";
    public static final String ROUTER_KEY = "router";
    private String userName = null;
    private String password = null;
    private String router = null;
    QName qn[] = null;
    
    public void init(HandlerInfo info)
    {
        qn = info.getHeaders();
        java.util.Map m = info.getHandlerConfig();
        userName = (String)m.get("user");
        password = (String)m.get("password");
        router = (String)m.get("router");
    }
    
    public QName[] getHeaders()
    {
        return qn;
    }
    
    public boolean handleRequest(MessageContext context)
    {
        try {
            // test if userName and password exist
            System.out.println("Name is " + userName);
            System.out.println("Password is "+password);
            System.out.println("Router is "+router);
            if(userName == null || password == null) {
                throw new JAXRPCException("username or password null");
            }
            
            
            SOAPMessageContext messageContext = (SOAPMessageContext) context;
            
            
            // gets the SOAP header for authentication
            SOAPHeader header = messageContext.getMessage().getSOAPPart().getEnvelope().getHeader();
            SOAPEnvelope se = messageContext.getMessage().getSOAPPart().getEnvelope();
            
            // adds the authetication header
            Name name = se.createName(AUTH_HEADER.getLocalPart(), null, AUTH_HEADER.getNamespaceURI());
            SOAPHeaderElement element = header.addHeaderElement(name);
            
            SOAPElement usernameTokenElement = element.addChildElement(USERNAME_TOKEN.getLocalPart(), "", USERNAME_TOKEN.getNamespaceURI());
            
            SOAPElement userNameElement = usernameTokenElement.addChildElement(USER_NAME.getLocalPart(), "", USER_NAME.getNamespaceURI());
            userNameElement.addTextNode(userName);
            SOAPElement passwordElement = usernameTokenElement.addChildElement(PASSWORD.getLocalPart(), "", PASSWORD.getNamespaceURI());
            passwordElement.addTextNode(password);
            
            // gets the SOAP header for router
            if (router!=null && router.length()>0) {
                SOAPHeader router_header = messageContext.getMessage().getSOAPPart().getEnvelope().getHeader();
                SOAPEnvelope router_se = messageContext.getMessage().getSOAPPart().getEnvelope();
                
                // adds the router header
                Name router_name = router_se.createName(ROUTER.getLocalPart(), null, ROUTER.getNamespaceURI());
                SOAPHeaderElement router_he = router_header.addHeaderElement(router_name);
                // adds the router information
                SOAPElement router_element = router_he.addChildElement(ROUTER.getLocalPart(), "", ROUTER.getNamespaceURI());
                router_he.addTextNode(router);
            } // if (router!=null && router.length>0)
        } catch (Exception e) {
            throw new JAXRPCException(e);
        }
        return true;
    }
    
    public boolean handleResponse(MessageContext context)
    {
        try {
            // test if userName and password exist
            System.out.println("Name is " + userName);
            System.out.println("Password is "+password);
            System.out.println("Router is "+router);
            if(userName == null || password == null) {
                throw new JAXRPCException("username or password null");
            }
            
            SOAPMessageContext messageContext = (SOAPMessageContext) context;
            
            // gets the SOAP header
            SOAPHeader header = messageContext.getMessage().getSOAPPart().getEnvelope().getHeader();
            SOAPEnvelope se = messageContext.getMessage().getSOAPPart().getEnvelope();
            
            // adds the authetication header
            Name name = se.createName(AUTH_HEADER.getLocalPart(), null, AUTH_HEADER.getNamespaceURI());
            SOAPHeaderElement element = header.addHeaderElement(name);
            
            SOAPElement usernameTokenElement = element.addChildElement(USERNAME_TOKEN.getLocalPart(), "", USERNAME_TOKEN.getNamespaceURI());
            
            SOAPElement userNameElement = usernameTokenElement.addChildElement(USER_NAME.getLocalPart(), "", USER_NAME.getNamespaceURI());
            userNameElement.addTextNode(userName);
            SOAPElement passwordElement = usernameTokenElement.addChildElement(PASSWORD.getLocalPart(), "", PASSWORD.getNamespaceURI());
            passwordElement.addTextNode(password);
            // gets the SOAP header for router
            if (router!=null && router.length()>0) {
                SOAPHeader router_header = messageContext.getMessage().getSOAPPart().getEnvelope().getHeader();
                SOAPEnvelope router_se = messageContext.getMessage().getSOAPPart().getEnvelope();
                
                // adds the router header
                Name router_name = router_se.createName(ROUTER.getLocalPart(), null, ROUTER.getNamespaceURI());
                SOAPHeaderElement router_he = router_header.addHeaderElement(router_name);
                // adds the router information
                SOAPElement router_element = router_he.addChildElement(ROUTER.getLocalPart(), "", ROUTER.getNamespaceURI());
                router_he.addTextNode(router);
            } // if (router!=null && router.length>0)
        } catch (Exception e) {
            throw new JAXRPCException(e);
        }
        return true;
    }
}

.NET

To create custom SOAP headers, use a custom output filter to insert the Router element into the SOAP header of the outgoing message. The following code example demonstrates a C# class that extends SoapOutputFilter:


using System;
using System.Xml;
using Microsoft.Web.Services2;
using Microsoft.Web.Services2.Configuration;


namespace PE_C_Sharp_solution
{ 
public class PEHeaderFilter : SoapOutputFilter
{
        public PEHeaderFilter()
        {
        }
        public override void ProcessMessage(SoapEnvelope envelope)
        {
            if (envelope == null) throw new ArgumentNullException("envelope");
            string router = (string)envelope.Context["router"];
            if (router!=null)
            {
                XmlElement soapHeader = envelope.CreateHeader();
                XmlElement routerHeader = envelope.CreateElement("Router", "http://www.filenet.com/ns/fnpe/2004/06/ws/schema");         
                routerHeader.InnerText =router;
                soapHeader.AppendChild(routerHeader);
            }

        }
        public static void InstallPEHeaderFilter()
        {
            SoapOutputFilterCollection outputFilters =
                WebServicesConfiguration.FilterConfiguration.OutputFilters;
            outputFilters.Add(new PEHeaderFilter());
        }
    }
}

The ProcessMessage method retrieves the router information from the SOAP context and creates the SOAP header. The InstallPEHeaderFilter method provides a way for the application to install this filter. This method is called once at program start as shown in the following example:


static void Main() 
{           
    PEHeaderFilter.InstallPEHeaderFilter ();
    Application.Run(new Form1());
}

Before a web service method is invoked, in addition to setting the user name and password, the router value is initialized in the RequestSoapContext method as follows:


peWS.ProcessEngineServiceWse peSession = new peWS.ProcessEngineServiceWse();

UsernameToken tok = new UsernameToken(peUsername, pePassword, PasswordOption.SendPlainText);      
peSession.RequestSoapContext.Security.Tokens.Add(tok);
peSession.RequestSoapContext["router"]=peRouter;

Other Toolkits Supporting JAX-RPC

If you use a web services toolkit other than WebSphere Studio, you must also install a handler class that extends the Java™ API for XML-based Remote Procedure Call (JAX-RPC) handler (javax.xml.rpc.handler.*). Although the procedure for installing the handler is toolkit-specific (and not covered here), the implementation of the handleRequest method is common to all toolkits. The router name is passed as a property in the toolkit-specific SOAP message context parameter.