Интерфейс 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`	Константа, содержащая имя свойства среды, задающего список используемых фабрик элементов управления.

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

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

Модификатор и тип	Поле	Описание
`static final String`	`AUTHORITATIVE`	Константа, содержащая имя свойства среды, задающего степень достоверности запрошенной службы.
`static final String`	`BATCHSIZE`	Константа, содержащая имя свойства среды, задающего размер пакета для возврата данных через протокол службы.
`static final String`	`DNS_URL`	Константа, содержащая имя свойства среды, задающего имена узла DNS и домена для контекста URL JNDI (например, "dns://somehost/wiz.com").
`static final String`	`INITIAL_CONTEXT_FACTORY`	Константа, содержащая имя свойства среды, задающего используемую фабрику начального контекста.
`static final String`	`LANGUAGE`	Константа, содержащая имя свойства среды, задающего предпочтительный язык для использования со службой.
`static final String`	`OBJECT_FACTORIES`	Константа, содержащая имя свойства среды, задающего список используемых фабрик объектов.
`static final String`	`PROVIDER_URL`	Константа, содержащая имя свойства среды, задающего сведения о конфигурации для поставщика службы.
`static final String`	`REFERRAL`	Константа, содержащая имя свойства среды, задающего способ обработки перенаправлений, обнаруженных поставщиком службы.
`static final String`	`SECURITY_AUTHENTICATION`	Константа, содержащая имя свойства среды, задающего используемый уровень безопасности.
`static final String`	`SECURITY_CREDENTIALS`	Константа, содержащая имя свойства среды, задающего учетные данные субъекта для аутентификации вызывающего объекта в службе.
`static final String`	`SECURITY_PRINCIPAL`	Константа, содержащая имя свойства среды, задающего идентификатор субъекта для аутентификации вызывающего объекта в службе.
`static final String`	`SECURITY_PROTOCOL`	Константа, содержащая имя свойства среды, задающего используемый протокол безопасности.
`static final String`	`STATE_FACTORIES`	Константа, содержащая имя свойства среды, задающего список используемых фабрик состояний.
`static final String`	`URL_PKG_PREFIXES`	Константа, содержащая имя свойства среды, задающего список префиксов пакетов, используемых при загрузке фабрик контекстов URL.

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

ADD_ATTRIBUTE, REMOVE_ATTRIBUTE, REPLACE_ATTRIBUTE

Модификатор и тип	Поле	Описание
`static final int`	`ADD_ATTRIBUTE`	Эта константа указывает добавить атрибут с заданными значениями.
`static final int`	`REMOVE_ATTRIBUTE`	Эта константа указывает удалить из атрибута заданные значения.
`static final int`	`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)`	Задает элементы управления запросами для последующих вызовов методов этого контекста.

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

Модификатор и тип	Метод	Описание
`Object`	`addToEnvironment(String propName, Object propVal)`	Добавляет новое свойство среды в среду этого контекста.
`void`	`bind(String name, Object obj)`	Связывает имя с объектом.
`void`	`bind(Name name, Object obj)`	Связывает имя с объектом.
`void`	`close()`	Закрывает этот контекст.
`String`	`composeName(String name, String prefix)`	Составляет имя этого контекста с именем, относительным к этому контексту.
`Name`	`composeName(Name name, Name prefix)`	Составляет имя этого контекста с именем, относительным к этому контексту.
`Context`	`createSubcontext(String name)`	Создает и связывает новый контекст.
`Context`	`createSubcontext(Name name)`	Создает и связывает новый контекст.
`void`	`destroySubcontext(String name)`	Уничтожает именованный контекст и удаляет его из пространства имен.
`void`	`destroySubcontext(Name name)`	Уничтожает именованный контекст и удаляет его из пространства имен.
`Hashtable<?,?>`	`getEnvironment()`	Получает среду, действующую для этого контекста.
`String`	`getNameInNamespace()`	Получает полное имя этого контекста в его собственном пространстве имен.
`NameParser`	`getNameParser(String name)`	Получает анализатор, связанный с именованным контекстом.
`NameParser`	`getNameParser(Name name)`	Получает анализатор, связанный с именованным контекстом.
`NamingEnumeration<NameClassPair>`	`list(String name)`	Перечисляет имена, связанные с объектами в именованном контексте, вместе с именами классов связанных с ними объектов.
`NamingEnumeration<NameClassPair>`	`list(Name name)`	Перечисляет имена, связанные с объектами в именованном контексте, вместе с именами классов связанных с ними объектов.
`NamingEnumeration<Binding>`	`listBindings(String name)`	Перечисляет имена, связанные с объектами в именованном контексте, вместе со связанными с ними объектами.
`NamingEnumeration<Binding>`	`listBindings(Name name)`	Перечисляет имена, связанные с объектами в именованном контексте, вместе со связанными с ними объектами.
`Object`	`lookup(String name)`	Получает именованный объект.
`Object`	`lookup(Name name)`	Получает именованный объект.
`Object`	`lookupLink(String name)`	Получает именованный объект, следуя по ссылкам, кроме конечного атомарного компонента имени.
`Object`	`lookupLink(Name name)`	Получает именованный объект, следуя по ссылкам, кроме конечного атомарного компонента имени.
`void`	`rebind(String name, Object obj)`	Связывает имя с объектом, заменяя существующую привязку.
`void`	`rebind(Name name, Object obj)`	Связывает имя с объектом, заменяя существующую привязку.
`Object`	`removeFromEnvironment(String propName)`	Удаляет свойство среды из среды этого контекста.
`void`	`rename(String oldName, String newName)`	Связывает новое имя с объектом, связанным со старым именем, и отменяет привязку старого имени.
`void`	`rename(Name oldName, Name newName)`	Связывает новое имя с объектом, связанным со старым именем, и отменяет привязку старого имени.
`void`	`unbind(String name)`	Отменяет привязку именованного объекта.
`void`	`unbind(Name name)`	Отменяет привязку именованного объекта.

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

Модификатор и тип	Метод	Описание
`void`	`bind(String name, Object obj, Attributes attrs)`	Связывает имя с объектом и связанными с ним атрибутами.
`void`	`bind(Name name, Object obj, Attributes attrs)`	Связывает имя с объектом и связанными с ним атрибутами.
`DirContext`	`createSubcontext(String name, Attributes attrs)`	Создает и связывает новый контекст вместе со связанными атрибутами.
`DirContext`	`createSubcontext(Name name, Attributes attrs)`	Создает и связывает новый контекст вместе со связанными атрибутами.
`Attributes`	`getAttributes(String name)`	Получает все атрибуты, связанные с именованным объектом.
`Attributes`	`getAttributes(String name, String[] attrIds)`	Получает выбранные атрибуты, связанные с именованным объектом.
`Attributes`	`getAttributes(Name name)`	Получает все атрибуты, связанные с именованным объектом.
`Attributes`	`getAttributes(Name name, String[] attrIds)`	Получает выбранные атрибуты, связанные с именованным объектом.
`DirContext`	`getSchema(String name)`	Получает схему, связанную с именованным объектом.
`DirContext`	`getSchema(Name name)`	Получает схему, связанную с именованным объектом.
`DirContext`	`getSchemaClassDefinition(String name)`	Получает контекст, содержащий объекты схемы для определений классов именованного объекта.
`DirContext`	`getSchemaClassDefinition(Name name)`	Получает контекст, содержащий объекты схемы для определений классов именованного объекта.
`void`	`modifyAttributes(String name, int mod_op, Attributes attrs)`	Изменяет атрибуты, связанные с именованным объектом.
`void`	`modifyAttributes(String name, ModificationItem[] mods)`	Изменяет атрибуты, связанные с именованным объектом, используя упорядоченный список изменений.
`void`	`modifyAttributes(Name name, int mod_op, Attributes attrs)`	Изменяет атрибуты, связанные с именованным объектом.
`void`	`modifyAttributes(Name name, ModificationItem[] mods)`	Изменяет атрибуты, связанные с именованным объектом, используя упорядоченный список изменений.
`void`	`rebind(String name, Object obj, Attributes attrs)`	Связывает имя с объектом и связанными атрибутами, заменяя существующую привязку.
`void`	`rebind(Name name, Object obj, Attributes attrs)`	Связывает имя с объектом и связанными атрибутами, заменяя существующую привязку.
`NamingEnumeration<SearchResult>`	`search(String name, String filterExpr, Object[] filterArgs, SearchControls cons)`	Выполняет поиск в именованном контексте или объекте записей, соответствующих заданному фильтру поиска.
`NamingEnumeration<SearchResult>`	`search(String name, String filter, SearchControls cons)`	Выполняет поиск в именованном контексте или объекте записей, соответствующих заданному фильтру поиска.
`NamingEnumeration<SearchResult>`	`search(String name, Attributes matchingAttributes)`	Выполняет поиск в одном контексте объектов, содержащих заданный набор атрибутов.
`NamingEnumeration<SearchResult>`	`search(String name, Attributes matchingAttributes, String[] attributesToReturn)`	Выполняет поиск в одном контексте объектов, содержащих заданный набор атрибутов, и получает выбранные атрибуты.
`NamingEnumeration<SearchResult>`	`search(Name name, String filterExpr, Object[] filterArgs, SearchControls cons)`	Выполняет поиск в именованном контексте или объекте записей, соответствующих заданному фильтру поиска.
`NamingEnumeration<SearchResult>`	`search(Name name, String filter, SearchControls cons)`	Выполняет поиск в именованном контексте или объекте записей, соответствующих заданному фильтру поиска.
`NamingEnumeration<SearchResult>`	`search(Name name, Attributes matchingAttributes)`	Выполняет поиск в одном контексте объектов, содержащих заданный набор атрибутов.
`NamingEnumeration<SearchResult>`	`search(Name name, Attributes matchingAttributes, String[] attributesToReturn)`	Выполняет поиск в одном контексте объектов, содержащих заданный набор атрибутов, и получает выбранные атрибуты.

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

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, используя переданные управляющие элементы и среду этого контекста.

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

Этот метод задаёт connCtls этого контекста в качестве новых управляющих элементов запроса подключения. Управляющие элементы запроса контекста не изменяются. После вызова этого метода все последующие неявные повторные подключения будут выполняться с использованием 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, 2025, 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.