openadaptor™ Feb 2007 1
What is openadaptor?
Openadaptor is a Java software toolkit for Enterprise Application 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
The toolkit provides software components for connecting to a variety of transports
(e.g. JMS, Tibco, RDBMS, SOAP, HTTP, SMTP, Files). It provides components for
“working with” different data representations (e.g. XML, JDBC result sets, fixed width
and delimited string records); however it is not tied to any specific data
The framework includes support for transactions (local or JTA), 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
All openadaptor components are Java Beans 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 2007 2
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”.
All 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.
XML XSLT XML
Read Filter Write
Converter Processor Validator
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 2007 3
The three fundamental components in openadaptor are as follows…
Read Connector These connect to an external resource and
receive / poll data
Processor These operate on data, either by transforming
it in someway or discarding it
Write Connector These connect to an external resource and
send / publish data.
Logically an adaptor looks like this…
Resource Object Processor Object Resource
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
The simplest adaptor it is possible to configure looks like this…
Processors components can be chained together like this…
Read Processor Processor Processor Write
Connector 1 2 3 Connector
As stated above, an adaptor can have multiple write connectors, like this…
External Write External
Resource Connector Resource
A 1 B
openadaptor™ Feb 2007 4
Adaptors can also have multiple read connectors, like this…
External Read External
Resource Connector Processor Resource
A 1 B
Adaptors can also have multiple distinct “pipelines”, like this…
External Read Write External
Resource Connector Connector Resource
A 1 1 B
External Read Write External
Resource Connector Connector Resource
C 2 2 D
For simple adaptors (see example spring configurations and code) a developer only
needs to deal with Connectors and Processors and specify how they are “chained
together”. The standard framework Adaptor and Pipeline components will “auto box”
the Connectors and Processors in the appropriate adaptor framework components.
The rest of the section provides more details about the adaptor framework.
Within the adaptor framework the Connectors and Processors 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.
Read Node Read Connector (and optionally a Processor)
Processor Node Processor
Write Node Write Connector (and optionally a Processor)
Where as the fundamental components (Connectors 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
openadaptor™ Feb 2007 5
Nodes are typically managed by an Adaptor component. This co-ordinates the
lifecycle and allows Adaptor Read Nodes to initiate the processing of messages. The
following diagram illustrates a typical adaptor configuration.
Message / Response
Message / Response Pipeline / Router
Message / Response Message / Response
Read Node Processor Node Write Node
Resource Read Processor Processor Write Resource
A Processor B
Connector (optional) (optional) Connector
A Pipeline / Router is a component that “knows” how the Nodes are chained together.
A 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
The Adaptor delegates the message routing to a Pipeline or Router. But it is worth
noting that all the adaptor components (Node subclasses, Adaptor, Router and
Pipeline) actually implement the same interface (IMessageProcessor). So it is
perfectly legitimate to couple Nodes together directly or for an Adaptor to delegate
directly to a Node. You are also free to develop complimentary frameworks which use
Nodes, Connectors, Processors, Routers and Pipelines.
openadaptor™ Feb 2007 6
Key interfaces and classes
The components described in the previous section are illustrated in the following
implements has a implements has a implements
org.oa3.core.adaptor org.oa3.core.node.Node org.oa3.core.router.Router
has one or more
may have a
implements extends extends
has a has a
org.oa3.core.IReadConnector org.oa3.core.IDataProcessor org.oa3.core.IWriteConnector
connect() Exception validate() connect()
disconnect() reset() disconnect()
isDry() Object process(Object) Object deliver (Object)
The following interfaces and classes are core to lifecycle management.
String getState() org.oa3.core.lifecycle.ILifecylceListener
setState(String) has zero
boolean isState(IState) or many stateChanged(IComponent, IState)
openadaptor™ Feb 2007 7
Distribution and Code Organisation
The distribution of openadaptor contains jar files, example code and documentation.
There are a number of jars
openadaptor.jar The openadaptor code
openadaptor-depends.jar The single jar of the core third-party code upon
which the openadaptor code depends
openadaptor-spring.jar 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 Contains core interfaces and implementations
org.openadaptor.auxil Contains connectors and processors that rely
on the core java and javax packages.
Processors that convert between data
representations are referred to as convertors.
org.openadaptor.thirdparty contains connectors and processors that rely
on third-party software
org.openadaptor.spring Contains components that directly use the
Why the re-write?
Openadaptor was originally developed in 1997, 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 2Mb, this reflects how we have attempted to “boil
down” openadaptor to what we feel is original and worthwhile.
openadaptor™ Feb 2007 8