Интерфейс LdapContext

public interface LdapContext extends DirContext

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

Сведения об использовании элементов управления

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

Элементы управления запросов

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

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

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

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

Элементы управления запросов контекста

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

1. ldapContext.newInstance(reqCtls)
2. ldapContext.setRequestControls(reqCtls)

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

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

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

Элементы управления запросов подключения

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

1. new InitialLdapContext(env, connCtls)
2. refException.getReferralContext(env, connCtls)
3. 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[], возвращаемый любым методом, является неизменяемым и не может быть изменен впоследствии ни вызывающим кодом, ни поставщиком службы.