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