com.novell.ldap
Class LDAPAttributeSet

java.lang.Object
  java.util.AbstractCollection<E>
      java.util.AbstractSet
          com.novell.ldap.LDAPAttributeSet

All Implemented Interfaces:

java.io.Externalizable, java.io.Serializable, java.lang.Cloneable, java.lang.Iterable, java.util.Collection, java.util.Set

public class LDAPAttributeSet
extends java.util.AbstractSet
implements java.lang.Cloneable, java.util.Set, java.io.Externalizable

A set of LDAPAttribute objects.

An LDAPAttributeSet is a collection of LDAPAttribute classes as returned from an LDAPEntry on a search or read operation. LDAPAttributeSet may be also used to contruct an entry to be added to a directory. If the add() or addAll() methods are called and one or more of the objects to be added is not an LDAPAttribute, ClassCastException is thrown (as discussed in the documentation for java.util.Collection).

Sample Code: AddEntry.java

See Also:

LDAPAttribute, LDAPEntry, Serialized Form

Field Summary

private java.util.HashMap

map This is the underlying data structure for this set.

Constructor Summary

LDAPAttributeSet()
Constructs an empty set of attributes.

Method Summary

boolean	add(java.lang.Object attr) Adds the specified attribute to this set if it is not already present.
boolean	addAll(java.util.Collection c) Adds all LDAPAttribute objects in the specified collection to this collection.
void	clear() Removes all of the elements from this set.
java.lang.Object	clone() Returns a deep copy of this attribute set.
boolean	contains(java.lang.Object attr) Returns true if this set contains an attribute of the same name as the specified attribute.
LDAPAttribute	getAttribute(java.lang.String attrName) Returns the attribute matching the specified attrName.
LDAPAttribute	getAttribute(java.lang.String attrName, java.lang.String lang) Returns a single best-match attribute, or null if no match is available in the entry.
LDAPAttributeSet	getSubset(java.lang.String subtype) Creates a new attribute set containing only the attributes that have the specified subtypes.
(package private) static LDAPXMLHandler	getXMLHandler(java.lang.String tagname, LDAPXMLHandler parenthandler) This method return the LDAPHandler which handles the XML (DSML) tags for this class
boolean	isEmpty() Returns true if this set contains no elements
java.util.Iterator	iterator() Returns an iterator over the attributes in this set.
(package private) void	newLine(int indentTabs, java.io.Writer out)
static java.lang.Object	readDSML(java.io.InputStream input) This method is used to deserialize the DSML encoded representation of this class.
void	readExternal(java.io.ObjectInput in) Reads the serialized object from the underlying input stream.
boolean	remove(java.lang.Object object) Removes the specified object from this set if it is present.
int	size() Returns the number of attributes in this set.
java.lang.String	toString() Returns a string representation of this LDAPAttributeSet
private void	writeAttribute(LDAPAttribute attr, java.lang.StringBuffer buff)
private void	writeAttribute(LDAPAttribute attr, java.io.Writer out)
void	writeDSML(java.io.OutputStream oout) This method does DSML serialization of the instance.
void	writeExternal(java.io.ObjectOutput out) Writes the object state to a stream in XML format

Methods inherited from class java.util.AbstractSet

equals, hashCode, removeAll

Methods inherited from class java.util.AbstractCollection

containsAll, retainAll, toArray, toArray

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface java.util.Set

containsAll, equals, hashCode, removeAll, retainAll, toArray, toArray

Field Detail

map

private java.util.HashMap map

This is the underlying data structure for this set.

HashSet is similar to the functionality of this set. The difference is we use the name of an attribute as keys in the Map and LDAPAttributes as the values. We also do not declare the map as transient, making the map serializable.

Constructor Detail

LDAPAttributeSet

public LDAPAttributeSet()

Constructs an empty set of attributes.

Method Detail

clone

public java.lang.Object clone()

Returns a deep copy of this attribute set.

Overrides:

clone in class java.lang.Object

Returns:

A deep copy of this attribute set.

getAttribute

public LDAPAttribute getAttribute(java.lang.String attrName)

Returns the attribute matching the specified attrName.

For example:

• getAttribute("cn") returns only the "cn" attribute
• getAttribute("cn;lang-en") returns only the "cn;lang-en" attribute.

In both cases, null is returned if there is no exact match to the specified attrName.

Note: Novell eDirectory does not currently support language subtypes. It does support the "binary" subtype.

Parameters:

attrName - The name of an attribute to retrieve, with or without subtype specifications. For example, "cn", "cn;phonetic", and "cn;binary" are valid attribute names.

Returns:

The attribute matching the specified attrName, or null if there is no exact match.

getAttribute

public LDAPAttribute getAttribute(java.lang.String attrName,
                                  java.lang.String lang)

Returns a single best-match attribute, or null if no match is available in the entry.

LDAP version 3 allows adding a subtype specification to an attribute name. For example, "cn;lang-ja" indicates a Japanese language subtype of the "cn" attribute and "cn;lang-ja-JP-kanji" may be a subtype of "cn;lang-ja". This feature may be used to provide multiple localizations in the same directory. For attributes which do not vary among localizations, only the base attribute may be stored, whereas for others there may be varying degrees of specialization.

For example, getAttribute(attrName,lang) returns the LDAPAttribute that exactly matches attrName and that best matches lang.

If there are subtypes other than "lang" subtypes included in attrName, for example, "cn;binary", only attributes with all of those subtypes are returned. If lang is null or empty, the method behaves as getAttribute(attrName). If there are no matching attributes, null is returned.

Assume the entry contains only the following attributes:

• cn;lang-en
• cn;lang-ja-JP-kanji
• sn

Examples:

• getAttribute( "cn" ) returns null.
• getAttribute( "sn" ) returns the "sn" attribute.
• getAttribute( "cn", "lang-en-us" ) returns the "cn;lang-en" attribute.
• getAttribute( "cn", "lang-en" ) returns the "cn;lang-en" attribute.
• getAttribute( "cn", "lang-ja" ) returns null.
• getAttribute( "sn", "lang-en" ) returns the "sn" attribute.

Note: Novell eDirectory does not currently support language subtypes. It does support the "binary" subtype.

Parameters:

attrName - The name of an attribute to retrieve, with or without subtype specifications. For example, "cn", "cn;phonetic", and cn;binary" are valid attribute names.

lang - A language specification with optional subtypes appended using "-" as separator. For example, "lang-en", "lang-en-us", "lang-ja", and "lang-ja-JP-kanji" are valid language specification.

Returns:

A single best-match LDAPAttribute, or null if no match is found in the entry.

getSubset

public LDAPAttributeSet getSubset(java.lang.String subtype)

Creates a new attribute set containing only the attributes that have the specified subtypes.

For example, suppose an attribute set contains the following attributes:

• cn
• cn;lang-ja
• sn;phonetic;lang-ja
• sn;lang-us

Calling the getSubset method and passing lang-ja as the argument, the method returns an attribute set containing the following attributes:

• cn;lang-ja
• sn;phonetic;lang-ja

Parameters:

subtype - Semi-colon delimited list of subtypes to include. For example:

• "lang-ja" specifies only Japanese language subtypes
• "binary" specifies only binary subtypes
• "binary;lang-ja" specifies only Japanese language subtypes which also are binary

Note: Novell eDirectory does not currently support language subtypes. It does support the "binary" subtype.

Returns:

An attribute set containing the attributes that match the specified subtype.

iterator

public java.util.Iterator iterator()

Returns an iterator over the attributes in this set. The attributes returned from this iterator are not in any particular order.

Specified by:

iterator in interface java.lang.Iterable

Specified by:

iterator in interface java.util.Collection

Specified by:

iterator in interface java.util.Set

Specified by:

iterator in class java.util.AbstractCollection

Returns:

iterator over the attributes in this set

size

public int size()

Returns the number of attributes in this set.

Specified by:

size in interface java.util.Collection

Specified by:

size in interface java.util.Set

Specified by:

size in class java.util.AbstractCollection

Returns:

number of attributes in this set.

isEmpty

public boolean isEmpty()

Returns true if this set contains no elements

Specified by:

isEmpty in interface java.util.Collection

Specified by:

isEmpty in interface java.util.Set

Overrides:

isEmpty in class java.util.AbstractCollection

Returns:

true if this set contains no elements

contains

public boolean contains(java.lang.Object attr)

Returns true if this set contains an attribute of the same name as the specified attribute.

Specified by:

contains in interface java.util.Collection

Specified by:

contains in interface java.util.Set

Overrides:

contains in class java.util.AbstractCollection

Parameters:

attr - Object of type LDAPAttribute

Returns:

true if this set contains the specified attribute

Throws:

java.lang.ClassCastException - occurs the specified Object is not of type LDAPAttribute.

add

public boolean add(java.lang.Object attr)

Adds the specified attribute to this set if it is not already present.

If an attribute with the same name already exists in the set then the specified attribute will not be added.

Specified by:

add in interface java.util.Collection

Specified by:

add in interface java.util.Set

Overrides:

add in class java.util.AbstractCollection

Parameters:

attr - Object of type LDAPAttribute

Returns:

true if the attribute was added.

Throws:

java.lang.ClassCastException - occurs the specified Object is not of type LDAPAttribute.

remove

public boolean remove(java.lang.Object object)

Removes the specified object from this set if it is present.

If the specified object is of type LDAPAttribute, the specified attribute will be removed. If the specified object is of type String, the attribute with a name that matches the string will be removed.

Specified by:

remove in interface java.util.Collection

Specified by:

remove in interface java.util.Set

Overrides:

remove in class java.util.AbstractCollection

Parameters:

object - LDAPAttribute to be removed or String naming the attribute to be removed.

Returns:

true if the object was removed.

Throws:

java.lang.ClassCastException - occurs the specified Object is not of type LDAPAttribute or of type String.

clear

public void clear()

Removes all of the elements from this set.

Specified by:

clear in interface java.util.Collection

Specified by:

clear in interface java.util.Set

Overrides:

clear in class java.util.AbstractCollection

addAll

public boolean addAll(java.util.Collection c)

Adds all LDAPAttribute objects in the specified collection to this collection.

Specified by:

addAll in interface java.util.Collection

Specified by:

addAll in interface java.util.Set

Overrides:

addAll in class java.util.AbstractCollection

Parameters:

c - Collection of LDAPAttribute objects.

Returns:

true if this set changed as a result of the call.

Throws:

java.lang.ClassCastException - occurs when an element in the collection is not of type LDAPAttribute.

toString

public java.lang.String toString()

Returns a string representation of this LDAPAttributeSet

Overrides:

toString in class java.util.AbstractCollection

Returns:

a string representation of this LDAPAttributeSet

newLine

void newLine(int indentTabs,
             java.io.Writer out)
       throws java.io.IOException

Throws:

java.io.IOException

writeAttribute

private void writeAttribute(LDAPAttribute attr,
                            java.io.Writer out)
                     throws java.io.IOException

Throws:

java.io.IOException

writeDSML

public void writeDSML(java.io.OutputStream oout)
               throws java.io.IOException

This method does DSML serialization of the instance.

Parameters:

oout - Outputstream where the serialzed data has to be written

Throws:

java.io.IOException - if write fails on OutputStream

readDSML

public static java.lang.Object readDSML(java.io.InputStream input)
                                 throws java.io.IOException

This method is used to deserialize the DSML encoded representation of this class.

Parameters:

input - InputStream for the DSML formatted data.

Returns:

Deserialized form of this class.

Throws:

java.io.IOException - when serialization fails.

getXMLHandler

static LDAPXMLHandler getXMLHandler(java.lang.String tagname,
                                    LDAPXMLHandler parenthandler)

This method return the LDAPHandler which handles the XML (DSML) tags for this class

Parameters:

tagname - Name of the Root tag used to represent this class.

parenthandler - Parent LDAPXMLHandler for this tag.

Returns:

LDAPXMLHandler to handle this element.

writeAttribute

private void writeAttribute(LDAPAttribute attr,
                            java.lang.StringBuffer buff)
                     throws java.io.IOException

Throws:

java.io.IOException

writeExternal

public void writeExternal(java.io.ObjectOutput out)
                   throws java.io.IOException

Writes the object state to a stream in XML format

Specified by:

writeExternal in interface java.io.Externalizable

Parameters:

out - The ObjectOutput stream where the Object in XML format is being written to

Throws:

java.io.IOException - - If I/O errors occur

readExternal

public void readExternal(java.io.ObjectInput in)
                  throws java.io.IOException,
                         java.lang.ClassNotFoundException

Reads the serialized object from the underlying input stream.

Specified by:

readExternal in interface java.io.Externalizable

Parameters:

in - The ObjectInput stream where the Serialized Object is being read from

Throws:

java.io.IOException - - If I/O errors occur

java.lang.ClassNotFoundException - - If the class for an object being restored cannot be found.