net.juniper.smgt.sae.portal
Class Subscription

java.lang.Object
  |
  +--net.juniper.smgt.sae.portal.Subscription

public class Subscription

extends Object

This bean represents the relationship between a currently logged in user and a currently loaded service to which the user is subscribed. The current value of this bean's serviceName property, together with either its userIp or its userDn property, determines which subscription this bean represents. Whenever one of the two user-identifying properties (userIp or userDn) is set, the other is automatically set to null.
A subscription can be activated and deactivated via the setActive method. This applies and removes policies on the user's E-series interface, and gathers accounting information for billing purposes.
To leverage the power of the service policy parameterization introduced in SSC 3.0, a user may have multiple simultaneous subscription sessions per subscription:

• Each subscription session is identified by a unique (relative to its subscription) session name. That name is this Subscription bean's sessionName property.
• Each session can be activated and deactivated independently. Doing so applies or removes policies from an E-series router interface in the normal manner, and generates accounting data in the normal manner.
• Each session can have its own unique substitutions for its service policies. These substitutions customize the actual policies applied when the session is activated. In the substitution acquisition path, the session's substitutions are the most specific. See the SSC Administration and Operations Guide for more details about how parameter substitutions can be used to customize service policies via paramater value aquisition.

By setting the sessionName property, a subscription bean is initialized to represent a session. Specifying an existing (i.e. active) session's name makes this bean represent that active session. Specifying a new session name prepares this bean to create a new session. Subsequently calling setActive(true) actually creates (i.e. activates) the session.
A subscription bean that has never had its sessionName property set will automatically have the default session name Subscription.DEFAULT_SESSION_NAME. A subscription bean with this default session name represents the subscription's default session. The default session provides backwards compatibility with pre-3.0 portals.
This bean's serviceName property and either its userIp or its userDn property must be set before any other properties are read or written.

Field Summary

static String	ACTIVATE_ON_LOGIN A possible value for this bean's activationTrigger property.
static String	DEFAULT_SESSION_NAME The default value for this bean's sessionName property.
static String	MANUAL A possible value for this bean's activationTrigger property.

Constructor Summary

Subscription()
The default bean constructor.

Subscription(User userBean)

Method Summary

String	getActivationTrigger() Returns either Subscription.ACTIVATE_ON_LOGIN or Subscription.MANUAL, indicating when this subscription will be activated.
SortedSet	getActiveSessionNames() Returns the names of all currently active sessions associated with this subscription.
Object	getAttribute(String attributeName) Returns the value of the named attribute from this subscription's entry in SSP's LDAP user directory.
String[]	getAttributeNames() Get the names of the LDAP attributes defined for the current service session profile.
int	getDownStreamBandwidth() Return the service down stream bandwidth for the subscription session represented by this bean.
long	getDurationActive() Returns the number of milliseconds that have passed since this subscription was activated (i.e.
long	getInterimTime() Returns the interval, in seconds, between service interim records used in the active subscription session represented by this bean.
String	getMultiSubscriptionName() Returns the suffix of the subscription name with which this bean was initialized.
Set	getPersistentSessionNames()
List	getPolicyParameters() Returns a List of substitutions which define the values which this subscription would use for the policy parameters if activated.
int	getRemainingSessionTime() Returns the time in seconds that remain before this subscription will be automatically deactivated by SSP.
String[]	getReplyMessages() Return the "reply messages" from the authorization plug-in for the current user session.
List	getRuntimeParameters() Returns a List of substitutions which define the runtime values (e.g.
String	getServiceName() Returns the service name with which this bean was initialized (e.g.
List	getServiceParameters() Returns a List of substitutions which define the operational values which this subscription would use for the service parameters if activated.
String	getSessionName() Returns the subscription session name with which this bean was initialized.
String	getSessionTag() Return the session tag for the subscription session represented by this bean.
String	getSessionVolumeQuota() Returns the session volume quota for the subscription session represented by this bean.
String	getSubscriptionName() Returns the subscription name with which this bean was initialized (e.g.
String	getSubscriptionPassword() Returns the password that will be used for authentication the next time this subscription is activated, if the subscribed service requires authentication.
String	getSubscriptionUsername() Returns the username that will be used for authentication the next time this subscription is activated, if the subscribed service requires authentication.
String[]	getSubstitutions() Returns the set of susbtitutions defined for the subscription session currently represented by this bean.
int	getUpStreamBandwidth() Return the service up stream bandwidth for the subscription session represented by this bean.
Usage	getUsage() Returns statistics describing the network traffic between the user and the subscribed service (i.e.
String	getUserDn() Returns the LDAP dististinguished name with which this bean was initialized (e.g.
String	getUserIp() Returns the IP address with which this bean was initialized (e.g.
boolean	isActive() Returns true if this subscription is currently active.
boolean	isCurrentlyAvailable() Returns true if the user's subscription to the service is currently available.
boolean	isInitialized() Returns true if this bean has been fully initialized.
boolean	isPersistentActivation() Check if a selected service is to be persistently activated.
boolean	isPersistentSession() Check if a selected session is persistent.
boolean	isSuspended() Returns true if the user's subscription to the service is currently suspended for any reason (e.g.
void	modify() Modifies this subscription session.
void	pollUsage() Collects statistics describing the network traffic between the user and the subscribed service (i.e.
void	setActivationTrigger(String trigger) This method modifies the user's profile in the SSP's LDAP directory to specify when this subscription will be activated.
void	setActive(boolean b) Activates or deactivates this subscription session.
void	setDownStreamBandwidth(int bw) Specifies a service down stream bandwidth to be used the next time the subscription session represented by this bean is activated (i.e.
void	setInterimTime(int time) Specifies the interval, in seconds, between service interim records to be used in the subscription session represented by this bean.
void	setPersistentActivation(boolean active) Creates or deletes a persistent activation.
void	setPersistentSession(boolean persistent) Creates or deletes a persistent service session.
void	setServiceName(String serviceName) Setting this property specifies which of the user's subscribed services will be described or affected by all subsequent reads or writes of this bean's properties.
void	setSessionName(String sessionName) Setting this property specifies which subscription session will be described or affected by all subsequent reads or writes of this bean's properties.
void	setSessionTag(String tag) Tag a service session.
void	setSessionTimeout(int timeout) Specifies a session timeout to be used the next time the subscription session represented by this bean is activated (i.e.
void	setSessionVolumeQuota(String sessionVolumeQuota) Specifies a session volume quota to be used in the subscription session represented by this bean.
void	setSubscriptionPassword(String subscriptionPassword) If the subscribed service requires authentication, then the subscription username and subscription password properties must be set before this subscription is activated.
void	setSubscriptionUsername(String subscriptionUsername) If the subscribed service requires authentication, then the subscription username and subscription password properties must be set before this subscription is activated.
void	setSubstitutions(String[] substs) Sets the substitutions to be used the next time the subscription session represented by this bean is activated (i.e.
void	setUpStreamBandwidth(int bw) Specifies a service up stream bandwidth to be used the next time the subscription session represented by this bean is activated (i.e.
void	setUserDn(String userDn) Setting this property specifies which interface user's subscription will be described or affected by all subsequent reads or writes of this bean's properties.
void	setUserIp(String userIp) Setting this property specifies which user's subscription will be described or affected by all subsequent reads or writes of this bean's properties.
String	toString() For debugging only.
void	updateSessionTimeout(int timeout) Update the session timeout used in the subscription session represented by this bean.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

DEFAULT_SESSION_NAME

public static final String DEFAULT_SESSION_NAME

The default value for this bean's sessionName property.

Since:

3.0

See Also:

setSessionName(java.lang.String), Constant Field Values

MANUAL

public static final String MANUAL

A possible value for this bean's activationTrigger property. A MANUAL activation trigger means that the subscription must be explicitly activated by setting the Subscription bean's active property to true (e.g. via user interaction with a JSP web page).

See Also:

setActivationTrigger(java.lang.String), setActive(boolean), Constant Field Values

ACTIVATE_ON_LOGIN

public static final String ACTIVATE_ON_LOGIN

A possible value for this bean's activationTrigger property. An ACTIVATE_ON_LOGIN activation trigger means that the subscription will be automatically activated whenever the user logs in to SSP. The subscription can still be manually deactivated and activated using the Subscription bean's active property.

See Also:

setActivationTrigger(java.lang.String), setActive(boolean), Constant Field Values

Constructor Detail

Subscription

public Subscription()

The default bean constructor.

Subscription

public Subscription(User userBean)

Method Detail

setUserIp

public void setUserIp(String userIp)
               throws UnknownUserException

Setting this property specifies which user's subscription will be described or affected by all subsequent reads or writes of this bean's properties. Setting this userIp property has the side-effect of setting the userDn property to null.

Parameters:

userIp - The desired user's current IP address in string format (e.g. "192.168.3.34").

Throws:

IllegalArgumentException - If the userIp string does not contain a parseable IP address.

UnknownUserException - If the specified user is not currently logged in to SSP.

NonUniqueUserException - If the user specified by this bean's userDn property is logged in more than once.

getUserIp

public String getUserIp()

Returns the IP address with which this bean was initialized (e.g. "192.168.3.34").

Returns:

Null, if this bean was initialized with an LDAP distinguished name instead of an IP address.

Throws:

IllegalStateException - If this bean has not been properly initialized.

setUserDn

public void setUserDn(String userDn)
               throws UnknownUserException,
                      NonUniqueUserException

Setting this property specifies which interface user's subscription will be described or affected by all subsequent reads or writes of this bean's properties. Setting this userDn property has the side-effect of setting the userIp

Parameters:

userDn - The desired interface user's LDAP Distinguished Name in string format (e.g. "siteName=OttawaOffice,enterpriseName=XyzCorp,ou=Ottawa,retailername=ISP3,o=Users,o=UMC").

Throws:

IllegalArgumentException - If the userDn string does not contain a parseable DN.

UnknownUserException - If an interface user with the specified DN is not currently logged in to SSP.

NonUniqueUserException - If the user specified by this bean's userDn property is logged in more than once.

Since:

3.0

getUserDn

public String getUserDn()

Returns the LDAP dististinguished name with which this bean was initialized (e.g. "siteName=OttawaOffice,enterpriseName=XyzCorp,ou=Ottawa,retailername=ISP3,o=Users,o=UMC").

Returns:

Null, if this bean was initialized with an IP address instead of an LDAP distinguished name.

Throws:

IllegalStateException - If this bean has not been properly initialized.

Since:

3.0

setServiceName

public void setServiceName(String serviceName)
                    throws UnknownServiceException

Setting this property specifies which of the user's subscribed services will be described or affected by all subsequent reads or writes of this bean's properties. Note that the value of some Subscription properties will vary according to the current location of the user who is subscribed to the service.

Parameters:

serviceName - The desired service's name (e.g. "Video Gold").

Throws:

UnknownServiceException - If the service specified by the serviceName argument is not currently loaded into SSP.

getServiceName

public String getServiceName()

Returns the service name with which this bean was initialized (e.g. "Video Gold").

Throws:

IllegalStateException - If this bean has not been properly initialized.

getSubscriptionName

public String getSubscriptionName()

Returns the subscription name with which this bean was initialized (e.g. "Video%channel1"). Only if a service was subscribed using a subscription session name, the subscriptionName is different from the serviceName

Throws:

IllegalStateException - If this bean has not been properly initialized.

getMultiSubscriptionName

public String getMultiSubscriptionName()
                                throws UnknownUserException,
                                       NonUniqueUserException,
                                       UnknownSubscriptionException

Returns the suffix of the subscription name with which this bean was initialized.

E.g. if the subscription was "Video%channel1", the string "channel1" is returned.

Returns:

Identifier of a multiple subscription, or null if the default subscription was accessed.

Throws:

IllegalStateException - If this bean has not been properly initialized.

UnknownUserException

NonUniqueUserException

UnknownSubscriptionException

setSessionName

public void setSessionName(String sessionName)

Setting this property specifies which subscription session will be described or affected by all subsequent reads or writes of this bean's properties. This property is automatically initialized to the default value DEFAULT_SESSION_NAME in all new Subscription beans. Every session has a unique (relative to the subscription) session name. Setting this property to an existing session's name initializes this bean to represent that session. Setting this property to a new session name allows the creation of a new session via a subsequent call to setActive(true).

Parameters:

sessionName - The unique name (relative to the subscription) of the subscription session that this bean is to represent.

Throws:

IllegalArgumentException - If sessionName is null or zero-length.

Since:

3.0

See Also:

DEFAULT_SESSION_NAME

getSessionName

public String getSessionName()

Returns the subscription session name with which this bean was initialized.

Since:

3.0

See Also:

DEFAULT_SESSION_NAME

isInitialized

public boolean isInitialized()

Returns true if this bean has been fully initialized. It is fully initialized if the userIp or userDn property, and the serviceName property, have been set.

isSuspended

public boolean isSuspended()
                    throws UnknownUserException,
                           NonUniqueUserException,
                           UnknownSubscriptionException

Returns true if the user's subscription to the service is currently suspended for any reason (e.g. until payment is received). Any attempt to activate a suspended subscription will result in an exception being thrown. Subscriptions are stored in the SSP's LDAP directory as sspServiceProfile objects. Suspended subscriptions are sspServiceProfile objects in which the sspState attribute does not equal "SUBSCRIBED".

Throws:

IllegalStateException - If this bean has not been properly initialized.

UnknownUserException - If the user is no longer logged in to SSP.

NonUniqueUserException - If the user specified by this bean's userDn property is logged in more than once.

UnknownSubscriptionException - If the user is no longer subscribed to the service.

isCurrentlyAvailable

public boolean isCurrentlyAvailable()
                             throws UnknownUserException,
                                    UnknownSubscriptionException,
                                    NonUniqueUserException

Returns true if the user's subscription to the service is currently available. Any attempt to activate a currently not available subscription will result in an exception being thrown.

Throws:

IllegalStateException - If this bean has not been properly initialized.

UnknownUserException - If the user is no longer logged in to SSP.

UnknownSubscriptionException - If the user is no longer subscribed to the service.

NonUniqueUserException

Since:

4.0

getUsage

public Usage getUsage()
               throws UnknownUserException,
                      NonUniqueUserException,
                      UnknownSubscriptionException,
                      UnknownServiceException

Returns statistics describing the network traffic between the user and the subscribed service (i.e. the network resource controlled by the subscribed service). Depending on how SSP is configured, usage statistics may be collected from the network at regular intervals after this subscription is activated. The returned Usage object contains the usage statistics from the most recent such collection. It includes the time at which the statistics were collected.

Returns:

Null, if no usage statistics are available. This will occur if the subscription is not active, or if SSP is configured to not collect statistics for the subscribed service, or if the subscription was recently activated but usage statistics have net yet been collected from the network.

Throws:

IllegalStateException - If this bean has not been properly initialized.

UnknownUserException - If the user is no longer logged in to SSP.

NonUniqueUserException - If the user specified by this bean's userDn property is logged in more than once.

UnknownServiceException - If the service is no longer loaded in SSP.

UnknownSubscriptionException - If the user is no longer subscribed to the service.

getDurationActive

public long getDurationActive()
                       throws UnknownUserException,
                              NonUniqueUserException,
                              UnknownSubscriptionException

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

Returns:

Returns 0 if this subscription is not currently active.

Throws:

IllegalStateException - If this bean has not been properly initialized.

UnknownUserException - If the user is no longer logged in to SSP.

NonUniqueUserException - If the user specified by this bean's userDn property is logged in more than once.

UnknownSubscriptionException - If the user is no longer subscribed to the service.

getAttribute

public Object getAttribute(String attributeName)
                    throws UnknownUserException,
                           NonUniqueUserException,
                           UnknownSubscriptionException

Returns the value of the named attribute from this subscription's entry in SSP's LDAP user directory. If the attribute is a single value, the returned Object must be cast to the appropriate type. If the attribute is multi-valued, the returned Object must be cast to an array of the appropriate type.

Returns:

Returns null if this subscriptions's entry in SSP's LDAP user directory does not contain an attribute with the specified name.

Throws:

IllegalStateException - If this bean has not been properly initialized.

UnknownUserException - If the user is no longer logged in to SSP.

NonUniqueUserException - If the user specified by this bean's userDn property is logged in more than once.

UnknownSubscriptionException - If the user is no longer subscribed to the service.

Since:

3.0

setSubstitutions

public void setSubstitutions(String[] substs)
                      throws UnknownUserException,
                             NonUniqueUserException,
                             UnknownSubscriptionException

Sets the substitutions to be used the next time the subscription session represented by this bean is activated (i.e. this property will only affect sessions activated via subsequent calls to setActive(true) - note that this restriction may be relaxed in a future release).
Setting substitutions allows the policies defined for the associated service to be customized on a per-session basis. See the SSC Administration and Operations Guide for details about how substitutions affect service policies via paramater value aquisitions, and for detailed information about the format of the Strings that contain the substitutions. In its simplest form, a substitution passed to this method can be encoded as a String of the form <var>=<val>, where <var> is a variable name found in a service's policies, and <val> is the value to be assigned to that variable.

Parameters:

substs - The set of substitutions, with one substitution defined in each String in the array.

Throws:

IllegalArgumentException - If the substitutions are in the wrong format.

IllegalStateException - If this bean has not been properly initialized.

UnknownUserException - If the user is no longer logged in to SSP.

NonUniqueUserException - If the user specified by this bean's userDn property is logged in more than once.

UnknownSubscriptionException - If the user is no longer subscribed to the service.

Since:

3.0

getSubstitutions

public String[] getSubstitutions()
                          throws UnknownUserException,
                                 NonUniqueUserException,
                                 UnknownSubscriptionException

Returns the set of susbtitutions defined for the subscription session currently represented by this bean. These are the substitutions that were passed to the setSubstitutions method of the Subscription bean that represented the session immediately before the session was activated. Note well that these are not necessarily the same as the substitutions most recently passed to this bean's setSubstitutions method.
See the SSC Administration and Operations Guide for details about how substitutions affect service policies via paramater value aquisitions, and for detailed information about the format of the Strings that contain the substitutions.
This method can only be called when the session is active. This restriction may be relaxed in a future release.

Returns:

The set of substitutions, or a zero-length String[] if no substitutions are defined for the session.

Throws:

IllegalStateException - If this bean has not been properly initialized, or if the subscription session specified by this bean's properties is not currently active.

UnknownUserException - If the user is no longer logged in to SSP.

NonUniqueUserException - If the user specified by this bean's userDn property is logged in more than once.

UnknownSubscriptionException - If the user is no longer subscribed to the service.

Since:

3.0

setSessionTimeout

public void setSessionTimeout(int timeout)

Specifies a session timeout to be used the next time the subscription session represented by this bean is activated (i.e. this property will only affect sessions activated via subsequent calls to setActive(true)). SSP will automatically deactivate the session after it has been active for timeout seconds. The session timeout value may be modified via plug-ins after the subscription is activated.

Parameters:

timeout - The session timeout in seconds. A value of -1 (the default if this method is never called) means the session will never time out.

Since:

3.0

updateSessionTimeout

public void updateSessionTimeout(int timeout)
                          throws UnknownUserException,
                                 NonUniqueUserException,
                                 UnknownSubscriptionException

Update the session timeout used in the subscription session represented by this bean. The session timeout counts from the current time, not from the time of the start of the session. If the session timeout is currently not active, it is activated. If the value for timeout is equal to -1, the session timeout is cancelled. The new value for the session timeout is not updated on the E-series router.

Parameters:

timeout - The session timeout in seconds.

Throws:

UnknownUserException - if the User is currently not logged in.

NonUniqueUserException - If the user specified by this bean's userDn property is logged in more than once.

UnknownSubscriptionException - If the user is no longer subscribed to the service.

Since:

4.1

getRemainingSessionTime

public int getRemainingSessionTime()
                            throws UnknownUserException,
                                   NonUniqueUserException,
                                   UnknownSubscriptionException

Returns the time in seconds that remain before this subscription will be automatically deactivated by SSP. This value is the current session timeout value minus the time the subscription has already been active. The session timeout value may be modified via plug-ins after the subscription is activated.

Returns:

Returns -1 if this subscription has no session timeout. Returns 0 if this subscription is not currently active.

Throws:

IllegalStateException - If this bean has not been properly initialized.

UnknownUserException - If the user is no longer logged in to SSP.

NonUniqueUserException - If the user specified by this bean's userDn property is logged in more than once.

UnknownSubscriptionException - If the user is no longer subscribed to the service.

Since:

3.0

setInterimTime

public void setInterimTime(int time)
                    throws UnknownUserException,
                           NonUniqueUserException

Specifies the interval, in seconds, between service interim records to be used in the subscription session represented by this bean. The interim interval value can be modified via plug-ins after the subscription is activated. If the value for time is set to zero or to a value less than zero, interim records are cancelled. If interim records were not been generated (i.e. not set before and no service specific value and no default value), after setting the interval to a value greater than zero, interim records will be generated.

Parameters:

time - The interim interval in seconds.

Throws:

IllegalStateException - If this bean has not been properly initialized.

UnknownUserException - If the user is no longer logged in to SSP.

NonUniqueUserException - If the user specified by this bean's userDn property is logged in more than once.

Since:

4.1

getInterimTime

public long getInterimTime()
                    throws UnknownUserException,
                           NonUniqueUserException,
                           UnknownSubscriptionException

Returns the interval, in seconds, between service interim records used in the active subscription session represented by this bean.

Returns:

Returns interim interval in seconds or -1 if service session is not active

Throws:

IllegalStateException - If this bean has not been properly initialized.

UnknownUserException - If the user is no longer logged in to SSP.

NonUniqueUserException - If the user specified by this bean's userDn property is logged in more than once.

UnknownSubscriptionException - If the user is no longer subscribed to the service.

Since:

4.1

setSessionVolumeQuota

public void setSessionVolumeQuota(String sessionVolumeQuota)
                           throws UnknownUserException,
                                  NonUniqueUserException

Specifies a session volume quota to be used in the subscription session represented by this bean.

Parameters:

sessionVolumeQuota - The session volume quota.

Throws:

UnknownUserException - If the user is no longer logged in to SSP.

NonUniqueUserException - If the user specified by this bean's userDn property is logged in more than once.

Since:

4.1

See Also:

getSessionVolumeQuota()

getSessionVolumeQuota

public String getSessionVolumeQuota()
                             throws UnknownUserException,
                                    NonUniqueUserException

Returns the session volume quota for the subscription session represented by this bean. The session volume quota is a string which contains two decimal encoded numbers, separated by ";". The first number is the number of octets allowed to be sent from the network to the user, the second number is the number of octets allowed to be sent from the user to the network. The value for the session volume quota could be set by this portal API, by a Service Authorization plugin or by the Service definition object.

Returns:

Returns null if this subscription is not currently active.

UnknownUserException

NonUniqueUserException

Since:

4.1

setSubscriptionUsername

public void setSubscriptionUsername(String subscriptionUsername)
                             throws UnknownUserException,
                                    NonUniqueUserException,
                                    UnknownSubscriptionException

If the subscribed service requires authentication, then the subscription username and subscription password properties must be set before this subscription is activated. If the subscribed service has a non-null domainName property, then "@" and the service's domain name are appended to this subscription username for the purpose of authentication only.

Parameters:

subscriptionUsername - Leading and trailing whitespace are automatically trimmed from this String.

Throws:

IllegalStateException - If this bean has not been properly initialized.

UnknownUserException - If the user is no longer logged in to SSP.

NonUniqueUserException - If the user specified by this bean's userDn property is logged in more than once.

UnknownSubscriptionException - If the user is no longer subscribed to the service.

See Also:

setSubscriptionPassword(java.lang.String), Service.isAuthenticationRequired()

getSubscriptionUsername

public String getSubscriptionUsername()
                               throws UnknownUserException,
                                      NonUniqueUserException,
                                      UnknownSubscriptionException

Returns the username that will be used for authentication the next time this subscription is activated, if the subscribed service requires authentication. If the subscribed service has a non-null domainName property, then "@" and the service's domain name are appended to this subscription username for the purpose of authentication only.

Returns:

Null, if the subscriptionUsername property has never been set.

Throws:

IllegalStateException - If this bean has not been properly initialized.

UnknownUserException - If the user is no longer logged in to SSP.

NonUniqueUserException - If the user specified by this bean's userDn property is logged in more than once.

UnknownSubscriptionException - If the user is no longer subscribed to the service.

setSubscriptionPassword

public void setSubscriptionPassword(String subscriptionPassword)
                             throws UnknownUserException,
                                    NonUniqueUserException,
                                    UnknownSubscriptionException

If the subscribed service requires authentication, then the subscription username and subscription password properties must be set before this subscription is activated.

Parameters:

subscriptionPassword - Leading and trailing whitespace are automatically trimmed from this String.

Throws:

IllegalStateException - If this bean has not been properly initialized.

UnknownUserException - If the user is no longer logged in to SSP.

NonUniqueUserException - If the user specified by this bean's userDn property is logged in more than once.

UnknownSubscriptionException - If the user is no longer subscribed to the service.

See Also:

setSubscriptionUsername(java.lang.String), Service.isAuthenticationRequired()

getSubscriptionPassword

public String getSubscriptionPassword()
                               throws UnknownUserException,
                                      NonUniqueUserException,
                                      UnknownSubscriptionException

Returns the password that will be used for authentication the next time this subscription is activated, if the subscribed service requires authentication.

Returns:

Null, if the subscriptionPassword property has never been set.

Throws:

IllegalStateException - If this bean has not been properly initialized.

UnknownUserException - If the user is no longer logged in to SSP.

NonUniqueUserException - If the user specified by this bean's userDn property is logged in more than once.

UnknownSubscriptionException - If the user is no longer subscribed to the service.

setActivationTrigger

public void setActivationTrigger(String trigger)
                          throws UnknownUserException,
                                 NonUniqueUserException,
                                 UnknownSubscriptionException,
                                 UnknownServiceException,
                                 ServiceAuthenticationException,
                                 SspException

This method modifies the user's profile in the SSP's LDAP directory to specify when this subscription will be activated. There are two possible values:

• Subscription.MANUAL: The subscription will be activated only when setActive(true) is called explicitly by a JSP page.
• Subscription.ACTIVATE_ON_LOGIN: The subscription will be activated automatically every time the user logs in to SSP.

Parameters:

trigger - Must be either Subscription.MANUAL or Subscription.ACTIVATE_ON_LOGIN.

Throws:

IllegalArgumentException - If the trigger parameter is neither Subscription.MANUAL nor Subscription.ACTIVATE_ON_LOGIN.

IllegalStateException - If this bean has not been properly initialized.

UnknownUserException - If the user is no longer logged in to SSP.

NonUniqueUserException - If the user specified by this bean's userDn property is logged in more than once.

UnknownSubscriptionException - If the user is no longer subscribed to the service.

UnknownServiceException - If the service is no longer loaded in SSP.

ServiceAuthenticationException - If permission to modify this subscription is denied for any reason. For example, anonymous users are not permitted to modify any subscriptions, subscriptions to services that require authentication may never be marked as ACTIVATE_ON_LOGIN, constraints imposed by mutex groups (i.e. sets of incompatible services) may forbid some combinations of subscriptions being marked as ACTIVATE_ON_LOGIN, etc.

SspException - If this operation fails due to an unexpected error condition in SSP or in an external system upon which SSP depends (e.g. an LDAP directory, a RADIUS server, an E-series router, etc.)

getActivationTrigger

public String getActivationTrigger()
                            throws UnknownUserException,
                                   NonUniqueUserException,
                                   UnknownSubscriptionException

Returns either Subscription.ACTIVATE_ON_LOGIN or Subscription.MANUAL, indicating when this subscription will be activated.

Throws:

IllegalStateException - If this bean has not been properly initialized.

UnknownUserException - If the user is no longer logged in to SSP.

NonUniqueUserException - If the user specified by this bean's userDn property is logged in more than once.

UnknownSubscriptionException - If the user is no longer subscribed to the service.

See Also:

setActivationTrigger(java.lang.String)

setActive

public void setActive(boolean b)
               throws UnknownUserException,
                      NonUniqueUserException,
                      UnknownServiceException,
                      UnknownSubscriptionException,
                      ServiceAuthenticationException,
                      OverloadException,
                      SspException

Activates or deactivates this subscription session. If the subscribed service's authenticationRequired property is true, then this subscription's subscriptionUsername and subscriptionPassword properties are authenticated before the service is activated (i.e. the subscriptionUsername and subscriptionPassword properties must be set before this subscription is activated). Note that if the subscribed service has a non-null domainName property then an "@" and the service's domainName property are automatically appended to the subscriptionUsername property for the purpose of authentication only.
If the subscribed service is of type Service.NORMAL, then the following will occur:

1. The subscribed service's policies will be applied (on activation) or removed (on deactivation).

If the subscribed service is of type Service.ISP, and it is being activated, then the following will occur:

1. After the user's current DHCP lease expires the user will lose his current `token' IP address.
2. The user will be logged out of SSP (and all subscriptions will be deactivated).
3. The user will get a new public IP address.
4. The user will be logged in to SSP (and all ACTIVATE_ON_LOGIN subscriptions will be activated).
5. The subscribed ISP service's policies will be applied.

If the subscribed service is of type Service.ISP, and it is being deactivated, then the following will occur:

1. After the user's current DHCP lease expires the user will lose his current public IP address.
2. The user will be logged out of SSP (and all subscriptions will be deactivated).
3. The user will get a new `token' IP address.
4. The user will be logged in to SSP (and all ACTIVATE_ON_LOGIN subscriptions will be activated).

Throws:

IllegalStateException - If this bean has not been properly initialized.

UnknownUserException - If the user is no longer logged in to SSP.

NonUniqueUserException - If the user specified by this bean's userDn property is logged in more than once.

UnknownServiceException - If the service is no longer loaded in SSP.

UnknownSubscriptionException - If the user is no longer subscribed to the service.

ServiceAuthenticationException - If permission to activate this subscription is denied for any reason. For example, an invalid username or password may be specified, a constraint imposed by mutex groups (i.e. sets of incompatible services) may be violated, etc.

OverloadException - If the COPS interface is currently overloaded.

SspException - If this operation fails due to an unexpected error condition in SSP or in an external system upon which SSP depends (e.g. an LDAP directory, a RADIUS server, an E-series router, etc.)

See Also:

Service.getType(), Service.isAuthenticationRequired(), User.isTokenDhcpUser()

modify

public void modify()
            throws UnknownUserException,
                   NonUniqueUserException,
                   UnknownServiceException,
                   UnknownSubscriptionException,
                   UnknownServiceSessionException,
                   ServiceAuthenticationException,
                   OverloadException,
                   SspException

Modifies this subscription session.
If the subscribed service is of type Service.NORMAL, then the following will occur:

1. If the subscription is not active, throw the exception UnknownServiceSessionException.
2. Publishe the authorization event to the registered plug-ins. If the upStreamBandwidth or downStreamBandwidth properties are set for this bean, the authorize event contains the delta bandwidth (i.e. the difference between the current value for the active session and the new one set by the bean property).
3. Calculate new policies using the properties set by this bean. Compare them against the ones currently in use for the active session. If they have changed, remove them from the router and install the new ones. Save accounting data for the session. The new service session is saved on the router. An interim event is published to registered plug-ins to inform about the modified service session.

If the subscribed service is of type Service.ISP, the exception ServiceAuthenticationException is thrown.

Throws:

IllegalStateException - If this bean has not been properly initialized.

UnknownUserException - If the user is no longer logged in to SSP.

NonUniqueUserException - If the user specified by this bean's userDn property is logged in more than once.

UnknownServiceException - If the service is no longer loaded in SSP.

UnknownSubscriptionException - If the user is no longer subscribed to the service.

UnknownServiceSessionException - If the service session specified by this bean is not active.

ServiceAuthenticationException - If permission to modify this subscription is denied for any reason. For example, trying to modify a session from ISP service, a constraint imposed by an authorization plugin, etc.

OverloadException - If the COPS interface is currently overloaded.

SspException - If this operation fails due to an unexpected error condition in SSP or in an external system upon which SSP depends (e.g. an LDAP directory, an ERX router, etc.)

Since:

4.2

isActive

public boolean isActive()
                 throws UnknownUserException,
                        NonUniqueUserException,
                        UnknownSubscriptionException

Returns true if this subscription is currently active.

Throws:

IllegalStateException - If this bean has not been properly initialized.

UnknownUserException - If the user is no longer logged in to SSP.

NonUniqueUserException - If the user specified by this bean's userDn property is logged in more than once.

UnknownSubscriptionException - If the user is no longer subscribed to the service.

getActiveSessionNames

public SortedSet getActiveSessionNames()
                                throws UnknownUserException,
                                       NonUniqueUserException

Returns the names of all currently active sessions associated with this subscription.

Returns:

The set of active session names, sorted lexicographically. Could be an empty set if there is no currently active sessions associated with this subscription.

Throws:

IllegalStateException - If this bean has not been properly initialized.

UnknownUserException - If the user is no longer logged in to SSP.

NonUniqueUserException - If the user specified by this bean's userDn property is logged in more than once.

Since:

3.0

getPersistentSessionNames

public Set getPersistentSessionNames()
                              throws UnknownUserException,
                                     NonUniqueUserException

UnknownUserException

NonUniqueUserException

setUpStreamBandwidth

public void setUpStreamBandwidth(int bw)

Specifies a service up stream bandwidth to be used the next time the subscription session represented by this bean is activated (i.e. this property will only affect session activated via subsequent calls to setActive(true)). SSP will send it to plug-ins to verify there is enough bandwidth to be allocated for this service.

Parameters:

bw - The up stream bandwidth in bps. A value of -1 (the default if this method is never called) means the there is no up stream bandwidth limitation.

Since:

3.1

getUpStreamBandwidth

public int getUpStreamBandwidth()
                         throws UnknownUserException,
                                NonUniqueUserException

Return the service up stream bandwidth for the subscription session represented by this bean.

Returns:

Return 0 if this subscription is not currently active. Return -1 if up stream bandwidth is not initialized.

Throws:

IllegalStateException - If this bean has not been properly initialized.

UnknownUserException - If the user is no longer logged in to SSP.

NonUniqueUserException - If the user specified by this bean's userDn property is logged in more than once.

Since:

4.2

setDownStreamBandwidth

public void setDownStreamBandwidth(int bw)

Specifies a service down stream bandwidth to be used the next time the subscription session represented by this bean is activated (i.e. this property will only affect session activated via subsequent calls to setActive(true)). SSP will send it to plug-ins to verify there is enough bandwidth to be allocated for this service.

Parameters:

bw - The down stream bandwidth in bps. A value of -1 (the default if this method is never called) means the there is no down stream bandwidth limitation.

Since:

3.1

getDownStreamBandwidth

public int getDownStreamBandwidth()
                           throws UnknownUserException,
                                  NonUniqueUserException

Return the service down stream bandwidth for the subscription session represented by this bean.

Returns:

Return 0 if this subscription is not currently active. Return -1 if down stream bandwidth is not initialized.

Throws:

IllegalStateException - If this bean has not been properly initialized.

UnknownUserException - If the user is no longer logged in to SSP.

NonUniqueUserException - If the user specified by this bean's userDn property is logged in more than once.

Since:

4.2

getAttributeNames

public String[] getAttributeNames()
                           throws UnknownUserException,
                                  NonUniqueUserException,
                                  UnknownSubscriptionException

Get the names of the LDAP attributes defined for the current service session profile. Each returned string can be used as an argument for getAttribute().

Returns:

Array of attribute names

Throws:

UnknownUserException - if the User is currently not logged in.

NonUniqueUserException - If the user specified by this bean's userDn property is logged in more than once.

UnknownServiceException - if the Service is not loaded.

UnknownSubscriptionException

Since:

4.0

setSessionTag

public void setSessionTag(String tag)

Tag a service session. The tag is an arbitrary string and can be used for accounting purposes.

Parameters:

tag - the session tag.

Since:

4.0

getSessionTag

public String getSessionTag()
                     throws UnknownUserException,
                            NonUniqueUserException

Return the session tag for the subscription session represented by this bean.

Returns:

Return null if this subscription is not currently active. Return "" if session tag is not initialized.

Throws:

IllegalStateException - If this bean has not been properly initialized.

UnknownUserException - If the user is no longer logged in to SSP.

NonUniqueUserException - If the user specified by this bean's userDn property is logged in more than once.

Since:

4.2

getReplyMessages

public String[] getReplyMessages()
                          throws UnknownUserException,
                                 NonUniqueUserException

Return the "reply messages" from the authorization plug-in for the current user session. An authorization plug-in can specify a "reply message", when authorization is granted.

Throws:

UnknownUserException - if the User is currently not logged in.

NonUniqueUserException - If the user specified by this bean's userDn property is logged in more than once.

setPersistentSession

public void setPersistentSession(boolean persistent)
                          throws IllegalStateException,
                                 net.juniper.smgt.sae.datamgr.DataMgrException,
                                 UnknownServiceException,
                                 UnknownUserException,
                                 NonUniqueUserException

Creates or deletes a persistent service session. A session name must be set with setSessionName prior to a call to this method; otherwise, a service session is not stored. If sspTimeOut has been changed with setSessionTimeout, the value is saved as well as substitutions set with setSubstitutions for the persistent session. Default values will be overwritten with these values when the session will be activated again.

Parameters:

persistent - true to create a persistent service session, false to delete a persistent service session.

Throws:

IllegalStateException - If this bean has not been properly initialized.

net.juniper.smgt.sae.datamgr.DataMgrException - if the LDAP directory is not available.

UnknownServiceException - if the Service is not loaded.

UnknownUserException - if the User is currently not logged in.

NonUniqueUserException

Since:

4.0

setPersistentActivation

public void setPersistentActivation(boolean active)
                             throws IllegalStateException,
                                    net.juniper.smgt.sae.datamgr.DataMgrException,
                                    UnknownServiceException,
                                    UnknownUserException,
                                    NonUniqueUserException,
                                    ServiceAuthenticationException

Creates or deletes a persistent activation. If setSessionName is called prior to a call to this method, a persistent activation is created for that session. Otherwise, a persistent activation for the default session is created. When a persistent activation or session already exists for the requested session, this method only sets/resets the session for the persistent activation and does not remove the persistent activation/session for deactivation requests. A persistent activation cannot be created for ISP services.

Parameters:

active - true to create a persistent activation, false to delete a persistent activation.

Throws:

IllegalStateException - If this bean has not been properly initialized.

net.juniper.smgt.sae.datamgr.DataMgrException - if the LDAP directory is not available.

UnknownServiceException - if the Service is not loaded.

UnknownUserException - if the User is currently not logged in.

NonUniqueUserException

ServiceAuthenticationException

Since:

4.0

isPersistentActivation

public boolean isPersistentActivation()

Check if a selected service is to be persistently activated.

Returns:

true a service is persistently ACTIVE_ON_LOGIN.

Since:

4.0

isPersistentSession

public boolean isPersistentSession()

Check if a selected session is persistent. If

Returns:

true a session is persistent.

Since:

4.0

getRuntimeParameters

public List getRuntimeParameters()
                          throws UnknownServiceException,
                                 UnknownUserException,
                                 NonUniqueUserException,
                                 UnknownSubscriptionException,
                                 SspException

Returns a List of substitutions which define the runtime values (e.g. "ifSpeed", "userIp", "virtualSSPAddress") of the user owning this subscription.

Returns:

java.util.List

Throws:

UnknownServiceException - If the service is no longer loaded in SSP.

UnknownUserException - If the user is no longer logged in to SSP.

NonUniqueUserException - If the user specified by this bean's userDn property is logged in more than once.

UnknownSubscriptionException - If the user is no longer subscribed to the service.

SspException - If this operation fails due to an unexpected error condition in SSP or in an external system upon which SSP depends (e.g. an LDAP directory, a RADIUS server, an E-series router, etc.)

getPolicyParameters

public List getPolicyParameters()
                         throws UnknownServiceException,
                                UnknownUserException,
                                NonUniqueUserException,
                                UnknownSubscriptionException,
                                SspException

Returns a List of substitutions which define the values which this subscription would use for the policy parameters if activated. Includes using substitutions acquired from

Returns:

java.util.List

Throws:

UnknownServiceException - If the service is no longer loaded in SSP.

UnknownUserException - If the user is no longer logged in to SSP.

NonUniqueUserException - If the user specified by this bean's userDn property is logged in more than once.

UnknownSubscriptionException - If the user is no longer subscribed to the service.

SspException - If this operation fails due to an unexpected error condition in SSP or in an external system upon which SSP depends (e.g. an LDAP directory, a RADIUS server, an E-series router, etc.)

getServiceParameters

public List getServiceParameters()
                          throws UnknownServiceException,
                                 UnknownUserException,
                                 NonUniqueUserException,
                                 UnknownSubscriptionException,
                                 SspException

Returns a List of substitutions which define the operational values which this subscription would use for the service parameters if activated. Includes using substitutions acquired from Service Scope, Specialized Service, and Runtimes Creation date: (11/17/01 1:08:22 AM)

Returns:

java.util.List

Throws:

UnknownServiceException - If the service is no longer loaded in SSP.

UnknownUserException - If the user is no longer logged in to SSP.

NonUniqueUserException - If the user specified by this bean's userDn property is logged in more than once.

UnknownSubscriptionException - If the user is no longer subscribed to the service.

SspException - If this operation fails due to an unexpected error condition in SSP or in an external system upon which SSP depends (e.g. an LDAP directory, a RADIUS server, an E-series router, etc.)

pollUsage

public void pollUsage()
               throws UnknownUserException,
                      NonUniqueUserException,
                      UnknownSubscriptionException,
                      UnknownServiceException,
                      OverloadException,
                      SspException

Collects statistics describing the network traffic between the user and the subscribed service (i.e. the network resource controlled by the subscribed service). The usage counters can be retreived with getUsage method.

Throws:

IllegalStateException - If this bean has not been properly initialized.

UnknownUserException - If the user is no longer logged in to SSP.

NonUniqueUserException - If the user specified by this bean's userDn property is logged in more than once.

UnknownServiceException - If the service is no longer loaded in SSP.

UnknownSubscriptionException - If the user is no longer subscribed to the service.

OverloadException - If the COPS interface is currently overloaded.

SspException

Since:

4.1

toString

public String toString()

For debugging only. Returns a description of this Subscription bean.

Overrides:

toString in class Object