jDiameter Open Source Diameter Protocol Implementation

5 minutes Tutorial

JDiameter

5 minutes Tutorial
version 1.5.x

jDiameter Open Source Diameter Protocol Implementation

5 minutes Tutorial

Disclaimer of warranty
jDiameter team makes no representations or warranties, either expressed or implied, by or with respect to anything in this document, and shall not be liable for any implied warranties of merchantability or fitness for a particular purpose or for any indirect, special or consequential damages.

jDiameter Open Source Diameter Protocol Implementation

5 minutes Tutorial

Installation
The JDiameter Tutorials are practical guides for programmers who want to use the JDiameter implementation to work with diameter network. The following prerequisites are required for this tutorial:

JDiameter API 1.5.x JDiameter Default Implemetation 1.5.x JDK 1.5 or greater Pico Container: binary & sources

If you have any problems getting this program to work, please do not hesitate to use the Mailing Lists in order to talk to the JDiameter developers. Compilation commands and steps to execute the program have been removed for brevity. If you need help learning how to either compile of execute java programs, please consult the Java tutorial

Client part
The JDiameter Tutorials are practical guides for programmers who want to use the JDiameter implementation to work with diameter network. First you need to create a stack instance:
// Client version Class diameterClass = Class.forName("org.jdiameter.client.impl.StackImpl"); Stack diameter = (Stack)diameterClass.newInstance(); // Server version Class diameterClass = Class.forName("org.jdiameter.server.impl.StackImpl"); Stack diameter

or we create a stack shared instance:

Class diameterClass = Class.forName("org.jdiameter.client.impl.StackImpl"); Stack diameter = (Stack)diameterClass.newInstance(); StackManager.registerStack(diameter); ... StackManager.unregisterStack(diameter);

Secondly you need be configured created stack instance:

XMLConfiguration configuration = null; ... configuration = new XMLConfiguration( this.getClass().getResourceAsStream("/configuration.xml") ); SessionFactory factory = stack.init(configuration); ...

Example of a client configuration files :

<?xml version="1.0"?> <Configuration xmlns="http://www.jdiameter.org/jdiameter-client">

jDiameter Open Source Diameter Protocol Implementation <LocalPeer> <URI value="aaa://localhost:1812"/> <IPAddress value="127.0.0.1"/> <Realm value="home"/> <VendorID value="193"/> <ProductName value="jDiameter"/> <FirmwareRevision value="1"/> <Applications> <ApplicationID> <VendorId value="193"/> <AuthApplId value="0"/> <AcctApplId value="19302"/> </ApplicationID> <ApplicationID> <VendorId value="193"/> <AuthApplId value="19301"/> <AcctApplId value="0"/> </ApplicationID> </Applications> </LocalPeer> <Parameters> <QueueSize value="10000"/> <MessageTimeOut value="60000"/> <StopTimeOut value="10000"/> <CeaTimeOut value="10000"/> <IacTimeOut value="30000"/> <DwaTimeOut value="10000"/> <DpaTimeOut value="5000"/> <RecTimeOut value="10000"/> </Parameters> <Network> <Peers> <Peer name="aaa://localhost:1813" rating="1"/> </Peers> <Realms> <Realm name="home" peers="localhost"/> </Realms> </Network> <Extensions/> </Configuration>

5 minutes Tutorial

Also you can create configuration file in runtime by helper class EmptyConfiguration : package org.jdiameter.server; import org.jdiameter.server.impl.helpers.EmptyConfiguration; import static org.jdiameter.server.impl.helpers.Parameters.*; public class ClientTestsConfiguration extends EmptyConfiguration { public static final String peerOne = "localhost"; public static final String peerTwo = "terra"; public ClientTestsConfiguration() { super(); add(Assembler, Assembler.defValue());

jDiameter Open Source Diameter Protocol Implementation

5 minutes Tutorial

add(OwnDiameterURI, "aaa://"+ peerOne +":1812"); add(OwnRealm, "home"); add(OwnVendorID, 193); // Set Applications add(ApplicationId, // AppId 1 getInstance(). add(VendorId, 193). add(AuthApplId, 19302). add(AcctApplId, 19302) ); add(DuplicateProtection, false); add(AcceptUndefinedPeer, true); // Set peer table add(PeerTable, // Peer 1 getInstance(). add(PeerRating, 1). add(PeerAttemptConnection, true). add(PeerName, "aaa://"+ peerOne +":1813"), // Peer 2 getInstance(). add(PeerRating, 1). add(PeerAttemptConnection, true). add(PeerName, "aaa://"+ peerTwo +":1814") ); // Set realm table add( RealmTable, // Realm 1 getInstance().add( RealmEntry, getInstance(). add(RealmName, "home"). add(ApplicationId, getInstance(). add(VendorId, 1). add(AuthApplId, 2). add(AcctApplId, 3) ). add(RealmHosts, peerOne + "," + peerTwo). add(RealmLocalAction, "LOCAL"). add(RealmEntryIsDynamic, false). add(RealmEntryExpTime, 1000L) ) ); } } Application can use external plugins ( MINA FrameWork for transport layer): // Set extension external transport layer MutableConfiguration extTransport = (MutableConfiguration) getChildren(Extensions.ordinal())[ TransportLayer.id() ]; extTransport.add(InternalTransportFactory, "org.jdiameter.plugins.mina.TransportLayerFactoryImpl");

List of supported extensions and extension parameters:

StackLayer: InternalMetaData, InternalSessionFactory, InternalMessageParser, InternalElementParser ControllerLayer: InternalPeerFsmFactory, InternalRouterEngine 5

jDiameter Open Source Diameter Protocol Implementation

5 minutes Tutorial

TransportLayer: InternalTransportFactory

After configuration it is possible to read the meta-information on a stack:

MetaData metaData = stack.getMetaData();

Logger management: ...

Logger logger = stack.getLogger(); logger.addHandler( new Handler() { public void publish(LogRecord record) { if (record.getLevel() == Level.SEVERE) { System.out.println("Severe:"+record); } else if (record.getLevel() == Level.WARNING) { System.out.println("Warning:"+record); } } public void flush() { } public void close() throws SecurityException { } } );
...

// Set logger levels Loggers.FSM.logger().setLevel(Level.ALL); ConsoleHandler fh = new ConsoleHandler(); fh.setLevel(Level.ALL); stack.getLogger().addHandler(fh); stack.getLogger().setUseParentHandlers(false); It's necessary to call a start (..) method to begin a stack work Not blocking start - stack.start(); Blocking start - stack.start(Mode.ANY_PEER, 10, TimeUnit.SECONDS); The thread is blocked till time will not expire or the condition defined by the first parameter will not be satisfied (Any/All peers pass to condition "OKAY") Using factory we create diameter session and establish listener that will process requests from a s erver.
SessionFactory factory = stack.getSessionFactory(); Session session = factory.getNewSession();

jDiameter Open Source Diameter Protocol Implementation session. setRequestListener(listener); Further we create diameter message

5 minutes Tutorial

Message msg = session.createRequest(1, ApplicationId.createByAccAppId(19302), "network", "localhost"); fill its with necessary data: msg.getAvps().addAvp(100, 100); and send to a server: session.send(msg, answerListener); After a while, on callback one of methods signalling that the answer is recei ved will be caused. EventListener answerListener listener = new EventListener() { public void receivedSuccessMessage(Request r, Answer a) { } public void timeoutExpired(Message r) { } }

After work with session is finished, it is necessary to release resources bor rowed by session: session.release(); For a stop of a stack it's necessary to cause blocking command stop(...), whi ch stops network activity of a stack (expects when all peers will pass to condition PeerState .DOWN). If during specified time the stack doesn't pass in a condition "stop", then e xception is generated. stack.stop(10, TimeUnit.SECONDS); After work it's necessary to release all resources which were used with a sta ck: stack.destroy();

Server part
Statistics Statistics allows control of the stack instance. Examples
MutablePeerTable mw = stack.unwrap(MutablePeerTable.class); Statistic stat = mw.getStatistic( mw.getPeerTable .toArray(new Peer[0])[0].getUri().getFQDN()); for (StatisticRecord sr : stat.getRecords()) { logger.info( sr.getDescription() + sr.getValueAsInt()); }

Configuration

jDiameter Open Source Diameter Protocol Implementation

5 minutes Tutorial

Example of configuration file:

<?xml version="1.0"?> <Configuration xmlns="http://www.jdiameter.org/jdiameter-server"> <LocalPeer> <URI value="aaa://localhost:1812"/> <IPAddresses> <IPAddress value="127.0.0.1"/> <IPAddress value="127.0.0.2"/> </IPAddresses> <Realm value="home"/> <VendorID value="193"/> <ProductName value="jDiameter"/> <FirmwareRevision value="1"/> <OverloadMonitor> <Entry index="1" lowThreshold="0.5" highThreshold="0.6"> <ApplicationID> <VendorId value="193"/> <AuthApplId value="0"/> <AcctApplId value="19302"/> </ApplicationID> </Entry> </OverloadMonitor> </LocalPeer> <Parameters> <AcceptUndefinedPeer value="true"/> <DuplicateProtection value="true"/> <DuplicateTimer value="240000"/> <QueueSize value="10000"/> <MessageTimeOut value="60000"/> <StopTimeOut value="10000"/> <CeaTimeOut value="10000"/> <IacTimeOut value="30000"/> <DwaTimeOut value="10000"/> <DpaTimeOut value="5000"/> <RecTimeOut value="10000"/> </Parameters> <Network> <Peers> <Peer name="aaa://localhost:1813" attempt_connect="true" rating=" 1"/> </Peers> <Realms> <Realm name ="abc" peers="localhost" local_action="LOCAL" dynamic ="false" exp_time="1"> <ApplicationID> <VendorId value="193"/> <AuthApplId value="0"/> <AcctApplId value="19302"/> </ApplicationID> </Realm> </Realms> </Network> <Extensions/>

jDiameter Open Source Diameter Protocol Implementation </Configuration>

5 minutes Tutorial

Mutable Configuration allows changes parameters of stack.

Levels Runtime

Parameters name DuplicateTimer AcceptUndefinedPeer MessageTimeOut StopTimeOut CeaTimeOut IacTimeOut DwaTimeOut DpaTimeOut RecTimeOut PeerTable, Peer, PeerName, PeerRating, PeerAttemptConnection ( by NetWork interface) RealmTable, Realm, RealmEntry RealmName, RealmHosts, RealmLocalAction, RealmEntryIsDynamic, RealmEntryExpTime ( by NetWork interface) OwnDiameterURI OwnIPAddresses, OwnIPAddress OwnRealm OwnVendorID OwnProductName OwnFirmwareRevision ApplicationId, VendorId, AuthApplId, AcctApplId OverloadMonitor, OverloadMonitorEntry, OverloadMonitorData, OverloadEntryIndex OverloadEntryhighThreshold, OverloadEntrylowThreshold DuplicateProtection QueueSize

Restart stack

Not changable

Examples
MutableConfiguration configuration1 = (MutableConfiguration) serverStack.getConfiguration(); ConfigurationListener cf = new ConfigurationListener() { public boolean elementChanged(int i, Object o) { return false; // rollback changes } }; configuration1.addChangeListener(cf, AcceptUndefinedPeer.ordinal()); configuration1.setBooleanValue(AcceptUndefinedPeer.ordinal(), false); configuration1.removeChangeListener(cf, AcceptUndefinedPeer.ordinal());

jDiameter Open Source Diameter Protocol Implementation

5 minutes Tutorial

Overload Manager
Overload manager allows an application to manage app/stack behaviour if we has CPU, Network overloads. Using listener, we can reduce the load on the network level : OverloadManager manager = serverStack1.unwrap(OverloadManager.class); OverloadListener lsr = new OverloadListener() { public void overloadDetected(URI uri, double v) { ..... } public void overloadCeased(URI uri) { .... } }; manager.addOverloadListener( lsr, 0.5D, 1.0D, 0); Using overload manager, we can reduce the application load skipping new network requests to application OverloadManager manager = serverStack.unwrap(OverloadManager.class); manager.parentAppOverloadDetected(ApplicationId.createByAccAppId(193, 19302), 0, 1D ); .. manager.parentAppOverloadCeased( ApplicationId.createByAccAppId(193, 19302), 0);

10