dk.i1.diameter.node
Class Node

Object
  dk.i1.diameter.node.Node

public class Node
extends Object

A Diameter node. The Node class manages diameter transport connections and peers. It handles the low-level messages itself (CER/CEA/DPR/DPA/DWR/DWA). The rest is sent to the MessageDispatcher. When connections are established or closed the ConnectionListener is notified. Message can be sent and received through the node but no state is maintained per message.

Node is quite low-level. You probably want to use NodeManager instead.

Node instances logs with the name "dk.i1.diameter.node", so you can get detailed logging (including hex-dumps of incoming and outgoing packets) by putting "dk.i1.diameter.node.level = ALL" into your log.properties file (or equivalent)

Enabling TCP and/or SCTP transport protocols

The Node instance uses two properties when deciding which transport-protocols to support:

• dk.i1.diameter.node.use_tcp= [true|false|maybe] (default:true)
• dk.i1.diameter.node.use_sctp= [true|false|maybe] (default:maybe)

DW jitter, system RNG and stalls on first connection

dk.i1.diameter.node.jitter_prng=your favorite PRNG

See Also:

NodeManager

Node

public Node(MessageDispatcher message_dispatcher,
            ConnectionListener connection_listener,
            NodeSettings settings)

Constructor for Node. Constructs a Node instance with the specified parameters. The node is not automatically started. Implemented as this(message_dispatcher,connection_listener,settings,null);

Parameters:

message_dispatcher - A message dispatcher. If null, a default dispatcher is used you. You probably dont want that one.

connection_listener - A connection observer. Can be null.

settings - The node settings.

Node

public Node(MessageDispatcher message_dispatcher,
            ConnectionListener connection_listener,
            NodeSettings settings,
            NodeValidator node_validator)

Constructor for Node. Constructs a Node instance with the specified parameters. The node is not automatically started.

Parameters:

message_dispatcher - A message dispatcher. If null, a default dispatcher is used you. You probably dont want that one.

connection_listener - A connection observer. Can be null.

settings - The node settings.

node_validator - a custom NodeValidator. If null then a DefaultNodeValidator is used.

Since:

0.9.4

start

public void start()
           throws java.io.IOException,
                  UnsupportedTransportProtocolException

Start the node. The node is started. If the port to listen on is already used by another application or some other initial network error occurs a java.io.IOException is thrown.

Throws:

java.io.IOException - Usually when a priviledge port is specified, system out of resoruces, etc.

UnsupportedTransportProtocolException - If a transport-protocol has been specified as mandatory but could not be initialised.

stop

public void stop()

Stop the node. Implemented as stop(0)

stop

public void stop(long grace_time)

Stop the node. All connections are closed. A DPR is sent to the each connected peer unless the transport connection's buffers are full. Threads waiting in waitForConnection() are woken. Graceful connection close is not guaranteed in all cases.

Parameters:

grace_time - Maximum time (milliseconds) to wait for connections to close gracefully.

Since:

grace_time parameter introduced in 0.9.3

waitForConnection

public void waitForConnection()
                       throws InterruptedException

Wait until at least one connection has been established to a peer and capability-exchange has finished.

Throws:

InterruptedException

Since:

0.9.1

waitForConnection

public void waitForConnection(long timeout)
                       throws InterruptedException

Wait until at least one connection has been established or until the timeout expires. Waits until at least one connection to a peer has been established and capability-exchange has finished, or the specified timeout has expired.

Parameters:

timeout - The maximum time to wait in milliseconds.

Throws:

InterruptedException

Since:

0.9.1

waitForConnectionTimeout

public void waitForConnectionTimeout(long timeout)
                              throws InterruptedException,
                                     ConnectionTimeoutException

Wait until at least one connection has been established or until the timeout expires. Waits until at least one connection to a peer has been established and capability-exchange has finished, or the specified timeout has expired. If the timeout expires then a ConnectionTimeoutException is thrown.

Parameters:

timeout - The maximum time to wait in milliseconds.

Throws:

ConnectionTimeoutException - If the timeout expires without any connection established.

InterruptedException

Since:

0.9.6.5

findConnection

public ConnectionKey findConnection(Peer peer)

Returns the connection key for a peer. Behaviour change since 0.9.6: Connections that are not in the "Open" state (rfc3588 section 5.6) will not be returned.

Returns:

The connection key. Null if there is no connection to the peer.

isConnectionKeyValid

public boolean isConnectionKeyValid(ConnectionKey connkey)

Returns if the connection is still valid. This method is usually only of interest to programs that do lengthy processing of requests nad are located in a poor network. It is usually much easier to just call sendMessage() and catch the exception if the connection has gone stale.

connectionKey2Peer

public Peer connectionKey2Peer(ConnectionKey connkey)

Returns the Peer on a connection.

connectionKey2InetAddress

public java.net.InetAddress connectionKey2InetAddress(ConnectionKey connkey)

Returns the IP-address of the remote end of a connection. Note: for connections using the SCTP transport protocol the returned IP-address will be one of the peer's IP-addresses but it is unspecified which one. In this case it is better to use connectionKey2Peer()

nextHopByHopIdentifier

public int nextHopByHopIdentifier(ConnectionKey connkey)
                           throws StaleConnectionException

Returns the next hop-by-hop identifier for a connection

Throws:

StaleConnectionException

sendMessage

public void sendMessage(Message msg,
                        ConnectionKey connkey)
                 throws StaleConnectionException

Send a message. Send the specified message on the specified connection.

Parameters:

msg - The message to be sent

connkey - The connection to use. If the connection has been closed in the meantime StaleConnectionException is thrown.

Throws:

StaleConnectionException

initiateConnection

public void initiateConnection(Peer peer,
                               boolean persistent)

Initiate a connection to a peer. A connection (if not already present) will be initiated to the peer. On return, the connection is probably not established and it may take a few seconds before it is. It is safe to call multiple times. If persistent true then the peer is added to a list of persistent peers and if the connection is lost it will automatically be re-established. There is no way to change a peer from persistent to non-persistent.

If/when the connection has been established and capability-exchange has finished threads waiting in waitForConnection() are woken.

You cannot initiate connections before the node has been started. Connection to peers specifying an unsupported transport-protocl are simply ignored.

Parameters:

peer - The peer that the node should try to establish a connection to.

persistent - If true the Node wil try to keep a connection open to the peer.

isAllowedApplication

public boolean isAllowedApplication(Message msg,
                                    Peer peer)

Determine if a message is supported by a peer. The auth-application-id, acct-application-id or vendor-specific-application AVP is extracted and tested against the peer's capabilities.

Parameters:

msg - The message

peer - The peer

Returns:

True if the peer should be able to handle the message.

addOurHostAndRealm

public void addOurHostAndRealm(Message msg)

Add origin-host and origin-realm to a message. The configured host and realm is added to the message as origin-host and origin-realm AVPs

nextEndToEndIdentifier

public int nextEndToEndIdentifier()

Returns an end-to-end identifier that is unique. The initial value is generated as described in RFC 3588 section 3 page 34.

makeNewSessionId

public String makeNewSessionId()

Generate a new session-id. Implemented as makeNewSessionId(null)

Since:

0.9.2

makeNewSessionId

public String makeNewSessionId(String optional_part)

Generate a new session-id. A Session-Id consists of a mandatory part and an optional part. The mandatory part consists of the host-id and two sequencers. The optional part can be anything. The caller provide some information that will be helpful in debugging in production environments, such as user-name or calling-station-id.

Since:

0.9.2

stateId

public int stateId()

Returns the node's state-id.

Since:

0.9.2