Интерфейс LdapContext

Все суперинтерфейсы:: Контекст, DirContext

Все известные реализующие классы:: InitialLdapContext

public interface LdapContext
extends DirContext

Этот интерфейс представляет контекст, в котором можно выполнять операции с контролами LDAPv3 и расширенные операции LDAPv3. Для приложений, которым не требуются такие контролы или расширенные операции, следует использовать более универсальный javax.naming.directory.DirContext вместо этого.

Подробности использования контролей

Этот интерфейс обеспечивает поддержку контролей LDAP v3. На высоком уровне эта поддержка позволяет программе пользователя устанавливать контролы запроса для операций LDAP, выполняемых в ходе вызова программой пользователя методов Context/DirContext, и читать контролы ответа, полученные в результате операций LDAP. На уровне реализации есть некоторые детали, которые должны понимать разработчики как программы пользователя, так и поставщики услуг, чтобы правильно использовать контролы запроса и ответа.

Контролы запроса

Существует два типа контролей запроса:

Контролы запроса, влияющие на создание соединения
Контролы запроса, влияющие на методы контекста

Первый тип используется всякий раз, когда необходимо установить или повторно установить соединение с сервером LDAP. Второй тип используется при отправке всех остальных операций LDAP на сервер LDAP. Причина, по которой необходимо различать эти два типа контролей запроса, заключается в том, что JNDI — это API высокого уровня, который не работает напрямую с соединениями. За управление соединениями отвечают поставщики услуг. Следовательно, одно соединение может быть разделено между несколькими экземплярами контекста, и поставщик услуг свободен использовать свои собственные алгоритмы для сохранения соединения и использования сети. Таким образом, при вызове метода на экземпляре контекста поставщик услуг может потребоваться выполнить некоторое управление соединением в дополнение к выполнению соответствующих операций LDAP. Для управления соединением он использует контролы запроса соединения, а для обычных операций LDAP — контролы запроса контекста.

Если не указано иное, термин «контролы запроса» относится к контролям запроса контекста.

Контролы запроса контекста

Существует два способа, которыми экземпляр контекста получает свои контролы запроса:

ldapContext.newInstance(reqCtls)
ldapContext.setRequestControls(reqCtls)

где ldapContext является экземпляром LdapContext. Указание null или пустого массива для reqCtls означает отсутствие контролей запроса. newInstance() создаёт новый экземпляр контекста, используя reqCtls, в то время как setRequestControls() обновляет контролы запроса существующего экземпляра контекста до reqCtls.

В отличие от свойств среды, контролы запроса экземпляра контекста не наследуются экземплярами контекста, полученными из него. Полученные экземпляры контекста имеют null в качестве своих контролей запроса контекста. Вы должны явно задать контролы запроса полученного экземпляра контекста, используя setRequestControls().

Контролы запроса экземпляра контекста извлекаются с помощью метода getRequestControls().

Контролы запроса соединения

Существует три способа установки контролей запроса соединения:

new InitialLdapContext(env, connCtls)
refException.getReferralContext(env, connCtls)
ldapContext.reconnect(connCtls);

где refException является экземпляром LdapReferralException, а ldapContext — экземпляром LdapContext. Указание null или пустого массива для connCtls означает отсутствие контролей запроса соединения.

Как и свойства среды, контролы запроса соединения контекста наследуются контекстами, полученными из него. Как правило, вы инициализируете контролы запроса соединения, используя конструктор InitialLdapContext или LdapReferralContext.getReferralContext(). Эти контролы запроса соединения наследуются контекстами, которые используют то же самое соединение — то есть контекстами, полученными из исходного или контекста пересылки.

Используйте reconnect() для изменения контролей запроса соединения контекста. Вызов ldapContext.reconnect() влияет только на соединение, используемое ldapContext и любые новые экземпляры контекста, полученные из ldapContext. Контексты, которые ранее использовали соединение с ldapContext остаются неизменными. То есть контролы запроса соединения контекста должны быть изменены явно и не влияют на изменения контролей запроса соединения другого контекста.

Контролы запроса соединения экземпляра контекста извлекаются с помощью метода getConnectControls().

Требования к поставщику услуг

Поставщик услуг поддерживает контролы запроса соединения и контекста следующим образом. Контроли запроса контекста должны быть связаны на основе каждого экземпляра контекста, в то время как контролы запроса соединения должны быть связаны на основе каждого экземпляра соединения. Поставщик услуг должен искать контролы запроса соединения в свойстве среды «java.naming.ldap.control.connect» и передавать это свойство среды экземплярам контекста, которые он создаёт.

Контролы ответа

Метод LdapContext.getResponseControls() используется для получения контролей ответа, сгенерированных операциями LDAP, выполненными в результате вызова операции Context/DirContext. Результатом являются все контролы ответов, сгенерированные базовыми операциями LDAP, включая любое неявное повторное подключение. Чтобы получить только контролы ответа повторного подключения, используйте reconnect() и затем getResponseControls().

Параметры

Массив Control[] параметров, переданный в любой метод, принадлежит вызывающей стороне. Поставщик услуг не будет изменять массив или хранить ссылку на него, хотя он может хранить ссылки на отдельные объекты Control в массиве. Массив Control[] возвращаемый любым методом, является неизменяемым и не может быть изменён ни вызывающей стороной, ни поставщиком услуг.

С:: 1.3
См. также:: InitialLdapContext, LdapReferralException.getReferralContext(java.util.Hashtable,javax.naming.ldap.Control[])

Поля

Модификатор и тип	Поле и описание
`static String`	`CONTROL_FACTORIES` Константа, хранящая имя свойства среды для указания списка фабрик контролей для использования.

Поля, унаследованные от интерфейса javax.naming.directory.DirContext

ADD_ATTRIBUTE, REMOVE_ATTRIBUTE, REPLACE_ATTRIBUTE

Поля, унаследованные от интерфейса javax.naming.Контекст

APPLET, AUTHORITATIVE, BATCHSIZE, DNS_URL, INITIAL_CONTEXT_FACTORY, LANGUAGE, OBJECT_FACTORIES, PROVIDER_URL, REFERRAL, SECURITY_AUTHENTICATION, SECURITY_CREDENTIALS, SECURITY_PRINCIPAL, SECURITY_PROTOCOL, STATE_FACTORIES, URL_PKG_PREFIXES

Методы

Модификатор и тип	Метод и описание
`ExtendedResponse`	`extendedOperation(ExtendedRequest request)` Выполняет расширенную операцию.
`Control[]`	`getConnectControls()` Извлекает контролы запроса соединения, действующие для этого контекста.
`Control[]`	`getRequestControls()` Извлекает контролы запроса, действующие для этого контекста.
`Control[]`	`getResponseControls()` Извлекает контролы ответа, полученные в результате последнего вызова метода в этом контексте.
`LdapContext`	`newInstance(Control[] requestControls)` Создаёт новый экземпляр этого контекста, инициализированный с использованием контролей запроса.
`void`	`reconnect(Control[] connCtls)` Подключается к серверу LDAP повторно с использованием предоставленных контролей и среды этого контекста.
`void`	`setRequestControls(Control[] requestControls)` Устанавливает контролы запроса для методов, которые будут вызваны впоследствии в этом контексте.

Методы, унаследованные от интерфейса javax.naming.directory.DirContext

bind, bind, createSubcontext, createSubcontext, getAttributes, getAttributes, getAttributes, getAttributes, getSchema, getSchema, getSchemaClassDefinition, getSchemaClassDefinition, modifyAttributes, modifyAttributes, modifyAttributes, modifyAttributes, rebind, rebind, search, search, search, search, search, search, search, search

Методы, унаследованные от интерфейса javax.naming.Контекст

addToEnvironment, bind, bind, close, composeName, composeName, createSubcontext, createSubcontext, destroySubcontext, destroySubcontext, getEnvironment, getNameInNamespace, getNameParser, getNameParser, list, list, listBindings, listBindings, lookup, lookup, lookupLink, lookupLink, rebind, rebind, removeFromEnvironment, rename, rename, unbind, unbind

Поля

CONTROL_FACTORIES

static final String CONTROL_FACTORIES

Константа, хранящая имя свойства среды для указания списка фабрик управления, которые нужно использовать. Значение свойства должно быть списком, разделенным двоеточиями, полностью квалифицированных имен классов фабричных классов, которые создадут элемент управления, учитывая другой элемент управления. См. ControlFactory.getControlInstance() для получения дополнительной информации. Это свойство может быть указано в среде, параметре апплета, свойстве системы или в одном или нескольких файлах ресурсов.

Значение этой константы равно "java.naming.factory.control".

См. также:: ControlFactory, Context.addToEnvironment(java.lang.String, java.lang.Object), Context.removeFromEnvironment(java.lang.String), Значения постоянных полей

Методы

extendedOperation

ExtendedResponse extendedOperation(ExtendedRequest request)
                            throws NamingException

Выполняет расширенную операцию. Этот метод используется для поддержки расширенных операций LDAPv3.

Параметры:: request - Непустой запрос, который необходимо выполнить.
Возвращает:: Возможный ответ операции. null означает, что операция не сгенерировала никакого ответа.
Исключения:: NamingException - Если при выполнении расширенной операции произошла ошибка.

newInstance

LdapContext newInstance(Control[] requestControls)
                 throws NamingException

Создает новый экземпляр этого контекста, инициализированный с помощью управляющих элементов запроса. Этот метод является удобным методом для создания нового экземпляра этого контекста в целях многопотокового доступа. Например, если несколько потоков хотят использовать разные управляющие элементы запроса контекста, каждый поток может использовать этот метод для получения собственной копии этого контекста и установки/получения управляющих элементов запроса контекста без необходимости синхронизации с другими потоками.

Новый контекст имеет те же свойства среды и управляющие элементы запроса подключения, что и этот контекст. Подробности см. в описании класса. Реализации также могут разрешить этому контексту и новому контексту совместно использовать одно и то же сетевое подключение или другие ресурсы, если это не препятствует независимости ни одного из контекстов.

Параметры:: requestControls - Возможные управляющие элементы запроса для нового контекста. Если null, контекст инициализируется без управляющих элементов запроса.
Возвращает:: Непустой экземпляр LdapContext.
Исключения:: NamingException - Если при создании нового экземпляра произошла ошибка.
См. также:: InitialLdapContext

reconnect

void reconnect(Control[] connCtls)
        throws NamingException

Подключается к серверу LDAP с использованием предоставленных управляющих элементов и среды контекста.

Этот метод — способ явного запуска операции "bind" LDAP. Например, вы можете использовать этот метод для установки управляющих элементов запроса для операции LDAP "bind" или для явного подключения к серверу, чтобы получить управляющие элементы ответа, возвращаемые операцией LDAP "bind".

Этот метод устанавливает управляющие элементы запроса подключения этого контекста в качестве новых управляющих элементов запроса подключения. Управляющие элементы запроса контекста этого контекста не затрагиваются. После вызова этого метода любые последующие неявные повторные подключения будут выполняться с использованием connCtls. connCtls также используются в качестве управляющих элементов запроса подключения для новых экземпляров контекста, полученных из этого контекста. Эти управляющие элементы запроса подключения не затрагиваются setRequestControls().

Реализаторы поставщика услуг должны прочитать раздел "Поставщик услуг" в описании класса для получения подробностей о реализации.

Параметры:: connCtls - Возможные управляющие элементы. Если null, управляющие элементы не используются.
Исключения:: NamingException - Если при повторном подключении произошла ошибка.
См. также:: getConnectControls(), newInstance(javax.naming.ldap.Control[])

getConnectControls

Control[] getConnectControls()
                      throws NamingException

Возвращает управляющие элементы запроса подключения, действующие для этого контекста. Управляющие элементы принадлежат реализации JNDI и неизменяемы. Массив и управляющие элементы не могут быть изменены вызывающим объектом.

Возвращает:: Возможный массив управляющих элементов. null означает, что для этого контекста не было установлено управляющих элементов подключения.
Исключения:: NamingException - Если при получении управляющих элементов запроса произошла ошибка.

setRequestControls

void setRequestControls(Control[] requestControls)
                 throws NamingException

Устанавливает управляющие элементы запроса для методов, которые будут вызваны впоследствии на этом контексте. Управляющие элементы запроса принадлежат реализации JNDI и неизменяемы. Массив и управляющие элементы не могут быть изменены вызывающим объектом.

Это удаляет все предыдущие управляющие элементы запроса и добавляет requestControls для использования последующими методами, вызываемыми на этом контексте. Этот метод не влияет на управляющие элементы запроса подключения этого контекста.

Обратите внимание, что requestControls будет действовать до следующего вызова setRequestControls(). Вам необходимо явно вызвать setRequestControls() с null или пустым массивом, чтобы очистить управляющие элементы, если вы не хотите, чтобы они влияли на методы контекста больше. Чтобы проверить, какие управляющие элементы запроса действуют для этого контекста, используйте getRequestControls().

Параметры:: requestControls - Возможные управляющие элементы. Если null, управляющие элементы не используются.
Исключения:: NamingException - Если при установке управляющих элементов запроса произошла ошибка.
См. также:: getRequestControls()

getRequestControls

Control[] getRequestControls()
                      throws NamingException

Возвращает управляющие элементы запроса, действующие для этого контекста. Управляющие элементы запроса принадлежат реализации JNDI и неизменяемы. Массив и управляющие элементы не могут быть изменены вызывающим объектом.

Возвращает:: Возможный массив управляющих элементов. null означает, что для этого контекста не были установлены управляющие элементы запроса.
Исключения:: NamingException - Если при получении управляющих элементов запроса произошла ошибка.
См. также:: setRequestControls(javax.naming.ldap.Control[])

getResponseControls

Control[] getResponseControls()
                       throws NamingException

Возвращает управляющие элементы ответа, полученные в результате последнего метода, вызванного на этом контексте. Управляющие элементы ответа принадлежат реализации JNDI и неизменяемы. Массив и управляющие элементы не могут быть изменены вызывающим объектом.

Эти управляющие элементы ответа могут быть сгенерированы успешной или неудачной операцией.

Когда вызывается метод контекста, который может возвращать управляющие элементы ответа, управляющие элементы ответа от предыдущего вызова метода очищаются. getResponseControls() возвращает все управляющие элементы ответа, сгенерированные операциями LDAP, используемыми методом контекста в порядке, полученном от сервера LDAP. Вызов getResponseControls() не очищает управляющие элементы ответа. Вы можете вызывать его многократно (и получать те же управляющие элементы) до тех пор, пока не будет вызван следующий метод контекста, который может возвращать управляющие элементы.

Возвращает:: Возможный массив управляющих элементов. Если null, предыдущий вызов метода на этом контексте не сгенерировал никаких управляющих элементов.
Исключения:: NamingException - Если при получении управляющих элементов ответа произошла ошибка.

© 1993, 2020, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.