net.juniper.smgt.ent.im
Interface ServiceProvider

public interface ServiceProvider

This is the interface that controls an enterprise manager's session. A manager session starts with a call to bind(java.lang.String, java.lang.String) and stops with a call to unbind(). All manager operations are performed by calling methods on a bound instance of a ServiceProvider, or on the objects returned by that bound instance of a ServiceProvider.

This interface provides information about the currently bound session (if any), such as the scope of its currently bound manager. The scope of a manager is the set of objects to which the manager has access (e.g. a Site and its Accesses, an Enterprise, its Sites, and its Accesses, etc.). This interface also provides information about Services, global variables, and Retailers.

Field Summary

static String	ACCESS
static String	ENTERPRISE
static String	ENTERPRISEFOLDERS
static String	MANAGER
static String	RETAILER All the keys that can be used as input for the getBoundInfo method to get corresponding bound information.
static String	RETAILERFOLDERS
static String	SITE
static String	SITEFOLDERS

Method Summary

Persistent	bind(String principal, String password) Starts a manager session by binding this ServiceProvider instance to the SSC's LDAP directory using a specific manager's prinicpal (i.e. optionally qualified login ID) and password.
void	clearCache() Clears the in-memory cache of all Persistent objects.
String	getBoundAccessName() Returns the name of the access that contains the currently bound manager's scope of control (i.e. that is equal to or higher in the Retailer-Enterprise-Site-Access hierarchy than the object returned by getScope).
String	getBoundEnterpriseName() Returns the name of the enterprise that contains the currently bound manager's scope of control (i.e. that is equal to or higher in the Retailer-Enterprise-Site-Access hierarchy than the object returned by getScope).
String[]	getBoundInfo(String kindOf) Returns the information about the currently bound session (if any).
Manager	getBoundManager() Returns the Manager that was specified in the most recent successful call to bind.
String	getBoundPrincipal() Returns the principal (i.e. the optionally qualified login ID) of the currently bound manager, exactly as it was passed to the bind method, or null if this ServiceProvider is not currently bound.
String	getBoundRetailerName() Returns the name of the retailer that contains the currently bound manager's scope of control (i.e. that is equal to or higher in the Retailer-Enterprise-Site-Access hierarchy than the object returned by getScope).
String	getBoundSiteName() Returns the name of the site that contains the currently bound manager's scope of control (i.e. that is equal to or higher in the Retailer-Enterprise-Site-Access hierarchy than the object returned by getScope).
String	getFullBoundPrincipal() Returns the principal that was passed to the bind method, expanded such that it is fully qualified (i.e. including those parts of the principal that were not explicitly specified in the call to bind).
List	getGlobals() Returns the set of Substitutions that represent global variables.
PersistentIterator	getRetailers() Returns an iterator over all Retailers in the SSC's LDAP directory.
Persistent	getScope() Returns the object at the root of the tree of objects over which the currently bound manager has control.
Service	getService(String serviceName) Returns the generic service with the specified name.
PersistentIterator	getServices() Returns a iterator over all the available generic Services.
Subscriber	getSubscriber(String subrId) Given a subscriber’s id, returns the subscriber.
VPN	getVPN(String vpnName) Get the named VPN object.
boolean	isBound() Returns true only if a manager is currently bound using this ServiceProvider.
void	unbind() Unbinds the currently bound manager.

Field Detail

RETAILER

public static final String RETAILER

All the keys that can be used as input for the getBoundInfo method to get corresponding bound information.

See Also:

Constant Field Values

RETAILERFOLDERS

public static final String RETAILERFOLDERS

See Also:

Constant Field Values

ENTERPRISE

public static final String ENTERPRISE

See Also:

Constant Field Values

ENTERPRISEFOLDERS

public static final String ENTERPRISEFOLDERS

See Also:

Constant Field Values

SITE

public static final String SITE

See Also:

Constant Field Values

SITEFOLDERS

public static final String SITEFOLDERS

See Also:

Constant Field Values

ACCESS

public static final String ACCESS

See Also:

Constant Field Values

MANAGER

public static final String MANAGER

See Also:

Constant Field Values

Method Detail

bind

public Persistent bind(String principal,
                       String password)
                throws CommunicationException,
                       AccessControlException,
                       UnknownIdentityException

Starts a manager session by binding this ServiceProvider instance to the SSC's LDAP directory using a specific manager's prinicpal (i.e. optionally qualified login ID) and password.

The manager's principal is of the form managerId{site}.}enterprise.}{retailer}}}. The components contained in {} are optional. If there is no "@" in the principal, the entry for the manager is searched for in the directory's "o=Operators,o=UMC" subtree. If an "@" is present, the part after the "@" specifies where to search for the manager entry in the directory. The bind will succeed only if there is exactly one manager entry with the given principal in the directory subtree indicated by the part of the principal following the "@".

Some examples:

• managerId:
  A manager over all retailers. The manager entry named "managerId" must by in the o=Operators,o=UMC subtree.
• managerId@:
  A manager somewhere in the retailer named "default" (i.e. the retailer of the wholesaler). The manager entry named "managerId" must be in the subtree retailername=default,o=users,o=umc.
• managerId@retailisp:
  A manager in the retailer "retailisp" The manager entry named "managerId" must be in the subtree retailername=retailisp,o=users,o=umc.
• managerId@acme.:
  A manager in enterprise "acme" in the retailer named "default" The manager entry named "managerId" must be in the subtree enterprisename=acme,ou=(any folder name),retailername=default,o=users,o=umc.
• managerId@acme.retailisp:
  A manager in enterprise "acme" in retailer "retailisp" The manager entry named "managerId" must be in the subtree enterprisename=acme,ou=(any folder name),retailername=retailisp,o=users,o=umc.
• managerId@headquarters.acme.retailisp:
  A manager in site "headquarters" in enterprise "acme" in retailer "retailisp" The manager entry named "managerId" must be in the subtree sitename=headquarters,enterprisename=acme,ou=(any folder name),retailername=retailisp,o=users,o=umc. (Note that each Enterprise in a given retailer must have a unique name, regardless of the use of "ou=XXX" folders in the LDAP data.)
• managerId@backup.headquarters.acme.retailisp:
  A manager for access "backup" in site "headquarters" in enterprise "acme" in retailer "retailisp" The manager entry named "managerId" must be in a child of accessname=backup,sitename=headquarters,enterprisename=acme,ou=(any folder name),retailername=retailisp,o=users,o=umc.
• managerId@entaccess..acme.retailisp:
  A manager for access "entaccess" in enterprise "acme" in retailer "retailisp" The manager entry named "managerId" must be in a child of accessname=backup,enterprisename=acme,ou=(any folder name),retailername=retailisp,o=users,o=umc.

Parameters:

principal - The optionally qualified login ID for the manager.

password - The password for the manager.

Returns:

The scope of the manager. See getScope() for more information.

Throws:

AccessControlException - Thrown if the authentication fails.

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

UnknownIdentityException - Thrown if the manager entry or its scoping entry are deleted from the directory during the login process

clearCache

public void clearCache()

Clears the in-memory cache of all Persistent objects. Persistent objects are those that are stored persistently in SSC's LDAP directory, such as Manager, Enterprise, Site, Access, Subscription, etc., objects. Persistent objects are loaded from the directory only once per manager session (i.e. only once after each call to bind), unless this method clearCache method is called.

getBoundAccessName

public String getBoundAccessName()

Returns the name of the access that contains the currently bound manager's scope of control (i.e. that is equal to or higher in the Retailer-Enterprise-Site-Access hierarchy than the object returned by getScope). If getScope returns a Retailer or Enterprise or Site, this method will return null, since no access contains the manager's scope of control.

In other words, if getScope returns an Access object, this method returns the value of the LDAP RDN of that Access object, otherwise it returns null.

Returns null if this ServiceProvider is not currently bound.

getBoundEnterpriseName

public String getBoundEnterpriseName()

Returns the name of the enterprise that contains the currently bound manager's scope of control (i.e. that is equal to or higher in the Retailer-Enterprise-Site-Access hierarchy than the object returned by getScope). If getScope returns a Retailer, this method will return null, since no enterprise contains the manager's scope of control.

In other words, if getScope returns an Enterprise object, this method returns the value of the LDAP RDN of that Enterprise object, otherwise it returns the value of the LDAP RDN of the Enterprise object that is the ancestor of the Site or Access object returned by getScope, if any such Enterprise ancestor object exists.

Returns null if this ServiceProvider is not currently bound.

getBoundInfo

public String[] getBoundInfo(String kindOf)

Returns the information about the currently bound session (if any). According to the input parameter value which could be one of the above static attributes, the returned information could be bound retailer name, bound enterprise name, bound site name, bound access name, bound manager name, bound retailer folder names, bound enterprise folder names or bound site folder names. This method will return null, if the asked information is not available.

getBoundManager

public Manager getBoundManager()
                        throws AccessControlException,
                               CommunicationException

Returns the Manager that was specified in the most recent successful call to bind. Returns null if this ServiceProvider is not currently bound.

Throws:

AccessControlException - Thrown if the currently bound manager doesn't have sufficient privileges for this operation.

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

getBoundPrincipal

public String getBoundPrincipal()

Returns the principal (i.e. the optionally qualified login ID) of the currently bound manager, exactly as it was passed to the bind method, or null if this ServiceProvider is not currently bound.

See Also:

bind(String, String)

getBoundRetailerName

public String getBoundRetailerName()

Returns the name of the retailer that contains the currently bound manager's scope of control (i.e. that is equal to or higher in the Retailer-Enterprise-Site-Access hierarchy than the object returned by getScope). In other words, if getScope returns a Retailer object, this method returns the value of the LDAP RDN of that Retailer object, otherwise it returns the value of the LDAP RDN of the Retailer object that is the ancestor of the object returned by getScope. Note that in the special case where the currently bound manager has control over retailers, this method and all the other getBoundXxx methods will return null.

Returns:

Null if this ServiceProvider is not currently bound, otherwise returns the retailer's name.

getBoundSiteName

public String getBoundSiteName()

Returns the name of the site that contains the currently bound manager's scope of control (i.e. that is equal to or higher in the Retailer-Enterprise-Site-Access hierarchy than the object returned by getScope). If getScope returns a Retailer or Enterprise, this method will return null, since no site contains the manager's scope of control.

In other words, if getScope returns a Site object, this method returns the value of the LDAP RDN of that Site object, otherwise it returns the value of the LDAP RDN of the Site object that is the ancestor of the Access object returned by getScope, if any such Site ancestor object exists (recall that Site objects are optional in the Enterprise-Site-Access hierarchy).

Returns null if this ServiceProvider is not currently bound.

getFullBoundPrincipal

public String getFullBoundPrincipal()

Returns the principal that was passed to the bind method, expanded such that it is fully qualified (i.e. including those parts of the principal that were not explicitly specified in the call to bind). Returns null if this ServiceProvider is not currently bound.

See Also:

bind(String, String)

getGlobals

public List getGlobals()
                throws CommunicationException

Returns the set of Substitutions that represent global variables. Each such substitution has a variable name, and optionally a value if the global variable has a default value.

Throws:

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

getRetailers

public PersistentIterator getRetailers()
                                throws AccessControlException,
                                       CommunicationException

Returns an iterator over all Retailers in the SSC's LDAP directory.

Throws:

AccessControlException - Thrown if the current manager doesn't have access to all Retailers.

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

getScope

public Persistent getScope()
                    throws CommunicationException,
                           UnknownIdentityException

Returns the object at the root of the tree of objects over which the currently bound manager has control. Returns null in the special case of a manager that has control over all retailers (i.e. control over everything). The objects are arranged in a Retailer-Enterprise-Site-Access hierarchy.

Returns:

The Retailer, Enterprise, Site, or Access at the root of the tree of objects over which this ServiceProvider is bound. Returns null if manager that has control over all retailers. Also Returns null if it is not bound (use the isBound method to distinguish between these two cases).

Throws:

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

UnknownIdentityException - Thrown if the entry over which the bound manager has control is deleted from the directory after this service provider was bound.

getService

public Service getService(String serviceName)
                   throws UnknownIdentityException,
                          CommunicationException

Returns the generic service with the specified name.

Parameters:

serviceName - String the name of the Service to be returned.

Throws:

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

UnknownIdentityException - Thrown if there is no service with the specified name.

getServices

public PersistentIterator getServices()
                               throws CommunicationException

Returns a iterator over all the available generic Services.

Returns:

An iterator over the Services available for subscription.

Throws:

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

isBound

public boolean isBound()

Returns true only if a manager is currently bound using this ServiceProvider.

unbind

public void unbind()

Unbinds the currently bound manager.

getVPN

public VPN getVPN(String vpnName)
           throws UnknownIdentityException,
                  CommunicationException,
                  AccessControlException

Get the named VPN object.

Parameters:

vpnName - The name of the required VPN.

Throws:

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

AccessControlException - Thrown if the current manager does not have write access for the named attribute.

UnknownIdentityException - Thrown if the named VPN entry does not exist in the directory.

getSubscriber

public Subscriber getSubscriber(String subrId)
                         throws UnknownIdentityException,
                                CommunicationException,
                                AccessControlException

Given a subscriber’s id, returns the subscriber.

Parameters:

subrId - The id of the required subscriber.

Throws:

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

AccessControlException - Thrown if the current manager does not have write access for the named attribute.

UnknownIdentityException - Thrown if the required subscriber entry does not exist in the directory.