dk.i1.diameter.session
Class BaseSession

Object
  dk.i1.diameter.session.BaseSession

All Implemented Interfaces:

Session

Direct Known Subclasses:

AASession

public abstract class BaseSession
extends Object
implements Session

A basic implementation of a Diameter session It implements a state model as described in RFC3588 section 8.1, and takes care of generating unique session-ids.

Subclasses must override the methods:

• startAuth()
• startReauth()
• handleAnswer(Message,Object).

• getSessionIdOptionalPart()

• handleRequest(Message)
• handleSTA(Message)
• calcNextTimeout() and handleTimeout()
• newStatePre(State,State,Message,int)
• newStatePost(State,State,Message,int)
• collectSTRInfo(Message,int)
• getDestinationRealm()

session_auth_timers

protected SessionAuthTimers session_auth_timers

BaseSession

public BaseSession(int auth_app_id,
                   SessionManager session_manager)

Constructor for BaseSession

Parameters:

auth_app_id - The authentication application-id that will be reported in AAR and STR requests

session_manager - The session manager that manages this session

sessionManager

public final SessionManager sessionManager()

Returns:

The session manager that this session uses

sessionId

public final String sessionId()

Returns the session-id of the session. If the session-id has not been generated yet, null is returned.

Specified by:

sessionId in interface Session

Returns:

The session-id, or null

state

public final BaseSession.State state()

Returns the current state of the session. See RFC3588 section 8.1 for details

authAppId

public final int authAppId()

Retrieve the auth-application-id specified when creating this session.

Returns:

The auth-app-id specified when this session was constructed

authInProgress

public final boolean authInProgress()

Determine if authentication/(re-)authorization is currently in progress.

Returns:

true if initial authentication+authorization or re-authorization is in progress.

authInProgress

protected final void authInProgress(boolean auth_in_progress)

Update the auth-in-progress flag.

stateMaintained

public boolean stateMaintained()

Return whether the server is maintaining state about this sessions. Derived from Auth-Session-State AVP.

Returns:

true if server maintanis state and STR must be sent

stateMaintained

protected void stateMaintained(boolean state_maintained)

Specify if server is maintaining state

Parameters:

state_maintained - If true STR will be sent

firstAuthTime

public long firstAuthTime()

Return the time when the session was first authorized. This is the time when authSuccessful() was first called.

Returns:

The absolute time in milliseconds when the session was first authorized. 0 If it never was.

handleRequest

public int handleRequest(Message request)

Handle a request regarding this session. The BaseSession implementation knows how to handle re-auth-requests and abort-session requests by calling handleRAR() and handleASR(). If an unknown command is encountered COMMAND_UNSUPPORTED is returned. If a subclass implements a diameter application that has additional server-initiated commands it should override this method.

Specified by:

handleRequest in interface Session

Parameters:

request - The request

Returns:

result from handleRAR(), handleASR() or COMMAND_UNSUPPORTED

handleAnswer

public void handleAnswer(Message answer,
                         Object state)

Handle an answer. The BaseSession implementation knows how to handle session-termination answers by calling handleSTA(). If an unknown command is encountered a warning is logged but otherwise ignored.

Specified by:

handleAnswer in interface Session

Parameters:

answer - The answer message

state - The state object specified in sendRequest()

handleNonAnswer

public void handleNonAnswer(int command_code,
                            Object state)

Handle a non-answer. The BaseSession implementation knows how to deal with missing answers to session-termination.

Specified by:

handleNonAnswer in interface Session

Parameters:

command_code - The command_code from the original request.

state - The state object specified in sendRequest()

handleRAR

protected int handleRAR(Message msg)

Process an Re-Auth Request. This implementation starts re-authorization if not already in progress.

Returns:

result-code (success)

handleASR

protected int handleASR(Message msg)

Process an Abort-Session Request. This implementation will stop the session unconditionally. An STR will be sent if the server said it kept state.

Returns:

result-code (success)

authSuccessful

protected void authSuccessful(Message msg)

Tell BaseSession that (re-)authorization succeeded. A subclass must call this method when it has received and successfully processed an authorization-answer.

Parameters:

msg - Message that caused the success. Can be null.

authFailed

protected void authFailed(Message msg)

Tell BaseSession that (re-)authorization failed. The BaseSession implementation closes the session with a suitable termination-cause. A subclass must call this method when it has not received and successfully processed an authorization-answer.

Parameters:

msg - Message that caused the failure. Can be null.

handleSTA

public void handleSTA(Message msg)

Process STA (or lack of STA). This method is called when an STA has been received, or when an STA has not been received (broken link/server down)

Parameters:

msg - The STA message or null

calcNextTimeout

public long calcNextTimeout()

Calculate the next timeout for this session. The BaseSession calculates this based on session-timeout, auth-lifetime and auth-grace-period.

Example override:

         public long calcNextTimeout() //In your session class
             long timeout = BaseSession.calcNextTimeout();
             timeout = Math.min(timeout, quota_timeout);
             return timeout;
         }
         

When overriding this method you should also override handleTimeout().

Specified by:

calcNextTimeout in interface Session

Returns:

The next timeout, or Long.MAX_VALUE if none

handleTimeout

public void handleTimeout()

Handle timeout event. If the session-time (if any) has expired the session is closed. If the auth-lifetime+auth-grace-period has expired the session is closed. If the auth-lifetime is near a reauthorization is initiated.

Specified by:

handleTimeout in interface Session

newStatePre

public void newStatePre(BaseSession.State prev_state,
                        BaseSession.State new_state,
                        Message msg,
                        int cause)

State transition hook. This method is called before the session changes from one state to another

Parameters:

prev_state - The current state

new_state - The next state

msg - The message that caused this transition. May be null if the transition is not caused by a message.

cause - The termination cause. 0 if next_state is not discon.

newStatePost

public void newStatePost(BaseSession.State prev_state,
                         BaseSession.State new_state,
                         Message msg,
                         int cause)

State transition hook. This method is called after the session changes from one state to another

Parameters:

prev_state - The previous state

new_state - The current (new) state

msg - The message that caused this transition. May be null if the transition was not caused by a message.

cause - The termination cause. 0 if next_state is not discon.

openSession

public void openSession()
                 throws InvalidStateException

Open a session. Initiate opening a session. If the session is not idle or is being reused InvalidStateException is thrown. The session does not switch to state 'open' immediately, but rather the session-specific authentication/authorization is initiated.

Throws:

InvalidStateException

closeSession

public void closeSession(int termination_cause)

Close a session. Initiate session tear-down by issuing STR etc. It is harmless to try to close a session more than once.

Parameters:

termination_cause - The reason for closing the session. See RFC3588 section 8.15 for details

closeSession

protected void closeSession(Message msg,
                            int termination_cause)

Close a session.

Parameters:

msg - The message that caused this session to close

termination_cause - The termination-cause for the session.

startAuth

protected abstract void startAuth()

Start the session by sending the first authentication/authorization. This method is called by BaseSession when the session is opened. If there are no authentication/authorization as such for the session type you implement you can call authSuccessful() immediately.

startReauth

protected abstract void startReauth()

Send re-authorization. This method is called by BaseSession when the authorization-lifetime expires or when an RAR has been received.

updateSessionTimeout

protected void updateSessionTimeout(int session_timeout)

Update the session-timeout of this session.

Parameters:

session_timeout - The relative session-time in seconds

collectSTRInfo

protected void collectSTRInfo(Message request,
                              int termination_cause)

Collect information to send in STR message The BaseSession implementation adds Session-Id, Origin-Host, Origin-Realm, Destination-Realm, Auth-Application-Id and Termination-Cause. Subclasses may want to override this to add application-specific AVPs, such as user-name, calling-station-id, etc. When overriding this method, the subclass must first call this method, then add its own AVPs.

Parameters:

request - The STR message

termination_cause - The Termination-Cause for closing the session.

getDestinationRealm

protected String getDestinationRealm()

Get a suitable Destination-Realm value. This method is called when the session needs a value to put into destination-realm AVP (RFC3588 section 6.6) The BaseSession just returns the same realm as the realm in the SessionManager's settings. Subclasses may want to override this and eg. specify the user's realm instead.

Returns:

A suitable destination-realm.

getSessionIdOptionalPart

protected String getSessionIdOptionalPart()

Get optional part of Session-Id. A Session-Id consists of a mandatory part and an optional part. A subclass can override this to provide some information that will be helpful in debugging in production environments. This implementation returns null because it does not have any additional useful information to add. A subclass may want to return eg. user-name or calling-station-id.

Returns:

null

getResultCode

protected static final int getResultCode(Message msg)

Extract the Result-Code AVP value from a message

Returns:

Result-Code value, or -1 if something fails.

addCommonStuff

public void addCommonStuff(Message request)

Add session-id, origin-host+realm and destination-realm to a request. Most Diameter messages have these 4 AVPs. The origin-host and origin-realm are the ones specified in the NodeManager's settings. Destination-realm will be the value returned by getDestinationRealm().

Parameters:

request - The request that should have the 4 AVPs added.