Package com.isode.dsapi

Class AttributeValue

  • All Implemented Interfaces:
    java.lang.Comparable<AttributeValue>
    public class AttributeValue
extends java.lang.Object
implements java.lang.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, java.lang.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, java.lang.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, java.lang.String ldap_str, java.lang.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, java.lang.String attrName, boolean isBER)
      Construct an AttributeValue, using a String representation of an attribute name, from either binary or BER encoding.
      AttributeValue​(java.lang.String ldap_str, AttributeType attrType)
      Build an AttributeValue from a suitable LDAP String representation of a specified AttributeType.
      AttributeValue​(java.lang.String ldap_str, java.lang.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

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      int compareTo​(AttributeValue other)
      Compares this value with the specified AttributeValue for sort order.
      boolean equals​(java.lang.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.
      java.lang.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.
      java.lang.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.
      java.lang.String getString()
      Returns a string representation of this AttributeValue.
      int getSyntaxID()
      Get the syntax identifier.
      java.lang.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.
      java.lang.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 Detail

      • 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
        java.lang.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
        java.lang.NullPointerException - if buffer or attrTypeis null.

      • AttributeValue

        public AttributeValue​(boolean allowBadValue,
                      byte[] buffer,
                      java.lang.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
        java.lang.NullPointerException - if buffer is null.

      • AttributeValue

        public AttributeValue​(byte[] buffer,
                      java.lang.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
        java.lang.NullPointerException - if buffer is null.

      • AttributeValue

        public AttributeValue​(boolean allowBadValue,
                      java.lang.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
        java.lang.NullPointerException - if attrType or ldap_str is null.

      • AttributeValue

        public AttributeValue​(java.lang.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,
                      java.lang.String ldap_str,
                      java.lang.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.
        java.lang.NullPointerException - if ldap_str is null.
        NativeLibraryException - if an unrecoverable error was detected by the native library

      • AttributeValue

        public AttributeValue​(java.lang.String ldap_str,
                      java.lang.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.
        java.lang.NullPointerException - if ldap_str is null.
        NativeLibraryException - if an unrecoverable error was detected by the native library

    • Method Detail

      • 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 java.lang.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 java.lang.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 java.lang.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 java.lang.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 java.lang.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:
        java.lang.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​(java.lang.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 java.lang.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 java.lang.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(), isLegalForLocalSchema()

      • getString

        public java.lang.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:
        getBinary(), isLegalForLocalSchema()

      • getCanonicalString

        public java.lang.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 java.lang.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