| Oracle Agile Engineering Data Management Enterprise Integration Platform Development Guide for Agile Release e6.2.0.0 E52569-01 |
|
 Previous |
 Next |
| Oracle Agile Engineering Data Management Enterprise Integration Platform Development Guide for Agile Release e6.2.0.0 E52569-01 |
|
Previous |
Next |
The configuration file is based on XML. Upon the startup of the Enterprise Integration Platform, the controller reads the configuration file in order to know which connectors need to be started etc.
The configuration data is converted into an internal XML Data Object (XDO), which the controller provides to each connector. The connector itself is responsible for pulling the connector-specific information out of the configuration XDO.
Below is an example of the minimum configuration for a connector. The tags "name", "version", "class" and "active" are required.
<connector name="example" version="2.2.0" active="false" class="com.eigner.eai.connector.ExampleConnector"></connector>
In detail, adding a connector would require to add a section for this specific connector. It depends on the functionality of the connector, what information needs to be provided e.g. connection parameters or available functions of the interface. It is recommended to put all connection related parameters under a connection tag that can be accessed easily from within the connector's source code.
<connector name="plm" version="2.2.0" active="true" class="com.eigner.eai.connector.plm.PlmConnector">
…
<connectionname="default" active="true">
<host>plm_server</host>
<socket>16067</socket>
<env>axalantORIGIN</env>
<user>EDB-EIP</user>
<pwd>{PLM-AES-128}+YEVllbJyH1/jvIH9OgsFY21pmz8LbcuR2OWYJ7Uzog=</pwd>
<id>''</id>
<connection-timeout>300000</connection-timeout>
<call-timeout>300000</call-timeout> </connection>
…
</connector>
The connector also needs to be defined either as source or target connector in the workflow area. This describes the initial direction of the data transfer:
<workflow name="plm-erp" active="true" type="asynchronous">
<source>plm</source>
<target>erp</target>
<request-pipe>plm-erp</request-pipe>
<response-pipe>erp-plm</response-pipe>
</workflow>
The name and path of the mapping file (XSL) must also be provided. The mapping file is responsible for converting the XDO data from the source system format to the target system format.
<pipe name="plm-erp">
<path>${eai.conf}/plm_erp.xsl</path></pipe>
The connector itself is a Java class, which must provide (extend) certain methods like init, warmup, start, stop, and release from the connector interface (see JavaDoc for package com.eigner.eai.connector).
There are two types of connectors: synchronous and asynchronous. The most common one is the asynchronous connector.
To determine which type of connector to develop, the modes of operation are important.
Asynchronous connector
Used to gather data from its system if it is the source connector. The data is stored into a queue accessed only by the EIP through its controller and the source connector is done for now and waits for the next transfer order. The controller then reads the data from this queue and sends them to the target connector. The target connector processes the data and sends them back to the controller, which stores them into the queue again. The data is then read by controller and sent back to the source connector.
Synchronous connector
Used to gather data from its system, sends them in synchronous mode through the controller to the target connector, and waits for the results to send them to its system.
Depending on its purpose the connector must implement either the AsyncConnector interface (methods sendToController and receiveFromController) or the SyncConnector interface (method process). For convenience reasons, there are the abstract class AbstractConnector, AbstractAsyncConnector, and AbstractSyncConnector (also available from the package com.eigner.eai.connector).
An asynchronous connector usually reads the data from its system when the controller is requesting them (sendToController). This data is stored in an EIP queue, and the connector is able to process further requests. When results are returned, the controller triggers the connector by calling its receiveFromController method.
An asynchronous connector must inherit from the com.eigner.eai.connector.AsyncConnector interface. There is also an abstract base class AbstractAsyncConnector, which is recommended to be used since it already implements most of the basic methods.
|
Note: For an example please refer to the file ExampleAsyncConnector.java in the docs directory |
A synchronous connector is mostly triggered by its system, usually reads the needed data, sends them to the controller (via the connector's "process" method) and waits for the results.
A synchronous connector must inherit from the com.eigner.connector.SyncConnector interface. There is also an abstract base class AbstractSyncConnector, which is recommended to be used since it already implements most of the basic methods.
|
Note: For an example please refer to the file ExampleSyncConnector.java in the docs directory. |
The vehicle to transfer the data from controller to connector and back is a BusinessObject (BO) or a part of the BO (see JavaDoc for package com.eigner.commons.businessobject). The BO is based on a XDO (XML Data Object, see JavaDoc for package com.eigner.commons.dataobject), and consists of a control area (that is maintained by the controller) and a data area that holds the data for the connector. For further information on the structure of a BO, please refer to the Enterprise Integration Platform Administration Guide for Agile e6.2.0.0.
A connector should support at least one of the two possible modes: source mode (MODE_SOURCE) or target mode (MODE_TARGET).
Source mode means that the connector can act as a data source. It may then be used as a source in a workflow definition or in a receive activity inside a BPM process.
Target mode means that the connector can act as a data target. It may then be used as a target in a workflow definition or in an "invoke" or "reply" activity inside a BPM process.
As a convenience, there is also a mode MODE_BOTH for connectors that support both.
The mode has to be returned by the connector's getMode() method.
As a conclusion, a connector that supports MODE_SOURCE has to implement the sendToController() method, whereas a connector that supports MODE_TARGET has to implement the receiveFromController() method.
We will discuss the single connector methods now in more detail.
It is assumed that there is already a custom connector class that has been derived properly from one of the abstract base classes.
The constructor and the init method will only be called if the connector's configuration is set active in the eai_ini.xml.
public ExampleSyncConnector()
The constructor must be a default constructor (without any arguments). It must call the super constructor with the connector's class name, which will be used by the logging framework. You will have access to the logger inside the connector's source code by calling the method getLogger (). Please refer to the JavaDoc of the package com.eigner.commons.logging for further information.
It must then call the setVersion () method with a version number string (e.g. "2.2.0") that must be the same as the one defined in the connector's configuration inside the eai_ini.xml. It should be the same as the current EIP version. The controller uses these version numbers to determine if a configuration is compliant with the connector.
The version numbering consists of three numbers where the first one is the major version, the second one is the minor version and the last one is the revision version. It is required that a connector that differs only by the revision number should read its configuration of a lesser or equal revision number (e.g. a connector with version 2.2.2 should read a configuration for version 2.2.0). This is not required if the versions differ on the major or minor version.
public void init(ControllerInstance controller, String connectorName)
The controller calls this method after the constructor is called. There the connector's class members should be initialized as well as third party APIs (if any is needed to communicate with the external system).
It is required to call the super init method before all other code. Then you should read in the connector's connection configuration by calling the controller's getConnectionContext() method. For further processing of the returned element object, please refer to the JavaDoc of package com.eigner.commons.dataobject.
Each connector may have a BOR (Business Object Repository) assigned if needed that defines the calls into the external system depending on the direction (e.g. "SEND"), the business object (e.g. "BOM") and a verb (e.g. "RELEASE"). Since this BOR is highly dependent on the external system, no general advice can be given here. The BOR can be accessed inside the source code by calling the controller's getBorContext() method. The further processing of the returned element object is equivalent to the one returned by getConnectionContext()).
Then you may call the third party's API as needed to initialize it.
public void warmup() throws ConnectorException
The controller calls this method after method init() and before method start(). This allows you to do further initialization that depends on a fully initialized connector before it is started. It is mostly sufficient to not overwrite this method but to use the base class' default implementation.
public void start() throws ConnectorException
The controller calls this method when the connector should connect to its system. This is only done when the dynamic-connect feature is not activated or the connector is a source connector as defined in the workflows.
The dynamic-connect feature is an optional configuration tag for the connector inside the eai_ini.xml. For further information, please refer to the Enterprise Integration Platform Administration Guide for Agile e6.2.0.0.
public boolean sendToController() throws ConnectorException, UnavailableException
The controller calls this method periodically if the connector is derived from AsyncConnector. The interval is defined in the controller's configuration via the parameter polling-interval inside the eai_ini.xml.
This method should read data from the external system, construct a DataArea with these data, and send it to the controller. If a connection problem occurs when reading the data from the system, a UnavailableException should be thrown. If another error occurs, a ConnectorException should be thrown.
The method should return the value "true", if the controller's send() method had been called. Otherwise, the value "false" should be returned.
public boolean receiveFromController(BusinessObject bo) throws ConnectorException, UnavailableException
The controller calls this method when the controller has data that should be delivered to the connector in asynchronous mode. The connector may query the BO's control area, to determine the type of the BO (e.g. isResponse() for data sent by another connector or previously sent data via its own sendToController() method), or an error state (by calling hasError()).
This method may write data to the external system, construct a ReturnArea with this status information, and send it to the controller. If a connection problem occurs when writing the data to the system, an UnavailableException should be thrown. If another error occurs, a ConnectorException should be thrown.
The method should return the value "true", if the controller's send() method had been called. Otherwise, the value "false" should be returned.
public BusinessObject process(String id) throws ConnectorException, UnavailableExceptionpublic BusinessObject process(Collection params) throws ConnectorException, UnavailableException
The external system may call these methods when it wants to have data transferred in synchronous mode. Depending on the third party API, you may also have your own class that calls directly the controller's process() method.
The first method takes a GUID string that is used to identify and read the data from the external system.
The second method gets all the required parameters that are needed to process the synchronous request. The connector may then write the data into the external system, or just use them to construct a DataArea and call the controller's process method. If a connection problem occurs when writing the data to the system, an UnavailableException should be thrown. If another error occurs, a ConnectorException should be thrown.
The method should return the BO that is received as a return value from the controller's process() method.
public String snapshot(Collection params) throws ConnectorException, UnavailableException
The external system may call this method when it wants to have data read and stored in a snapshot field in synchronous mode. This method should not make any calls into the controller.
When running in asynchronous mode, the EIP reads the data that should be transferred not at the moment when the request is done. Depending on the polling-interval, the current amount of transfers and the availability of connectors, this is a point of time in the near or far future. To have the data collected at the moment the request is made, the snapshot() method is intended to be used. The data should be stored in the external system to be accessed later in asynchronous mode.
The method should return the GUID of the data that it has read from the external system.
public void stop() throws ConnectorException
The controller calls this method when the connector should disconnect from its system. This is done when the dynamic-connect feature is activated and the transfer has been completed or the EIP is terminating.
The dynamic-connect feature is an optional configuration tag for the connector inside the eai_ini.xml. For further information, please refer to the Enterprise Integration Platform Administration Guide for Agile e6.2.0.0.
When implementing the connector please ensure that the access to member variables is thread-safe when they are used in multiple methods.
Please have also in mind to use the smallest synchronization blocks as possible. You should not synchronize the interface methods since this may lead to locking problems on the connector itself.
