.diameter.diameter-core-docs-sources-asciidoc.1.7.0.137.source-code.Section-JDiameter-Source_Overview.adoc Maven / Gradle / Ivy
[[_jdiameter_source_overview]]
= Diameter Stack Source overview
Diameter stack is built with the following basic components:
Session Factory::
The Session Factory governs the creation of sessions - raw and specific application sessions.
Raw and Application Sessions::
Sessions govern stateful message routing between peers.
Specific application sessions consume different type of messages and act differently based on the data present.
Stack::
The Stack governs all necessary components, which are used to establish connection and communicate with remote peers.
NOTE: For more detailed information, please refer to the Javadoc or the simple examples that can be found here: https://github.com/RestComm/jdiameter/tree/master/testsuite/load[Git Testsuite HEAD].
[[_jdiameter_source_overview_session_factory]]
== Session Factory
[class]`SessionFactory` provides the stack user with access to session objects.
It manages registered application session factories in order to allow for the creation of specific application sessions.
A Session Factory instance can be obtained from the stack using the [method]`getSessionFactory()` method.
The base [class]`SessionFactory` interface is defined below:
[source,java]
----
package org.jdiameter.api;
import org.jdiameter.api.app.AppSession;
public interface SessionFactory {
RawSession getNewRawSession() throws InternalException;
Session getNewSession() throws InternalException;
Session getNewSession(String sessionId) throws InternalException;
T getNewAppSession(ApplicationId applicationId,
Class userSession) throws InternalException;
T getNewAppSession(String sessionId, ApplicationId
applicationId, Class userSession) throws InternalException;
}
----
However, since the stack is extensible, it is safe to cast the [class]`SessionFactory` object to this interface:
[source,java]
----
package org.jdiameter.client.api;
public interface ISessionFactory extends SessionFactory {
T getNewAppSession(String sessionId,
ApplicationId applicationId, java.lang.Class
aClass, Object... args) throws InternalException;
void registerAppFacory(Class sessionClass,
IAppSessionFactory factory);
void unRegisterAppFacory(Class sessionClass);
IConcurrentFactory getConcurrentFactory();
}
----
[method]`RawSession getNewRawSession() throws InternalException;`::
This method creates a [class]`RawSession`.
Raw sessions are meant as handles for code performing part of the routing decision on the stack's, such as rely agents for instance.
[method]`Session getNewSession() throws InternalException;`::
This method creates a session that acts as the endpoint for peer communication (for a given session ID). It declares the method that works with the [class]`Request` and [class]`Answer` objects.
A session created with this method has an autogenerated ID.
It should be considered as a client session.
[method]`Session getNewSession(String sessionId) throws InternalException;`::
As above.
However, the created session has an ID equal to that passsed as an argument.
This created session should be considered a server session.
[method]` T getNewAppSession(ApplicationId applicationId, Class userSession) throws InternalException;`::
This method creates a new specific application session, identified by the application ID and class of the session passed.
The session ID is generated by implementation.
New application sessions should be considered as client sessions.
It is safe to type cast the return value to class passed as an argument.
This method delegates the call to a specific application session factory.
[method]` T getNewAppSession(String sessionId, ApplicationId applicationId, Class userSession) throws InternalException;`::
As above.
However, the session Id is equal to the argument passed.
New sessions should be considered server sessions.
[method]` T getNewAppSession(String sessionId, ApplicationId applicationId, java.lang.Class aClass, Object... args) throws InternalException;`::
As above.
However, it allows the stack to pass some additional arguments.
Passed values are implementation specifc.
[method]`void registerAppFacory(Class sessionClass, IAppSessionFactory factory);`::
Registers the [parameter]`factory` for a certain [parameter]`sessionClass`.
This factory will receive a delegated call when ever the [method]`getNewAppSession` method is called with an application class matching one from the register method.
[method]`void unRegisterAppFacory(Class sessionClass);`::
Removes the application session factory registered for the [parameter]`sessionClass`.
.SessionFactory use example
====
[source,java]
----
class Test implements EventListener
{
....
public void test(){
Stack stack = new StackImpl();
XMLConfiguration config = new XMLConfiguration(new FileInputStream(new File(configFile));
SessionFactory sessionFactory = stack.init(config);
stack.start();
//perferctly legal, both factories are the same.
sessionFactor = stack.getSessionFactory();
Session session = sessionFactory.getNewSession();
session.setRequestListener(this);
Request r = session.createRequest(308,ApplicationId.createByAuth(100L,10101L),
"mobicents.org","aaa://uas.fancyapp.mobicents.org");
//add avps specific for app
session.send(r,this);
}
}
----
====
.SessionFactory use example
====
[source,java]
----
class Test implements EventListener
{
Stack stack = new StackImpl();
XMLConfiguration config = new XMLConfiguration(new FileInputStream(new File(configFile));
ISessionFactory sessionFactory = (ISessionFactory)stack.init(config);
stack.start();
//perferctly legal, both factories are the same.
sessionFactor = (ISessionFactory)stack.getSessionFactory();
sessionFactory.registerAppFacory(ClientShSession.class, new ShClientSessionFactory(this));
//our implementation of factory does not require any parameters
ClientShSession session = (ClientShSession) sessionFactory.getNewAppSession(null, null
, ClientShSession.class, null);
...
session.sendUserDataRequest(udr);
}
----
====
[[_jdiameter_source_overview_session]]
== Sessions
[class]`RawSessions`, [class]`Sessions` and [class]`ApplicationSessions` provide the means for dispatching and receiving messages.
Specific implementation of [class]`ApplicationSession` may provide non standard methods.
The [class]`RawSession` and the [class]`Session` life span is controlled entirely by the application.
However, the [class]`ApplicationSession` life time depends on the implemented state machine.
[class]`RawSession` is defined as follows:
[source,java]
----
public interface BaseSession extends Wrapper, Serializable {
long getCreationTime();
long getLastAccessedTime();
boolean isValid();
Future send(Message message) throws InternalException,
IllegalDiameterStateException, RouteException, OverloadException;
Future send(Message message, long timeOut, TimeUnit timeUnit)
throws InternalException, IllegalDiameterStateException, RouteException, OverloadException;
void release();
}
public interface RawSession extends BaseSession {
Message createMessage(int commandCode, ApplicationId applicationId, Avp... avp);
Message createMessage(int commandCode, ApplicationId applicationId,
long hopByHopIdentifier, long endToEndIdentifier, Avp... avp);
Message createMessage(Message message, boolean copyAvps);
void send(Message message, EventListener listener)
throws InternalException, IllegalDiameterStateException, RouteException, OverloadException;
void send(Message message, EventListener listener,
long timeOut, TimeUnit timeUnit) throws InternalException,
IllegalDiameterStateException, RouteException, OverloadException;
}
----
[method]`long getCreationTime();`::
Returns the time stamp of this session creation.
[method]`long getLastAccessedTime();`::
Returns the time stamp indicating the last sent or received operation.
[method]`boolean isValid();`::
Returns `true` when this session is still valid (ie, [method]`release()` has not been called).
[method]`void release();`::
Application calls this method to inform the user that the session should free any associated resource - it shall not be used anymore.
[method]`Future send(Message message)`::
Sends a message in async mode.
The [class]`Future` reference provides the means of accessing the answer once it is received
[method]`void send(Message message, EventListener listener, long timeOut, TimeUnit timeUnit)`::
As above.
Allows to specify the time out value for send operations.
[method]`Message createMessage(int commandCode, ApplicationId applicationId, Avp... avp);`::
Creates a Diameter message.
It should be explicitly set either as a request or answer.
Passed parameters are used to build messages.
[method]`Message createMessage(int commandCode, ApplicationId applicationId, long hopByHopIdentifier, long endToEndIdentifier, Avp... avp);`::
As above.
However, it also allows for the Hop-by-Hop and End-to-End Identifiers in the message header to be set.
This method should be used to create answers.
[method]`Message createMessage(Message message, boolean copyAvps);`::
Clones a message and returns the created object.
The copyAvps parameter defines whether basic AVPs (Session, Route and Proxy information) should be copied to the new object.
[method]`void send(Message message, EventListener listener)`::
Sends a message.
The answer will be delivered by the specified listener
[method]`void send(Message message, EventListener listener, long timeOut, TimeUnit timeUnit)`::
As above.
It also allows for the answer to be passed after timeout.
[class]`Session` defines similar methods, with exactly the same purpose:
[source,java]
----
public interface Session extends BaseSession {
String getSessionId();
void setRequestListener(NetworkReqListener listener);
Request createRequest(int commandCode, ApplicationId appId, String destRealm);
Request createRequest(int commandCode, ApplicationId appId, String destRealm, String destHost);
Request createRequest(Request prevRequest);
void send(Message message, EventListener listener)
throws InternalException, IllegalDiameterStateException, RouteException, OverloadException;
void send(Message message, EventListener listener, long timeOut,
TimeUnit timeUnit) throws InternalException, IllegalDiameterStateException,
RouteException, OverloadException;
}
----
== Application Session Factories
In the table below, you can find session factories provided by current implementation, along with a short description:
.Application Factories
[cols="1,1,1,1", frame="all", options="header"]
|===
| Factory class | Application type & id | Application | Reference
| org.jdiameter.common.impl.app.acc.AccSessionFactoryImpl | AccountingId[0:3] | Acc | FC3588
| org.jdiameter.common.impl.app.auth.AuthSessionFactoryImpl | Specific | Auth | RFC3588
| org.jdiameter.common.impl.app.cca.CCASessionFactoryImpl | AuthId[0:4] | CCA | RFC4006
| org.jdiameter.common.impl.app.sh.ShSessionFactoryImpl | AuthId[10415:16777217] | Sh | TS.29328, TS.29329
| org.jdiameter.common.impl.app.cxdx.CxDxSessionFactoryImpl | AuthId[13019:16777216] | Cx | TS.29228, TS.29229
| org.jdiameter.common.impl.app.cxdx.CxDxSessionFactoryImpl | AuthId[10415:16777216] | Dx | TS.29228, TS.29229
| org.jdiameter.common.impl.app.acc.AccSessionFactoryImpl | AccountingId[10415:3] | Rf | S.32240
| org.jdiameter.common.impl.app.cca.CCASessionFactoryImpl | AuthId[10415:4] | Ro | TS.32240
|===
NOTE: There is no specific factory for Ro and Rf.
Those applications reuse the respective session and session factories.
NOTE: Application IDs contain two numbers - [VendorId:ApplicationId].
IMPORTANT: Spaces have been introduced in the `Factory class` column values to correctly render the table.
Please remove them when using copy/paste.
© 2015 - 2025 Weber Informatics LLC | Privacy Policy