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