writing a connector

Writing a Custom Connector

Version: 17.07

Developer Guide

Overview

Project-X Framework provides you the ability to write your own custom connector for your custom requirements. If you couldn’t find a suitable connector for your custom requirement, then the last thing that you want is to write a connector from the scratch to fulfill your requirement. Don’t worry, you don’t have to write it from the scratch by your own, we have given you the ability to write your own connector with a few lines of Java codes.

This documentation describes how to write your custom connector elements and use it in your integration flows easily.

Writing a Custom Ingress Connector

You can write your custom ingress connector using the UltraStudio by going through the following steps,

  1. Add relevant transport dependency based on the transport protocol.

Ingress Connectors will always be connected with some transport protocol to connected to fetch/ receive message from an external entity. Project-X framework contains ability to communicate through almost all the well known transport protocols, you just have to do is select the correct dependency and add it to your pom.xml. Refer the following table to find out the correct transport dependency for your connector based on the transport protocol that you are going to use.

  1. Create a java class for your custom ingress connector within the src/main/java folder in your Ultra Project. Refer the Creating a Project section for more information on creating a project in UltraStudio.

  2. Extend that class from the "org.adroitlogic.x.base.connector.IngressConnectorElement" and provide the respective ListenerConfig and IngressConfig typed parameters for the IngressConnectorElement. Find out the respective ListenerConfig and IngressConfig types for your custom ingress connector from the following table.

  3. Implement the required methods which are inherited from the IngressConnectorElement class. As an example if you are going to write a custom JMS Ingress Connector, your class skeleton should be like below at this stage.

public class CustomJMSIngressConnector extends IngressConnectorElement<JMSListenerConfig, JMSIngressConfig> {

    @Override
    protected TransportListener<JMSListenerConfig, JMSIngressConfig> newListener(ApplicationContext applicationContext) {
        return null;
    }

    @Override
    public JMSListenerConfig getListenerConfig() {
        return null;
    }

    @Override
    public JMSIngressConfig getIngressConfig() {
        return null;
    }
}
  1. Define required parameters for your custom ingress connector. Each parameter should be annotated from the @Parameter annotation and define the required values for each property of the @Parameter annotation. As an example, if you want to declare a parameter for the JMS queue name that you are going to listener via your JMS Ingress Connector, then queu name parameter would be like below,

  @Parameter(displayName = "Source queue", inputType = TEXT_BOX, placeHolder = "sample", description = "Name of the source queue")
  private String queueName;

All the defined parameters should have a getter and setter method to make it accessible to the UltraStudio and populate values for each parameter. Parameters in the Ingress Connectors are divided logically into two categories. Parameters which are related to the transport protocol level of the connectors are categorized as ListenerConfig parameters. ListenerConfig parameters should be able to use to differentiate the actual external resource that we are going to fetch/ receive the message. All other parameters which are related to the specific flow that you are going to use to initiate your integration flow should belong to the IngressConfig parameters. As an example for JMS Ingress Connector, JMS ConnectionFactory parameter should belong to the ListenerConfig since it’s one of the key parameter which will differentiate the actual JMS server that we are going to connect. Queue name will be IngressConfig parameter since it’s only specific to your integration flow.

  1. Implement the "newLister" method of your custom ingress connector class. "newLister" method is supposed to create a new transport listener instance for the transport protocol that you are going to use in your custom ingress connector. Respective transport listener types can be found from the following table for each transport protocol. Example implementation for the "newListener" method would be like below for a custom JMS Ingress Connector.

  @Override
  protected JMSTransportListener<JMSListenerConfig, JMSIngressConfig> newListener(ApplicationContext applicationContext) {
          return new JMSTransportListener(getListenerConfig());
  }
  1. Implement the "getListenerConfig" method of your custom ingress connector. This method is supposed to create and return a new instance of the JMSListenerConfig by populating it with the declared parameters related to ListenerConfig within your ingress connector. Example implementation for the "getListenerConfig" method would be like below,

  @Override
  public JMSListenerConfig getListenerConfig() {
        JMSListenerConfig listenerConfig = new JMSListenerConfig(getServerConfig());
        listenerConfig.setConnectionFactory(connectionFactory);
        listenerConfig.setCacheLevel(cacheLevel);
        listenerConfig.setConcurrentConsumers(concurrentConsumers);
        ...
        ...
        listenerConfig.setPubSubDomain(pubSubDomain);
        listenerConfig.setPubSubNoLocal(pubSubNoLocal);
        return listenerConfig;
  }
  1. Implement the "getIngressConfig" method of your custom ingress connector. This method is supposed to create and return a new instance of the JMSIngressConfig by populating it with the declared parameters related to ingress config within your ingress connector. Example implementation for the "getIngressConfig" method would be like below,

  @Override
  public JMSIngressConfig getIngressConfig() {
        JMSIngressConfig ingressConfig new JMSIngressConfig(beanName);
        ...
        return ingressConfig;
  }
  1. If you want to do custom processing at the connector level for your received message before injecting it to your integration flow and message engine, you can override the "processReceivedMessage" method. In this method you will get the access to the constructed message context object and you can do all your custom processing on that message context object.

Now you have completed the implementation of your custom ingress connector. To make it available in your connectors palate within the UltraStudio, compile the project via mvn clean install command. Then you should be able to use your custom ingress connector for your integration flows.

Writing a Custom Egress Connector

To create your custom egress connector using the UltraStudio go through the following steps,

  1. Add relevant transport dependency based on the transport protocol.

Same as in the ingress connector, you have to select the respective transport dependency for your egress connector using the following table.

  1. Create a java class for your custom ingress connector within the src/main/java folder in your Ultra Project. Refer the Creating a Project section for more information on creating a project in UltraStudio.

  2. Extend that class from the "org.adroitlogic.x.base.connector.EgressConnectorElement" and provide the respective SenderConfig and EgressConfig typed parameters for the EgressConnectorElement. Find out the respective SenderConfig and EgressConfig types for your custom ingress connector from the following table.

  3. Implement the required methods which are inherited from the EgressConnectorElement class. As an example if you are going to write a custom JMS Egress Connector, your class skeleton should be like below at this stage.

public class CustomJMSEgressConnector extends EgressConnectorElement<JMSSenderConfig, JMSEgressContext> {

    @Override
    protected TransportSender<JMSSenderConfig, JMSEgressContext> newSender(ApplicationContext applicationContext) {
        return null;
    }

    @Override
    public JMSSenderConfig getSenderConfig() {
        return null;
    }

    @Override
    public JMSEgressContext getEgressContext(XMessageContext xMessageContext) {
        return null;
    }
}
  1. Define required parameters for your custom egress connector. Each parameter should be annotated from the @Parameter annotation and define the required values for each property of the @Parameter annotation.

All the defined parameters should have a getter and setter method to make it accessible to the UltraStudio and populate values for each parameter. Parameters in the Egress Connectors are divided logically into two categories. Parameters which are related to the transport protocol level of the connectors, are categorized as SenderConfig parameters. SenderConfig parameters should be able to use to differentiate the actual external resource that we are going to send the message. All other parameters which are specific to your message sending connector element should belong to the EgressConfig parameters. As an example for JMS Egress Connector, JMS Template parameter should belong to the SenderConfig since it’s one of the key parameter which will differentiate the actual JMS server and message creation approach for the configured JMS Server that we are going to send messages. Queue name will be EgressConfig parameter since it’s only specific to your integration flow.

  1. Implement the "newSender" method of your custom egress connector class. "newSender" method is supposed to create a new transport sender instance for the transport protocol that you are going to use in your custom egress connector. Respective transport sender types can be found from the following table for each transport protocol. Example implementation for the "newSender" method would be like below for a custom JMS Ingress Connector.

  @Override
  protected JMSTransportSender<JMSSenderConfig, JMSEgressContext> newSender(ApplicationContext applicationContext) {
          return new JMSTransportSender(getListenerConfig());
  }
  1. Implement the "getSenderConfig" method of your custom egress connector. This method is supposed to create and return a new instance of the JMSSenderConfig by populating it with the declared parameters related to SenderConfig within your egress connector. Example implementation for the "getSenderConfig" method would be like below,

  @Override
  public JMSSenderConfig getSenderConfig() {
        JMSSenderConfig senderConfig = new JMSSenderConfig(getServerConfig());
        jmsSenderConfig.setTemplate(template);
        ...
        ...
        return senderConfig;
  }
  1. Implement the "getEgressContext" method of your custom egress connector. This method is supposed to create and return a new instance of the JMSEgressContext by populating it with the declared parameters related to egress config within your egress connector. Example implementation for the "getEgressContext" method would be like below,

  @Override
  public JMSEgressContext getEgressContext() {
        JMSEgressContext jmsEgressContext = new JMSEgressContext(destination);
        jmsEgressContext.setMetaInfoPopulator(metaInfoPopulator);
        ...
        return jmsEgressContext;
  }

Now you have completed the implementation of your custom egress connector. To make it available in your connectors palate within the UltraStudio, compile the project via mvn clean install command. Then you should be able to use your custom egress connector for your integration flows.

Ingress Connector Information

Transport Protocol

Dependency

Listener Class

ListenerConfig Class

IngressConfig Class

HTTP-NIO

<dependency> <groupId>org.adroitlogic.x.transports</groupId> <artifactId>x-transport-nio-http</artifactId> <version>17.07</version> </dependency>

NIOHttpListener

HttpListenerConfig

HttpIngressConfig

HTTPS-NIO

<dependency> <groupId>org.adroitlogic.x.transports</groupId> <artifactId>x-transport-nio-http</artifactId> <version>17.07</version> </dependency>

NIOHttpsListener

HttpsListenerConfig

HttpIngressConfig

Spring JMS

<dependency> <groupId>org.adroitlogic.x.transports</groupId> <artifactId>x-transport-jms</artifactId> <version>17.07</version> </dependency>

JMSTransportListener

JMSListenerConfig

JMSIngressConfig

SFTP

<dependency> <groupId>org.adroitlogic.x.transports</groupId> <artifactId>x-transport-sftp</artifactId> <version>17.07</version> </dependency>

SFTPTransportListener

SFTPListenerConfig

SFTPIngressConfig

SCP

<dependency> <groupId>org.adroitlogic.x.transports</groupId> <artifactId>x-transport-scp</artifactId> <version>17.07</version> </dependency>

SCPTransportListener

SCPListenerConfig

SCPIngressConfig

Local File

<dependency> <groupId>org.adroitlogic.x.transports</groupId> <artifactId>x-transport-file</artifactId> <version>17.07</version> </dependency>

FileTransportListener

FileListenerConfig

FileIngressConfig

Local NIO File

<dependency> <groupId>org.adroitlogic.x.transports</groupId> <artifactId>x-transport-nio-file</artifactId> <version>17.07</version> </dependency>

NIOFileTransportListener

NIOFileListenerConfig

NIOFileIngressConfig

Timer

<dependency> <groupId>org.adroitlogic.x.transports</groupId> <artifactId>x-transport-timer</artifactId> <version>17.07</version> </dependency>

TimerTaskTransportListener

TimerListenerConfig

TimerIngressConfig

AMQP

<dependency> <groupId>org.adroitlogic.x.transports</groupId> <artifactId>x-transport-amqp</artifactId> <version>17.07</version> </dependency>

AMQPTransportListener

AMQPListenerConfig

AMQPIngressConfig

Database

<dependency> <groupId>org.adroitlogic.x.transports</groupId> <artifactId>x-transport-db</artifactId> <version>17.07</version> </dependency>

DBTransportListener

DBListenerConfig

DBIngressConfig

Mail

<dependency> <groupId>org.adroitlogic.x.transports</groupId> <artifactId>x-transport-mail</artifactId> <version>17.07</version> </dependency>

MailTransportListener

MailListenerConfig

MailIngressConfig

FIX

<dependency> <groupId>org.adroitlogic.x.transports</groupId> <artifactId>x-transport-fix</artifactId> <version>17.07</version> </dependency>

FIXTransportListener

FIXListenerConfig

FIXIngressConfig

Egress Connector Information

Transport Protocol

Dependency

Sender Class

SenderConfig Class

EgressContext Class

HTTP-NIO

<dependency> <groupId>org.adroitlogic.x.transports</groupId> <artifactId>x-transport-nio-http</artifactId> <version>17.07</version> </dependency>

NIOHttpSender

HttpSenderConfig

HttpEgressContext

HTTPS-NIO

<dependency> <groupId>org.adroitlogic.x.transports</groupId> <artifactId>x-transport-nio-http</artifactId> <version>17.07</version> </dependency>

NIOHttpsSender

HttpsSenderConfig

HttpEgressContext

Spring JMS

<dependency> <groupId>org.adroitlogic.x.transports</groupId> <artifactId>x-transport-jms</artifactId> <version>17.07</version> </dependency>

JMSTransportSender

JMSSenderConfig

JMSEgressContext

SFTP

<dependency> <groupId>org.adroitlogic.x.transports</groupId> <artifactId>x-transport-sftp</artifactId> <version>17.07</version> </dependency>

SFTPTransportSender

SFTPSenderConfig

FileEgressContext

SCP

<dependency> <groupId>org.adroitlogic.x.transports</groupId> <artifactId>x-transport-scp</artifactId> <version>17.07</version> </dependency>

SCPTransportSender

SCPSenderConfig

FileEgressContext

Local File

<dependency> <groupId>org.adroitlogic.x.transports</groupId> <artifactId>x-transport-file</artifactId> <version>17.07</version> </dependency>

FileTransportSender

FileSenderConfig

FileEgressContext

AMQP

<dependency> <groupId>org.adroitlogic.x.transports</groupId> <artifactId>x-transport-amqp</artifactId> <version>17.07</version> </dependency>

AMQPTransportSender

AMQPSenderConfig

AMQPEgressContext

Database

<dependency> <groupId>org.adroitlogic.x.transports</groupId> <artifactId>x-transport-db</artifactId> <version>17.07</version> </dependency>

DBTransportSender

DBSenderConfig

DBEgressContext

Mail

<dependency> <groupId>org.adroitlogic.x.transports</groupId> <artifactId>x-transport-mail</artifactId> <version>17.07</version> </dependency>

MailTransportSender

MailSenderConfig

MailEgressContext

FIX

<dependency> <groupId>org.adroitlogic.x.transports</groupId> <artifactId>x-transport-fix</artifactId> <version>17.07</version> </dependency>

FIXTransportSender

FIXSenderConfig

FIXEgressContext

IBM MQ

<dependency> <groupId>org.adroitlogic.x.transports</groupId> <artifactId>x-transport-mq-ibm</artifactId> <version>17.07</version> </dependency>

IBMMQTransportSender

IBMMQSenderConfig

IBMMQEgressContext

HTTP-Netty

<dependency> <groupId>org.adroitlogic.x.transports</groupId> <artifactId>x-transport-netty-http</artifactId> <version>${project-x.version}</version> </dependency>

NettyHttpTransportSender

NettyHttpSenderConfig

NettyHttpEgressContext

In this topic
In this topic
Contact Us