openadaptor 3. Whitepaper openadaptor Feb 007
What is openadaptor? Openadaptor is a Java software toolkit for Enterprise pplication Integration. It was written to help a large financial organisation integrate it s applications with Message Oriented Middleware. The toolkit provides a framework and components for building links between systems and various middleware solutions, what we call an adaptor in this case. The toolkit provides software components for connecting to a variety of transports (e.g. JMS, Tibco, RDMS, SOP, HTTP, SMTP, Files). It provides components for working with different data representations (e.g. XML, JDC result sets, fixed width and delimited string records); however it is not tied to any specific data representation. The framework includes support for transactions (local or JT), the ability to capture and manage processing exceptions and remote administration (JMX or HTPP). The components can be quickly wired together and allow a developer to deliver a production quality adaptor extremely quickly. The framework is designed to be as lightweight as possible it does not require any infrastructure other than the Java Runtime Environment. The framework can be used to run adaptors as standalone process, embedded in other software or deployed within application containers. The components can be used with or without the framework and writing custom components does not require extensive knowledge of the framework. ll openadaptor components are Java eans and can be used with the spring framework (http://www.springframework.org). This means that adaptor processes can be developed by writing an XML configuration file rather than having to write and compile Java code. openadaptor Feb 007
Give me an example? The possibilities for using openadaptor are broad. It can be used to link enterprise systems to a core middleware solution or it can be used to link systems together directly. It can even be used to do simple file transformation. Its flexibility reflects the technological diversity of the large organisations in which it is used. For example you may want to poll an application database for events, extract the data that relates to those events, transform the data to an XML document and publish to a JMS topic. openadaptor has components to do all of this and this simple adaptor can be assembled by configuring the components and wiring them together in a simple Pipeline. JDC XML Converter JMS JMS pplication Database ll of this can be achieved by writing a short XML configuration file. We provide a standard program to run the configuration as a stand alone process. However you are free to wire the components together using a few lines of Java code or to embed the XML configuration in any other process that uses the spring framework. Functionality can be added to the adaptor by inserting additional components in the pipeline. For instance you may want to filter out certain data, transform it into your company s enterprise business model and perhaps validate it before publishing it. JDC Filter XML Converter XSLT XML Validator JMS JMS pplication Database The adaptor can easily be system tested, by swapping out the transport specific connectors with file based connectors. When the components are used with the framework you automatically receive the benefits of the framework, for example standardized process management and remote administration. openadaptor Feb 007 3
Design The three fundamental components in openadaptor are as follows These connect to an external resource and receive / poll data These operate on data, either by transforming it in someway or discarding it These connect to an external resource and send / publish data. Logically an adaptor looks like this Object[] Object[] In that every adaptor will have one or more read connectors, zero or more processors and one or more write connectors. These are typically chained together in a pipeline. The data that flows through the pipeline is an array of Plain Old Java Objects. The simplest adaptor it is possible to configure looks like this s components can be chained together like this 3 s stated above, an adaptor can have multiple write connectors, like this C openadaptor Feb 007 4
daptors can also have multiple read connectors, like this C daptors can also have multiple distinct pipelines, like this C D For simple adaptors (see example spring configurations and code) a developer only needs to deal with s and s and specify how they are chained together. The standard framework daptor and Pipeline components will auto box the s and s in the appropriate adaptor framework components. The rest of the section provides more details about the adaptor framework. Within the adaptor framework the s and s are wrapped inside Node components. These provide the lifecycle management, exception capture, transaction management and data batching capabilities of openadaptor. There are specific subclasses of Node for the different fundamental components. wraps Node Node Node (and optionally a ) (and optionally a ) Where as the fundamental components (s and processors) are data agnostic, the adaptor components expect to receive data wrapped in a Message object and respond with a Response object. These are used to propagate context information such as the transaction and the actual data, discarded data and processing exceptions. openadaptor Feb 007 5
Nodes are typically managed by an daptor component. This co-ordinates the lifecycle and allows daptor Nodes to initiate the processing of messages. The following diagram illustrates a typical adaptor configuration. daptor Message / Response Message / Response Pipeline / Router Node Message / Response Node Message / Response Node (optional) (optional) Pipeline / Router is a component that knows how the Nodes are chained together. Pipeline is actually a simple case of a Router. It can be used when the linkage between the adaptor components is a non-branching chain and there are no complex exception capture and routing requirements. The advantage of using a Pipeline is that it requires less code (or configuration if you are using the spring framework) to assemble. The Router allows more sophisticated routing and exception management. The daptor delegates the message routing to a Pipeline or Router. ut it is worth noting that all the adaptor components (Node subclasses, daptor, Router and Pipeline) actually implement the same interface (IMessage). So it is perfectly legitimate to couple Nodes together directly or for an daptor to delegate directly to a Node. You are also free to develop complimentary frameworks which use Nodes, s, s, Routers and Pipelines. openadaptor Feb 007 6
Key interfaces and classes The components described in the previous section are illustrated in the following class diagram. java.lang.runnable org.oa3.core.imessage Response process(message) org.oa3.core.adaptor.daptor org.oa3.core.node.node org.oa3.core.router.router org.oa3.core.lifecycle.irunnable int getexitcode() has one or more org.oa3.core.router.pipeline org.oa3.core.transaction.itransactioninitiator may have a org.oa3.core.node.node org.oa3.core.node.node org.oa3.core.i connect() disconnect() isdry() Object[] next(long) Object getercontext() org.oa3.core.idata Exception[] validate() reset() Object[] process(object) org.oa3.core.i connect() disconnect() Object deliver(object[]) The following interfaces and classes are core to lifecycle management. org.oa3.core.icomponent id org.oa3.core.lifecycle.component ILifecycleComponent validate(list) start() stop() boolean isstate(istate) waitforstate(istate) addlistener(ilifecyclelistener) removelistener(ilifecyclelistener) org.oa3.core.lifecycle.lifecyclecomponent org.oa3.core.lifecycle.lifecycledelegate IComponent conponent String getstate() setstate(string) boolean isstate(istate) boolean waitforstate(istate) addlistener(ilifecyclelistener) removelistener(ilifecyclelistener has zero or many org.oa3.core.lifecycle.ilifecylcelistener statechanged(icomponent, IState) org.oa3.core.node.node openadaptor Feb 007 7
Distribution and Code Organisation The distribution of openadaptor contains jar files, example code and documentation. There are a number of jars openadaptor.jar openadaptor-depends.jar openadaptor-spring.jar The openadaptor code The single jar of the core third-party code upon which the openadaptor code depends The openadaptor code that is complimentary to the spring framework The example code area contains readme files that describe how to correctly setup the java classpath. The package structure of openadaptor is split as follows org.openadaptor.core org.openadaptor.auxil org.openadaptor.thirdparty org.openadaptor.spring Contains core interfaces and implementations Contains connectors and processors that rely on the core java and javax packages. s that convert between data representations are referred to as convertors. contains connectors and processors that rely on third-party software Contains components that directly use the spring framework Why the re-write? Openadaptor was originally developed in 997, this predated the popularity of XML and integral to openadaptor was a canonical data representation called DataObjects. DataObjects have long been regarded as non-strategic. Certain standards and technologies have evolved that we wish to accommodate. Using components of openadaptor outside the adaptor paradigm is difficult as is extending it to provide more sophisticated functionality such as workflow. Like allot of software that has been incrementally developed, some of the design and implementation was sub-optimal but retained because we didn t want to break interfaces. The latest version of the openadaptor.jar is 400K compared to the previous release which was over Mb, this reflects how we have attempted to boil down openadaptor to what we feel is original and worthwhile. openadaptor Feb 007 8