Customisation Guide

The following diagram illustrates the main activity in SupplierConnect.

A listener is an object that is waiting to receive an incoming message. The listener may parse the message, convert it into a format for dispatch. The sample configuration uses a HTTP servlet listener (ListenerServlet) which listens for messages via HTTP POST, and passes the POSTed contents to the dispatcher bean.

The HTTP listener is configured via the web-app descriptor web.xml. The same servlet class is used to provide different servlets for cxml and BASDA eBIS-XML messages.

<!--
    Configure an instance of the ListenerServlet to listen for cXML
    order messages.
-->
<servlet>
    <servlet-name>CxmlOrderServlet</servlet-name>
    <servlet-class>com.kenisys.supplierconnect.web.ListenerServlet</servlet-class>
    <init-param>
        <param-name>listener-name</param-name>
        <param-value>cxml-orders</param-value>
    </init-param>
</servlet>

<!--
    Configure an instance of the ListenerServlet to listen for eBIS-XML
    order messages.
-->
<servlet>
    <servlet-name>BasdaOrderServlet</servlet-name>
    <servlet-class>com.kenisys.supplierconnect.web.ListenerServlet</servlet-class>
    <init-param>
        <param-name>listener-name</param-name>
        <param-value>ebisxml-orders</param-value>
    </init-param>
</servlet>

NB: This section is from /config/merge/servlets.xml, which is merged into web.xml by xdoclet during the build.

The HTTP listener provided in the sample configuration enables SupplierConnect to receive cXML purchase orders from the ASN. A listener may be any type of object which can receive messages and pass them to the dispatcher. Examples:

• Message-driven EJBs - to receive message notification from a JMS queue
• SOAP Web Service
• File/Folder watcher
• POP mail reader

By creating custom listener classes, SupplierConnect is ready to support any type of integration process.

The Pipeline Dispatcher session bean is the main entry point for messages entering SupplierConnect via listeners. The dispatcher reads it's configuration from a file supplierconnect-config.xml which defines a handler pipeline for messages coming from each listener.

The dispatcher performs the following steps

• matches the incoming message to a pipeline
• creates and configures a PipelineContext and PipelineResponse
• calls each Handler configured in the pipeline in turn
• replies to the listener with the PipelineResponse

The cXML order pipeline configuration is displayed below:

<!-- cXML order listener -->
<listener name="cxml-orders">
    <pipeline>
        
        <!-- 
            pipeline is an ordered list of handlers to process 
        -->
        <handler-ref id="setupCxmlPipeline" />
        <handler-ref id="parseCxml" />
        <handler-ref id="senderCredentialValidator" />
        <handler-ref id="fromCredentialValidator" />
        <handler-ref id="transformXml">
            <params>
                <param name="stylesheet">cxml2internal.xsl</param>
            </params>
        </handler-ref>
        <handler-ref id="xmlToFile">
            <params>
                <param name="filePath">%temp%</param>
            </params>
        </handler-ref>
        
        <!-- 
            optional interrupt-handler executes if a handler indicates
            early termination
        -->
        <!--<interrupt-handler-ref id="xxx" />-->
    </pipeline>
</listener>

Handlers are registered earlier in the config file, an example:

<!-- cXML handlers: Parse String to cXML Document -->
<handler id="parseCxml" type="POJO">
    <class>com.kenisys.supplierconnect.cxml.ParseCxmlHandler</class>
    <params>
        <!-- optionally ignore the DOCTYPE declaration and use this dtd -->
        <param name="dtd-override">cXML.dtd</param>
    </params>
</handler>

Handler registration includes parameters, which apply to the use of that handler in any pipeline. In a specific pipeline those parameters can be overriden, however. This is shown in the cXML order pipeline above - the transformXML handler is provided with a 'stylesheet' parameter specific to this pipeline. The configuration of handlers in this way is to promote the re-use of handlers between pipelines.

When handlers in a pipeline are executed, the dispatcher provides a PipelineContext instance to each handler. The context is a map which can hold any object keyed by a string, as well as some predefined bean properties. The context holds the message from the listener (get/setMessage()) as well as the message parsed to XML (if applicable - get/setMessageXML()).

It's worth noting that some handlers will alter the content of the message. The TransformXMLHandler performs an XSL transformation, and updates the XML message stored in the context. For reference, the original content is stored in the context under the key 'original-xml'.

The PipelineResponse is a simple holder for the results of a pipeline execution. The default pipeline response contains only a String response.

A pipeline handler can replace the pipeline response with a specific sub-class of PipelineResponse using the setResponse() method of the PipelineContext. This is used in the cXML orders pipeline in the sample configuration. The first handler (setupCxmlPipeline) creates a new CxmlPipelineResponse and replaces the default reponse in context.

To create a handler, implement the interface RequestHandler. Implement the method process() to provide your action logic.

Handlers can be implemented as plain java objects by just implementing the RequestHandler interface. They are registered in the config.xml like this:

                 
<handler id="parseCxml" type="POJO">
    <class>com.kenisys.supplierconnect.cxml.ParseCxmlHandler</class>
    <params>
        <!-- optionally ignore the DOCTYPE declaration and use this dtd -->
        <param name="dtd-override">cXML.dtd</param>
    </params>
</handler>

Session EJBs can be used as handlers in a pipeline. XDoclet is used in the sample configuration for EJB handlers. See an example in SenderCredentialValidatorBean. Further XDoclet tags are required to specify transaction requirements.

Session Bean handlers are registered in the config.xml like this:

                 
<handler id="senderCredentialValidator" type="EJB">
    <jndi>java:comp/env/ejb/SenderCredentialValidatorLocal</jndi>
    <params>
        <!-- all valid sender credentials -->
        <param name="validCredentials">
            <credential domain="AribaNetworkUserId">
                <identity>sysadmin@ariba.com</identity>
                <shared-secret>abracadabra</shared-secret>
            </credential>
        </param>
    </params>
</handler>

Please join the user mailing list and ask your question there. We'll try to help as much as possible!