Adapter Framework

Overview

This sample opens a Visual Studio Solution that contains the Neuron ESB Adapter Framework. The Neuron ESB Adapter Framework contains all the base functions and libraries that enable custom Neuron ESB Adapter development. Developers using this framework can create rich Neuron ESB Adapters that support the message exchange patterns exposed by many of the native Neuron ESB Adapters, such as Publish, Subscribe, Request/Response and Solicit/Response mode adapters. A rich set of custom properties and metadata can be included for design time configuration within the Neuron ESB Explorer when configuring an Adapter Endpoint.

Users should read through all of the commentary found in the Visual Studio solution to learn what every piece of code accomplishes.

Visual Studio Solution

The Visual Studio solution contains one project called Esb-Name-Adapter. The project needs a reference to Neuron.Esb.dll which is contained in the instance folder of the Neuron ESB installation (e.g. C:\Program Files\Neudesic\Neuron ESB v3\DEFAULT).

In this sample, there are three C# code files that serve three different purposes. Out of the three, the two named Adapter.cs and NameAdapter.cs are partial classes that, to an extent, separate the base class functions from user defined functions, respectively. The third file CertificateConverter.cs shows users how they can access a list of certificates stored in a Neuron Configuration to use in their custom adapter at design time.

In the following documentation, system refers to whatever the adapter is designed to connect Neuron ESB to.

Adapter.cs

This class inherits from the ESBAdapterBase class and can be used as a base for all custom adapters. Generally, developers would not do anything to this class except change the class name (which must match in both partial classes), remove the adapter modes not supported, and remove the generic publish mode functions if publish/request-reply modes are not implemented or remove just the polling functions if publish/request-reply modes do not use polling.

The three overridden methods inherited from the ESBAdapterBase class are the Connect, Disconnect, and SendToEndpoint methods. Connect is called at adapter startup with the adapter mode as a parameter. This is where the adapter validates that the mode chosen for running the adapter is supported. Also, the user defined ConnectAdapter method, which resides in NameAdapter.cs, is called by the Connect method. Disconnect is called when the adapter shuts down and contains a call to the user defined method DisconnectResources. SendToEndpoint is where the user defined method SendToDataSource is called. SendToDataSource can be found in NameAdapter.cs and should contain all the logic needed to send a message received from the bus to an endpoint (i.e. Subscribe/SolicitResponse mode).

The ReceiveThreadRoutine method is responsible for executing a polling operation in accordance with the PollingInterval property. This method calls another method called TryReceive. TryReceive is responsible for returning a Boolean that tells the ReceiveThreadRoutine if polling fails.

Please see the comments in the code for more details about the other code in this class.

NameAdapter.cs

This is the partial class that contains all the user defined functionality of the adapter. The constructor resides here which should always contain the logic to initialize the ESBAdapterBase.AdapterModes and ESBAdapterBase.Capabilities base class members. These two members of the ESBAdapterBase class are what Neuron ESB uses to control the Adapter modes shown in Neuron Explorer and what adapter properties should be able to be accessed at runtime by other things in Neuron (such as the Set Properties Process Step or the Http Client Utility).

The ConnectAdapter method contains all the logic that should be executed to validate the properties that are set for the adapter. If an exception is thrown here, it will be caught by the runtime and the adapter will fail to start up. It will appear as an error in the Neuron ESB Event log and the adapter will be in a stopped state within Endpoint Health. This is also where users would set the custom message metadata properties that should be included with every message that goes through the adapter.

The DisconnectResources method should contain all the logic needed to cleanup resources when an adapter is disconnected.

The SendToDataSource method is used for Subscribe/SolicitResponse mode adapters. This method should contain the logic to format and send a message to the system the adapter connects to. It should also contain the logic to decide if the adapter should wait for a reply from the system it connects to (i.e. if the adapter is set to SolicitResponse mode, call the method that waits for a reply and publishes to the bus versus calling the method that only sends to the connected system which would be Subscribe mode).

The ReceiveFromSource method should call the method that contains the logic that polls the connected system for anything that should be published to the bus. This could be a change to an account, change to a filesystem, a message that needs to be retrieved, etc. Polling is usually used when the system doesnt fire off an event to notify when something has changed or if a message is waiting to be retrieved.

The InitializeRequestReplyListener method is where the logic to initialize a listener goes and is used for RequestReply mode. A request would be sent from the system to the adapter. Then the method would publish the request to the bus and wait for a reply to send back to the system. If a user needs to poll for the request, they can use the ReceiveFromSource method and add code to check for the adapter mode (if both Publish and RequestReply modes are supported) to determine if the adapter should wait for a reply to send back to the system.

The SendToDataSource overloaded method takes one ESBMessage as a parameter and is used to send a one way message from the bus to the system (i.e. Subscribe mode).

The QueryDataSource method should contain logic to send the message to the system and wait for a response to publish back to the bus.

The PublishMessageFromSource method should contain the logic to retrieve the data from the system during a poll. This might include calling a method to validate if the data should be published or if data is available.

Please see the comments in the code for more details about the other code in this class.

CertificateConverter.cs

This class inherits from the base class StringConverter which is a class found in the System.ComponentModel namespace that inherits from the TypeConverter base class. The purpose of a TypeConverter is to convert types of values to other types or, in the case of the StringConverter, convert String objects to and from other representations. The CertificateConverter class will obtain a Dictionary that has a string as the key and an ESBCredential object as the value. It then takes the name of each ESBCredential and adds it to a list of strings, then sorts and turns that list into a StandardValuesCollection of strings. Notice in NameAdapter.cs that the property named Certificate is of type string, which is basically what the converter changes the Dictionary<string, ESBCredential> into. Also, a drop down menu uses a StandardValuesCollection type which allows the collection of strings to be displayed.

Please see the comments in the code for more details about how the adapter gets the credentials from Neuron Explorer programmatically.

Using a Custom Adapter

To use a custom adapter, simply copy the adapter assembly from the Visual Studio build output folder (e.g. C:\Program Files\Neudesic\Neuron ESB v3\Samples\CustomAdapters\AdapterFramework\bin\Debug) to the Adapters folder in the Neuron program files installation directory (C:\Program Files\Neudesic\Neuron ESB v3\DEFAULT\Adapters). Restart Neuron Explorer if it is open and then the adapter should appear in the Adapter dropdown menu when adding a new adapter.