Tutorial: Basic Service Sample

This sample demonstrates how to register a DXL service to receive Request messages and send Response messages back to an invoking Client.

Prior to running this sample make sure you have completed the client provisioning step.

Running the Sample

To run this sample execute the sample/basic/service-example.js script as follows:

$ node sample/basic/service-example.js

Output

The output should appear similar to the following:

Service received request payload: ping
Client received response payload: pong

The code for the sample is broken into two main sections.

Register service

The first section is responsible for creating a request callback that will be invoked for a specific topic associated with the service. The callback will send back a Response message with a payload of "pong" for any Request messages that are received.

It then creates a ServiceRegistrationInfo instance and registers the request callback with the client via the addTopic method.

Finally it registers the service with the fabric via the registerServiceAsync method of the client.

// Create service registration object
var info = new dxl.ServiceRegistrationInfo(client, 'myService')

// Add a topic for the service to respond to
info.addTopic(SERVICE_TOPIC,
  // Handle the receipt of an incoming service request
  function (request) {
    // Extract information from request.  The toString() call converts the
    // payload from a binary Buffer into a string, decoded using UTF-8
    // character encoding.
    console.log('Service received request payload: ' +
      request.payload.toString())
    // Create the response message
    var response = new dxl.Response(request)
    // Populate the response payload
    response.payload = 'pong'
    // Send the response
    client.sendResponse(response)
  })

// Register the service with the fabric
client.registerServiceAsync(info,
  function (error) {
    if (error) {
      // Destroy the client - frees up resources so that the application
      // stops running
      client.destroy()
      console.log('Error registering service: ' + error.message)
      // ...
    }
  })

Invoke Service

After receiving notification of a successful registration of the service, the second section sends a Request message to the service that contains a payload of "ping" via the asyncRequest method of the client.

The payloads of the Request and Response messages are printed.

// Create the request message
var request = new dxl.Request(SERVICE_TOPIC)
// Populate the request payload
request.payload = 'ping'
// Send the request
client.asyncRequest(request,
  // Handle the response to the request
  function (error, response) {
    // Destroy the client - frees up resources so that the application
    // stops running
    client.destroy()
    // Display the contents of an error, if one occurred
    if (error) {
      console.log('Request error: ' + error.message)
      // The 'code' property, if set, typically has a string
      // representation of the error code.
      if (error.code) {
        console.log('Request error code: ' + error.code)
      // If no string representation is available for the error code
      // but the error is a DXL 'RequestError', a numeric error
      // code should be available in the
      // 'dxlErrorResponse.errorCode' property.
      } else if (error.dxlErrorResponse) {
        console.log('Request error code: ' +
          error.dxlErrorResponse.errorCode)
      }
    // No error occurred, so extract information from the response. The
    // toString() call converts the payload from a binary Buffer into a
    // string, decoded using UTF-8 character encoding.
    } else {
      console.log('Client received response payload: ' +
        response.payload.toString())
    }
  })