Sun GlassFish Communications Server Diameter Adapter 1.0 Installation and Quick Start Guide

Chapter 3 Generating Diameter Code for Communications Server

The attribute value pair (AVP) code generation tool is based on data present in the dictionary.xml file. The schema for the Diameter dictionary is defined by the dictionary.xsd file. All files are available under the as-install/addons/sundiameter/tools directory.

Generating Diameter Code

For in-depth understanding, refer to the schema for the dictionary.xsd file. The schema defines the following elements:

Application. Identifies the application being supported by the Diameter stack. Includes a list of messages and supported AVPs.
AVP. Holds information that applies to a particular AVP, such as, datatype, vendor information, document reference.
Message. Defines the messages supported by the application, and lists the supported AVPs .

To Use the AVP Code Generation Tool

Input to the code generation tool is done by editing the dictionary.xml file (recommended) or the interfaces that are decorated with required annotations. After editing the dictinary.xml file, you must validate dictionary.xml against dictionary.xsd.

You can directly write the AVP interface decorated with appropriate annotations (example below) and use the tool to generate implementation class.

In the following examples, you can specify AVP attributes such as protected, vendor-bit, mandatory, may-encrypt, or vendor-id of choice. ID and code value should be the same, and unique for each AVP in the dictionary.xml file. The doc-ref-ID always points to a value such as code or code:vendor-id (if vendor-id is present).

Before You Begin

The Diameter service must be created before the Diameter code generation tool can be used.

(Optional) Edit the dictionary.xml file to add a new application or edit an existing application.

Note –
The application ID should be unique for the dictionary.xml file. This step is not mandatory. You can also edit or add AVPs under an existing application.

Example of adding a new application:
<application id="0" package-name="com.sun.diameter.base.api"> .... set of AVPs goes here... </application>

Edit the dictionary.xml file to add new AVPs under a specific application.

Example of adding enumeration AVP:

<avp name="My-Enum-AVP" protected="may" vendor-bit="mustnot" code="899" 
description="" mandatory="must" may-encrypt="no" ID="899" doc-ref-ID="899">
<type type-name="Enumerated"></type>
<enum name="STATE_MAINTAINED" code="0"></enum>
<enum name="NO_STATE_MAINTAINED" code="1"></enum>
</avp>

Example of adding base datatypes AVP:

<avp name="My-Unsigned32-AVP" protected="may" vendor-bit="mustnot" 
code="900" mandatory="must" may-encrypt="no" ID="900" doc-ref-ID="900">
<type type-name="Unsigned32"></type>
</avp>

Example of adding grouped AVP:

<avp name="My-Grouped-AVP" protected="may" vendor-bit="mustnot" code="901" 
mandatory="must" may-encrypt="no" ID="901" doc-ref-ID="900">
<grouped>
<gavp name="My-Unsigned32-AVP" max="-1"/>
<gavp name="My-OctetString-AVP"/>
</grouped>
</avp>

<avp name="My-Unsigned32-AVP" protected="may" vendor-bit="mustnot" code="900" 
mandatory="must" may-encrypt="no" ID="900" doc-ref-ID="900">
<type type-name="Unsigned32"></type>
</avp>

<avp name="My-OctetString-AVP" protected="may" vendor-bit="must" code="902" 
mandatory="must" may-encrypt="no" ID="902" vendor-id="10415" doc-ref-ID="902:10415">
<type type-name="OctetString"></type>
</avp>

Note –

In the preceding examples, you can specify AVP attributes such as protected, vendor-bit, mandatory, may-encrypt, vendor-id of your choice. ID and code value should be same and unique for each AVP in the dictionary.xml file. The doc-ref-ID always points to a value such as 'code' or code:vendor-id (if vendor-id is present).

Edit the dictionary.xml file to add document reference at the end of dictionary.xml file.

Example of adding document reference for Java Docs:
<docs doc-ID="287"> <![CDATA[ <pre> My Document for AVP goes here. </pre>]]> </docs>

Generate AVP classes by running the following command:

% cd as-install/addons/diametertools
% ../../lib/ant/bin/ant all

If you have made changes in the dictionary.xml file as mentioned in Step 2, the following files are created:

EnumMyEnumAVP.java

This is the Enum class for AVP code 899 under given package name (as-install/addons/sundiameter/tools/generated/src/package-name).

Code snapshot:

package com.sun.diameter.application.credit.api;

			import com.sun.diameter.annotation.AVPInfo;

			@AVPInfo(code = 899)
			public enum EnumMyEnumAVP {

			    STATE_MAINTAINED (0),
			    NO_STATE_MAINTAINED (1);
			
			    private int value;

				private EnumMyEnumAVP(int value) {
			        this.value = value;
    			}

			    public int getValue() {
        			return value;
    			}

			    public static EnumMyEnumAVP toValue(int mValue) {
        			if (mValue == 0) {
			            return EnumMyEnumAVP.STATE_MAINTAINED;
        			}
			        if (mValue == 1) {
            			return EnumMyEnumAVP.NO_STATE_MAINTAINED;
        			}
			        return null;
    			}

			}

MyGroupedAVP.java

This is the Java class for AVP code 901 under given package name (as-install/addons/sundiameter/tools/generated/src/package-name).

Code snapshot:

package com.sun.diameter.application.credit.api;

			import java.util.List;
			import com.sun.diameter.annotation.AVPInfo;
			import com.sun.diameter.base.api.AVP;

			@AVPInfo(code = 901, mandatory = "must", mayEncrypt = "no", protect = "may")
			public interface MyGroupedAVP
				extends AVP
			{


				@AVPInfo(code = 900, type = "Unsigned32")
				public List<Long> getMyUnsigned32AVPList();

				@AVPInfo(code = 900, type = "Unsigned32")
				public void setMyUnsigned32AVPList(List<Long> data);

				@AVPInfo(code = 902, vendorId = 10415, type = "OctetString")
				public String getMyOctetStringAVP();

				@AVPInfo(code = 902, vendorId = 10415, type = "OctetString")
				public void setMyOctetStringAVP(String data);

			}

MyGroupedAVPImpl.java

This is the Impl Java class for AVP code 901 under given package name (as-install/addons/sundiameter/tools/generated/src/package-name/impl).

Code snapshot:

package com.sun.diameter.application.credit.api.impl;

			import java.util.ArrayList;
			import java.util.List;
			import com.sun.diameter.annotation.AVPInfo;
			import com.sun.diameter.application.GeneratedApplicationAVPFactory;
			import com.sun.diameter.application.credit.api.MyGroupedAVP;
			import com.sun.diameter.base.api.AVP;
			import com.sun.diameter.base.datatypes.OctetString;
			import com.sun.diameter.base.datatypes.Unsigned32;
			import com.sun.diameter.base.impl.AVPImpl;
			import com.sun.diameter.base.impl.GroupedAVPImpl;

			@AVPInfo(code = 901)
			public class MyGroupedAVPImpl
				extends GroupedAVPImpl
				implements MyGroupedAVP
			{

				private AVPImpl _t;
				private List<Long> myUnsigned32AVPList = new ArrayList<Long>();
				private String myOctetStringAVP;

				public MyGroupedAVPImpl() {
					super();
					this.setCode(901);
					this.setMandatory(true);
					this.setVendorSpecific(false);
					this.setSecured(false);
				}

				public void addAVP(AVP avp) {
					switch ((avp.getCode())) {
						case (900):
						    myUnsigned32AVPList.add(((Unsigned32) avp.getDataAsType()).getValueByObject());
						    break;
						case (902):
						    myOctetStringAVP = ((OctetString) avp.getDataAsType()).getValue();
						    break;
					}
					super.addAVP(avp);
				}

				public boolean isGenerated() {
					return (true);
				}

				public List<Long> getMyUnsigned32AVPList() {
					return myUnsigned32AVPList;
				}MyGroupedAVP.java

				public void setMyUnsigned32AVPList(List<Long> value) {
					this.myUnsigned32AVPList=value;
					this.removeAllAVP(900,-1);
					for (Long v: value) {
						AVP avp;
						avp = GeneratedApplicationAVPFactory.createMyUnsigned32AVP(v);
						this.getNestedAVPs().add(avp);
					}
				}

				public String getMyOctetStringAVP() {
					return myOctetStringAVP;
				}

				public void setMyOctetStringAVP(String value) {
					this.myOctetStringAVP=value;
					this.removeAVP(902,10415);
					AVP avp;
					avp = GeneratedApplicationAVPFactory.createMyOctetStringAVP10415(value);
					this.getNestedAVPs().add(avp);
				}

			}

Makes an entry for Base data type AVPs under:

as-install/addons/sundiameter/tools/generated/src/com/sun/diameter/
application/GeneratedApplicationAVPFactory.java

Code snapshot:

@AVPInfo(code = 900)
			public static AVP createMyUnsigned32AVP(long data) {
				AVPImpl avpImpl = new AVPImpl();
				avpImpl.setData(new Unsigned32(data));
				avpImpl.setCode(900);
				avpImpl.setMandatory(true);
				avpImpl.setVendorSpecific(false);
				avpImpl.setSecured(false);
				return avpImpl;
			}

			@AVPInfo(code = 902, vendorId = 10415)
			public static AVP createMyOctetStringAVP10415(String data) {
				AVPImpl avpImppublic static MyGroupedAVP createMyGroupedAVP() {
				return new MyGroupedAVPImpl();
			}l = new AVPImpl();
				avpImpl.setData(new OctetString(data));
				avpImpl.setCode(902);
				avpImpl.setMandatory(true);
				avpImpl.setVendorSpecific(true);
				avpImpl.setVendorId(10415);
				avpImpl.setSecured(false);
				return avpImpl;
			}

			@AVPInfo(code = 899)
			public static AVP createMyEnumAVP(EnumMyEnumAVP data) {
				AVPImpl avpImpl = new AVPImpl();
				avpImpl.setData(new Enumerated((data.getValue())));
				avpImpl.setCode(899);
				avpImpl.setMandatory(true);
				avpImpl.setVendorSpecific(false);
				avpImpl.setSecured(false);
				return avpImpl;
			}

Makes an entry for Grouped type AVPs under:

as-install/addons/sundiameter/tools/generated/src/com/sun/diameter
/application/ApplicationAVPFactory.java

Code snapshot:

public static MyGroupedAVP createMyGroupedAVP() {
				return new MyGroupedAVPImpl();
			}

Here, package-name points to the attribute value present at application level. For example:

<application id="0" package-name="com.sun.diameter.base.api">

All files are compiled and available under as-install/addons/sundiameter/tools.

Use newly generated classes in Diameter.

% cd as-install/addons/sundiameter/tools/build/   
% jar -cvf jar-name .
% cp jar-name as-install/domains/domain-name/applications/j2ee-modules/sundiameter/
% cd as-install/domains/domain-name/applications/j2ee-modules/sundiameter/
% jar -xvf jar-name

Note –

For a cluster scenario, you must run this sequence manually on each instance, then restart the cluster. Use the stop-cluster(1) and start-cluster(1) commands to restart the instances.

Restart the domain.

Use the stop-domain(1) and start-domain(1) commands.

If you have given your own package-name at the application level, you need to make the same entry as a JVM Option.
1. Open Admin Console.
2. Go to Application Server -> JVM Settings -> JVM Options
3. Click Add JVM Option and add the following entry:
  -Dsun.diameter.avp.packagelist=<package-name>
4. Click Save.
5. Restart the domain.
  
  Use the stop-domain(1) and start-domain(1) commands.