Mobicents Diameter Sh-Client - mobicents-public

Mobicents Diameter Sh (Client)

Introduction (Section converted to XML)

The Sh interface is the reference for interactions between the HSS (Home Subscriber Server) and the SIP AS (Application Server) and between the HSS and the OSA SCS (Service Capability Server) in IMS. It is described in TS29.328 and TS29.329. This will only refer to the interactions between AS and HSS and only for client-mode. Sh defines the following messages:

Command-Name	Abbr.	Code	Source	Destination
User-Data-Request	UDR	306	AS	HSS
User-Data-Answer	UDA	306	HSS	AS
Profile-Update-Request	PUR	307	AS	HSS
Profile-Update-Answer	PUA	307	HSS	AS
Subscribe-Notifications-Request	SNR	308	AS	HSS
Subscribe-Notifications-Answer	SNA	308	HSS	AS
Push-Notification-Request	PNR	309	HSS	AS
Push-Notification-Answer	PNA	309	AS	HSS

As can be seen from the Command Names, these are related to managing User Data in the HSS. UDR/UDA is used in order to request data from the User profile. Client (AS) sends the request indicating which data he wants (see below for possible kinds of data) and if it has permissions on the HSS, they will be received via UDA. PUR is meant to be used to update the profile of the user, and the success (or not) of the action is reported back in PUA. SNR offers the possibility to request for changes made in the user profile. If SNR is successful a SNA will be received stating that the operation was successful and when there are profile changes, a PNR will be sent by the HSS to the AS (this is the only time HSS initiates conversation) and the AS should acknowledge with a PNA.

Resource Adaptor Type Section converted to XML

Activities:

ShClientActivity - stateless, created per request, it ends when answer is received or times out. API definition can be found here.

ShClientSubscriptionActivity - stateful, created either on demand or for SNR (depends on impl). It ends once subscription ends or times out. API definition can be found here.

API defines methods to easly create and send answers/request for certain activity. Also it allows to retrieve some session specific data. Life cycle of activity depends on type of received reqeust and application interaction. In case of subscritpion activity timeout of session is taken into consideration as subscription may be time based. Activities allow to retrieve message and avp factories bound to this session. Based on impl it can provide some functionality.

Provider:

Provider allows SBBs to create activities on demand and retrieve AVP and message factories. API definition can be found here. It alows to fetch connection information (peers connected).

Message Factory

Message factory creates events that can be fired into SLEE or sent through RA. API definition can be found here. Depending on case factory prefils some AVPs, to best of its knowledge about session.

Example usage of API Section converted to XML

PNR example

               public void onPushNotificationRequest(net.java.slee.resource.diameter.sh.client.events.PushNotificationRequest pnr, ActivityContextInterface aci)
               {
                   try
                   {
                       logger.info( "Push-Notification-Request activity["+aci.getActivity()+"] received.\n"+pnr );

                       // Let's be nice and say OK :)
                       ShClientSubscriptionActivityImpl shActivity = (ShClientSubscriptionActivityImpl) aci.getActivity();

                       shActivity.sendPushNotificationAnswer( 2001, false );
                   }
                   catch ( IOException e ) {
                     logger.error( "Failure while creating/sending PNA.", e );
                   }
               }

Send UDR example

               private void doSimpleTestsSendUDR()
               {

                   try {
                          ShClientActivity basicClientActivity=this.provider.createShClientActivity();
                         logger.info(" On TimerEvent: activity created");


                          localACI.attach(getSbbContext().getSbbLocalObject());


                         DiameterIdentity[] peers=provider.getConnectedPeers();

                          for(DiameterIdentity peer: peers)
                           {
                             logger.info(" On TimerEvent: Connected Peer: "+peer.toString());
                          }

                          logger.info(" On TimerEvent: creating UDR");

                          UserDataRequest udr=((ShClientMessageFactory)basicClientActivity.getDiameterMessageFactory()).createUserDataRequest();

                         List<DiameterAvp> avps = new ArrayList<DiameterAvp>();

                            avps.add(avpFactory.getBaseFactory().createAvp(Avp.SESSION_ID, basicClientActivity.getSessionId().getBytes() ));

                            DiameterAvp avpVendorId = avpFactory.getBaseFactory().createAvp( Avp.VENDOR_ID, MessageFactory._SH_VENDOR_ID );
                            DiameterAvp avpAcctApplicationId = avpFactory.getBaseFactory().createAvp( Avp.ACCT_APPLICATION_ID, MessageFactory._SH_APP_ID );

                             avps.add( avpFactory.getBaseFactory().createAvp( Avp.VENDOR_SPECIFIC_APPLICATION_ID, new DiameterAvp[]{avpVendorId, avpAcctApplicationId} ) );

                             avps.add(avpFactory.getBaseFactory().createAvp(Avp.ORIGIN_HOST, ("aaa://" + originIP + ":1812").getBytes() ));
                            avps.add(avpFactory.getBaseFactory().createAvp(Avp.ORIGIN_REALM, "mobicents.org".getBytes() ));

                             avps.add(avpFactory.getBaseFactory().createAvp(Avp.DESTINATION_HOST, ("aaa://" + destinationIP + ":3868").getBytes() ));
                             avps.add(avpFactory.getBaseFactory().createAvp(Avp.DESTINATION_REALM, "mobicents.org".getBytes() ));
                             UserIdentityAvp ui=avpFactory.createUserIdentity();
                             ui.setPublicIdentity("sip:subscriber@mobicents.org");

                             avps.add(ui);
                             ui=avpFactory.createUserIdentity();
                             ui.setPublicIdentity("TEL:+64216543210");

                             avps.add(ui);
                             udr.setExtensionAvps(avps.toArray(new DiameterAvp[avps.size()]));

                             logger.info(" On TimerEvent: Sending message:\n"+udr);
                            basicClientActivity.sendUserDataRequest(udr);

                          logger.info(" On TimerEvent: Message send");



                       } catch (Exception e) {
                        logger.error( "Failure trying to create/sen UDR.", e );
                       }
               }

    Above example makes use of setExtensionAvps() methods. However it is possible to use specific methods, like udr.setUserIdentity(); for instance.

Resource Adaptor

The Sh-Client Resource Adaptor provides the Sh client application layer to SLEE.

Build from source

In order to build from source you need to make sure you meet the following requirements:

Have maven 2.x installed (see recommended version);
Have ant 1.7.x installed;
Have JBOSS_HOME environment variable set, pointing to your JBoss installation folder

You can obtain the latest version of the source code from here and here (common). Tagged and released versions can be obtained in this location and this (common).

After checking out the code from SVN repository, run the following command in the source root folder: mvn clean install

That command should compile the source and copy the relevant jars into your JBoss deploy folder.

From the binary

Grab the binary from SourceForge. Extract the files and deploy the DU jar (diameter-sh-client-ra-DU-<version>.jar) in your JBoss deploy folder. SLEE Deployer will catch it and perform the necessary steps automatically.

If you wish to use JMX deployment, run the ant deploy command in the extracted zip folder.

Examples

There is a simple example (well, actually is a test application, for a real example check the OpenIMS Integration Example) provided for Sh Client which just sends Sh commands for Seagull. In order to test it you need to setup Seagull in your machine, configure the Mux accordingly to the settings defined in seagull and start it.

Depending on the version of Seagull you are getting, you might have or have not the necessary scenario files. You can copy them from here if you need it:

1) UDR-UDA:

<?xml version="1.0" encoding="ISO-8859-1" ?>

<init>

</command>

</action>

</receive>

</avp>

</command>

</send>

</init>

</command>

</action>

</receive>

</action>

</command>

</send>

</traffic>

</scenario>

2) SNR-SNA

<?xml version="1.0" encoding="ISO-8859-1" ?>

<init>

</command>

</action>

</receive>

</command>

</send>

</init>

</command>

</action>

</receive>

</action>

</command>

</send>

</traffic>

</scenario>

As can be seen, the scenarios require the CER/CEA messages to be exchanged in order to correctly establish the connection between peers. To use this, save the scenario in a file (eg: udr-uda.server.xml and snr-sna.server.xml) and pass it to seagull as the scenario file. Please feel free to change the scenarios for whatever fits your needs (eg, change the Result-Code AVP value). A sample command line to run it would be:

seagull -conf ../config/conf.server.xml -dico ../config/base_sh.xml -scen ../scenario/udr-uda.server.xml -log ../logs/udr-uda.server.log -llevel ET

Configuration Section converted to XML

At the moment it is not possible to make any configuration changes unless you edit the code, as it was just a test application, enabling/disabling the following method calls:

public void onTimerEvent(TimerEvent event, ActivityContextInterface aci)

{

doSimpleTestsSendUDR();

//doSimpleTestSendSNR();

}

Expect future release to include a properties file where you can change that and some more options easily.

Build from source

Please make sure you meet the exact same requirements stated above in the RA section.

You can obtain the latest version of the source code from here. Tagged and released versions can be obtained in this location.

After checking out the code from SVN repository, run the following command in the source root folder: mvn clean install

That command should compile the source and copy the relevant jars into your JBoss deploy folder.

From the binary

Grab the binary from SourceForge. Extract the files and deploy the DU jar (diameter-sh-client-example-DU-<version>.jar) in your JBoss deploy folder. SLEE Deployer will catch it and perform the necessary steps automatically.

If you wish to use JMX deployment, run the ant deploy command in the extracted zip folder.

Version:

prack_problem	Jan 6
MMS SS7 Support	Dec 23
Mobicents Diameter Roadmap	Dec 15
A Mobicents Documentation Hub	Dec 3
tutorial.zip	Nov 30
Tutorial for Mobicents and Tomcat	Nov 27
Mobicents Performance Guide	Nov 24
Mobicents SS7 Roadmap	Nov 23
server.log (2)	Nov 18
mobicents-jainslee-server-v2	Nov 16