Пакет javax.naming.ldap

Предоставляет поддержку расширенных операций и контролей LDAPv3.

Этот пакет расширяет операции каталога в Java Naming and Directory Interface^TM (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
    }
}