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 will use 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:
rmi:host:port/connection_point_name
For example:
<Router xmlns="http://www.filenet.com/ns/fnpe/2004/06/ws/schema">
rmi://localhost:32771/connectionPoint2</Router>
You can specify only the connection point name when using a simple connection point URL.
Examples
Examples are provided below for IBM® WebSphere® Studio and the Microsoft® .NET framework. Refer to Other Toolkits Supporting JAX-RPC for useful information for other toolkits.
WebSphere Studio
To create custom SOAP headers, you need to install a handler class that extends the JAX-RPC handler (javax.xml.rpc.handler.*). The following 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 is an example of a C# class extending 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 should be called once at program start. For example:
static void Main()
{
PEHeaderFilter.InstallPEHeaderFilter ();
Application.Run(new Form1());
}
|
Prior to invoking a web service method, in addition to setting the username and password, the router value should be initialized in RequestSoapContext 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;
|
If you are using a web services toolkit other than WebSphere Studio, you will also need to 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.