com.sas.edir
Interface EnterpriseDirectory

All Superinterfaces:

Caching, java.util.EventListener, java.beans.PropertyChangeListener

public interface EnterpriseDirectory

extends Caching, java.beans.PropertyChangeListener

An enterprise directory is a service that accesses the enterprise naming and directory server using JNDI. It is the entry point into the enterprise directory. After an authenticated binding with the server, the enterprise directory service provides:

• Limited access to the enterprise directory based on a user's security profile.
• Access to the User object.
• A mechanism for refreshing the enterprise directory cache and the cache of objects it contains.
• A mechanism for emitting PropertyChangeEvents when any of the objects it contains, e.g. User, Profile, etc..., fire PropertyChangeEvents.

Version:

1.0

Author:

SAS

Field Summary

static java.lang.String	APPLICATION_CONTEXT An enterprise directory environment key whose value contains the String representation of the context where application-specific information is stored.
static java.lang.String	BASE_CONTEXT An enterprise directory environment key whose value contains the String representation of the context where ...
static java.lang.String	CLASS_MAPPING A static string used by the EnterpriseDirectory to map class attributes for reflection.
static java.lang.String	DEBUG An enterprise directory environment key whose value contains the PrintStream used for debug messages.
static java.lang.String	ENTITY_MAPPING A static string used by the EnterpriseDirectory to map entity type for reflection.
static java.lang.String	GROUP_CONTEXT An environment key for accessing the base location of group entries.
static java.lang.String	PROPERTY_CHANGED The property change fired when one or more properties in an entity change.
static java.lang.String	SUBPROPERTY_CHANGED The property change fired when one or more properties in an entity contained within the entity change.
static java.lang.String	USER_CONTEXT An environment key for accessing the base location of person entries.

Method Summary

void	addCacheChangeListener(CacheChangeListener listener) Add a cache change listener
void	addChangeListener(DirectoryChangeListener listener, java.lang.String dn) Add an entry change listener.
void	addPropertyChangeListener(java.beans.PropertyChangeListener listener) Adds a property change listener to the listener list.
void	cacheChange(java.lang.String dn) Process a cache change from another source.
void	close() Close the connection to the enterprise directory server and release resources.
void	edirAddAttributes(java.lang.String namedObject, EnterpriseDirectoryAttributes attributes) Adds attributes to the named object.
void	edirCreate(java.lang.String context, EnterpriseDirectoryAttributes attrs) Creates an entity in the directory.
EnterpriseDirectoryAttributes	edirGetAttribute(java.lang.String context, java.lang.String attribute) Retrieve a single named attribute from a directory entry.
EnterpriseDirectoryAttributes	edirGetAttributes(java.lang.String namedObject) Returns the attributes for the named object.
EnterpriseDirectoryAttributes	edirGetAttributes(java.lang.String context, java.lang.String[] attributes) Retrieve a list of attributes from a directory entry.
java.util.ListIterator	edirListIterator(Filter filter) Given a filter, return a ListIterator of Entities that match that filter.
java.util.ListIterator	edirListIterator(Filter filter, java.util.Comparator compare) Returns a sorted listIterator of Entities that match the criteria specified in the filter.
Entity	edirNewEntity(java.lang.String context, EnterpriseDirectoryAttributes attributes) Creates a new entity from attributes retrieved from the directory service.
void	edirRemove(java.lang.String context) Removes an entity from the directory.
void	edirRemoveAttributes(java.lang.String namedObject, EnterpriseDirectoryAttributes attributes) Removes attributes from the named object.
void	edirRemoveSubtree(java.lang.String context) Removes a subtree from the directory.
void	edirReplaceAttributes(java.lang.String namedObject, EnterpriseDirectoryAttributes attributes) Replaces attributes in the named object.
java.util.Enumeration	edirSearch(SearchFilter filter) Search the enterprise directory for entries that satisfy the filter.
java.util.Enumeration	edirSearch(java.lang.String filter, EnterpriseDirectorySearchConstraint constraints) Search the enterprise directory for entries that satisfy the filter and contraints.
java.util.Enumeration	edirSearch(java.lang.String context, java.lang.String filter, EnterpriseDirectorySearchConstraint constraints) Search in the specified context of the enterprise directory for entries that satisfy the filter and contraints.
void	edirUpdateObject(Entity entity, EnterpriseDirectoryModificationItem[] modList) Process a modification list on an object to update it in the directory.
java.io.PrintStream	getDebugStream() Returns the stream used to display debug messages.
java.util.Map	getEnvironment() Returns the enterprise directory environment.
java.util.Map	getFactoryMap() Return the factory map.
java.util.Locale	getLocale() Returns the current locale.
PortalPool	getPoolSettings() Creates a PortalPool object using the directory environment.
EnterpriseDirectorySecurity	getSecurityObject() Get the security object for this instance.
java.lang.Object	getTrackedObject(long id) Get an object associated with a tracking id.
User	getUser() Returns the User object which represents the identity used by this instance to establish a connection to the directory server.
EnterpriseDirectoryAttribute	newAttribute(java.lang.String attrName) Return a new Attribute object
EnterpriseDirectoryAttribute	newAttribute(java.lang.String attrName, java.lang.Object attrValue) Return a new Attribute object.
EnterpriseDirectoryAttributes	newAttributes() Return a new attribute set.
EnterpriseDirectoryAttributes	newAttributes(java.lang.String attrName, java.lang.Object attrValue) Return a new attribute set initialized with an attribute.
java.lang.Object	newObject(java.lang.String key) Creates a new object using reflection by looking up the key in the mapping list to find an array of reflection arguments.
java.lang.Object	newObject(java.lang.String[] pArray) Creates a new object using reflection
java.lang.Object	newObject(java.lang.String[] pArray, java.lang.Object[] ctorArgs) Creates a new object using a String array of properties plus an array of constructor arguments.
java.lang.Object	newObject(java.lang.String key, java.lang.Object[] ctorArgs) Constructs a new object using reflection.
EnterpriseDirectorySearchConstraint	newSearchConstraint() Return a new EnterpriseSearchConstraint
void	removeCacheChangeListener(CacheChangeListener listener) Removes a cache change listener to this object
void	removeChangeListener(DirectoryChangeListener listener, java.lang.String dn) Remove an entry change listener from the list.
void	removePropertyChangeListener(java.beans.PropertyChangeListener listener) Removes a property change listener from the listener list.
void	setLocale(java.util.Locale locale) Sets the current locale.
void	trackObject(TrackedObject thingToTrack) Add an object to the tracking list.

Methods inherited from interface com.sas.edir.Caching

edirUpdateStore, getTimeToLive, isExpired, refreshCache, refreshCachedObjects, releaseCache, setDirty, setTimeToLive, setTimeToLive, updateStore

Methods inherited from interface java.beans.PropertyChangeListener

propertyChange

Field Detail

APPLICATION_CONTEXT

public static final java.lang.String APPLICATION_CONTEXT

An enterprise directory environment key whose value contains the String representation of the context where application-specific information is stored.

BASE_CONTEXT

public static final java.lang.String BASE_CONTEXT

An enterprise directory environment key whose value contains the String representation of the context where ...

USER_CONTEXT

public static final java.lang.String USER_CONTEXT

An environment key for accessing the base location of person entries.

GROUP_CONTEXT

public static final java.lang.String GROUP_CONTEXT

An environment key for accessing the base location of group entries.

DEBUG

public static final java.lang.String DEBUG

An enterprise directory environment key whose value contains the PrintStream used for debug messages.

CLASS_MAPPING

public static final java.lang.String CLASS_MAPPING

A static string used by the EnterpriseDirectory to map class attributes for reflection.

ENTITY_MAPPING

public static final java.lang.String ENTITY_MAPPING

A static string used by the EnterpriseDirectory to map entity type for reflection.

PROPERTY_CHANGED

public static final java.lang.String PROPERTY_CHANGED

The property change fired when one or more properties in an entity change.

SUBPROPERTY_CHANGED

public static final java.lang.String SUBPROPERTY_CHANGED

The property change fired when one or more properties in an entity contained within the entity change.

Method Detail

close

public void close()

Close the connection to the enterprise directory server and release resources.

edirNewEntity

public Entity edirNewEntity(java.lang.String context,
                            EnterpriseDirectoryAttributes attributes)
                     throws EnterpriseDirectoryException

Creates a new entity from attributes retrieved from the directory service.

Parameters:

context - The directory context of the entity to be created.

attributes - The attributes of the object to be created. If this parameter is null, the context is used to retrieve the attributes from the directory service.

Returns:

The new Entity that represents the directory entry.

Throws:

NamingException - Exceptions are thrown if the context is not valid in the directory service, or if the entry's object class doesn't have a valid mapping for reflection.

newObject

public java.lang.Object newObject(java.lang.String key)
                           throws ReflectionException

Creates a new object using reflection by looking up the key in the mapping list to find an array of reflection arguments.

Parameters:

key - The key into the mapping list for the object type desired.

Returns:

A new object matching the key requested

Throws:

ReflectionException - In the event the key was not found in the mapping list, or an error occurred creating the new object.

newObject

public java.lang.Object newObject(java.lang.String key,
                                  java.lang.Object[] ctorArgs)
                           throws ReflectionException

Constructs a new object using reflection.

The key is looked up in the mapping list and the resulting string array and constructor arguments are used to create the new object.

Parameters:

key - Mapping list key for the desired object type

ctorArgs - A list of constructor arguments to use when creating the object

Returns:

The new object of the requested type

Throws:

ReflectionException - if the key was not found in the mapping list, or there was an error creating the object

newObject

public java.lang.Object newObject(java.lang.String[] pArray)
                           throws ReflectionException

Creates a new object using reflection

A new object is created using the string array as a list of properties, and no constructor arguments to create a new object.

Parameters:

pArray - A String array of properties to use to create a new object.

Returns:

A new object.

Throws:

ReflectionException - if there was an error creating the object.

newObject

public java.lang.Object newObject(java.lang.String[] pArray,
                                  java.lang.Object[] ctorArgs)
                           throws ReflectionException

Creates a new object using a String array of properties plus an array of constructor arguments.

Parameters:

pArray - An array of Strings used as properties to create the new object. A class property is required.

Returns:

The new object

Throws:

ReflectionException - If there was an error creating the object.

getTrackedObject

public java.lang.Object getTrackedObject(long id)

Get an object associated with a tracking id.

The Enterprise Directory service keeps a list of objects that it creates in the newEntity and newObject methods by a tracking ID. This tracking ID can be used outside the directory service to refer to the object.

Parameters:

id - The tracking ID to look up

Returns:

The object with the requested tracking ID, or null

trackObject

public void trackObject(TrackedObject thingToTrack)

Add an object to the tracking list.

If an object created outside the Directory service needs to be tracked it can be added to the tracking list using this method.

Parameters:

thingToTrack - A TrackedObject to add to the tracking list

edirListIterator

public java.util.ListIterator edirListIterator(Filter filter)
                                        throws EnterpriseDirectoryException

Given a filter, return a ListIterator of Entities that match that filter.

Parameters:

filter - a Filter object that specifies the search criteria to use for returning objects from the directory.

Returns:

An iteration of user-specified entities.

Throws:

NamingException - Thrown for enterprise directory failure.

edirListIterator

public java.util.ListIterator edirListIterator(Filter filter,
                                               java.util.Comparator compare)
                                        throws EnterpriseDirectoryException

Returns a sorted listIterator of Entities that match the criteria specified in the filter.

Parameters:

filter - a Filter object that specifies the search criteria to use for returning objects from the directory.

compare - Comparator to use to sort the list.

Returns:

An iteration of user-specified entities.

Throws:

NamingException - Thrown for enterprise directory failure.

edirSearch

public java.util.Enumeration edirSearch(SearchFilter filter)
                                 throws EnterpriseDirectoryException

Search the enterprise directory for entries that satisfy the filter.

Parameters:

filter - The search filter.

Returns:

An Enumeration of SearchResults.

Throws:

EnterpriseDirectoryException - Thrown for enterprise directory failure.

edirSearch

public java.util.Enumeration edirSearch(java.lang.String filter,
                                        EnterpriseDirectorySearchConstraint constraints)
                                 throws EnterpriseDirectoryException

Search the enterprise directory for entries that satisfy the filter and contraints.

Parameters:

filter - The search filter. The syntax is the LDAP filter syntax defined in RFC 2254.

constraints - The search constraints.

Returns:

An Enumeration of SearchResults.

Throws:

EnterpriseDirectoryException - Thrown for enterprise directory failure.

edirSearch

public java.util.Enumeration edirSearch(java.lang.String context,
                                        java.lang.String filter,
                                        EnterpriseDirectorySearchConstraint constraints)
                                 throws EnterpriseDirectoryException

Search in the specified context of the enterprise directory for entries that satisfy the filter and contraints.

Parameters:

context - The context to search.

filter - The search filter. The syntax is the LDAP filter syntax defined in RFC 2254.

constraints - The search constraints.

Returns:

An Enumeration of SearchResults.

Throws:

EnterpriseDirectoryException - Thrown for enterprise directory failure.

addPropertyChangeListener

public void addPropertyChangeListener(java.beans.PropertyChangeListener listener)

Adds a property change listener to the listener list.

Parameters:

listener - The property change listener.

removePropertyChangeListener

public void removePropertyChangeListener(java.beans.PropertyChangeListener listener)

Removes a property change listener from the listener list.

Parameters:

listener - The property change listener.

edirUpdateObject

public void edirUpdateObject(Entity entity,
                             EnterpriseDirectoryModificationItem[] modList)
                      throws EnterpriseDirectoryException

Process a modification list on an object to update it in the directory.

Parameters:

entity - The object to update.

modList - An array of ModificationItems to apply to the object.

Throws:

NamingException - Thrown for enterprise directory failure.

edirAddAttributes

public void edirAddAttributes(java.lang.String namedObject,
                              EnterpriseDirectoryAttributes attributes)
                       throws EnterpriseDirectoryException

Adds attributes to the named object.

Parameters:

namedObject - The named object.

attributes - The attributes to add.

Throws:

EnterpriseDirectoryException - Thrown for enterprise directory failure.

edirGetAttribute

public EnterpriseDirectoryAttributes edirGetAttribute(java.lang.String context,
                                                      java.lang.String attribute)
                                               throws EnterpriseDirectoryException

Retrieve a single named attribute from a directory entry.

Parameters:

context - The directory context of the entry to look up

attribute - The attribute type to retrieve the value(s) for.

Returns:

an Attributes object containing the requested Attribute (if it exists in that entry)

Throws:

EnterpriseDirectoryException - in the event of a directory failure.

edirGetAttributes

public EnterpriseDirectoryAttributes edirGetAttributes(java.lang.String context,
                                                       java.lang.String[] attributes)
                                                throws EnterpriseDirectoryException

Retrieve a list of attributes from a directory entry.

Parameters:

context - The directory context of the entry to retrieve.

attributes - An array of attribute types to return for that entry.

Returns:

An Attributes object with Attribute entries for each requested attribute type (if they exist in the entry).

Throws:

EnterpriseDirectoryException - in the event of a directory failure.

edirGetAttributes

public EnterpriseDirectoryAttributes edirGetAttributes(java.lang.String namedObject)
                                                throws EnterpriseDirectoryException

Returns the attributes for the named object.

Parameters:

namedObject - The named object.

Returns:

The object's attributes.

Throws:

NamingException - Thrown for enterprise directory failure.

edirRemoveAttributes

public void edirRemoveAttributes(java.lang.String namedObject,
                                 EnterpriseDirectoryAttributes attributes)
                          throws EnterpriseDirectoryException

Removes attributes from the named object.

Parameters:

namedObject - The named object.

attributes - The attributes to remove.

Throws:

EnterpriseDirectoryException - Thrown for enterprise directory failure.

edirReplaceAttributes

public void edirReplaceAttributes(java.lang.String namedObject,
                                  EnterpriseDirectoryAttributes attributes)
                           throws EnterpriseDirectoryException

Replaces attributes in the named object.

Parameters:

namedObject - The named object.

attributes - The attributes to replace.

Throws:

EnterpriseDirectoryException - Thrown for enterprise directory failure.

edirRemove

public void edirRemove(java.lang.String context)
                throws EnterpriseDirectoryException

Removes an entity from the directory.

Parameters:

context - The context of the object to remove

Throws:

EnterpriseDirectoryException - Thrown for enterprise directory failure

edirRemoveSubtree

public void edirRemoveSubtree(java.lang.String context)
                       throws EnterpriseDirectoryException

Removes a subtree from the directory.

Parameters:

context - The context of the subtee to remove

Throws:

EnterpriseDirectoryException - Thrown for enterprise directory failure

edirCreate

public void edirCreate(java.lang.String context,
                       EnterpriseDirectoryAttributes attrs)
                throws EnterpriseDirectoryException

Creates an entity in the directory.

Parameters:

context - the context of the entry to add

attrs - the attributes to assign to the entry

Throws:

EnterpriseDirectoryException - Thrown for enterprise directory failure

getDebugStream

public java.io.PrintStream getDebugStream()

Returns the stream used to display debug messages.

Returns:

The stream.

getEnvironment

public java.util.Map getEnvironment()

Returns the enterprise directory environment.

Returns:

The environment.

getPoolSettings

public PortalPool getPoolSettings()

Creates a PortalPool object using the directory environment.

Returns:

a new PortalPool object that will use the same directory connection environment as this EnterpriseDirectory service.

getUser

public User getUser()

Returns the User object which represents the identity used by this instance to establish a connection to the directory server.

Returns:

The user.

Throws:

NamingException - Thrown for enterprise directory failure.

addCacheChangeListener

public void addCacheChangeListener(CacheChangeListener listener)

Add a cache change listener

The EnterpriseDirectory objects maintain a cache of entries it has retrieved from the directory server. Interested parties can be notified when cached objects change by being added using this method. This is typically used by other directory services to synchronize their data.

Parameters:

listener - A new CacheChangeListener to add to the list.

removeCacheChangeListener

public void removeCacheChangeListener(CacheChangeListener listener)

Removes a cache change listener to this object

Parameters:

listener - The listener to remove from the list.

cacheChange

public void cacheChange(java.lang.String dn)

Process a cache change from another source.

Parameters:

dn - The dn that was changed.

addChangeListener

public void addChangeListener(DirectoryChangeListener listener,
                              java.lang.String dn)

Add an entry change listener.

The directory service can also report changes to dn's. A listener registers itself, and the dn it's interested in. A "*" can be used to listen for changes to all entries.

Parameters:

listener - The object to add to the listener list.

dn - The directory context the object is interested in. "*" to listen for changes to all entries.

removeChangeListener

public void removeChangeListener(DirectoryChangeListener listener,
                                 java.lang.String dn)

Remove an entry change listener from the list.

Parameters:

listener - The listener to remove.

dn - The directory context the object is listening for.

getSecurityObject

public EnterpriseDirectorySecurity getSecurityObject()

Get the security object for this instance.

Returns:

A security object that can (hopefully) set access control on object in the directory.

getLocale

public java.util.Locale getLocale()

Returns the current locale.

Returns:

The current locale.

setLocale

public void setLocale(java.util.Locale locale)

Sets the current locale.

Parameters:

locale - The user's locale.

getFactoryMap

public java.util.Map getFactoryMap()

Return the factory map.

Returns:

The current factory map.

newAttribute

public EnterpriseDirectoryAttribute newAttribute(java.lang.String attrName)

Return a new Attribute object

Parameters:

attrName - The attribute name.

Returns:

A new Attribute object.

newAttribute

public EnterpriseDirectoryAttribute newAttribute(java.lang.String attrName,
                                                 java.lang.Object attrValue)

Return a new Attribute object.

Parameters:

attrName - The attribute name.

attrValue - The attribute value.

Returns:

A new attribute object.

newAttributes

public EnterpriseDirectoryAttributes newAttributes()

Return a new attribute set.

Returns:

a new attribute set.

newAttributes

public EnterpriseDirectoryAttributes newAttributes(java.lang.String attrName,
                                                   java.lang.Object attrValue)

Return a new attribute set initialized with an attribute.

Parameters:

attrName - The attribute name to initialize with.

attrValue - The attribute value to initialize with.

Returns:

a new attribute set.

newSearchConstraint

public EnterpriseDirectorySearchConstraint newSearchConstraint()

Return a new EnterpriseSearchConstraint