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