Интерфейс LdapContext

Все суперинтерфейсы:: Context, 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

См. также:

Краткое описание полей

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

Поля, объявленные в интерфейсе javax.naming.Context

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

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

ADD_ATTRIBUTE, REMOVE_ATTRIBUTE, REPLACE_ATTRIBUTE

Краткое описание методов

Модификатор и тип	Метод	Описание
`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.Context

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

Методы, объявленные в интерфейсе 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

Подробное описание полей

CONTROL_FACTORIES

static final String CONTROL_FACTORIES

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

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

См. также:

Подробное описание методов

extendedOperation

ExtendedResponse extendedOperation(ExtendedRequest request) throws NamingException

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

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

newInstance

LdapContext newInstance(Control[] requestControls) throws NamingException

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

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

Параметры:

requestControls - Возможно null управляющие элементы запроса для использования в новом контексте. Если null, контекст инициализируется без управляющих элементов запроса.

Возвращает:

Экземпляр LdapContext (не null).

Исключения:

NamingException - Если при создании нового экземпляра произошла ошибка.

См. также:

reconnect

void reconnect(Control[] connCtls) throws NamingException

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

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

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

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

Параметры:

connCtls - Возможно null управляющие элементы. Если null, управляющие элементы не используются.

Исключения:

NamingException - Если при повторном подключении произошла ошибка.

См. также:

getConnectControls

Control[] getConnectControls() throws NamingException

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

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

setRequestControls

void setRequestControls(Control[] requestControls) throws NamingException

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

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

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

Параметры:

requestControls - Возможно null управляющие элементы. Если null, управляющие элементы не используются.

Исключения:

NamingException - Если при установке управляющих элементов запроса произошла ошибка.

См. также:

getRequestControls

Control[] getRequestControls() throws NamingException

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

Возвращает:

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

Исключения:

NamingException - Если при получении управляющих элементов запроса произошла ошибка.

См. также:

getResponseControls

Control[] getResponseControls() throws NamingException

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

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

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

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

© 1993, 2023, 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.
https://docs.oracle.com/en/java/javase/21/docs/api/java.naming/javax/naming/ldap/LdapContext.html