Пакет javax.naming.ldap

Обеспечивает поддержку расширенных операций и управляющих элементов LDAPv3.

Этот пакет расширяет операции каталога в Java Naming and Directory Interface (JNDI). JNDI предоставляет приложениям, написанным на языке программирования Java, функциональность именования и каталогов. Он разработан для независимости от реализации конкретных служб именования или каталогов. Таким образом, к различным службам — новым, появляющимся и уже развернутым — можно получить доступ одинаковым способом.

Этот пакет предназначен для приложений и поставщиков услуг, которые работают с расширенными операциями и управляющими элементами LDAPv3, определенными в RFC 2251. Основной интерфейс в этом пакете — LdapContext, который определяет методы контекста для выполнения расширенных операций и обработки управляющих элементов.

Расширенные операции

Этот пакет определяет интерфейс ExtendedRequest для представления аргумента расширенной операции и интерфейс ExtendedResponse для представления результата расширенной операции. Расширенный ответ всегда связан с расширенным запросом, но не обязательно наоборот. То есть у вас может быть расширенный запрос без соответствующего расширенного ответа.

Приложение обычно не взаимодействует напрямую с этими интерфейсами. Вместо этого оно взаимодействует с классами, которые *реализуют* эти интерфейсы. Приложение получает эти классы либо как часть набора стандартизированных расширенных операций IETF, либо от поставщиков каталогов для поставщика-специфичных расширенных операций. Классы запросов должны иметь конструкторы, которые принимают аргументы удобным для пользователя и безопасным для типов способом, а классы ответов должны иметь методы доступа для получения данных ответа удобным для пользователя и безопасным для типов способом. Внутренне классы запроса/ответа обрабатывают кодирование и декодирование значений BER.

Например, предположим, что сервер LDAP поддерживает расширенную операцию "получение времени". Он предоставит классы, такие как GetTimeRequest и GetTimeResponse, чтобы приложения могли использовать эту функцию. Приложение будет использовать эти классы следующим образом:

GetTimeResponse resp =
    (GetTimeResponse) ectx.extendedOperation(new GetTimeRequest());
long time = resp.getTime();

Классы GetTimeRequest и GetTimeResponse могут быть определены следующим образом:

public class GetTimeRequest implements ExtendedRequest {
    // User-friendly constructor 
    public GetTimeRequest() {
    };

    // Methods used by service providers
    public String getID() {
        return GETTIME_REQ_OID;
    }
    public byte[] getEncodedValue() {
        return null;  // no value needed for get time request
    }
    public ExtendedResponse createExtendedResponse(
        String id, byte[] berValue, int offset, int length) throws NamingException {
        return new GetTimeResponse(id, berValue, offset, length);
    }
}
public class GetTimeResponse() implements ExtendedResponse {
    long time;
    // called by GetTimeRequest.createExtendedResponse()
    public GetTimeResponse(String id, byte[] berValue, int offset, int length)
        throws NamingException {
        // check validity of id
        long time =  ... // decode berValue to get time
    }

    // Type-safe and User-friendly methods
    public java.util.Date getDate() { return new java.util.Date(time); }
    public long getTime() { return time; }

    // Low level methods
    public byte[] getEncodedValue() {
        return // berValue saved;
    }
    public String getID() {
        return GETTIME_RESP_OID;
    }
}

Управляющие элементы

Этот пакет определяет интерфейс Control для представления управляющего элемента LDAPv3. Это может быть управляющий элемент, отправляемый на сервер LDAP (управляющий элемент запроса), или управляющий элемент, возвращаемый сервером LDAP (управляющий элемент ответа). В отличие от расширенных запросов и ответов, между управляющими элементами запроса и ответа не обязательно существует пара. Вы можете отправить управляющие элементы запроса и не ожидать управляющих элементов ответа или получить управляющие элементы ответа без отправки управляющих элементов запроса.

Приложение обычно не взаимодействует напрямую с этим интерфейсом. Вместо этого оно взаимодействует с классами, которые *реализуют* этот интерфейс. Приложение получает классы управляющих элементов либо как часть набора стандартизированных управляющих элементов IETF, либо от поставщиков каталогов для поставщика-специфичных управляющих элементов. Классы управляющих элементов запроса должны иметь конструкторы, которые принимают аргументы удобным для пользователя и безопасным для типов способом, а классы управляющих элементов ответа должны иметь методы доступа для получения данных ответа удобным для пользователя и безопасным для типов способом. Внутренне классы управляющих элементов запроса/ответа обрабатывают кодирование и декодирование значений BER.

Например, предположим, что сервер LDAP поддерживает управляющий элемент запроса "подписанные результаты", который, когда отправляется с запросом, просит сервер цифрово подписать результаты операции. Он предоставит класс SignedResultsControl, чтобы приложения могли использовать эту функцию. Приложение будет использовать этот класс следующим образом:

Control[] reqCtls = new Control[] {new SignedResultsControl(Control.CRITICAL)};
ectx.setRequestControls(reqCtls);
NamingEnumeration enum = ectx.search(...);

Класс SignedResultsControl может быть определен следующим образом:

public class SignedResultsControl implements Control {
    // User-friendly constructor 
    public SignedResultsControl(boolean criticality) {
        // assemble the components of the request control
    };

    // Methods used by service providers
    public String getID() {
        return // control's object identifier
    }
    public byte[] getEncodedValue() {
        return // ASN.1 BER encoded control value
    }
    ...
}

Когда поставщик услуг получает управляющие элементы ответа, он использует класс ControlFactory для создания конкретных классов, которые реализуют интерфейс Control.

Сервер LDAP может отправлять управляющие элементы ответа с операцией LDAP, а также с результатами перечисления, такими как те, что возвращаются операцией списка или поиска. LdapContext предоставляет метод (getResponseControls()) для получения управляющих элементов ответа, отправленных с операцией LDAP, в то время как интерфейс HasControls используется для извлечения управляющих элементов ответа, связанных с результатами перечисления.

Например, предположим, что сервер LDAP отправляет управляющий элемент "идентификатор изменения" в ответ на успешное изменение. Он предоставит класс ChangeIDControl, чтобы приложение могло использовать эту функцию. Приложение выполнит обновление, а затем попытается получить идентификатор изменения.

// Perform update
Context ctx = ectx.createSubsubcontext("cn=newobj");

// Get response controls
Control[] respCtls = ectx.getResponseControls();
if (respCtls != null) {
    // Find the one we want
    for (int i = 0; i < respCtls; i++) {
        if(respCtls[i] instanceof ChangeIDControl) {
            ChangeIDControl cctl = (ChangeIDControl)respCtls[i];
            System.out.println(cctl.getChangeID());
        }
    }
}

Поставщик может предоставить следующие классы ChangeIDControl и VendorXControlFactory. VendorXControlFactory будет использоваться поставщиком услуг при получении управляющих элементов ответа от сервера LDAP.

public class ChangeIDControl implements Control {
    long id;

    // Constructor used by ControlFactory
    public ChangeIDControl(String OID, byte[] berVal) throws NamingException {
        // check validity of OID
        id = // extract change ID from berVal
    };

    // Type-safe and User-friendly method
    public long getChangeID() {
        return id;
    }

    // Low-level methods
    public String getID() {
        return CHANGEID_OID;
    }
    public byte[] getEncodedValue() {
        return // original berVal
    }
    ...
}
public class VendorXControlFactory extends ControlFactory {
    public VendorXControlFactory () {
    }

    public Control getControlInstance(Control orig) throws NamingException {
        if (isOneOfMyControls(orig.getID())) {
            ...

            // determine which of ours it is and call its constructor
            return (new ChangeIDControl(orig.getID(), orig.getEncodedValue()));
        }
        return null;  // not one of ours
    }
}

Спецификация пакета

Спецификация API JNDI и связанные документы находятся в документации JNDI.