com.mentata.l3d
Class L3DObject

java.lang.Object
  com.mentata.l3d.L3DObject

All Implemented Interfaces:

Comparator

Direct Known Subclasses:

SG8Object

public abstract class L3DObject

extends Object

implements Comparator

A template for a class of entries in a directory database. This abstract class can be extended in context packages to correspond with one or more object classes from the target directory's schema, a specific location in the directory tree, filters, and other identifying characteristics. Each instance defines a set of L3DAttributes, often yet not always corresponding to those permitted in the directory schema. An instance may also define basic traits such as a friendly label, default sort behavior, a search limit, or use of incremental identifiers. An L3DObject initially represents a template container for an entry with no attribute values. There are no methods to manipulate this structure from without, but attribute values can be defined either manually or by populating the template with an identified directory entry. The attributes themselves are then available as L3DAttributes, providing access to type-specific functionality. An L3DObject instance can be bound with a directory connection for use in internal operations throughout its life. Given an authoritative connection, a populated L3DObject can be used to create, delete, or modify a corresponding entry in the database. Supporting methods also enable searching for entries, instantiating other objects in the same context, labelling attributes either explicitly or through external properties files, setting a locale, getting localized date/time stamps, and managing lists of attributes for various purposes.

Since:

0.7

Author:

Jon Roberts

Field Summary

static boolean	MULTIVALUE A multivalue attribute.
static int	ONE A scope that is limited to a single level of the directory hierarchy.
static boolean	OPTIONAL An optional attribute.
static boolean	REQUIRED A required attribute.
static boolean	SINGLEVALUE A single value attribute.
static int	SUBTREE A scope that includes an entire subtree of the directory hierarchy.

Constructor Summary

L3DObject(L3DContext context)
Constructs an empty object with an attribute structure fitting all object classes.

Method Summary

protected void	addAttribute(String name, L3DAttribute attribute) Adds a new attribute to the object definition.
protected void	addAttribute(String name, L3DAttribute attribute, boolean multivalue) Adds a new attribute to the object definition.
protected void	addAttribute(String name, L3DAttribute attribute, boolean multivalue, boolean required) Adds a new attribute to the object definition.
protected void	addAttributeList(String name, String[] attributes) Adds a new attribute list to the object.
protected void	addObjectclasses(String[] objectclasses) Adds directory objectclass values to this object.
protected void	addPrerequisite(String[] attributes, String[] prerequisites) Adds a prerequisite relationship for multiple attributes to the object.
protected void	addPrerequisite(String attribute, String[] prerequisites) Adds a new attribute prerequisite relationship to the object.
protected void	applyLabels() Reads object and attribute labels from a default properties bundle.
protected void	applyLabels(String tag) Reads object and attribute labels from a named properties bundle.
int	compare(Object one, Object two) Sorts given LDAPEntry instances by preconfigured attributes and orderings.
void	create() Create the associated entry in the directory via the bound connection.
void	create(LDAPConnection conn) Create the associated entry in the directory.
void	delete() Delete the associated entry from the directory via the bound connection.
void	delete(LDAPConnection conn) Delete the associated entry from the directory.
void	empty() Clears values from all attributes.
void	extend(LDAPConnection conn, String classname) Extends the associated entry with new objectclasses.
void	extend(String classname) Extends the associated entry with new objectclasses via a bound counnection.
L3DAttribute	getAttribute(String name) Returns the named attribute.
String[]	getAttributeList() Returns the names of all attributes of the object.
String[]	getAttributeList(String name) Returns the attribute names in the named list.
protected LDAPConnection	getBind() Returns the connection associated with an object.
String	getClassName() Returns the name of the object's Java class.
protected L3DContext	getContext() Returns the containing context for this object.
String	getContextName() Returns the name of the object's context.
static String	getDatestamp() Returns a stamp representing the current date in the default locale.
String	getDN() Returns the distinguished name for the associated entry.
String	getDN(String identifier) Determines the distinguished name for an identified entry.
String	getIdentifier() Returns the unique identifier value for the associated entry.
String	getIdentifierAttribute() Returns the name of the unique identifier attribute for entries of the object.
LDAPEntry	getIncrementEntry() Returns a counter entry for an auto-incrementing object.
LDAPEntry	getIncrementEntry(LDAPConnection conn) Returns a counter entry for an auto-incrementing object.
String	getLabel() Returns the label for the object type.
String	getLabel(String attribute) Returns the label for an attribute.
int	getLimit() Returns the maximum number of entries to return in a search.
Locale	getLocale() Returns the locale for the object.
String	getName() Returns the common name value for the associated entry.
String	getNameAttribute() Returns the name of the common name attribute for entries of the object.
L3DObject	getObject(String classname) Returns an empty instance of a given object from the same context.
String[]	getObjectclasses() Returns the directory objectclass values that this object uniquely defines.
L3DPath	getPath() Returns a path bean describing the object.
L3DPath	getPath(String attribute) Returns a path bean describing the object with attribute.
String[]	getPrerequisites(String attribute) Returns the prerequisite attributes for the named attribute.
static String	getTimestamp() Returns a UTC timestamp for the current date and time.
boolean	hasMatch() Indicates if an existing entry of the object type has the same identifier.
boolean	hasMatch(String filter) Indicates if an existing entry of the object type matches the submitted filter.
boolean	isBound() Identifies if the object is associated with a connection.
boolean	isIncremental() Identifies if the object uses auto-incrementing identifiers.
String[]	mergeAttributeLists(String[] lists) Returns a consolidation of attribute names from specified lists.
String[]	mergeAttributeLists(String[][] lists) Returns a consolidation of attribute names from given lists.
void	minimizeScope() Sets the object's scope to one.
static boolean	onList(String element, String[] list) Determines if a given element appears on a given list.
void	populate(LDAPEntry entry) Sets values of all attributes to reflect those of a given directory entry.
void	populate(String dn) Sets values of all attributes to reflect those of a given distinguished name.
void	populate(String dn, String[] attributes) Sets values of given attributes to reflect those of a given distinguished name.
void	prependBase(String rdn) Prepends a relative dn to the beginning of the object's base.
LDAPEntry[]	search(String filter) Returns complete entries matching a submitted filter.
LDAPEntry[]	search(String filter, String[] attributes) Returns entries matching a submitted filter.
LDAPEntry[]	search(String filter, String[] attributes, int limit) Returns entries matching a submitted filter.
LDAPEntry[]	search(String filter, String[] attributes, int limit, boolean sorted) Returns entries matching a submitted filter.
LDAPEntry[]	search(String filter, String[] attributes, int limit, boolean sorted, LDAPConnection conn) Returns entries matching a submitted filter.
void	setBind(LDAPConnection conn) Associates the object with a directory connection.
protected void	setFilter(String filter) Sets the default filter for the object.
protected void	setIncremental(String rdn, String attribute, String prefix) Configure auto-incrementing for identifiers.
protected void	setLabel(String label) Assigns a label to the type of object.
protected void	setLabel(String label, String attribute) Assigns a label to an attribute of the object.
void	setLimit(int limit) Sets a maximum for the number of entries to return in a search.
void	setLocale(Locale locale) Sets the locale for the object.
void	setSorting(String[] attributes, boolean[] ascending) Configures the sorting behavior for entries of the object.
void	update(LDAPConnection conn, String attribute) Updates the directory database with the current value for the given attribute.
void	update(String attribute) Updates the directory database with the current value for the given attribute via a bound connection.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface java.util.Comparator

equals

Field Detail

ONE

public static final int ONE

A scope that is limited to a single level of the directory hierarchy.

See Also:

Constant Field Values

SUBTREE

public static final int SUBTREE

A scope that includes an entire subtree of the directory hierarchy.

See Also:

Constant Field Values

REQUIRED

public static final boolean REQUIRED

A required attribute.

See Also:

Constant Field Values

OPTIONAL

public static final boolean OPTIONAL

An optional attribute.

See Also:

Constant Field Values

MULTIVALUE

public static final boolean MULTIVALUE

A multivalue attribute.

See Also:

Constant Field Values

SINGLEVALUE

public static final boolean SINGLEVALUE

A single value attribute.

See Also:

Constant Field Values

Constructor Detail

L3DObject

public L3DObject(L3DContext context)
          throws L3DException

Constructs an empty object with an attribute structure fitting all object classes.

Parameters:

context - a containing L3D context

Method Detail

getContext

protected L3DContext getContext()

Returns the containing context for this object.

Returns:

the containing L3D context

getObject

public final L3DObject getObject(String classname)
                          throws L3DException

Returns an empty instance of a given object from the same context.

Returns:

an L3D object

Throws:

L3DException - if the containing context or requested object are undefined

getContextName

public final String getContextName()

Returns the name of the object's context.

Returns:

the containing context's name

getClassName

public final String getClassName()

Returns the name of the object's Java class.

Returns:

the class name

setLabel

protected final void setLabel(String label)

Assigns a label to the type of object.

Parameters:

label - a clear description of object type

setLabel

protected final void setLabel(String label,
                              String attribute)

Assigns a label to an attribute of the object.

Parameters:

label - a clear description

attribute - an attribute to describe

getLabel

public final String getLabel()

Returns the label for the object type.

Returns:

the clear description of the object type

getLabel

public final String getLabel(String attribute)

Returns the label for an attribute.

Parameters:

attribute - an attribute

Returns:

the clear description of the attribute

applyLabels

protected final void applyLabels()
                          throws L3DException

Reads object and attribute labels from a default properties bundle.

Throws:

L3DException - if the default properties bundle is undefined

applyLabels

protected final void applyLabels(String tag)
                          throws L3DException

Reads object and attribute labels from a named properties bundle.

Parameters:

tag - the name of a properties bundle

Throws:

L3DException - if the named properties bundle is undefined

prependBase

public final void prependBase(String rdn)

Prepends a relative dn to the beginning of the object's base.

Parameters:

rdn - a relative distinguished name

minimizeScope

public final void minimizeScope()

Sets the object's scope to one.

setFilter

protected final void setFilter(String filter)

Sets the default filter for the object.

Parameters:

filter - a parenthetically enclosed directory filter

setLocale

public final void setLocale(Locale locale)

Sets the locale for the object.

Parameters:

locale - a locale

getLocale

public final Locale getLocale()

Returns the locale for the object.

Returns:

the locale

getTimestamp

public static final String getTimestamp()

Returns a UTC timestamp for the current date and time.

Returns:

the UTC timestamp

getDatestamp

public static final String getDatestamp()

Returns a stamp representing the current date in the default locale.

Returns:

the date stamp

addObjectclasses

protected final void addObjectclasses(String[] objectclasses)
                               throws L3DException

Adds directory objectclass values to this object.

Parameters:

objectclasses - names of directory objectclasses

Throws:

L3DException

getObjectclasses

public final String[] getObjectclasses()

Returns the directory objectclass values that this object uniquely defines.

Returns:

the date stamp

addAttributeList

protected final void addAttributeList(String name,
                                      String[] attributes)

Adds a new attribute list to the object.

Parameters:

name - a name for the attribute list

attributes - a list of attributes to include

getAttributeList

public final String[] getAttributeList()

Returns the names of all attributes of the object.

Returns:

the list of all attribute names

getAttributeList

public final String[] getAttributeList(String name)
                                throws L3DException

Returns the attribute names in the named list.

Parameters:

name - an attribute list name

Returns:

the named list of attribute names

Throws:

L3DException - if the named list is undefined

onList

public static boolean onList(String element,
                             String[] list)

Determines if a given element appears on a given list.

Parameters:

element - a string to find

list - a list of values to search

Returns:

whether the given element is on the list

addPrerequisite

protected final void addPrerequisite(String attribute,
                                     String[] prerequisites)

Adds a new attribute prerequisite relationship to the object.

Parameters:

attribute - an attribute name

prerequisites - a list of attributes required in use of the named attribute

addPrerequisite

protected final void addPrerequisite(String[] attributes,
                                     String[] prerequisites)

Adds a prerequisite relationship for multiple attributes to the object.

Parameters:

attributes - an list of attribute names

prerequisites - a list of attributes required in use of the named attributes

getPrerequisites

public final String[] getPrerequisites(String attribute)

Returns the prerequisite attributes for the named attribute.

Parameters:

attribute - an attribute name

Returns:

the list of attributes required in use of the named attribute

mergeAttributeLists

public String[] mergeAttributeLists(String[] lists)
                             throws L3DException

Returns a consolidation of attribute names from specified lists.

Parameters:

lists - a list of attribute list names

Returns:

the unordered list of all resulting unique or prerequisite attribute names

Throws:

L3DException - if a named attribute list is undefined

mergeAttributeLists

public String[] mergeAttributeLists(String[][] lists)

Returns a consolidation of attribute names from given lists.

Parameters:

lists - a list of lists of attribute names

Returns:

the unordered list of all resulting unique or prerequisite attribute names

getIdentifierAttribute

public final String getIdentifierAttribute()
                                    throws L3DException

Returns the name of the unique identifier attribute for entries of the object.

Returns:

the identifier attribute name

Throws:

L3DException - if the identify attribute list is undefined

getNameAttribute

public final String getNameAttribute()
                              throws L3DException

Returns the name of the common name attribute for entries of the object.

Returns:

the common name attribute name

Throws:

L3DException - if the identify attribute list is undefined

setSorting

public final void setSorting(String[] attributes,
                             boolean[] ascending)

Configures the sorting behavior for entries of the object.

Parameters:

attributes - a list of attribute names to sort by

ascending - a list of indicators for sort order per attribute

compare

public int compare(Object one,
                   Object two)

Sorts given LDAPEntry instances by preconfigured attributes and orderings.

Specified by:

compare in interface Comparator

Parameters:

one - first entry for comparison

two - second entry for comparison

Returns:

standard integer representation for less than, greater than, or equals

addAttribute

protected final void addAttribute(String name,
                                  L3DAttribute attribute)

Adds a new attribute to the object definition.

Parameters:

name - a name for the new attribute

attribute - a new L3D attribute

addAttribute

protected final void addAttribute(String name,
                                  L3DAttribute attribute,
                                  boolean multivalue)

Adds a new attribute to the object definition.

Parameters:

name - a name for the new attribute

attribute - a new L3D attribute

multivalue - an indicator for the attribute's cardinality

addAttribute

protected final void addAttribute(String name,
                                  L3DAttribute attribute,
                                  boolean multivalue,
                                  boolean required)

Adds a new attribute to the object definition.

Parameters:

name - a name for the new attribute

attribute - a new L3D attribute

multivalue - an indicator for the attribute's cardinality

required - an indicator for the attribute's necessity

getAttribute

public final L3DAttribute getAttribute(String name)
                                throws L3DException

Returns the named attribute.

Parameters:

name - an attribute name

Returns:

the named L3D attribute

Throws:

L3DException - if the named attribute is undefined

setBind

public final void setBind(LDAPConnection conn)

Associates the object with a directory connection.

Parameters:

conn - an LDAP connection to use in operations

isBound

public final boolean isBound()

Identifies if the object is associated with a connection.

Returns:

whether the object is bound with a connection

getBind

protected final LDAPConnection getBind()

Returns the connection associated with an object.

Returns:

the associated connection or null if there isn't one

setLimit

public final void setLimit(int limit)

Sets a maximum for the number of entries to return in a search.

Parameters:

limit - a maximum number of entries in search results

getLimit

public final int getLimit()

Returns the maximum number of entries to return in a search.

Returns:

the maximum number of entries in search results

search

public LDAPEntry[] search(String filter)
                   throws L3DException

Returns complete entries matching a submitted filter.

Parameters:

filter - a parenthetically enclosed directory filter

Returns:

a list of matching LDAP entries

Throws:

L3DException - if the search fails or the sorting criteria are mismatched

search

public LDAPEntry[] search(String filter,
                          String[] attributes)
                   throws L3DException

Returns entries matching a submitted filter.

Parameters:

filter - a parenthetically enclosed directory filter

attributes - a list of attributes to include in results

Returns:

a list of matching LDAP entries

Throws:

L3DException - if the search fails or the sorting criteria are mismatched

search

public LDAPEntry[] search(String filter,
                          String[] attributes,
                          int limit)
                   throws L3DException

Returns entries matching a submitted filter.

Parameters:

filter - a parenthetically enclosed directory filter

attributes - a list of attributes to include in results

limit - a maximum number of entries in results

Returns:

a list of matching LDAP entries

Throws:

L3DException - if the search fails or the sorting criteria are mismatched

search

public LDAPEntry[] search(String filter,
                          String[] attributes,
                          int limit,
                          boolean sorted)
                   throws L3DException

Returns entries matching a submitted filter.

Parameters:

filter - a parenthetically enclosed directory filter

attributes - a list of attributes to include in results

limit - a maximum number of entries in results

sorted - an indicator of sorting necessity

Returns:

a list of matching LDAP entries

Throws:

L3DException - if the search fails or the sorting criteria are mismatched

search

public LDAPEntry[] search(String filter,
                          String[] attributes,
                          int limit,
                          boolean sorted,
                          LDAPConnection conn)
                   throws L3DException

Returns entries matching a submitted filter.

Parameters:

filter - a parenthetically enclosed directory filter

attributes - a list of attributes to include in results

limit - a maximum number of entries in results

sorted - an indicator of sorting necessity

conn - an LDAP connection to use in the search

Returns:

a list of matching LDAP entries

Throws:

L3DException - if the search fails or the sorting criteria are mismatched

hasMatch

public boolean hasMatch()
                 throws L3DException

Indicates if an existing entry of the object type has the same identifier.

Returns:

whether the an existing entry has the same identifier

Throws:

L3DException - if the search fails

hasMatch

public boolean hasMatch(String filter)
                 throws L3DException

Indicates if an existing entry of the object type matches the submitted filter.

Parameters:

filter - a parenthetically enclosed directory filter

Returns:

whether the an existing entry has the same identifier

Throws:

L3DException - if the search fails

populate

public final void populate(LDAPEntry entry)
                    throws L3DException

Sets values of all attributes to reflect those of a given directory entry.

Parameters:

entry - an LDAP entry to reflect

Throws:

L3DException

populate

public void populate(String dn)
              throws L3DException

Sets values of all attributes to reflect those of a given distinguished name.

Parameters:

dn - a distinguished name

Throws:

L3DException - if no entry exists with the given dn or the search fails

populate

public void populate(String dn,
                     String[] attributes)
              throws L3DException

Sets values of given attributes to reflect those of a given distinguished name.

Parameters:

dn - a distinguished name

attributes - a list of attributes to assign values to

Throws:

L3DException - if no entry exists with the given dn or the search fails

empty

public void empty()
           throws L3DException

Clears values from all attributes.

Throws:

L3DException - if an attribute is not properly defined

getIdentifier

public final String getIdentifier()
                           throws L3DException

Returns the unique identifier value for the associated entry.

Returns:

the entry identifier

Throws:

L3DException - if the identify attribute list is undefined

getName

public final String getName()
                     throws L3DException

Returns the common name value for the associated entry.

Returns:

the entry common name

Throws:

L3DException - if the identify attribute list is undefined

getDN

public final String getDN()
                   throws L3DException

Returns the distinguished name for the associated entry.

Returns:

the entry distinguished name

Throws:

L3DException

getDN

public final String getDN(String identifier)
                   throws L3DException

Determines the distinguished name for an identified entry.

Parameters:

identifier - an entry unique identifier

Returns:

the distinguished name of a matching entry

Throws:

L3DException - if no identifier attribute is defined or a unique entry doesn't exist

getPath

public L3DPath getPath()
                throws L3DException

Returns a path bean describing the object.

Returns:

the qualified L3D path bean

Throws:

L3DException - if no identifier attribute is defined

getPath

public L3DPath getPath(String attribute)
                throws L3DException

Returns a path bean describing the object with attribute.

Parameters:

attribute - an attribute name

Returns:

the qualified L3D path bean

Throws:

L3DException - if no identifier attribute is defined

setIncremental

protected final void setIncremental(String rdn,
                                    String attribute,
                                    String prefix)

Configure auto-incrementing for identifiers.

Parameters:

rdn - a distinguished name relative to the object base for the id counter entry

attribute - an attribute of the entry which contains the count

prefix - a prefix for all identifiers

isIncremental

public final boolean isIncremental()

Identifies if the object uses auto-incrementing identifiers.

Returns:

whether the object is incremental

getIncrementEntry

public final LDAPEntry getIncrementEntry()
                                  throws L3DException

Returns a counter entry for an auto-incrementing object.

Returns:

the counter entry

Throws:

L3DException

getIncrementEntry

public final LDAPEntry getIncrementEntry(LDAPConnection conn)
                                  throws L3DException

Returns a counter entry for an auto-incrementing object.

Parameters:

conn - a connection to the directory server

Returns:

the counter entry

Throws:

L3DException

create

public final void create()
                  throws L3DException

Create the associated entry in the directory via the bound connection.

Throws:

L3DException - if the object has no bound connection or the entry can't be created

create

public final void create(LDAPConnection conn)
                  throws L3DException

Create the associated entry in the directory.

Parameters:

conn - the authenticated connection to use in creating the entry

Throws:

L3DException - if the entry can't be created

delete

public final void delete()
                  throws L3DException

Delete the associated entry from the directory via the bound connection.

Throws:

L3DException - if the object has no bound connection or the entry can't be removed

delete

public final void delete(LDAPConnection conn)
                  throws L3DException

Delete the associated entry from the directory.

Parameters:

conn - the authenticated connection to use in deleting the entry

Throws:

L3DException - if the entry has subordinates or can't be removed

extend

public final void extend(String classname)
                  throws L3DException

Extends the associated entry with new objectclasses via a bound counnection.

Parameters:

classname - the name of the target object

Throws:

L3DException - if the object has no bound connection or the entry can't be extended

extend

public final void extend(LDAPConnection conn,
                         String classname)
                  throws L3DException

Extends the associated entry with new objectclasses.

Parameters:

conn - the authenticated connection to use in extending the entry

classname - the name of the target object

Throws:

L3DException - if the entry shouldn't or can't be extended

update

public final void update(String attribute)
                  throws L3DException

Updates the directory database with the current value for the given attribute via a bound connection.

Parameters:

attribute - the name of the attribute to modify

Throws:

L3DException - if the object has no bound connection or the attribute is improperly defined or can't be modified

update

public final void update(LDAPConnection conn,
                         String attribute)
                  throws L3DException

Updates the directory database with the current value for the given attribute.

Parameters:

conn - an authenticated directory connection to use for updating

attribute - the name of the attribute to modify

Throws:

L3DException - if the attribute is improperly defined or can't be modified