Пакет 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-сервер отправляет элемент управления «идентификатор изменения» в ответ на успешную модификацию. Для использования этой функции он предоставит класс 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.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
    }
}

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