Package com.isode.dsapi

Class AttributeValue

java.lang.Object
com.isode.dsapi.AttributeValue
All Implemented Interfaces:
Comparable<AttributeValue>
public class AttributeValue extends Object implements Comparable<AttributeValue>
Representation of a single attribute value. Depending on how the object was instantiated, the value may be stored as the BER encoding and/or LDAP string format.

The getBer() and getString() methods return the BER and String encoding of the AttributeValue, if available. BER values are converted to String values, and String to BER values, as necessary to return a value.

AttributeValues may be created by an application using one of the constructors in this class. AttributeValue objects are also created by the library to represent values returned from directory operations (such as reading an entry), as well as to represent values loaded from LDIF files.

AttributeValue objects normally contain values which are legal according to the current local schema, and this is typically the desired behaviour. However, there are situations where values may be encountered which are not legal. For example, as a result of dealing with non-local directories that have non-compatible schema, or processing LDIF data that was generated by a non-compatible directory, it could be that an object will contain an "illegal" value.

Generally, programs will be manipulating AttributeValue objects that contain legal values, so constructors are provided which automatically validate values, throwing BadValueException for illegal values. However, constructors are also provided which allow this check to be overridden: these constructors have allowBadValue argument, which should be set to true to disable this check, and prevent any consequent BadValueException.

In all cases, you can test whether a given AttributeValue is legal according to the local schema by using the method isLegalForLocalSchema().

  • Constructor Summary

    Constructors
    Constructor
    Description
    AttributeValue(boolean allowBadValue, byte[] buffer, AttributeType attrType, boolean isBER)
    Construct an AttributeValue, using an AttributeType, from either binary or BER encoding, optionally validating the value against the local schema.
    AttributeValue(boolean allowBadValue, byte[] buffer, String attrName, boolean isBER)
    Construct an AttributeValue, using a String representation of an attribute name, from either binary or BER encoding, optionally validating the value against the local schema.
    AttributeValue(boolean allowBadValue, String ldap_str, AttributeType attrType)
    Build an AttributeValue from a suitable LDAP String representation of a specified AttributeType, optionally validating the value against the local schema.
    AttributeValue(boolean allowBadValue, String ldap_str, String attrName)
    Build an AttributeValue from a suitable LDAP String representation of a specified AttributeType, optionally checking validating the value against the local schema.
    AttributeValue(byte[] buffer, AttributeType attrType, boolean isBER)
    Construct an AttributeValue, using an AttributeType, from either binary or BER encoding.
    AttributeValue(byte[] buffer, String attrName, boolean isBER)
    Construct an AttributeValue, using a String representation of an attribute name, from either binary or BER encoding.
    AttributeValue(String ldap_str, AttributeType attrType)
    Build an AttributeValue from a suitable LDAP String representation of a specified AttributeType.
    AttributeValue(String ldap_str, String attrName)
    Build an AttributeValue from a suitable LDAP String representation, using the String representation of an attribute name Objects created with this constructor will always be valid according to the local schema.

  • Method Summary

    Modifier and Type
    Method
    Description
    int
    compareTo(AttributeValue other)
    Compares this value with the specified AttributeValue for sort order.
    boolean
    equals(Object anObject)
    Compare this AttributeValue to the specified object, and return true iff the argument is a AttributeValue that represents the same value as this object.
    int
    exactCompareTo(AttributeValue oo)
    Order two AttributeValues according to comparisons on their exact values (that is, their string or binary or BER values), rather than based on syntax-specific folding of case or whatever, as is done by compareTo().
    boolean
    exactEquals(AttributeValue oo)
    Check whether two AttributeValues are exactly equal, having identical string, binary or BER representations.
    String
    getAttributeName()
    Determine the attribute name for this value
    AttributeType
    getAttributeType()
    Determine the attribute type for this value.
    byte[]
    getBer()
    Get the BER value for this AttributeValue, if it has one.
    byte[]
    getBinary()
    Returns the binary representation of the String value for this AttributeValue.
    String
    getCanonicalString()
    Returns the canonical string representation of this AttributeValue, if there is one, or otherwise null.
    AttributeValue
    getNormalizedValue()
    Create a normalized version of this AttributeValue.
    String
    getString()
    Returns a string representation of this AttributeValue.
    int
    getSyntaxID()
    Get the syntax identifier.
    String
    getSyntaxName()
    Get the syntax name for this object.
    boolean
    hasBer()
    Test whether this AttributeValue already has a BER value attached.
    int
    hashCode()
    Overrides Object.hashCode in order to be consistent with the equals(Object) method.
    boolean
    isLegalForLocalSchema()
    Determine whether this object contains a value which is is valid according to the local schema's definition of its AttributeType.
    boolean
    isUTF8String()
    Determine whether the value held in this object is a valid UTF-8 String.
    AttributeValue
    relocate(DN... source_target_list)
    If this AttributeValue contains a DN, and that DN is within one of the subtrees specified in the arguments, then it is relocated to the same relative location within the corresponding target subtree (using DN.getRelocatedDN()), and a new AttributeValue is created and returned.
    AttributeValue
    relocate(DN source, DN target)
    If this AttributeValue contains a DN, and that DN is within the subtree indicated by 'source', then it is relocated to the same relative location within the 'target' subtree (using DN.getRelocatedDN()), and a new AttributeValue is created and returned.
    String
    toString()
    Return a String representation of this object.

    Methods inherited from class java.lang.Object

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

  • Constructor Details

    • AttributeValue

      public AttributeValue(boolean allowBadValue, byte[] buffer, AttributeType attrType, boolean isBER) throws BadValueException, NativeLibraryException
      Construct an AttributeValue, using an AttributeType, from either binary or BER encoding, optionally validating the value against the local schema.

      It may be useful to create attribute values using binary data where there is no suitable string representation.

      AttributeValues created using a BER that are valid according to the local schema will also contain a String encoding. Otherwise, in the case of such objects, getString() and getBinary() will return null.

      Parameters:
      allowBadValue - true to allow values to be created even if they are not valid according to the local schema, or false if such values are not to be allowed (in which case BadValueException may be thrown).
      buffer - Either the BER encoding or the binary representation of the attribute value. This must not be null.
      attrType - an AttributeType; must not be null.
      isBER - specifies whether buffer contains a BER encoded value (true) or a binary representation (false).
      Throws:
      BadValueException - if allowBadValue was false, and the value specified is illegal for attrType
      NativeLibraryException - if an unrecoverable error was detected by the native library
      NullPointerException - if buffer or attrTypeis null.

    • AttributeValue

      public AttributeValue(byte[] buffer, AttributeType attrType, boolean isBER) throws BadValueException, NativeLibraryException
      Construct an AttributeValue, using an AttributeType, from either binary or BER encoding. Objects created with this constructor will always be valid according to the local schema.

      It may be useful to create attribute values using binary data where there is no suitable string representation.

      AttributeValues created using from BER with this constructor will also contain a String encoding (generated by the syntax handler for the relevant attribute type).

      Parameters:
      buffer - Either the BER encoding or the binary representation of the attribute value. This must not be null.
      attrType - an AttributeType; must not be null.
      isBER - specifies whether buffer contains a BER encoded value (true) or a binary representation (false).
      Throws:
      BadValueException - if the value specified is illegal for attrType
      NativeLibraryException - if an unrecoverable error was detected by the native library
      NullPointerException - if buffer or attrTypeis null.

    • AttributeValue

      public AttributeValue(boolean allowBadValue, byte[] buffer, String attrName, boolean isBER) throws BadAttributeTypeException, BadValueException, NativeLibraryException
      Construct an AttributeValue, using a String representation of an attribute name, from either binary or BER encoding, optionally validating the value against the local schema.

      It may be useful to create attribute values using binary data where there is no suitable string representation.

      AttributeValues created using a BER that are valid according to the local schema will also contain a String encoding. Otherwise, in the case of such objects, getString() and getBinary() will return null.

      Parameters:
      allowBadValue - true to allow values to be created even if they are not valid according to the local schema, or false if such values are not to be allowed (in which case BadValueException may be thrown).
      buffer - Either the BER encoding or the binary representation of the attribute value. This must not be null.
      attrName - an attribute name. This must not be null.
      isBER - specifies whether buffer contains a BER encoded value (true) or a binary representation (false).
      Throws:
      BadAttributeTypeException - if attrName is null, or not recognized.
      BadValueException - if allowBadValue was false, and the value specified is illegal for attrName
      NativeLibraryException - if an unrecoverable error was detected by the native library
      NullPointerException - if buffer is null.

    • AttributeValue

      public AttributeValue(byte[] buffer, String attrName, boolean isBER) throws BadAttributeTypeException, BadValueException, NativeLibraryException
      Construct an AttributeValue, using a String representation of an attribute name, from either binary or BER encoding. Objects created with this constructor will always be valid according to the local schema.

      It may be useful to create attribute values using binary data where there is no suitable string representation.

      AttributeValues created using a BER encoding with this constructor will also contain a String encoding (generated by the syntax handler for the relevant attribute type).

      Parameters:
      buffer - Either the BER encoding or the binary representation of the attribute value. This must not be null.
      attrName - an attribute name. This must not be null.
      isBER - specifies whether buffer contains a BER encoded value (true) or a binary representation (false).
      Throws:
      BadAttributeTypeException - if attrName is null, or not recognized.
      BadValueException - if the value specified is illegal for attrName
      NativeLibraryException - if an unrecoverable error was detected by the native library
      NullPointerException - if buffer is null.

    • AttributeValue

      public AttributeValue(boolean allowBadValue, String ldap_str, AttributeType attrType) throws BadValueException
      Build an AttributeValue from a suitable LDAP String representation of a specified AttributeType, optionally validating the value against the local schema.

      For example, 

          AttributeValue av = new AttributeValue(true,"jim smith", commonNameAT);
      Parameters:
      allowBadValue - true to allow values to be created even if they are not valid according to the local schema, or false if such values are not to be allowed (in which case BadValueException may be thrown).
      ldap_str - a String representation of a value of type attrType (not null).
      attrType - an AttributeType (not null).
      Throws:
      BadValueException - if allowBadValue was true, and ldap_str is not a valid LDAP string representation of an attrType.
      NativeLibraryException - if an unrecoverable error was detected by the native library
      NullPointerException - if attrType or ldap_str is null.

    • AttributeValue

      public AttributeValue(String ldap_str, AttributeType attrType) throws BadValueException
      Build an AttributeValue from a suitable LDAP String representation of a specified AttributeType.

      For example: 

          AttributeValue av = new AttributeValue("US", countryNameAT);
      Objects created with this constructor will always be valid according to the local schema.
      Parameters:
      ldap_str - an valid LDAP String representation of an value of type attrType (not null).
      attrType - an AttributeType (not null).
      Throws:
      BadValueException - if ldap_str is not a valid LDAP string representation of an attrType.
      NativeLibraryException - if an unrecoverable error was detected by the native library

    • AttributeValue

      public AttributeValue(boolean allowBadValue, String ldap_str, String attrName) throws BadAttributeTypeException, BadValueException
      Build an AttributeValue from a suitable LDAP String representation of a specified AttributeType, optionally checking validating the value against the local schema.

      For example, 

          AttributeValue av = new AttributeValue(true,"jim smith", "commonname");
      Parameters:
      allowBadValue - true to allow values to be created even if they are not valid according to the local schema, or false if such values are not to be allowed (in which case BadValueException may be thrown).
      ldap_str - a String representation of a value of type attrName.
      attrName - an attribute name. This must not be null.
      Throws:
      BadValueException - if allowBadValue was true, and ldap_str is not a valid LDAP string representation of an attrName.
      BadAttributeTypeException - if attrName is null, or not recognized.
      NullPointerException - if ldap_str is null.
      NativeLibraryException - if an unrecoverable error was detected by the native library

    • AttributeValue

      public AttributeValue(String ldap_str, String attrName) throws BadAttributeTypeException, BadValueException
      Build an AttributeValue from a suitable LDAP String representation, using the String representation of an attribute name Objects created with this constructor will always be valid according to the local schema.

      For example, 

          AttributeValue av = new AttributeValue("US", "c");
      Parameters:
      ldap_str - an valid LDAP String representation of an value corresponding to attrName
      attrName - an attribute name. This must not be null.
      Throws:
      BadValueException - if ldap_str is not a valid LDAP string representation for an attrName attribute.
      BadAttributeTypeException - if attrName is null, or not recognized.
      NullPointerException - if ldap_str is null.
      NativeLibraryException - if an unrecoverable error was detected by the native library

  • Method Details

    • getBer

      public byte[] getBer()
      Get the BER value for this AttributeValue, if it has one. If the attribute value was originally created from a string or binary data, then the BER will be generated automatically and stored in the AttributeValue. Note that some types and/or values (e.g. invalid values) do not have a BER representation and will return null.
      Returns:
      An array of bytes containing the BER representation of this attribute value. This array is a copy of the object's internal BER data, so any changes made to the returned array do not affect the contents of the AttributeValue object.

      This method returns null if no BER representation is available for this AttributeValue.

    • hasBer

      public boolean hasBer()
      Test whether this AttributeValue already has a BER value attached. Depending on how the AttributeValue was created, it might or might not already have a BER value stored. Calling getBer() will force generation of BER and store it in the AttributeValue, but to avoid that overhead when not required, this function may be called first to check.
      Returns:
      true if the AttributeValue already has a BER value attached, or false if it doesn't.
      Since:
      14.4

    • toString

      public String toString()
      Return a String representation of this object. The value returned will always be a non-null String, but the format of the String will depend on the syntax and contents.
      Overrides:
      toString in class Object
      Returns:
      (LDAP) string representation, if possible. If the value cannot be converted to a String, then a String will be returned containing information about the size of the value in bytes, and whether or not the value has been validated against the local schema.

    • getSyntaxID

      public int getSyntaxID()
      Get the syntax identifier.
      Returns:
      Syntax identifier.

    • getSyntaxName

      public String getSyntaxName() throws NativeLibraryException
      Get the syntax name for this object. If a name cannot be determined, then a String representation of the numeric syntax identifier will be returned (e.g. "23").
      Returns:
      the name of the syntax (or a String representation of its numeric value).
      Throws:
      NativeLibraryException - if an unrecoverable error was detected by the native library

    • exactEquals

      public boolean exactEquals(AttributeValue oo)
      Check whether two AttributeValues are exactly equal, having identical string, binary or BER representations. This is a much stricter check than equals(), because equals() might use a case-insensitive match or do other syntax-specific folding of values before comparison.

      Note that in the case of AttributeValues without a string or binary representation, BER values are compared. This may cause two logically identical values to appear different due to slightly different BER encoding, i.e. the equality test may be too strict in this case.

      Since:
      14.5

    • exactCompareTo

      public int exactCompareTo(AttributeValue oo)
      Order two AttributeValues according to comparisons on their exact values (that is, their string or binary or BER values), rather than based on syntax-specific folding of case or whatever, as is done by compareTo(). This corresponds to exactEquals(), as compareTo() correponds to equals().
      Returns:
      -1, 0 or 1 depending on whether this object orders earlier, the same, or later than, the specified value.
      Since:
      14.5

    • compareTo

      public int compareTo(AttributeValue other) throws ClassCastException, NativeLibraryException
      Compares this value with the specified AttributeValue for sort order. Returns a negative integer, zero, or a positive integer depending on whether this object is "less than", "equal to", or "greater than" the specified AttributeValue.

      The comparison is made using the syntax-specific compare routines, and so values may be ordered differently when using this method than might be expected from a comparison of the values' String representations.

      Note also that not all types of AttributeValue will necessarily have a comparison routine, and so callers should not rely on being able to use this method for all types of Attribute.

      Specified by:
      compareTo in interface Comparable<AttributeValue>
      Parameters:
      other - the AttributeValue to be compared
      Returns:
      -1, 0 or 1 depending on whether this object orders earlier, the same, or later than, the specified value.
      Throws:
      ClassCastException - if other has an incompatible syntax to this AttributeValue, or if there is no syntax-specific comparison routine for this type of value
      NativeLibraryException - if an unrecoverable error was detected by the native library

    • equals

      public boolean equals(Object anObject)
      Compare this AttributeValue to the specified object, and return true iff the argument is a AttributeValue that represents the same value as this object. The comparison is syntax specific, and so two AttributeValues which have differing String representations may still compare as being "equal".

      Note that certain types of AttributeValue cannot be compared by the native library: for such values, this method always returns false. Callers may use compareTo(AttributeValue) to establish whether given AttributeValue objects are comparable.

      Overrides:
      equals in class Object
      Parameters:
      anObject - an object to compare this AttributeValue against.
      Returns:
      true if the values are equal, false if it's not possible to compare the values, or if they are not equal.

    • hashCode

      public int hashCode()
      Overrides Object.hashCode in order to be consistent with the equals(Object) method.
      Overrides:
      hashCode in class Object

    • isUTF8String

      public boolean isUTF8String()
      Determine whether the value held in this object is a valid UTF-8 String.

      Note that an attribute value which is a "binary" value, such as a JPEGPhoto may by chance happen to be a valid UTF-8 String. In other words, the fact that this method returns true does not guarantee that it is sensible to represent the value as a String.

      Returns:
      true if this value can be converted to a UTF-8 string, false otherwise.

    • getBinary

      public byte[] getBinary()
      Returns the binary representation of the String value for this AttributeValue. Note that in the case of values which are not legal for the local schema (e.g. that have been loaded as BER data from LDIF), this method may return null
      Returns:
      binary representation of the attribute value, if available. The array returned is a copy of that held by the object, and so modifications made to it do not affect the object itself.
      See Also:

    • getString

      public String getString()
      Returns a string representation of this AttributeValue. If this object was initialised with a BER value, then the string representation will be that generated by the syntax handler for the corresponding attribute type. In this case, values which are not legal for the local schema (e.g. that have been loaded as BER data from LDIF), this method will return null
      Returns:
      a String representation of the value which may be null if the value is not legal for the local schema, or if it cannot be decoded as a UTF-8 String.
      See Also:

    • getCanonicalString

      public String getCanonicalString()
      Returns the canonical string representation of this AttributeValue, if there is one, or otherwise null. This may be used for direct string-equality comparisons.
      Returns:
      Canonical string, or null if not available
      Since:
      R14.6

    • getAttributeType

      public AttributeType getAttributeType()
      Determine the attribute type for this value.
      Returns:
      the value's AttributeType

    • getAttributeName

      public String getAttributeName()
      Determine the attribute name for this value
      Returns:
      the value's attribute name

    • getNormalizedValue

      public AttributeValue getNormalizedValue()
      Create a normalized version of this AttributeValue. The string-value of the AttributeValue is converted to an internal form and then back to a string. This has the effect of normalizing the value, e.g. getting rid of unnecessary spaces from a DN, converting F.401 OR-Addresses to the default OR-Address format, and correcting the capitalisation on objectclass names. Either a new AttributeValue will be returned (if there has been a change), or otherwise the original one is returned.
      Returns:
      Normalized AttributeValue

    • isLegalForLocalSchema

      public boolean isLegalForLocalSchema()
      Determine whether this object contains a value which is is valid according to the local schema's definition of its AttributeType.

      AttributeValues which are loaded from LDIF or which are obtained as a result of a directory operation may contain data which is not legal according to the local schema.

      Returns:
      true if the value is valid according to the local schema's definition of AttributeType, false otherwise.

    • relocate

      public AttributeValue relocate(DN source, DN target)
      If this AttributeValue contains a DN, and that DN is within the subtree indicated by 'source', then it is relocated to the same relative location within the 'target' subtree (using DN.getRelocatedDN()), and a new AttributeValue is created and returned. Otherwise the current AttributeValue is returned.

      At the moment this only relocates DN-syntax values, but in the future it may be expanded to relocate ORNames and other types.

      Parameters:
      source - DN of base of source subtree (not null)
      target - DN of base of target subtree (not null)
      Returns:
      Resulting AttributeValue, or this if no change was necessary
      Since:
      14.6

    • relocate

      public AttributeValue relocate(DN... source_target_list)
      If this AttributeValue contains a DN, and that DN is within one of the subtrees specified in the arguments, then it is relocated to the same relative location within the corresponding target subtree (using DN.getRelocatedDN()), and a new AttributeValue is created and returned. Otherwise the current AttributeValue is returned.

      At the moment this only relocates DN-syntax values, but in the future it may be expanded to relocate ORNames and other types.

      Parameters:
      source_target_list - Array of an even number of DNs, handled in pairs. Of each pair, the first is treated as a source subtree, and the second as a target subtree. The DN is matched against source DNs in the list from the start to the end, and the first pair that it matches is the relocation that is performed. If there are no matches then 'this' is returned unchanged. (not null)
      Returns:
      Resulting AttributeValue, or this if no change was necessary
      Since:
      15.0