net.juniper.smgt.ent.im
Interface Session

public interface Session

An instance of this interface represents a subscription Session. A Session exists for every Access that is affected by a given Subscription. Recall that Subscriptions are created when a Subscriber (i.e. an Enterprise, Site, or Access) is subscribed to a service. When a Subscription is created, a set of Sessions is also created as a side-effect:

• Subscribing an Enterprise to a service will create a Subscription under the Enterprise, and as a side effect, an associated Session under each Access contained within the Enterprise (including those contained within all its Sites).
• Subscribing a Site to a service will create a Subscription under the Site, and as a side effect, an associated Session under each Access contained within the Site.
• Subscribing an Access to a service will create a Subscription under the Access, and as a side effect, an associated Session under the same Access.

The following Subscriber hierarchy provides an example:

• Acme Enterprise
  • Timbuktu Site
    • Primary Access
    • Backup Acccess
  • Skookumchuck Site
    • Remote Access

If the "Acme" Enterprise in this example were to subscribe to a service X, and the "Timbuktu" Site were to subscribe to a service Y, and the "Remote" access were to subscribe to a service Z, then the following Sessions would be created as a side effect:

• Acme Company
  • X Subscription
  • Skookumchuck Site
    • Remote Access
      • X Session (for the Remote Access)
  • Timbuktu Site
    • Y Subscription
    • Primary Access
      • X Session (for the Primary Access)
      • Y Session (for the Primary Access)
    • Backup Acccess
      • Z Subscription
      • X Session (for the Backup Access)
      • Y Session (for the Backup Access)
      • Z Session (for the Backup Access)

In other words, for every Access that is affected by a given Subscription, there will exist a corresponding Session. Session objects are not currently Persistent objects.

The role of Service Parameters

Understanding the Session's getXxxValues methods requires understanding service parameters. When a Session is activated, Service policies are applied to the ERX interface associated with the Session's Access. Those service policies may be parameterized. In such cases, some values that are required in those policies (e.g. the bandwidth to be used in a service that enforces rate limiting, the port to be used in a service that affects traffic to or from a specific TCP port) must be aquired at the time the Session is activated. The SSP server that is currently responsible for managing a Session will obtain such values from the parameter aquisition path. The parameter aquisition path is a sequence of objects that the SSP server searches to obtain values for each service parameter. This sequence of objects includes the relevant Enterprise, Site, and Access objects, as well as the relevant Subscription and Session objects, among others. These objects may be under the control of different Managers, who are able to affect the values for a given service parameter by defining Substitutions in the objects under their control. Substitutions assign values to the variables that are used as the parameters for a service's policies.

The values defined by Substitutions in objects accessible to Managers are administrative values. The values that can be obtained only by the SSP server when it is actually activating a Session (e.g. an ERX interface's bandwidth, the SSP server's IP address, etc.) are runtime values. The set of values that result from combining administrative and runtime values are the operational values. For a given Session, there must exist an opertional value for each service parameter; any attempt to activate a Session will fail until some Manager supplies the missing values by creating Substitutions in some object on the service parameter aquisition path. See the SDX Administration and Opeartions Guide for more detail.

Method Summary

List	getAdministrativeValues() Returns the administrative values for all service parameters, except those that will be bound to the value of run-time variables (see this interface's introduction and the SSC documentation for more detail).
Long	getBytesFromUser() Return the number of bytes sent across the network from the user to the service (i.e. to the network resource controlled by the subscribed service), as defined by the service's network policies.
Long	getBytesToUser() Return the number of bytes sent across the network from the service (i.e. from the network resource controlled by the subscribed service) to the user, as defined by the service's network policies.
Long	getCollectionTime() Return the time and date at which these usage statistics were collected from the network.
Long	getDurationActive() Return the number of milliseconds that have passed since this session was activated (i.e. since its `active' property was set to `true').
Long	getDurationActiveAtCollectionTime() Return the number of milliseconds that have passed since this session was activated (i.e. since its `active' property was set to `true') until the time and date returned by getCollectionTime().
List	getOperationalValues() Returns all the values for all service parameters, including those that will be bound to the value of run-time variables (see this interface's introduction and the SSC documentation for more detail).
Long	getPacketsFromUser() The number of IP packets sent across the network from the user to the service (i.e. to the network resource controlled by the subscribed service), as defined by the service's network policies.
Long	getPacketsToUser() Return the number of IP packets sent across the network from the service (i.e. from the network resource controlled by the subscribed service) to the user, as defined by the service's network policies.
List	getPolicyValues() For debugging and advanced portals only.
Long	getReloadTime() Return the last time that the reload() method was called.
List	getRuntimeValues() For debugging and advanced portals only.
Subscriber	getSubscriber() Returns the Access (or to be more precise, the leaf Subscriber) with which this Session is associated.
Subscription	getSubscription() Returns the Subscription associated with this Session.
boolean	isActive() Returns the operational state of this Session, as opposed to its administrative state.
void	reload() Contacts the SAE server currently responsible for managing this Session and obtains a updated version of the information that will subsequently be returned by the methods isActive, getRuntimeValues, getOperationalValues, and getPolicyValues, getDurtionActive, getCollectionTime, getBytesToUser, getBytesFromUser, getPacketsToUser, getPacketsFromUser.
void	setActive(boolean requestedOperationalState) Requests a specific operational state for this Session, regardless of its administrative state.

Method Detail

getSubscription

Subscription getSubscription()
                             throws CommunicationException

Returns the Subscription associated with this Session.

Throws:

CommunicationException - Thrown if there is a problem communicating with the directory.

getSubscriber

Subscriber getSubscriber()
                         throws CommunicationException

Returns the Access (or to be more precise, the leaf Subscriber) with which this Session is associated. Note that this is not necessarily the same as the value returned by getSubscription().getSubscriber().

Returns:

The Access (or to be more precise, the leaf Subscriber) with which this Session is associated.

Throws:

CommunicationException - Thrown if there is a problem communicating with the directory.

setActive

void setActive(boolean requestedOperationalState)
               throws CommunicationException,
                      AccessControlException,
                      SessionException

Requests a specific operational state for this Session, regardless of its administrative state. See isActive() for an explanation of administrative and operational states. The administrative state of this Session, and all the other Sessions associated with this Session's Subscription, will remain unchanged after calling this method. If the requested operational state is different from the current operational state, and this Session is managed by a local SSP server (i.e. an SSP server running inside the same Java virtual machine as the enterprise portal), then this method will attempt to activate or deactivate this Session.

Parameters:

requestedOperationalState - The requested state. True means active; false means inactive.

Throws:

CommunicationException - Thrown if there is a problem communicating with the directory.

AccessControlException - Thrown if the currently bound Manager does not have permission to alter the operational state of Sessions. (Note that feature is not supported with SSC release 3.0; this exception will not be thrown until a future SSC release.)

SessionException - Thrown if there is an error that prevents setting the operational state of this session. This includes an error while attempting to activate or deactivate the Session, and an error in which the Substitutions on the aquisition path fail to define values for all the required service parameters. (For more details, see this interface's introduction, its getXxxValues methods, and the Substitutions interface.)

isActive

boolean isActive()
                 throws SessionException

Returns the operational state of this Session, as opposed to its administrative state. The administrative state can be obtained by calling getSubscription().isActive(). If the administrative state of a Subscription is "active", then the administrative state of every Session associated with the Subscription is also "active". An "active" administrative state means that a session should be active (i.e. service policies should be applied to the ERX interface associated with the Session's Access). In contrast, the operational state of a Session indicates whether it actually is active. The operational state of a Session may be different from its administrative state for a variety of reasons, including delays or problems in directory communication paths, the state of the underlying ERX interface associated with the Session's Access, etc.

Returns:

Returns true if getSubscription() is active for getSubscriber()

Throws:

SessionException - Thrown if the SSP server managing the Session could not be located.

getAdministrativeValues

List getAdministrativeValues()
                             throws CommunicationException,
                                    AccessControlException,
                                    SubstitutionFormatException

Returns the administrative values for all service parameters, except those that will be bound to the value of run-time variables (see this interface's introduction and the SSC documentation for more detail). For each such service parameter, one Substitution object will be returned. The value in each returned Substitution may be an expression that includes run-time variables.

If any of the returned Substitutions has no value, or if the value is an expression that includes non-run-time variables, then not all the service parameters will be bound to values, and attempts to activate this Session will throw an excepeption.

Returns:

A List of Substitution objects. The order of the Substitutions in the List is the same as the order of the Substitutions returned by getSubscription().getService().getParameters(). If the parameter list is of the form [var1, var2, ..., varN] then the list of administrative values list will be of the form [var1=value1, var2=value2, ..., varN=valueN].

Throws:

CommunicationException - Thrown if there is a problem communicating with the directory.

AccessControlException - Thrown if the currently bound Manager does not have permission to get these Substitutions.

net.juniper.smgt.lib.subst.SubstitutionException - Thrown if there is an inconsistency in the type of Substitutions in the aquisition path that are bound to each other.

SubstitutionFormatException

getOperationalValues

List getOperationalValues()
                          throws SessionException

Returns all the values for all service parameters, including those that will be bound to the value of run-time variables (see this interface's introduction and the SSC documentation for more detail). For each such service parameter, one Substitution object will be returned. The values for the service parameters that will be bound to run-time variables are obtained by querying the SSP server that is responsible for this Session.

Returns:

A List of Substitution objects. No particular ordering of the Substitutions in the List is guaranteed.

Throws:

SessionException - Thrown if the SSP server managing this Session could be located.

getRuntimeValues

List getRuntimeValues()
                      throws SessionException

For debugging and advanced portals only. Returns all the values of only the run-time variables for this Session. The values are obtained by querying the SSP server that is responsible for this Session.

Returns:

A List of Substitution objects.

Throws:

SessionException - Thrown if the SSP server managing this Session could be located.

getPolicyValues

List getPolicyValues()
                     throws SessionException

For debugging and advanced portals only. Returns the values for the parameters that are defined in the service's policies.

Returns:

j A List of Substitution objects.

Throws:

SessionException - Thrown if the SSP server managing this Session could be located.

reload

void reload()
            throws SessionException

Contacts the SAE server currently responsible for managing this Session and obtains a updated version of the information that will subsequently be returned by the methods isActive, getRuntimeValues, getOperationalValues, and getPolicyValues, getDurtionActive, getCollectionTime, getBytesToUser, getBytesFromUser, getPacketsToUser, getPacketsFromUser.

Throws:

SessionException - Thrown if the SAE server managing this Session could not be located.

getReloadTime

Long getReloadTime()

Return the last time that the reload() method was called. The format is a Long representing number of milliseconds since the standard base time known as "the epoch", namely January 1, 1970, 00:00:00 GMT. Reload() is implicitly called automatically the first time any method that reads operational state of the session is called.

Returns:

the reload time or zero if reload() has never been called

getDurationActive

Long getDurationActive()
                       throws SessionException

Return the number of milliseconds that have passed since this session was activated (i.e. since its `active' property was set to `true').

Throws:

SessionException

getBytesToUser

Long getBytesToUser()
                    throws SessionException

Return the number of bytes sent across the network from the service (i.e. from the network resource controlled by the subscribed service) to the user, as defined by the service's network policies.

Throws:

SessionException

getBytesFromUser

Long getBytesFromUser()
                      throws SessionException

Return the number of bytes sent across the network from the user to the service (i.e. to the network resource controlled by the subscribed service), as defined by the service's network policies.

Throws:

SessionException

getPacketsToUser

Long getPacketsToUser()
                      throws SessionException

Return the number of IP packets sent across the network from the service (i.e. from the network resource controlled by the subscribed service) to the user, as defined by the service's network policies.

Throws:

SessionException

getPacketsFromUser

Long getPacketsFromUser()
                        throws SessionException

The number of IP packets sent across the network from the user to the service (i.e. to the network resource controlled by the subscribed service), as defined by the service's network policies.

Throws:

SessionException

getCollectionTime

Long getCollectionTime()
                       throws SessionException

Return the time and date at which these usage statistics were collected from the network. The format is a Long representing number of milliseconds since the standard base time known as "the epoch", namely January 1, 1970, 00:00:00 GMT. returns Long(0) if the collection time is unknown

Throws:

SessionException

getDurationActiveAtCollectionTime

Long getDurationActiveAtCollectionTime()
                                       throws SessionException

Return the number of milliseconds that have passed since this session was activated (i.e. since its `active' property was set to `true') until the time and date returned by getCollectionTime().

Throws:

SessionException