TIBCO Diameter Channel

Overview

This is the TIBCO Diameter channel for AciveSpaces Transactions (AST). It is a partial implementation of a diameter client and server.

Please see the enclosed javadoc.

Supported messages

The diameter channel supports the following messages :-

Starting the diameter channel

The diameter channel provides an implementation of the AST channel framework. See AST Devzone for further details of the API.

An example of how to create an instance of the server service is shown below :-

import com.tibco.diameterchannel.DiameterServerEndpoint;
import com.tibco.diameterchannel.DiameterServerService;
import com.tibco.diameterchannel.avp.BaseMsg;

....

serverService = new DiameterServerService(
            "Diameter-Server", // name
            "server service description", // description
            10, // int poolSize
            10, // int maxPoolSize
            60, // int queueCapacity
            10, // long keepAliveTime
            DiameterService.RejectPolicy.CallerRuns, // RejectPolicy rejectPolicy
            "server.realm.com", // String originHost
            "realm.com", // String originRealm
            "AST", // String productName
            210, // int firmwareRevision
            new int[]{ BaseMsg.DIAMETER_CREDITCONTROL_APPID, BaseMsg.THREEGPP_GX_APPID }, // int[] applicationIds
            serverWatchdogTime, // int watchdogTime
            1, // int numberOfWatchdogRetries
            true, // boolean checkApplicationId
            false, // boolean forwardCER
            true, // boolean forwardDPR
            connectionType, // ConnectionType connectionType
            "localhost", // String host
            port, // int port
            new String[]{ "TCP_NODELAY" }, // String[] socketOptions
            false, // boolean dprOnStop
            0, // long dpaTimeout
            0, // int dprDisconnectCause
            false // boolean useAnySessionForAnswer
        );
                        
serverService.start();

Diameter endpoints are created dynamically based on originHost from CER. When we known client originHost/originRealm we could create server endpoint manually

serverEndpoint = new DiameterServerEndpoint(
            serverService, // service
            "Diameter-Server-Endpoint", // name
            "Diameter Server Endpoint Description", // description
            "clienthost.realm.org", // destinationHost
            "realm.org", // destinationRealm,
            false, // dprOnStop
            0, // dpaTimeout
            0, // dprDisconnectCause
            false, // useAnySessionForAnswer
            false // deleteOnInactive
        );

Last parameter of DiameterServerEndpoint constructor specify if endpoint should be automatically deleted when last session is closed, for manually created endpoints we could this feature disable for persist endpoint also when is not active.

An example of how to create an instance of the client service/endpoint is shown below :-

import com.tibco.diameterchannel.DiameterClientEndpoint;
import com.tibco.diameterchannel.DiameterClientService;
import com.tibco.diameterchannel.avp.BaseMsg;

....

clientService = new DiameterClientService(
            "Diameter-Client", // name
            "Diameter Client service", // description
            1, // poolSize
            5, // maxPoolSize
            0, // queueCapacity
            10, // keepAliveTime
            DiameterService.RejectPolicy.Discard, // rejectPolicy
            "clienthost.realm.org", // originHost
            "realm.org", // originRealm
            "AST", // productName
            210, // firmwareRevision
            new int[]{ BaseMsg.DIAMETER_CREDITCONTROL_APPID,
               BaseMsg.THREEGPP_GX_APPID }, // applicationIds
            clientWatchdogTime, // watchdogTime
            0, // numberOfWatchdogRetries
            false, // checkApplicationId
            false, // forwardCER
            false, // forwardDPR
            connectionType // connectionType
        );

clientEndpoint = new DiameterClientEndpoint(
            clientService, // service
            "Diameter-Client-Endpoint", // name
            "Diameter Client Endpoint", // description
            "host.remote.realm", // destinationHost
            "remote.realm", // destinationRealm
            false, // dprOnStop
            0, // dpaTimeout
            0, // dprDisconnectCause
            true, // useAnySessionForAnswer
            "localhost", // host
            port, // port
            new String[]{}, // sockOption
            1, // connections
            0, // reconnectTime
            new int[0], // sourcePort
            0  // maxPendingMsg
        );
        
clientService.start();

Applications would typically include KCS based configuration to configure the service and endpoints.

Service / Endpoint / Session and Diamater Protocol

AST Service (Client or Server) represent one Diameter Host identified by originHost/originRealm, productName and supported ApplicationIds.

AST Endpoint represent remote Diameter Host (peer) identified by originalHost and originalRealm of remote peer. Server Endpoint are mainly created dynamically when connected peer is identified by CER.

AST Session represent transport connection and is associated to Endpoint (peer). For sending answer is used same session where request was received. In case that session not exist could be use any session of Endpoint if it is enabled. For sending request any active session is used for given Endpoint, selection is RoundRobin base.

Initial Connection

When a diameter client makes the first connect to the diameter server channel, the channel will wait for the Capabilities Exchange Request (CER) message and reply with a Capabilities Exchange Answer (CEA). The periodic watchdog process is then started . Hence, applications using the diameter server channel do not need to handle capabilities exchange, watchdog or disconnect peer messages, which are handled by channel.

The server service can be set to validate application ids if required.

When the diameter client channel connects to a diameter server, the channel will send the Capabilities Exchange Request (CER) message and wait for the Capabilities Exchange Answer (CEA) message. The periodic watchdog process is then started . Hence, applications using the diameter client channel do not need to handle capabilities exchange, watchdog or disconnect peer messages, which are handled by channel.

Sending a diameter message

Diameter messages are represented as first class java objects to simplify use in the application. Below is an example of composing and sending a diameter message :-

import com.tibco.diameterchannel.avp.RARMsg;
import com.tibco.diameterchannel.avp.ProxyInfo;

....

RARMsg request = new RARMsg("sessionid", "destrealm", "desthost", 0, 1);                                                        
request.userName = "me";
request.originStateId = 2;
request.proxyInfo = new ProxyInfo[] { new ProxyInfo("host", "state") };
request.routeRecord = new String[] { "a", "b"};
Message message = new Message(request);
message.target = Address.forLocalEndpoint("desthost");                    
Endpoint.dispatch(message);

Receiving a diameter message

To receive a diameter message, an application handler is used. See Application Handler.

Connection Types

The diameter channel support these connection types:

  • TCP - Blocking TCP connection. Synchronous send operation.
  • TCPNIO - Non blocking TCP connection. Asynchronous send operation. Handler will receive CompletionMsg after write operation.
  • SCTP - Non blocking SCTP connection. Asynchronous send operation. Handler will receive CompletionMsg after write operation.

Adding additional diameter message types

The diameter channel may be extended to provide support for additional messages. The following steps are required :-

  • Create a class representing the new message - this must inherit from BaseMsg.
  • Implement the parse() and compose() methods - note that the PDU class provides utility functions to simplify the work needed.
  • Create a factory class - this must inherit from BaseFactoryMsg.
  • Implement the createRequestMessage() and createAnswerMessage() methods.
  • On startup, call the registerFactory() method of CodecManager to register the factory class.
Structure

Management

Since the diameter channel implements the channel framework, the diameter channel can be managed from the commandline using switchadmin, or the AST GUI ASTA.

Performance test client

Supplied with the channel is a simple performance test client which runs under AST. To start the client, the following map be used :-

java  -jar <<SDK PATH>>/deploy.jar \
    -cp <<JAR PATH>>/diameterchannel.jar \
    adminport=<<ADMIN PORT>> \
    <<OPTIONS>> \
    com.tibco.diameterchannel.perfclient.PerfClient

The following options are supported :-

Option Default Description
-Ddiameterchannel.perf.host localhost Host of the diameter sever
-Ddiameterchannel.perf.port 3868 Port of the diameter server
-Ddiameterchannel.perf.targettps 200 Target messages per second
-Ddiameterchannel.perf.duration 200 Test duration in seconds
-Ddiameterchannel.perf.sessions 6000 Number of concurrent diameter sessions
-Ddiameterchannel.perf.latencyfile latency.csv Filename of latency report
-Ddiameterchannel.perf.createfirst false Send CCR-Is for all sessions first
-Ddiameterchannel.perf.randomselect false Select session randomly rather than sequentially
-Ddiameterchannel.perf.waitresponse false Wait for a response for a given session before sending the next
-Ddiameterchannel.perf.createfirsttps 200 Target messages per second for createfirst CCRI's
-Ddiameterchannel.perf.rampup false If true, gradually increase messages per second
-Ddiameterchannel.perf.rampuptime 60 Ramp up time in seconds
-Ddiameterchannel.perf.preroute false If true, pre-route messages to the right node (aka DRA)
-Ddiameterchannel.perf.preroutenodes 3 Number of nodes in the cluster
-Ddiameterchannel.perf.preroutethisnode 0 This node number ( 0 to preroutenodes-1 )
-Ddiameterchannel.perf.percentbreach 0 Percentage of messages which result in a quota breach
-Ddiameterchannel.perf.capturelatency true If true, capture each message latency
-Ddiameterchannel.perf.burst false If true, have a burst of traffic mid-way
-Ddiameterchannel.perf.bursttps 200 Burst messages per second
-Ddiameterchannel.perf.bursttime 60 Burst duration in seconds