LdapAttrDef (Jespa 2.0.9)

java.lang.Object
- jespa.ldap.LdapAttrDef

public class LdapAttrDef
extends java.lang.Object

A class for defining each LDAP attribute type, flags and automatic conversions if any. This feature adds attribute intelligence to LDAP applications. Single-valued attributes can be queried and set directly without going through another class or array. Attribute values can be automatically converted to and from alternative forms like formatted date strings, Base64 encoded data, etc. The developer can query attribute definitions to determine if they are single-valued, a DN and so on. Alltogether, this attribute intelligence can significantly reduce the complexity of LDAP code.

Each LdapSecurityProvider references a map of attribute definitions of type Map<String,LdapAttrDef>. The default definitions of an LdapSecurityProvider are determined by the ldap.disposition property. In practice, users will rarely if ever want to query or modify these default definitions.

Each LdapAttrDef object has type, flags and conv members. As attribute values are retrieved and set, their attribute definitions are used to determine if a value should be represented a List (because it is multi-valued) or to optionally convert values transparently to and from representations more suitable for use internally to Java.

Consider the following code fragment which creates and inserts a new attribute definition for a custom attribute. The attribute is defined as binary, single-valued and will automatically be converted to and from Base64 encoding for use within Java.

LdapSecurityProvider lsp = new LdapSecurityProvider(props);
try {
    Map<String,LdapAttrDef> attrdefs = (Map)lsp.getProperty("ldap.attributes.definitions");

    LdapAttrDef def = new LdapAttrDef(
            LdapAttrDef.TYPE_BINARY,
            LdapAttrDef.FLAG_SINGLE_VALUED,
            LdapAttrDef.CONV_BASE64_X_BINARY);
    attrdefs.put("someAttribute", def);
    lsp.setProperty("ldap.attributes.definitions", attrdefs);

    Map entry = lsp.getEntry(dn, new String[] { "someAttribute" }); 
    String someAttribute = (String)entry.get("someAttribute");

    System.out.println("someAttribute: " + someAttribute);
} finally {
    lsp.dispose();
}

Define a new attribute definition that automatically convertes the binary value of a custom attribute to and from Base64.

Note: Attribute definition conversions do not affect how data is stored within the directory. In this example, retrieving the binary value causes it to be converted into a Base64 encoded string at runtime. If the value is set, it will automatically be converted from Base64 to binary before it is written to the directory.

Although it is possible and valid to change the type and flags of existing attribute definitions, it is much more common to change only the conv member.

Attribute Definition Types

The type member of the attribute definition indicates what type of data is stored in the attribute in the LDAP directory. However, because LDAP attribute values are represented using such a wide variety of types (just for strings there is IA5String, Unicode String, DirectoryString, PrintableString to name a few), this API categorizes all attributes into only 5 types. These 5 types are described in the following table:

LDAP attribute definition types
Constant Identifier	Value	Java Type	Description
`TYPE_STRING`	`1`	`String`	A string presumably containing text. This is the most common attribute type. Fortunately regardless of how strings are stored within the directory, they are always represented within the LDAP communications protocol as UTF-8 and the default behavior is to convert these strings into a standard Java String (unless converted otherwise using an attribute conversion).
`TYPE_BOOLEAN`	`2`	`String`	A true or false value. Because `Map.get()` and other methods used to retrieve and set attribute values cannot return the Java `boolean` type, a `String` "true" or "false" is used to represent boolean values (unless converted otherwise using an attribute conversion). To manually convert a boolean attribute value into a `boolean` Java type, use the expression `"true".equals(sval)`.
`TYPE_BINARY`	`3`	`byte[]`	An squence of bytes. By default this attribute value will be represented as a `byte[]` array. However, in practice, most binary attributes have default attribute definition conversions that return a Base64 `String`, `jespa.util.SID` or another more user-friendly type. If this behavior is not desired, these default conversions can be disabled by setting the attribute definition `conv` member to 0.
`TYPE_TIME`	`4`	`String`	A type that represents a time or date and time. Within the directory these attribute values are usually represented as either timestamps or 64 bit integers. Because `Map.get()` and other methods for retrieving and setting attribute values cannot return a `long`, the Java type used to represent these values is always `String` (unless converted otherwise using an attribute conversion). In practice, default attribute definitions convert known date and time attributes into a 64 bit integer `String` representing the number of milliseconds since January 1, 1970, 00:00:00 GMT. To manually convert this value into a `long`, use an expression like `Long.parseLong(sval)`. To manually convert this value into a `java.util.Date`, use an expression like `new Date(Long.parseLong(sval))`.
`TYPE_INT32`	`5`	`String`	Because `Map.get()` and other methods for retrieving and setting attribute values cannot return an `int` type, the Java type used is always a `String` representing a 32 bit integer (unless converted otherwise using an attribute conversion). To manually convert this value to an `int`, use an expression like `Integer.parseInt(sval)`. Note: Beware that because Java integers are always signed, `int` values larger than 2^31 will be considered less than zero in conditional expressions.
`TYPE_INT64`	`6`	`String`	Because the `Map.get()` method and other methods for retrieving and setting attribute values cannot return a `long` type, the Java type used is always a `String` representing a 64 bit integer (unless converted otherwise using an attribute conversion). To manually convert this value to a `long`, use an expression like `Long.parseLong(sval)`. Note: Beware that because Java integers are always signed, `long` values larger than 2^63 will be considered less than zero in conditional expressions.

Attribute Definition Flags

The flags member of the attribute definition indicates as to whether or not the value is multivalued in which case a List of values of the specified type is returned (there are several other flags but they are generally not used).

LDAP attribute definition flags
Constant Identifier	Value	Description
`FLAG_SINGLE_VALUED`	`0x04`	Indicates that the value is single-valued. If this flag is not set, the attribute is multi-valued.
`FLAG_DN`	`0x10`	Indicates that the value is a Distinguished Name (DN).
`FLAG_PROTECTED`	`0x20`	Indicates that the attribute is special and cannot be set. Currently the only attribute definition that has this flag is the `distinguishedName` attribute and currently no logic within the Jespa implementation actually uses this flag.
`FLAG_CONSTRUCTED`	`0x40`	Indicates that the attribute value is dynamically generated on the LDAP server when the attribute is queried. Currently only the default attribute definitions for the `tokenGroups` and `unicodePwd` attributes have this flag although there are many other Active Directory attributes that are constructed.

Automatic Attribute Value Conversions

The conv member of the attribute definition allows the developer to automatically convert attribute values to and from more convenient forms. Dates in different forms such as UTC date strings and the Window's specific nanoseconds since 1601 dates can be automatically converted from and to the more familiar milliseconds since 1970 or from and to formatted date strings ideal for presenting direcly to users. Binary data can be transparently converted to and from Base64. Binary Windows SIDs can be converted to and from jespa.util.SID.

The programming constant identifiers for conv values are always organized as CONV_<int>_X_<dir> where <int> is the internal representation within Java to and from which the value will be converted and <dir> is the directory representation of values in the LDAP directory. For example, CONV_TIME1970M_X_TIMEUTC means UTC date strings in the directory will be automatically converted to and from milliseconds since 1970 for use internally with Java. The conversion CONV_BASE64_X_BINARY means binary attributes will be automatically converted to and from Base64 encoding within your Java code.

LDAP attribute value conversion constants
Conversion	Value	Description
`CONV_BASE64_X_BINARY`	`3`	Convert the attribute value between a Base64 encoded string within Java and binary within the directory.
`CONV_SID_X_BINARY`	`4`	Convert the attribute value between a `jespa.util.SID` Object and a binary SID within the directory. Even though the `jespa.util.SID` class is not documented, it's `equals` method may be used to compare SID Objects and it's `toString` method may be used to return the common textual representation of a Windows SID like `S-1-5-21-2779991297-2625803212-4394051119-1431`. This is the default conversion for the Active Directory attributes `objectSid` and `tokenGroups`. To obtain the binary representation of these attributes, it will be necessary to turn this conversion off by setting the attribute definition's `conv` member to 0.
`CONV_TIME1970M_X_TIMEUTC`	`5`	Convert the attribute value between an integer representing a time in milliseconds since 1970 and a UTC date string within the directory. For example, a UTC date string like `20100419233721.0Z` will be automatically converted to and from the integer `1271720241414` representing the same time in milliseconds since 1970. Note: Even though the ideal Java type for milliseconds would be `long`, `Map.get()` and other methods for retrieving attribute values always return Objects and therefore a `String` object representing an integer is returned. To convert this to a `long` it will be necessary to use an expression like `long lval = Long.parseLong(sval)`.
`CONV_TIME1970M_X_TIME1601`	`6`	Convert the attribute value between an integer representing a time in milliseconds since 1970 and the Active Directory specific nanoseconds since 1601 time representation in the directory. For example, a nanoseconds since 1601 time like `128980276368532080` will be automatically converted to and from the integer `1253554036853` representing the same time in milliseconds since 1970. Note: Even though the ideal Java type for milliseconds would be `long`, `Map.get()` and other methods for retrieving attribute values always return Objects and therefore a `String` object representing an integer is returned. To convert this to a `long` it will be necessary to use an expression like `long lval = Long.parseLong(sval)`.
`CONV_DATESTR_X_TIMEUTC`	`8`	Convert the attribute value between a formatted date string and a UTC date string within the directory. For example, a UTC date string like `20100419233721.0Z` will be automatically converted to and from a formatted date string like `2010-04-19 19:37:21`. Note: The date string format can be changed by setting the `ldap.attributes.date.format` property for the `LdapSecurityProvider` being used.
`CONV_DATESTR_X_TIME1601`	`9`	Convert the attribute value between a formatted date string and the Active Directory specific nanoseconds since 1601 time representation in the directory. For example, a nanoseconds since 1601 time like `128980276368532080` will be automatically converted to and from a formatted date string like `2009-09-21 13:27:16`. Note: The date string format can be changed by setting the `ldap.attributes.date.format` property for the `LdapSecurityProvider` being used.

Examples

The following example illustrates how to modify an attribute definition. Specifically, it retrieves the current attribute definition for the nTSecurityDescriptor attribute and changes it's conv member to 0. This turns off the default behavior of automatically converting this value to and from a Base64 string. The objective in this example is to retrieve the raw byte[] array value so that it can be printed in "hexdump" representation.

LdapSecurityProvider lsp = new LdapSecurityProvider(props);
try {
    Map<String,LdapAttrDef> attrdefs = (Map)lsp.getProperty("ldap.attributes.definitions");
    LdapAttrDef def = attrdefs.get("nTSecurityDescriptor");
    // This turns off the default automatic conversion of nTSecurityDescriptor value to Base64 string
    def.conv = 0;
    lsp.setProperty("ldap.attributes.definitions", attrdefs);

    Map entry = lsp.getEntry(dn, new String[] { "nTSecurityDescriptor" }); 
    // Note: You must be an Administrator to query this attribute
    byte[] nTSecurityDescriptor = (byte[])entry.get("nTSecurityDescriptor");

    jespa.util.Hexdump.hexdump(System.out, nTSecurityDescriptor, 0, nTSecurityDescriptor.length);
} finally {
    lsp.dispose();
}

-- output --

00000: 01 00 14 8C F4 09 00 00 10 0A 00 00 14 00 00 00  |....ô...........|
00010: 8C 00 00 00 04 00 78 00 02 00 00 00 07 5A 38 00  |......x......Z8.|
00020: 20 00 00 00 03 00 00 00 BE 3B 0E F3 F0 9F D1 11  | .......¾;.óð.Ñ.|
00030: B6 03 00 00 F8 03 67 C1 A5 7A 96 BF E6 0D D0 11  |¶...ø.gÁ¥z.¿æ.Ð.|
...

Print "hexdump" representation of nTSecurityDescriptor for an entry in Active Directory

The following example (from the LdapSearch utility) illustrates how to change time conversions from milliseconds to formatted date strings ideal for displaying directly to users. Meaning instead of returning and accepting attribute values that represent times as milliseconds since 1970 like 1200075597043, time values are formatted localized date strings like 2010-04-19 19:37:21.

LdapSecurityProvider provider = new LdapSecurityProvider(props);
try {
    HashMap<String,LdapAttrDef> attrdefs = (HashMap)provider.getProperty("ldap.attributes.definitions");
    Iterator<String> iter = attrdefs.keySet().iterator();
    while (iter.hasNext()) {
        String key = iter.next();
        LdapAttrDef def = attrdefs.get(key);
        if (def.conv == LdapAttrDef.CONV_TIME1970M_X_TIMEUTC) {
            def.conv = LdapAttrDef.CONV_DATESTR_X_TIMEUTC;
        } else if (def.conv == LdapAttrDef.CONV_TIME1970M_X_TIME1601) {
            def.conv = LdapAttrDef.CONV_DATESTR_X_TIME1601;
        }
    }
    provider.setProperty("ldap.attributes.definitions", attrdefs);
    ...
} finally {
    provider.dispose();
}

Changing Attribute Definition Conversions for Time Attributes

Default attibute definitions for Active directory and RFC based servers are hardcoded into the Jespa implementation. Additionally, some attribute definitions are deliberately incorrect. For example, the description attribute is defined in the Active Directory schema as multi-valued although the default Jespa attribute definition defines it as single-valued because Microsoft utilities that use this attribute always treat it as single-valued.

Field Summary

Fields
Modifier and Type	Field and Description
`int`	`conv`
`static int`	`CONV_BASE64_X_BINARY` See table in Attribute Definition Conversions section
`static int`	`CONV_DATESTR_X_TIME1601` See table in Attribute Definition Conversions section
`static int`	`CONV_DATESTR_X_TIMEUTC` See table in Attribute Definition Conversions section
`static int`	`CONV_HEXSTRING_X_BINARY` Reserved, do not use.
`static int`	`CONV_INT32_X_STRING` Reserved, do not use.
`static int`	`CONV_SID_X_BINARY` See table in Attribute Definition Conversions section
`static int`	`CONV_STRING_X_BINARY` Reserved, do not use.
`static int`	`CONV_TIME1970M_X_TIME1601` See table in Attribute Definition Conversions section
`static int`	`CONV_TIME1970M_X_TIMEUTC` See table in Attribute Definition Conversions section
`static int`	`FLAG_CASE_EXACT` See table in Attribute Definition Flags section
`static int`	`FLAG_CONSTRUCTED` See table in Attribute Definition Flags section
`static int`	`FLAG_DN` See table in Attribute Definition Flags section
`static int`	`FLAG_PROTECTED` See table in Attribute Definition Flags section
`static int`	`FLAG_SINGLE_VALUED` See table in Attribute Definition Flags section
`static int`	`FLAG_UNDEFINED` Reserved, do not use.
`int`	`flags`
`int`	`type`
`static int`	`TYPE_BINARY` See table in Attribute Definition Types section
`static int`	`TYPE_BOOLEAN` See table in Attribute Definition Types section
`static int`	`TYPE_INT32` See table in Attribute Definition Types section
`static int`	`TYPE_INT64` See table in Attribute Definition Types section
`static int`	`TYPE_STRING` See table in Attribute Definition Types section
`static int`	`TYPE_TIME` See table in Attribute Definition Types section

Constructor Summary

Constructors
Constructor and Description

LdapAttrDef(int type, int flags, int conv)

Constructors
Constructor and Description
`LdapAttrDef(int type, int flags, int conv)`

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`static java.util.HashMap`	`getDefaults(java.lang.String disposition)`
`java.lang.String`	`toString()`

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Field Detail
  - TYPE_STRING
```
public static final int TYPE_STRING
```
    See table in Attribute Definition Types section
    
    See Also:
    
    Constant Field Values
  - TYPE_BOOLEAN
```
public static final int TYPE_BOOLEAN
```
    See table in Attribute Definition Types section
    
    See Also:
    
    Constant Field Values
  - TYPE_BINARY
```
public static final int TYPE_BINARY
```
    See table in Attribute Definition Types section
    
    See Also:
    
    Constant Field Values
  - TYPE_TIME
```
public static final int TYPE_TIME
```
    See table in Attribute Definition Types section
    
    See Also:
    
    Constant Field Values
  - TYPE_INT32
```
public static final int TYPE_INT32
```
    See table in Attribute Definition Types section
    
    See Also:
    
    Constant Field Values
  - TYPE_INT64
```
public static final int TYPE_INT64
```
    See table in Attribute Definition Types section
    
    See Also:
    
    Constant Field Values
  - FLAG_UNDEFINED
```
public static final int FLAG_UNDEFINED
```
    Reserved, do not use.
    
    See Also:
    
    Constant Field Values
  - FLAG_SINGLE_VALUED
```
public static final int FLAG_SINGLE_VALUED
```
    See table in Attribute Definition Flags section
    
    See Also:
    
    Constant Field Values
  - FLAG_CASE_EXACT
```
public static final int FLAG_CASE_EXACT
```
    See table in Attribute Definition Flags section
    
    See Also:
    
    Constant Field Values
  - FLAG_DN
```
public static final int FLAG_DN
```
    See table in Attribute Definition Flags section
    
    See Also:
    
    Constant Field Values
  - FLAG_PROTECTED
```
public static final int FLAG_PROTECTED
```
    See table in Attribute Definition Flags section
    
    See Also:
    
    Constant Field Values
  - FLAG_CONSTRUCTED
```
public static final int FLAG_CONSTRUCTED
```
    See table in Attribute Definition Flags section
    
    See Also:
    
    Constant Field Values
  - CONV_INT32_X_STRING
```
public static final int CONV_INT32_X_STRING
```
    Reserved, do not use.
    
    See Also:
    
    Constant Field Values
  - CONV_STRING_X_BINARY
```
public static final int CONV_STRING_X_BINARY
```
    Reserved, do not use.
    
    See Also:
    
    Constant Field Values
  - CONV_BASE64_X_BINARY
```
public static final int CONV_BASE64_X_BINARY
```
    See table in Attribute Definition Conversions section
    
    See Also:
    
    Constant Field Values
  - CONV_SID_X_BINARY
```
public static final int CONV_SID_X_BINARY
```
    See table in Attribute Definition Conversions section
    
    See Also:
    
    Constant Field Values
  - CONV_TIME1970M_X_TIMEUTC
```
public static final int CONV_TIME1970M_X_TIMEUTC
```
    See table in Attribute Definition Conversions section
    
    See Also:
    
    Constant Field Values
  - CONV_TIME1970M_X_TIME1601
```
public static final int CONV_TIME1970M_X_TIME1601
```
    See table in Attribute Definition Conversions section
    
    See Also:
    
    Constant Field Values
  - CONV_HEXSTRING_X_BINARY
```
public static final int CONV_HEXSTRING_X_BINARY
```
    Reserved, do not use.
    
    See Also:
    
    Constant Field Values
  - CONV_DATESTR_X_TIMEUTC
```
public static final int CONV_DATESTR_X_TIMEUTC
```
    See table in Attribute Definition Conversions section
    
    See Also:
    
    Constant Field Values
  - CONV_DATESTR_X_TIME1601
```
public static final int CONV_DATESTR_X_TIME1601
```
    See table in Attribute Definition Conversions section
    
    See Also:
    
    Constant Field Values
  - type
```
public int type
```
  - flags
```
public int flags
```
  - conv
```
public int conv
```
- Constructor Detail
  - LdapAttrDef
```
public LdapAttrDef(int type,
                   int flags,
                   int conv)
```
- Method Detail
  - getDefaults
```
public static java.util.HashMap getDefaults(java.lang.String disposition)
```
  - toString
```
public java.lang.String toString()
```
    Overrides:
    
    toString in class java.lang.Object

Class LdapAttrDef

Attribute Definition Types

Attribute Definition Flags

Automatic Attribute Value Conversions

Examples

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

TYPE_STRING

TYPE_BOOLEAN

TYPE_BINARY

TYPE_TIME

TYPE_INT32

TYPE_INT64

FLAG_UNDEFINED

FLAG_SINGLE_VALUED

FLAG_CASE_EXACT

FLAG_DN

FLAG_PROTECTED

FLAG_CONSTRUCTED

CONV_INT32_X_STRING

CONV_STRING_X_BINARY

CONV_BASE64_X_BINARY

CONV_SID_X_BINARY

CONV_TIME1970M_X_TIMEUTC

CONV_TIME1970M_X_TIME1601

CONV_HEXSTRING_X_BINARY

CONV_DATESTR_X_TIMEUTC

CONV_DATESTR_X_TIME1601

type

flags

conv

Constructor Detail

LdapAttrDef

Method Detail

getDefaults

toString