Пакет 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
    }
}