JBoss.orgCommunity Documentation
The Mobicents Diameter Multiplexer (MUX) is designed as a stack wrapper. It serves two purposes:
It exposes the Diameter Stack and allows it to be shared between multiple listeners. The stack follows the MUX life cycle, ie, it is created and destroyed with the MUX.
It exposes management operations for JMX clients, one of them being the Jopr Console. For specifc information please refer to the Mobicents Diameter Management Console User Guide.
Mobicents Diameter MUX is a simple service provided on behalf of stack. Entities interested in receiving messages, for a certain Diameter application, may register for that in the MUX. Upon registration entity passes set of Application-Ids, which are of interest to it. Based on message content and registered listeners, MUX either drops message or passes it to proper listener. MUX checks Application-Ids present in message to match target listener.
Ensure that the following requirements have been met before continuing with the install.
This section provides instructions on how to obtain and build the Mobicents Diameter MUX from source code.
Downloading the source code
Subversion is used to manage its source code. Instructions for using Subversion, including install, can be found at http://svnbook.red-bean.com.
Use SVN to checkout a specific release source, the base URL is http://mobicents.googlecode.com/svn/tags/servers/diameter/core/mux, then add the specific release version, lets consider 1.3.0.FINAL.
[usr]$ svn co http://mobicents.googlecode.com/svn/tags/servers/diameter/core/mux/1.3.0.FINAL mux-1.3.0.FINAL
Building the source code
Maven 2.0.9 (or higher) is used to build the release. Instructions for using Maven2, including install, can be found at http://maven.apache.org.
Use Maven to build the deployable unit binary.
[usr]$ cd mux-1.3.0.FINAL [usr]$ mvn install
Once the process finishes you should have the SAR built. If JBOSS_HOME
environment variable is set, after execution SAR will be deployed in container.
By default Mobicents Diameter MUX; deploys in JBoss Application Server v4.x SAR. To change it run maven with profile switch: -Pjboss5
Similar process as for Section 3.2.2.1, “Release Source Code Building”, the only change is the SVN source code URL, which is http://mobicents.googlecode.com/svn/trunk/servers/diameter/core/mux.
MUX requires has three configuration files:
jboss-service.xml
This file is specific to SAR, please refer to JBoss Application Server manual for explanation. By default this file binds Mobicents Diameter MUX under following JMX object name: diameter.mobicents:service=DiameterStackMultiplexer
.
jdiameter-config.xml
This file configures stack exposed by MUX, please refer to Section 2.3, “Mobicents Diameter Stack Configuration” for details. It is located in mobicents-diameter-mux-1.3.0.FINAL.sar/config
dictionary.xml
This file configures dictionary. Its structure and content is identical to file described in Section 2.5.1, “Validator Configuration”.
Mobicents Diameter MUX capabilities are defined by a MBean interface: org.mobicents.diameter.stack.DiameterStackMultiplexerMBean
. This interface defines two types of methods:
Used by Jopr console, those methods are out of scope for user.
Methods which allow retrieval and usage of wrapped stack.
The following methods are of interest to Mobicents Diameter MUX user:
public Stack getStack();
Returns the stack instance wrapped by multiplexer. It's present as a convenience method, and stack should only be changed directly by expert users.
public void registerListener(DiameterListener listener, ApplicationId[] appIds) throws IllegalStateException;
Method for registering a Diameter listener, to be triggered when a message for certain application id is received.
public void unregisterListener(DiameterListener listener);
Method for unregistering a Diameter listener, for all its applications.
public DiameterStackMultiplexerMBean getMultiplexerMBean();
Returns the actual instance of MUX.
Listener interface is defined as follows:
package org.mobicents.diameter.stack;
import java.io.Serializable;
import org.jdiameter.api.Answer;
import org.jdiameter.api.EventListener;
import org.jdiameter.api.NetworkReqListener;
import org.jdiameter.api.Request;
public interface DiameterListener extends NetworkReqListener, Serializable,
EventListener<Request, Answer>
{
}
MUX can be used as follows:
public class DiameterActor implements DiameterListener
{
private ObjectName diameterMultiplexerObjectName = null;
private DiameterStackMultiplexerMBean diameterMux = null;
private synchronized void initStack() throws Exception {
this.diameterMultiplexerObjectName =
new ObjectName("diameter.mobicents:service=DiameterStackMultiplexer");
Object[] params = new Object[]{};
String[] signature = new String[]{};
String operation = "getMultiplexerMBean";
this.diameterMux=mbeanServer.invoke(this.diameterMultiplexerObjectName, operation,
params, signature);
long acctAppIds = new long[]{19312L};
long acctVendorIds = new long[]{193L};
long authAppIds = new long[]{4L};
long authVendorIds = new long[]{0L};
List<ApplicationId> appIds = new ArrayList<ApplicationId>();
for(int index = 0;index<acctAppIds.length;index++) {
appIds.add(ApplicationId.createByAccAppId(acctVendorIds[index], acctAppIds[index]));
}
for(int index = 0;index<authAppIds.length;index++) {
appIds.add(ApplicationId.createByAuthAppId(authVendorIds[index], authAppIds[index]));
}
this.diameterMux.registerListener(this, appIds.toArray(new ApplicationId[appIds.size()]));
this.stack = this.diameterMux.getStack();
this.messageTimeout = stack.getMetaData().getConfiguration().getLongValue(
MessageTimeOut.ordinal(), (Long) MessageTimeOut.defValue());
}
}
Dictionary is part of Diameter MUX package. Its purpose is to provide unified access to information regarding AVP structure, content and definition. Dictionary is configured via a XML file, dictionary.xml
.
The Dictionary logic is contained in org.mobicents.diameter.dictionary.AvpDictionary
class. It exposes the following methods:
public AvpRepresentation getAvp(int code)
Return an AvpRepresentation
object representing the AVP with the given code (assuming vendor id as 0 (zero)). If there is no AVP defined, null
is returned.
public AvpRepresentation getAvp(int code, long vendorId)
Returns an AvpRepresentation
object representing the AVP with the given code and vendor id. If there is no AVP defined, null
is returned.
public AvpRepresentation getAvp(String avpName)
Returns an AvpRepresentation
object representing the AVP with the given name. If there is no AVP defined, null
is returned.
Dictionary uses a POJO class (org.mobicents.diameter.dictionary.AvpRepresentation
) to provide access to stored information. It exposes the following methods:
public int getCode()
Returns the code assigned to represented AVP.
public long getVendorId()
Returns the vendor id assigned to represented AVP.
public String getName()
Returns the name assigned to represented AVP. If no name is defined, null
is returned.
public boolean isGrouped()
Returns true
if AVP is of grouped type.
public String getType()
Returns a String with the name of the represented AVP type. Return value is equal to one of defined types, for instance OctetString or Unsiged32.
public boolean isMayEncrypt()
Returns true
if AVP can be encrypted.
public boolean isProtected()
Returns true
if AVP must be encrypted. It returns true
only if public String getRuleProtected()
returns must
.
public boolean isMandatory()
Returns true
if AVP must be supported by agent to properly consume message. It returns true
only if public String getRuleMandatory()
returns must
.
public String getRuleMandatory()
Returns the mandatory rule value. It can return one of following values: may
, must
or mustnot
.
public String getRuleProtected()
Returns the protected rule value. It can have one of following values: may
, must
or mustnot
.
public String getRuleVendorBit()
Returns the vendor rule value. It can have one of following values: must
or mustnot
.
The Mobicents Diameter MUX Dictionary can be used as follows:
public static void addAvp(Message msg, int avpCode, long vendorId, AvpSet set, Object avp) {
AvpRepresentation avpRep = AvpDictionary.INSTANCE.getAvp(avpCode, vendorId);
if(avpRep != null) {
DiameterAvpType avpType = DiameterAvpType.fromString(avpRep.getType());
boolean isMandatoryAvp = avpRep.isMandatory();
boolean isProtectedAvp = avpRep.isProtected();
if(avp instanceof byte[]) {
setAvpAsRaw(msg, avpCode, vendorId, set, isMandatoryAvp, isProtectedAvp, (byte[]) avp);
}
else
{
switch (avpType.getType()) {
case DiameterAvpType._ADDRESS:
case DiameterAvpType._DIAMETER_IDENTITY:
case DiameterAvpType._DIAMETER_URI:
case DiameterAvpType._IP_FILTER_RULE:
case DiameterAvpType._OCTET_STRING:
case DiameterAvpType._QOS_FILTER_RULE:
setAvpAsOctetString(msg, avpCode, vendorId, set, isMandatoryAvp, isProtectedAvp,
avp.toString());
break;
case DiameterAvpType._ENUMERATED:
case DiameterAvpType._INTEGER_32:
setAvpAsInteger32(msg, avpCode, vendorId, set, isMandatoryAvp, isProtectedAvp,
(Integer) avp);
break;
case DiameterAvpType._FLOAT_32:
setAvpAsFloat32(msg, avpCode, vendorId, set, isMandatoryAvp, isProtectedAvp,
(Float) avp);
break;
case DiameterAvpType._FLOAT_64:
setAvpAsFloat64(msg, avpCode, vendorId, set, isMandatoryAvp, isProtectedAvp,
(Float) avp);
break;
case DiameterAvpType._GROUPED:
setAvpAsGrouped(msg, avpCode, vendorId, set, isMandatoryAvp, isProtectedAvp,
(DiameterAvp[]) avp);
break;
case DiameterAvpType._INTEGER_64:
setAvpAsInteger64(msg, avpCode, vendorId, set, isMandatoryAvp, isProtectedAvp,
(Long) avp);
break;
case DiameterAvpType._TIME:
setAvpAsTime(msg, avpCode, vendorId, set, isMandatoryAvp, isProtectedAvp,
(Date) avp);
break;
case DiameterAvpType._UNSIGNED_32:
setAvpAsUnsigned32(msg, avpCode, vendorId, set, isMandatoryAvp, isProtectedAvp,
(Long) avp);
break;
case DiameterAvpType._UNSIGNED_64:
setAvpAsUnsigned64(msg, avpCode, vendorId, set, isMandatoryAvp, isProtectedAvp,
(Long) avp);
break;
case DiameterAvpType._UTF8_STRING:
setAvpAsUTF8String(msg, avpCode, vendorId, set, isMandatoryAvp, isProtectedAvp,
(String) avp);
break;
}
}
}
}