1. Diameter Application Development Guide
  2. Using the Diameter Base Protocol API
  3. Working with Diameter Applications Using CDI and POJOs

Working with Diameter Applications Using CDI and POJOs

This section describes the creation and deployment of Diameter applications using Java EE Common Dependency Injections (CDIs) in conjunction with Plain Old Java Objects (POJOs).

Creating a Diameter Bean Using Annotations

Example 1-1 shows an implementation of a Diameter Bean, ExamplePOJO, that listens to RoApplication messages.

Example 1-1 Diameter Bean Listening to RoApplication Messages

@DiameterBean(applicationId = "4")
public class ExamplePOJO {
 
  @Inject DiameterSessionSource source;
 
  public void handleCCR(@Observes CCR ccr) {
    RoSession session = (RoSession) ccr.getSession();
    SipApplicationSession sas = source.getApplicationSession(session);
    //... Business logic...
  }
 
  public void handleSTR(@Observes @DiameterObserver(code=275) Message msg) {
    RoSession session = (RoSession) msg.getSession();
    SipApplicationSession sas = source.getApplicationSession(session);
    //... Business logic...
  }
}

The annotation, @DiameterBean, marks the Java class as a Diameter Bean. The Diameter stack looks for Common Dependency Injection (CDI) observer methods for feeding the requests or responses to the Diameter Bean. The method arguments and the command code, if any, act as a filter for feeding the messages.

Such an architecture avoids the need for registering a listener for subsequent messages in the Diameter session, since the Diameter session information can be obtained from the message.

The RoApplication can then be injected into a SIP servlet as shown in Example 1-2.

Example 1-2 SIP Servlet RoApplication Injection

public class FooServlet {
 
  @Inject @DiameterContext(applicationId = "4")
  Application roApp;
 
  @Inject
  DiameterSessionSource source;
 
  void doInvite(SipServletRequest request) throws IOException {
    RoSession session = (RoSession) source.createSession(roApp, request.getApplicationSession());
    CCR ccr = session.createCCR(RequestType.INITIAL);
    ccr.send();
  }
}

Built-in CDI Beans

The Diameter stack adds built-in CDI beans which can be injected into SIP Servlets and Diameter Beans.

SessionSource

This bean acts as a source for Diameter session objects, and helps SIP Servlet applications to associate a diameter Session with a SipApplicationSession and also obtain SipApplicationSession information from a Diameter session.

Application

A com.bea.wcp.diameter.Application can be injected with a CDI bean like a SIP servlet or a Diameter bean. The exact subtype of the Application is based on the annotation @DiameterContext.

Example 1-3 shows injecting an instance of RoApplication into a SIP Servlet.

Example 1-3 Injecting an RoApplication Instance into a SIP Servlet

public class ExampleServlet extends SipServlet {
  @Inject @DiameterContext(applicationId = 4)
  private Application application;
  ...
}

Application Subtypes

Application subtypes, such as RoApplication, RfApplication, ReApplication, RxApplication, GxApplication, GxxApplication, ShApplication, SyApplication can be injected into a CDI bean directly, and do not require the @DiameterContext annotation.

Example 1-4 shows injecting an instance of RoApplication, RfApplication, and ShApplication into a SIP servlet.

Example 1-4 Injecting Diameter Applications into a CDI Bean

public class ExampleServlet extends SipServlet {
  @Inject
  private RoApplication roApplication;
  @Inject
  private RfApplication rfApplication;
  @Inject
  private ShApplication shApplication;
  ...
}

Diameter Bean Selection

The Diameter stack selects the bean to handle incoming requests based on the following different criteria:

  • Application Identifier

  • Peer (host/realm)

  • Origin (origin host/ origin realm)

  • Destination (destination host / destination realm)

The stack finds the most specific Diameter bean to handle the message, irrespective of the application in which it is packaged. The following rules determine the most specific bean:

  • If the bean contains and matches all the selection criteria annotations, then it is considered most specific.

  • If the bean contains and matches a fewer number of selection critera annotations, then priority is given in the following order:

    Application then Peer then Destination then Origin.

  • For matching a node (Peer, Origin or Destination), priority is given to host rather than realm.

Example 1-5 shows a bean with a more complicated set of selection criteria. When a Diameter message comes in, ExampleBean1 is selected first, followed by the remaining beans in the following order:

ExampleBean2 then ExampleBean3 then ExampleBean4 then ExampleBean5

Example 1-5 Diameter Bean Selection Criteria

@DiameterBean(
applicationId = 4,
peers = { @DiameterNode(host = "ro.server", realm = "weblogic.com") },
origins = { @DiameterNode(host = "originserver", realm = "originserver.com"),
@DiameterNode(host = "ro.client", realm = "weblogic.com") },
destinations = { @DiameterNode(host = "ro.server", realm = "weblogic.com") })
public class ExampleBean1 {
}
 
//specify peers.
@DiameterBean(
applicationId = 4,
peers = { @DiameterNode(host = "ro.server", realm = "weblogic.com") },
public class ExampleBean2 {
}
 
//specify origins.
@DiameterBean(
applicationId = 4,
origins = { @DiameterNode(host = "originserver", realm = "originserver.com"),
@DiameterNode(host = "ro.client", realm = "weblogic.com") },
public class ExampleBean3 {
}
 
//destinations specify both host and realm.
@DiameterBean(
applicationId = 4,
destinations = { @DiameterNode(host = "ro.server", realm = "weblogic.com") })
public class ExampleBean3 {
}
 
//destinations only specify host.
@DiameterBean(
applicationId = 4,
destinations = { @DiameterNode(host = "ro.server") })
public class ExampleBean4 {
}

//destinations only specify realm.
@DiameterBean(
applicationId = 4,
destinations = { @DiameterNode(realm = "weblogic.com") })
public class ExampleBean5 {
}
}

Filtering Observer Methods Based on Command Codes and Parameters

A Diameter bean may need to filter the messages based on the command code of the message. For example, if the Diameter bean wants to receive Session Terminated Answer (STA) and Credit Control Answer (CCA) messages on two different methods, it can do so by using the @DiameterObserver annotation. If the @DiameterObserver annotation is specified in the method, then the code injected by @DiameterObserver will be used by the Diameter stack (CDI) for delivering the message to the correct method.

If two methods have the same @DiameterObserver annotation, the Diameter bean selects the method where the parameter is the same type as the message.

Example 1-6 illustrates this behavior.

Example 1-6 Filtering Observer Methods

public void handleCCA(@Observes @DiameterObserver(code=272) CCA cca) {
}

public void handleAnswer(@Observes @DiameterObserver(code=272) Answer answer) {
}

public void handleSTA(@Observes @DiameterObserver(code=275) Answer answer) {
}

public void handleCCR(@Observes @DiameterObserver(code=272) CCR ccr) {
}

public void handleRequest(@Observes @DiameterObserver(code=272) Request request) {
}

public void handleMessage(@Observes Message message) {
}

In Example 1-6 the following filtering occurs:

  • When a CCA message comes in, it is delivered to handleCCA() not handleAnswer(), because the handleCCA() parameter CCA matches the CCA message type exactly.

  • When an Answer message (not a CCA) with the command code 272 comes in, it it is delivered to the handleAnswer() method.

  • When an STA message comes in, it is delivered to the handleSTA() method.

  • When a CCR message comes in, it is delivered to the handleCCR() method rather than the handleRequest() method.

  • When a request message (not a CCR) with command code 272 comes in, it is delivered to the handleRequest() method.

  • When other Diameter messages come in, they are delivered to the handleMessage() method.

Dynamic Configuration

Since the host and realm values of a @DiameterNode may need to be updated frequently, Converged Application Server leverages Java Enterprise Edition Environmental Entries, and lets you define them as variables, placing their values in SIP application deployment descriptors, such as sip.xml, or web.xml rather than hard coding them in source code. The deployment descriptors can be then be modified without requiring an application recompile. Alternatively, you can use WebLogic deployment plans to modify environmental variables.

In a @DiameterNode if host or realm is defined using the pattern, ${xxxx}, the xxxx is treated as a variable name. That variable name is matched to env-entry-name elements in sip.xml or web.xml, and, when a match occurs, the associated value is returned, replacing ${xxxx}.

The host or realm variable can defined by using letters, digits, hyphen, dots and underscore character.

Example 1-7 is a typical sip.xml configuration file with two env-entry elements containing env-entry-name child elements.

Example 1-7 sip.xml Configuration File

<?xml version="1.0" encoding="UTF-8"?>
<sip-app xmlns="http://www.jcp.org/xml/ns/sipservlet" xmlns:javaee="http://java.sun.com/xml/ns/javaee">
  <app-name>FooServlet</app-name>
  <javaee:display-name>diameter abstract API Test</javaee:display-name>
  <distributable />
  <javaee:env-entry>
    <javaee:description>peer server host name</javaee:description>
    <javaee:env-entry-name>peer-server</javaee:env-entry-name>
    <javaee:env-entry-type> java.lang.String </javaee:env-entry-type>
    <javaee:env-entry-value>ro.client</javaee:env-entry-value>
  </javaee:env-entry>
  <javaee:env-entry>
    <javaee:description>peer server realm</javaee:description>
    <javaee:env-entry-name>peer-realm</javaee:env-entry-name>
    <javaee:env-entry-type> java.lang.String </javaee:env-entry-type>
    <javaee:env-entry-value>example.com</javaee:env-entry-value>
  </javaee:env-entry>
</sip-app>

In Example 1-8, the host value for @DiameterNode is defined as ${peer-server}. To retrieve the value of peer-server from sip.xml in Example 1-7, the env-entry elements are searched for an env-entry-name element that matches peer-server. The match in this case is the env-entry-value, ro.client. Likewise, the realm value, peer-realm from ${peer-realm} matches the env-entry-name, peer-realm, which then returns the env-entry-value, example.com.

Example 1-8 Referencing sip.xml Configuration Parameters

@DiameterBean
(applicationId= 4, 
  peers= {@DiameterNode (host = "${peer-server}", realm ="${peer-realm}")})
public class ExampleBean { 
}

The realm and host values of @DiameterNode can also be changed using a WebLogic deployment plan.

Example 1-9 illustrates a WebLogic Deployment Plan file, plan.xml.

Example 1-9 WebLogic Deployment Plan

<?xml version='1.0' encoding='UTF-8'?>
<deployment-plan xmlns="http://xmlns.oracle.com/weblogic/deployment-plan" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://xmlns.oracle.com/weblogic/deployment-plan http://xmlns.oracle.com/weblogic/deployment-plan/1.0/deployment-plan.xsd">
  <application-name>thirdpartyprotocol</application-name>
  <variable-definition>
    <variable>
      <name>new_peer-server</name>
      <value>ro.client2</value>
    </variable>
    <variable>
      <name>new_peer-realm</name>
      <value>example.com2</value>
    </variable>
  </variable-definition>
  <module-override>
    <module-name>thirdpartyprotocol.war</module-name>
    <module-type>war</module-type>
    <module-descriptor external="false">
      <root-element>web-app</root-element>
      <uri>WEB-INF/web.xml</uri>
    </module-descriptor>
    <module-descriptor external="false">
      <root-element>sip-app</root-element>
      <uri>WEB-INF/sip.xml</uri>
      <variable-assignment>
        <name>new_peer-server</name>
<xpath>/sip-app/env-entry/[env-entry-name="peer-server"]/env-entry-value</xpath>
        <operation>replace</operation>
      </variable-assignment>
      <variable-assignment>
        <name>new_peer-realm</name>    <xpath>/sip-app/env-entry/[env-entry-name="peer-realm"]/env-entry-value</xpath>
        <operation>replace</operation>
      </variable-assignment>
    </module-descriptor>
  </module-override>
</deployment-plan>

In Example 1-9 two variables are defined, new_peer-server and new_peer-realm, which are then used to replace the env-entry-values in sip.xml after plan.xml is deployed. You can use the WebLogic Administration Console to specify a deployment plan for your application, or you can use the weblogic.Deployer to deploy an application with the -plan parameter: 

java weblogic.Deployer -adminurl http://hostname:port -user username -password password -deploy -name application-name -source application-name.war -targets server-name -stage -plan plan.xml