Using the Inbound TCP Adapters

Overview of Inbound TCP Adapter

Ensemble provides the following inbound TCP adapters, all of which are subclasses of EnsLib.TCP.InboundAdapterOpens in a new tab:

• EnsLib.TCP.CountedInboundAdapterOpens in a new tab supports incoming TCP connections over which a TCP client and TCP listener exchange blocks of data, with the block length specified in the first 4 bytes of the block. The adapter uses the block length to acquire the meaningful portion of the data from the client application.

• EnsLib.TCP.CountedXMLInboundAdapterOpens in a new tab acts as a TCP listener for an XTE server. The adapter receives XML data in counted TCP format and imports the XML data into Ensemble. The result is an instantiated Ensemble object.

• EnsLib.TCP.TextLineInboundAdapterOpens in a new tab supports incoming TCP connections over which a TCP client and TCP listener exchange data as text strings that end with a line terminator character. The default terminator is the newline character (ASCII 10).

  An important example of a business service that uses the EnsLib.TCP.TextLineInboundAdapterOpens in a new tab is the built-in business service class EnsLib.TCP.StatusServiceOpens in a new tab. This class provides a command-line interface that allows a console user or command-line script to retrieve basic status information from a running Ensemble production. For more information, see “Adding a TCP Status Service,” later in this book.

Overall Behavior

Each TCP inbound adapter checks for data on a specified port, reads the input, and sends the input as a stream to the associated business service. The business service, which you create and configure, uses this stream and communicates with the rest of the production. The following figure shows the overall flow:

In more detail:

1. Each time the adapter encounters input from its configured data source, it calls the internal ProcessInput() method of the business service class, passing the stream as an input argument.

2. The internal ProcessInput() method of the business service class executes. This method performs basic Ensemble tasks such as maintaining internal information as needed by all business services. You do not customize or override this method, which your business service class inherits.

3. The ProcessInput() method then calls your custom OnProcessInput() method, passing the input object. The requirements for this method are described later in this chapter.

The response message follows the same path, in reverse.

Creating a Business Service to Use a TCP Inbound Adapter

To use any of the TCP adapters in your production, create a new business service class as described here. Later, add it to your production and configure it.

You must also create appropriate message classes, if none yet exist. See “Defining Ensemble Messages” in Developing Ensemble Productions.

The following list describes the basic requirements of the business service class:

• Your business service class should extend Ens.BusinessServiceOpens in a new tab.

• In your class, the ADAPTER parameter should equal EnsLib.TCP.CountedInboundAdapterOpens in a new tab, EnsLib.TCP.CountedXMLInboundAdapterOpens in a new tab, or EnsLib.TCP.TextLineInboundAdapterOpens in a new tab.

• Your class must implement the OnProcessInput() method, as described in “Implementing the OnProcessInput Method.”

• Your class can implement the OnConnect() callback method. This method is called each time the TCP inbound adapter establishes a new connection to or from a remote system.

  If you implement this method, it must have the following signature:

  Method OnConnect(pTimeout As %Numeric) As %Status
  

  

  Implement OnConnect() if you need to take some action each time a new connection is established, for example to send a logon sequence or a handshake token. The timeout argument is automatically provided by the TCP inbound adapter. It takes its value from the Read Timeout adapter setting. For details about Read Timeout, see “Reference for Settings.”

  If OnConnect() returns an error status, the new connection fails and the adapter is disconnected. If an untrapped exception occurs within OnConnect(), the adapter catches it and continues as if OnConnect() were not implemented.

• For other options and general information, see “Defining a Business Service Class” in Developing Ensemble Productions.

Implementing the OnProcessInput() Method

This section describes the method signature for OnProcessInput(), which depends upon the adapter, and describes how to implement this method.

Signature for OnProcessInput() for EnsLib.TCP.CountedInboundAdapter

If your business service class uses EnsLib.TCP.CountedInboundAdapterOpens in a new tab, your OnProcessInput() method should have the following signature:

Method OnProcessInput(pInput As %Library.GlobalCharacterStream,
                      Output pOutput As %Library.AbstractStream) As %Status

Where:

• pInput contains the incoming data stream that the TCP client has directed to the adapter.

• pOutput contains any response that the business service might provide to the TCP client.

Signature for OnProcessInput() for EnsLib.TCP.CountedXMLInboundAdapter

If your business service class uses EnsLib.TCP.CountedXMLInboundAdapterOpens in a new tab, your OnProcessInput() method should have the following signature:

Method OnProcessInput(pInput As %RegisteredObject,
                      Output pOutput As %RegisteredObject) As %Status

Where:

• pInput can be any of the objects specified by the Accept Class Names adapter setting.

  For details about Accept Class Names, see “Reference for Settings.”

• pOutput contains any response that you might need to return to the XTE server.

Signature for OnProcessInput() for EnsLib.TCP.TextLineInboundAdapter

If your business service class uses EnsLib.TCP.TextLineInboundAdapterOpens in a new tab, your OnProcessInput() method should have the following signature:

Method OnProcessInput(pInput As Ens.StringContainer,
                      Output pOutput As Ens.StringContainer) As %Status

Where:

• pInput contains the incoming line of text.

• pOutput contains the outgoing response string (if any).

Example for EnsLib.TCP.CountedInboundAdapter

The following is an example of a business service class that uses EnsLib.TCP.CountedInboundAdapterOpens in a new tab.

Class Test.HL7v3.InterfaceEngine.Service.HL7TCPIn Extends Ens.BusinessService
{

 Parameter ADAPTER = "EnsLib.TCP.CountedInboundAdapter";

 Parameter SINGLEPOOLJOB = 1;

 Parameter SETTINGS = "TargetConfigNames";

 /// Configuration item to which to send messages
 Property TargetConfigNames As %String;

 Method OnProcessInput(pInput As %GlobalCharacterStream,
                      pOutput As %RegisteredObject) As %Status
 {
  Set $ZTrap = "OnProcessInputET"

  Set tRequest =
      ##class(Test.HL7v3.InterfaceEngine.Request.Message).%New()
  Set tRequest.Stream = pInput
  Set tRequest.DocType = $Case(pInput.Size < 10000, 1:"MCOA", :"CDAR2")

  If (..TargetConfigNames '= "") {
    For tCount = 1:1:$Length(..TargetConfigNames, ",") {
      Set tTarget =
          $ZStrip($Piece(..TargetConfigNames, ",", tCount), "<>W")
      Set tStatus = ..SendRequestAsync(tTarget, tRequest)
    }
  }

  Quit $$$OK

 OnProcessInputET
   Set $ZTrap = ""
   Quit $$$ERROR($$$GeneralError,"Error in OnProcessInput: "_$ZError)
 }

 /// Return an array of connections for
 /// drawing lines on the config diagram
 ClassMethod OnGetConnections(Output pArray As %String,
                              item As Ens.Config.Item)
 {
  Set (tValue,tIndex)=""
  For {
    Set tIndex = item.Settings.Next(tIndex) Quit:tIndex=""
    Set tSetting = item.Settings.GetAt(tIndex)
    If tSetting.Name="TargetConfigNames" Set tValue=tSetting.Value
  }
  For i=1:1:$L(tValue,",") {
   Set tOne=$P(tValue,",",i)
   Continue:""=tOne
   Set pArray(tOne)=""
  }
  Quit
 }
}

Example for EnsLib.TCP.TextLineInboundAdapter

The following is an example of a business service class that uses EnsLib.TCP.TextLineInboundAdapterOpens in a new tab.

Class TestTCPTextLine.AuthorizationTCPService Extends Ens.BusinessService
{
/// Name of the adapter class
Parameter ADAPTER = "EnsLib.TCP.TextLineInboundAdapter";

Method OnProcessInput(pInput As Ens.StringContainer,
                      pOutput As Ens.StringContainer) As %Status
{
  set $ZT = "EXCEPTION"
  set st = $$$OK

  do {
    if ('$isobject($get(pInput))) { quit }

    // Input must have the following format: 'PatientCode:ProcedureCode'
    set tSubject = pInput.StringValue
    $$$TRACE("received line "_tSubject)

    set req = ##class(TestTCPTextLine.AuthorizationRequest).%New()
    set req.PatientCode = $piece(tSubject,":",1)
    set req.ProcedureCode = $piece(tSubject,":",2)

    set st = ..SendRequestSync("AuthorizationProcess", req, .resp)
    quit:$$$ISERR(st)

    set pOutput=
      ##class(Ens.StringContainer).%New(resp.AuthorizationFlag_
        ":"_resp.AuthorizationCode)
    } while (0)

EXIT
   //do ..Adapter.Disconnect()
   quit st

EXCEPTION
   set $ZT = ""
   set st = $$$EnsSystemError
   goto EXIT
}
}

Adding and Configuring the Business Service

To add your business service to an Ensemble production, use the Management Portal to do the following:

1. Add an instance of your business service class to the Ensemble production.

2. Configure the business service. For information on the settings, see “Reference for Settings.”

   When you configure the business service, you specify a value for the Allowed IP Addresses settings, along other settings. Note that Allowed IP Addresses provides a way to enable the adapter to initiate the connection.

3. Enable the business service.

4. Run the production.