docs.intersystems.com
Home  /  Application Development: Using Adapters and Gateways in Productions  /  Using TCP Adapters in Productions  /  Using the Inbound TCP Adapters


Using TCP Adapters in Productions
Using the Inbound TCP Adapters
[Back]  [Next] 
InterSystems: The power behind what matters   
Search:  


This chapter describes how to use each of the TCP inbound adapters (EnsLib.TCP.CountedInboundAdapter, EnsLib.TCP.CountedXMLInboundAdapter, and EnsLib.TCP.TextLineInboundAdapter). It contains the following sections:
Tip:
InterSystems IRIS™ also provides specialized business service classes that use TCP adapters, and one of those might be suitable for your needs. If so, no programming would be needed. See Connectivity Options in Introducing InterSystems IRIS Interoperability.
Also, you can develop a new inbound adapter class based on the EnsLib.TCP.InboundAdapter or any of its subclasses. See the section Creating Custom TCP Adapter Classes,” later in this book.
Overview of Inbound TCP Adapter
InterSystems IRIS provides the following inbound TCP adapters, all of which are subclasses of EnsLib.TCP.InboundAdapter:
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 production 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 Messages in Developing Productions.
The following list describes the basic requirements of the business service class:
Note:
Studio provides a wizard that you can use to create a business service stub. To access this wizard, click File —> New and then click the Production tab. Then click Business Service and click OK. Note that the wizard provides a generic input argument. If you use the wizard, InterSystems recommends that you edit the method signature to use the specific arguments needed with the adapter you chose; see the next section.
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.CountedInboundAdapter, your OnProcessInput() method should have the following signature:
Method OnProcessInput(pInput As %Library.GlobalCharacterStream,
                      Output pOutput As %Library.AbstractStream) As %Status
Where:
Signature for OnProcessInput() for EnsLib.TCP.CountedXMLInboundAdapter
If your business service class uses EnsLib.TCP.CountedXMLInboundAdapter, your OnProcessInput() method should have the following signature:
Method OnProcessInput(pInput As %RegisteredObject,
                      Output pOutput As %RegisteredObject) As %Status
Where:
Signature for OnProcessInput() for EnsLib.TCP.TextLineInboundAdapter
If your business service class uses EnsLib.TCP.TextLineInboundAdapter, your OnProcessInput() method should have the following signature:
Method OnProcessInput(pInput As Ens.StringContainer,
                      Output pOutput As Ens.StringContainer) As %Status
Where:
Implementing OnProcessInput()
In all cases, the OnProcessInput() method should do some or all of the following:
  1. Examine the input object (pInput) and decide how to use it.
  2. Create an instance of the request message, which will be the message that your business service sends.
    For information on creating message classes, see Defining Messages in Developing Productions.
  3. For the request message, set its properties as appropriate, using values in the input.
  4. Call a suitable method of the business service to send the request to some destination within the production. Specifically, call SendRequestSync(), SendRequestAsync(), or (less common) SendDeferredResponse(). For details, see Sending Request Messages in Developing Productions
    Each of these methods returns a status (specifically, an instance of %Status).
  5. Make sure that you set the output argument (pOutput). Typically you set this equal to the response message that you have received. This step is required.
  6. If the data source expects an acknowledgment or response to its input, OnProcessInput() must create this response and relay it to the data source, via the adapter.
  7. Return an appropriate status. This step is required.
Example for EnsLib.TCP.TextLineInboundAdapter
The following is an example of a business service class that uses EnsLib.TCP.TextLineInboundAdapter.
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 a production, use the Management Portal to do the following:
  1. Add an instance of your business service class to the 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.