Класс InitialDirContext

protected InitialDirContext(boolean lazy) throws NamingException

Создаёт начальный DirContext с опцией неинициализации. Это может использоваться конструктором подкласса, когда значение параметра окружения ещё не известно в момент вызова конструктора InitialDirContext. Конструктор подкласса вызовет этот конструктор, вычислит значение окружения и затем вызовет init(), прежде чем вернуть значение.

public InitialDirContext() throws NamingException

Создаёт начальный DirContext. Свойства окружения не передаются. Эквивалентно new InitialDirContext(null).

public InitialDirContext(Hashtable<?,?> environment) throws NamingException

Создаёт начальный DirContext, используя предоставленное окружение. Свойства окружения обсуждаются в описании класса javax.naming.InitialContext.

Если свойство java.naming.provider.url предоставленного окружения состоит из URL-адреса (или списка URL-адресов) с использованием протокола ldap, то результирующий LdapContext будет использовать сервер LDAP, разрешённый настроенным LdapDnsProviders:

1. Если это первый InitialDirContext созданный с java.naming.provider.url с использованием протокола ldap, то используется механизм ServiceLoader для поиска реализаций LdapDnsProvider с использованием системного загрузчика классов. Порядок расположения поставщиков определяется конкретной реализацией, и реализация свободна кэшировать распознанные поставщики.
2. Метод lookupEndpoints каждого поставщика, если он инициализирован, вызывается один раз с комбинацией каждого из URL-адресов в свойстве java.naming.provider.url и окружения, пока поставщик не вернёт непустое значение или не будут исчерпаны все поставщики. Если ни один из LdapDnsProviders не вернёт непустое значение result, то реализация предпримет все возможные усилия для определения конечной точки. Исключение ServiceConfigurationError, Error или RuntimeException при загрузке или вызове LdapDnsProvider, если оно возникнет, будет передано вызывающей потоку.

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

public Attributes getAttributes(String name) throws NamingException

Извлекает все атрибуты, связанные с именованным объектом. Подробности см. в DirContext.getAttributes(Name).

public Attributes getAttributes(String name, String[] attrIds) throws NamingException

Извлекает выбранные атрибуты, связанные с именованным объектом. Подробности см. в DirContext.getAttributes(Name, String[]).

public Attributes getAttributes(Name name) throws NamingException

Извлекает все атрибуты, связанные с именованным объектом. См. описание класса относительно моделей атрибутов, имён типов атрибутов и операционных атрибутов.

public Attributes getAttributes(Name name, String[] attrIds) throws NamingException

Извлекает выбранные атрибуты, связанные с именованным объектом. См. описание класса относительно моделей атрибутов, имён типов атрибутов и операционных атрибутов.

Если у объекта отсутствует указанный атрибут, то каталог проигнорирует несуществующий атрибут и вернёт запрошенные атрибуты, которые у объекта есть.

Каталог может вернуть больше атрибутов, чем было запрошено (см. Имена типов атрибутов в описании класса), но не имеет права возвращать произвольные, не связанные атрибуты.

См. также Операционные атрибуты в описании класса.

public void modifyAttributes(String name, int mod_op, Attributes attrs) throws NamingException

Изменяет атрибуты, связанные с именованным объектом. Подробности см. в DirContext.modifyAttributes(Name, int, Attributes).

public void modifyAttributes(Name name, int mod_op, Attributes attrs) throws NamingException

Изменяет атрибуты, связанные с именованным объектом. Порядок модификаций не определён. По возможности, модификации выполняются атомарно.

public void modifyAttributes(String name, ModificationItem[] mods) throws NamingException

Изменяет атрибуты, связанные с объектом с заданным именем, используя упорядоченный список изменений. Подробнее см. DirContext.modifyAttributes(Name, ModificationItem[]).

public void modifyAttributes(Name name, ModificationItem[] mods) throws NamingException

Изменяет атрибуты, связанные с объектом с заданным именем, используя упорядоченный список изменений. Изменения выполняются в указанном порядке. Каждое изменение указывает код операции изменения и атрибут, над которым нужно выполнить операцию. По возможности, изменения выполняются атомарно.

public void bind(String name, Object obj, Attributes attrs) throws NamingException

Связывает имя с объектом вместе с ассоциированными атрибутами. Подробнее см. DirContext.bind(Name, Object, Attributes).

public void bind(Name name, Object obj, Attributes attrs) throws NamingException

Связывает имя с объектом вместе с ассоциированными атрибутами. Если attrs равно null, результирующее связывание будет содержать атрибуты, связанные с obj, если obj является DirContext, и никаких атрибутов в противном случае. Если attrs не null, результирующее связывание будет иметь attrs в качестве своих атрибутов; любые атрибуты, связанные с obj, игнорируются.

public void rebind(String name, Object obj, Attributes attrs) throws NamingException

Связывает имя с объектом вместе с ассоциированными атрибутами, перезаписывая любое существующее связывание. Подробнее см. DirContext.rebind(Name, Object, Attributes).

public void rebind(Name name, Object obj, Attributes attrs) throws NamingException

Связывает имя с объектом вместе с ассоциированными атрибутами, перезаписывая любое существующее связывание. Если attrs равно null и obj является DirContext, используются атрибуты из obj. Если attrs равно null и obj не является DirContext, любые существующие атрибуты, связанные с уже связанным объектом в каталоге, остаются неизменными. Если attrs не null, любые существующие атрибуты, связанные с уже связанным объектом в каталоге, удаляются, и attrs связывается с именованным объектом. Если obj является DirContext и attrs не null, атрибуты obj игнорируются.

public DirContext createSubcontext(String name, Attributes attrs) throws NamingException

Создает и связывает новый контекст вместе с ассоциированными атрибутами. Подробнее см. DirContext.createSubcontext(Name, Attributes).

public DirContext createSubcontext(Name name, Attributes attrs) throws NamingException

Создает и связывает новый контекст вместе с ассоциированными атрибутами. Этот метод создает новый подконтекст с заданным именем, связывает его в целевом контексте (названном всеми, кроме конечного атомарного компонента имени) и связывает предоставленные атрибуты с вновь созданным объектом. Все промежуточные и целевые контексты должны уже существовать. Если attrs равно null, этот метод эквивалентен Context.createSubcontext().

public DirContext getSchema(String name) throws NamingException

Получает схему, связанную с объектом по имени. Подробности см. в DirContext.getSchema(Name).

public DirContext getSchema(Name name) throws NamingException

Получает схему, связанную с объектом по имени. Схема описывает правила, касающиеся структуры пространства имён и атрибутов, хранящихся в нём. Схема определяет типы объектов, которые могут быть добавлены в каталог и где они могут быть добавлены; какие обязательные и необязательные атрибуты может иметь объект. Диапазон поддержки схем зависит от каталога.

Этот метод возвращает корень дерева информации схемы, применимой к объекту по имени. Несколько объектов с именами (или даже весь каталог) могут использовать одну и ту же схему.

Такие вопросы, как структура и содержимое дерева схемы, разрешение на изменение содержимого дерева схемы и влияние таких изменений на каталог зависят от базового каталога.

public DirContext getSchemaClassDefinition(String name) throws NamingException

Получает контекст, содержащий объекты схемы определений классов указанного объекта по имени. Подробности см. в DirContext.getSchemaClassDefinition(Name).

public DirContext getSchemaClassDefinition(Name name) throws NamingException

Получает контекст, содержащий объекты схемы определений классов указанного объекта по имени.

Одна категория информации в схемах каталога — определения классов. Определение "класса объекта" указывает тип объекта и какие атрибуты (обязательные и необязательные) объект должен/может иметь. Обратите внимание, что термин "класс объекта", к которому здесь относится, относится к каталогу, а не к Java. Например, если объект по имени — объект каталога класса "Человек", getSchemaClassDefinition() вернёт DirContext, представляющий определение класса объекта "Человек" (каталога).

Информация, которая может быть получена из определения класса объекта, зависит от каталога.

До JNDI 1.2 этот метод возвращал один объект схемы, представляющий определение класса указанного объекта. С JNDI 1.2 этот метод возвращает DirContext, содержащий все определения классов указанного объекта.

public NamingEnumeration<SearchResult> search(String name, Attributes matchingAttributes) throws NamingException

Поиск в одном контексте объектов, содержащих заданный набор атрибутов. Подробности см. в DirContext.search(Name, Attributes).

public NamingEnumeration<SearchResult> search(Name name, Attributes matchingAttributes) throws NamingException

Поиск в одном контексте объектов, содержащих заданный набор атрибутов. Этот метод возвращает все атрибуты таких объектов. Эквивалентно передаче null в качестве параметра attributesToReturn методу search(Name, Attributes, String[]).
Подробное описание см. в DirContext.search(Name, Attributes, String[]).

public NamingEnumeration<SearchResult> search(String name, Attributes matchingAttributes, String[] attributesToReturn) throws NamingException

Поиск в одном контексте объектов, содержащих заданный набор атрибутов, и извлечение выбранных атрибутов. Подробности см. в DirContext.search(Name, Attributes, String[]).

public NamingEnumeration<SearchResult> search(Name name, Attributes matchingAttributes, String[] attributesToReturn) throws NamingException

Ищет в одном контексте объекты, содержащие указанный набор атрибутов, и извлекает выбранные атрибуты. Поиск выполняется с использованием стандартных SearchControls настроек.

Для выбора объекта каждый атрибут в matchingAttributes должен соответствовать какому-либо атрибуту объекта. Если matchingAttributes пусто или null, возвращаются все объекты в целевом контексте.

Атрибут A₁ в matchingAttributes считается соответствующим атрибуту A₂ объекта, если A₁ и A₂ имеют один и тот же идентификатор, и каждое значение A₁ равно некоторому значению A₂. Это подразумевает, что порядок значений не имеет значения, и что A₂ может содержать «лишние» значения, отсутствующие в A₁, не влияя на сравнение. Это также подразумевает, что если A₁ не имеет значений, то проверка соответствия эквивалентна проверке наличия атрибута A₂ с тем же идентификатором.

Точное определение «равенства», используемое при сравнении значений атрибутов, определяется службой каталогов. Она может использовать метод Object.equals, например, или может использовать схему для определения другой операции равенства. Для сопоставления на основе операций, отличных от равенства (например, сравнения подстрок), используйте версию метода search, принимающую аргумент фильтра.

Когда изменения вносятся в эту DirContext, влияние на перечисления, возвращаемые предыдущими вызовами этого метода, не определено.

Если объект не имеет указанного атрибута, каталог проигнорирует несуществующий атрибут и вернёт запрошенные атрибуты, которые у объекта есть.

Каталог может вернуть больше атрибутов, чем было запрошено (см. Имена типов атрибутов в описании класса), но не имеет права возвращать произвольные, не связанные атрибуты.

См. также Операционные атрибуты в описании класса.

public NamingEnumeration<SearchResult> search(String name, String filter, SearchControls cons) throws NamingException

Ищет в заданном контексте или объекте записи, удовлетворяющие заданному фильтру поиска. Выполняет поиск в соответствии с указанными настройками поиска. Подробнее см. DirContext.search(Name, String, SearchControls).

public NamingEnumeration<SearchResult> search(Name name, String filter, SearchControls cons) throws NamingException

Ищет в заданном контексте или объекте записи, удовлетворяющие заданному фильтру поиска. Выполняет поиск в соответствии с указанными настройками поиска.

Формат и интерпретация filter соответствует RFC 2254 с последующими интерпретациями attr и value, упомянутыми в RFC.

attr — идентификатор атрибута.

value — строковое представление значения атрибута. Перевод этого строкового представления в значение атрибута зависит от каталога.

Например, для утверждения «someCount=127», attr — «someCount», а value — «127». Поставщик, на основе идентификатора атрибута («someCount») (и, возможно, его схемы), определяет, что значение атрибута — целое число. Затем он правильно анализирует строку «127».

Любые символы, не входящие в ASCII, в строке фильтра должны быть представлены соответствующими символами Java (Unicode), а не кодироваться как UTF-8 октеты. В качестве альтернативы может использоваться обозначение «обратная косая черта-шестнадцатеричный код», описанное в RFC 2254.

Если каталог не поддерживает строковое представление некоторых или всех своих атрибутов, можно использовать форму search, которая принимает аргументы фильтра в виде объектов. Поставщик сервиса такого каталога затем преобразует аргументы фильтра в его собственную специфическую форму для оценки фильтра. См. search(Name, String, Object[], SearchControls).

RFC 2254 определяет определённые операторы для фильтра, включая соответствие подстрокам, равенство, приблизительное соответствие, больше, меньше. Эти операторы сопоставляются с операторами с соответствующей семантикой в базовом каталоге. Например, для оператора равенства, предположим, что каталог имеет правило соответствия, определяющее «равенство» атрибутов в фильтре. Это правило будет использоваться для проверки равенства атрибутов, указанных в фильтре, с атрибутами объектов в каталоге. Аналогично, если каталог имеет правило соответствия для упорядочения, это правило будет использоваться для проведения сравнений «больше» и «меньше».

Не все операторы, определённые в RFC 2254, применимы ко всем атрибутам. Когда оператор неприменим, выбрасывается исключение InvalidSearchFilterException.

Результат возвращается в перечислении объектов SearchResult. Каждый объект SearchResult содержит имя объекта и другую информацию об объекте (см. SearchResult). Имя является либо относительным к целевому контексту поиска (который назван параметром name), либо строкой URL. Если целевой контекст включён в перечисление (что возможно, когда cons задаёт область поиска SearchControls.OBJECT_SCOPE или SearchControls.SUBSTREE_SCOPE), его имя — пустая строка. SearchResult также может содержать атрибуты соответствующего объекта, если аргумент cons указал на то, что атрибуты должны быть возвращены.

Если у объекта нет запрашиваемого атрибута, этот несуществующий атрибут будет проигнорирован. Запрошенные атрибуты, которые у объекта есть, будут возвращены.

Каталог может вернуть больше атрибутов, чем было запрошено (см. Имена типов атрибутов в описании класса), но не имеет права возвращать произвольные, не связанные атрибуты.

См. также Операционные атрибуты в описании класса.

public NamingEnumeration<SearchResult> search(String name, String filterExpr, Object[] filterArgs, SearchControls cons) throws NamingException

Ищет в заданном контексте или объекте записи, удовлетворяющие заданному фильтру поиска. Выполняет поиск в соответствии с настройками поиска. Подробности см. в DirContext.search(Name, String, Object[], SearchControls).

public NamingEnumeration<SearchResult> search(Name name, String filterExpr, Object[] filterArgs, SearchControls cons) throws NamingException

Ищет в заданном контексте или объекте записи, удовлетворяющие заданному фильтру поиска. Выполняет поиск в соответствии с настройками поиска.

Интерпретация filterExpr основана на RFC 2254. Она может дополнительно содержать переменные вида {i} — где i — целое число — которые ссылаются на объекты в массиве filterArgs. Интерпретация filterExpr в остальном идентична параметру filter метода search(Name, String, SearchControls).

Когда переменная {i} появляется в фильтре поиска, она указывает на использование аргумента фильтра filterArgs[i] в этом месте. Такие переменные могут использоваться повсюду, где в грамматике фильтра RFC 2254, раздел 4, появляется производство attr, value или matchingrule. При подстановке строкового аргумента фильтра в переменную, фильтр интерпретируется так, как если бы строка была указана вместо переменной, и любые символы, имеющие специальное значение в фильтрах (такие как '*'), были экранированы в соответствии с правилами RFC 2254.

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

Этот метод возвращает перечисление результатов. Каждый элемент в перечислении содержит имя объекта и другую информацию об объекте (см. SearchResult). Имя является либо относительным к целевому контексту поиска (названному параметром name), либо это строка URL. Если целевой контекст включён в перечисление (что возможно, когда cons задаёт область поиска SearchControls.OBJECT_SCOPE или SearchControls.SUBSTREE_SCOPE), его имя — пустая строка.

SearchResult также может содержать атрибуты соответствующего объекта, если аргумент cons указывает на возврат атрибутов.

Если у объекта отсутствует запрашиваемый атрибут, этот несуществующий атрибут будет проигнорирован. Запрашиваемые атрибуты, которые есть у объекта, будут возвращены.

Каталог может вернуть больше атрибутов, чем было запрошено (см. Имена типов атрибутов в описании класса), но не разрешается возвращать произвольные, не связанные атрибуты.

Если этому методу предоставляется фильтр поиска с недопустимыми подстановками переменных, результат неопределён. При внесении изменений в этот DirContext, влияние на перечисления, возвращённые предыдущими вызовами этого метода, неопределённо.

См. также Операционные атрибуты в описании класса.