Пакет javax.naming.ldap

Этот пакет расширяет операции каталога 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;
    }
}

Контроли

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

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

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

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-сервер отправляет контроль «ID изменения» в ответ на успешное изменение. Он предоставит класс ChangeIDControl, чтобы приложение могло использовать эту функцию. Приложение выполнит обновление, а затем попытается получить ID изменения.

// 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.length; i++) {
        if(respCtls[i] instanceof ChangeIDControl) {
     ChangeIDControl cctl = (ChangeIDControl)respCtls[i];
     System.out.println(cctl.getChangeID());
        }
    }
}

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
    }
}

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