Интерфейс DirContext

Все суперинтерфейсы:: Context

Все известные дочерние интерфейсы:: EventDirContext, LdapContext

Все известные реализующие классы:: InitialDirContext, InitialLdapContext

public interface DirContext extends Context

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

Имена

Каждое имя, переданное в качестве аргумента методу DirContext, является относительным по отношению к данному контексту. Пустое имя используется для именования самого контекста. Параметр имени никогда не должен быть null.

Большинство методов имеют перегруженные версии, одна из которых принимает параметр Name, а другая — String. Эти перегруженные версии эквивалентны в том смысле, что если параметры Name и String представляют собой просто различные представления одного и того же имени, то перегруженные версии одних и тех же методов ведут себя одинаково. В описаниях методов ниже документирована только одна версия. Вторая версия вместо этого содержит ссылку на первую: та же документация применяется к обеим.

См. Context для обсуждения интерпретации аргумента имени для методов Context. Те же правила применяются к аргументу имени методов DirContext.

Модели атрибутов

Существует две основные модели того, какие атрибуты должны быть связаны с объектом. Во-первых, атрибуты могут быть непосредственно связаны с объектом DirContext. В этой модели операция с атрибутом на именованном объекте примерно эквивалентна поиску по имени (который возвращает объект DirContext), за которым следует операция с атрибутом, вызываемая на объекте DirContext, при этом вызывающий код предоставляет пустое имя. Атрибуты можно рассматривать как хранящиеся вместе с объектом (обратите внимание, что это не подразумевает, что реализация должна это делать).

Вторая модель заключается в том, что атрибуты связаны с именем (обычно атомным именем) в DirContext. В этой модели операция с атрибутом на именованном объекте примерно эквивалентна поиску по имени родительского DirContext именованного объекта, за которым следует операция с атрибутом, вызываемая на родителе, при этом вызывающий код предоставляет конечное атомное имя. Атрибуты можно рассматривать как хранящиеся в родительском DirContext (опять же, это не подразумевает, что реализация должна это делать). Объекты, которые не являются DirContexts, могут иметь атрибуты, если их родительские объекты являются DirContexts.

JNDI поддерживает обе эти модели. Решение о том, где "хранить" атрибуты, принимают поставщики конкретных сервисов. Клиенты JNDI безопаснее, когда не предполагают, хранятся ли атрибуты объекта как часть самого объекта или в родительском объекте и ассоциированы с именем объекта.

Имена типов атрибутов

В методах getAttributes() и search() вы можете указать атрибуты для возврата, предоставив список имен атрибутов (строки). Возвращаемые атрибуты могут иметь не такие же имена, как указанные вами имена атрибутов. Это происходит потому, что некоторые каталоги поддерживают функции, которые заставляют их возвращать другие атрибуты. Такие функции включают подклассы атрибутов, синонимы имен атрибутов и языковые коды атрибутов.

При подклассировании атрибутов атрибуты определяются в иерархии классов. Например, в некоторых каталогах атрибут "name" может быть суперклассом всех атрибутов, связанных с именем, включая "commonName" и "surName". Запрос атрибута "name" может вернуть как атрибуты "commonName", так и "surName".

При синонимах типов атрибутов каталог может назначать несколько имен одному и тому же атрибуту. Например, "cn" и "commonName" могут оба ссылаться на один и тот же атрибут. Запрос "cn" может вернуть атрибут "commonName".

Некоторые каталоги поддерживают языковые коды для атрибутов. Запрос такого каталога для атрибута "description", например, может вернуть все следующие атрибуты:

description
description;lang-en
description;lang-de
description;lang-fr

Операционные атрибуты

Некоторые каталоги имеют понятие "операционных атрибутов", которые являются атрибутами, связанными с объектом каталога в административных целях. Примером операционных атрибутов является список управления доступом для объекта.

В методах getAttributes() и search() вы можете указать, что все атрибуты, связанные с запрошенными объектами, должны быть возвращены, указав null в качестве списка атрибутов для возврата. Возвращаемые атрибуты не включают операционные атрибуты. Для извлечения операционных атрибутов необходимо явно указать их имена.

Именованный контекст

В некоторых методах имя должно разрешаться в контекст (например, при поиске в контексте одного уровня). В документации таких методов используется термин именованный контекст для описания параметра имени. Для этих методов, если именованный объект не является DirContext, NotContextException будет брошен. Помимо этих методов, нет требования, чтобы именованный объект был DirContext.

Параметры

Объект типа Attributes, SearchControls или массив, переданный в качестве параметра любому методу, не будет изменён поставщиком сервиса. Поставщик сервиса может сохранить ссылку на него на всё время выполнения операции, включая любое перечисление результатов метода и обработку любых ссылок, сгенерированных в результате. Вызывающий код не должен изменять объект в течение этого времени. Объект типа Attributes, возвращённый любым методом, принадлежит вызывающей стороне. Вызывающий код может его затем изменить; поставщик сервиса этого делать не будет.

Исключения

Все методы этого интерфейса могут генерировать исключение NamingException или любой из его подклассов. См. NamingException и их подклассы для подробностей о каждом исключении.

С момента:

1.3

См. также:

Context

Краткое описание полей

Модификатор и тип	Поле	Описание
`static final int`	`ADD_ATTRIBUTE`	Эта константа указывает на добавление атрибута со значениями.
`static final int`	`REMOVE_ATTRIBUTE`	Эта константа указывает на удаление указанных значений атрибута из атрибута.
`static final int`	`REPLACE_ATTRIBUTE`	Эта константа указывает на замену атрибута указанными значениями.

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

APPLET, 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

Краткое описание методов

Модификатор и тип	Метод	Описание
`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)`	Ищет в отдельном контексте объекты, содержащие заданный набор атрибутов, и извлекает выбранные атрибуты.

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

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

ADD_ATTRIBUTE

static final int ADD_ATTRIBUTE

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

Если атрибут не существует, он создаётся. Результирующий атрибут будет содержать объединённое множество заданных значений и предыдущих значений. Добавление атрибута без значений вызовет InvalidAttributeValueException, если атрибут должен иметь хотя бы одно значение. Для атрибута с одним значением, если атрибут уже существует, выбросит AttributeInUseException. Если пытаться добавить более одного значения в атрибут с единственным значением, то выбросит InvalidAttributeValueException.

Значение этой константы равно 1.

См. также:

REPLACE_ATTRIBUTE

static final int REPLACE_ATTRIBUTE

Эта константа указывает на замену атрибута указанными значениями.

Если атрибут уже существует, все его существующие значения заменяются новыми. Если атрибут не существует, он создаётся. Если не указано ни одного значения, удаляются все значения атрибута. Удаление последнего значения удалит сам атрибут, если атрибут обязан иметь хотя бы одно значение. Если пытаться добавить более одного значения в атрибут с единственным значением, выбросит InvalidAttributeValueException.

Значение этой константы равно 2.

См. также:

REMOVE_ATTRIBUTE

static final int REMOVE_ATTRIBUTE

Эта константа указывает на удаление указанных значений атрибута из атрибута.

Результирующий атрибут будет содержать разность множества его предыдущих значений и множества указанных значений. Если не указано ни одного значения, удаляется весь атрибут. Если атрибут не существует, или некоторые или все члены указанного набора значений не существуют, это отсутствие может быть проигнорировано, и операция выполняется успешно, или может быть выброшено исключение NamingException, чтобы указать на отсутствие. Удаление последнего значения удалит сам атрибут, если атрибут обязан иметь хотя бы одно значение.

Значение этой константы равно 3.

См. также:

Подробное описание методов

getAttributes

Attributes getAttributes(Name name) throws NamingException

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

Параметры:

name - имя объекта, из которого нужно получить атрибуты

Возвращает:

множество атрибутов, связанных с name. Возвращает пустое множество атрибутов, если у имени нет атрибутов; никогда не null.

Исключения:

NamingException - если возникает исключение при работе с именами

См. также:

getAttributes(String)
getAttributes(Name, String[])

getAttributes

Attributes getAttributes(String name) throws NamingException

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

Параметры:: name - имя объекта, из которого нужно получить атрибуты
Возвращает:: множество атрибутов, связанных с name
Исключения:: NamingException - если возникает исключение при работе с именами

getAttributes

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

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

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

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

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

Параметры:: name - имя объекта, из которого нужно получить атрибуты; attrIds - идентификаторы атрибутов для получения. null означает, что должны быть получены все атрибуты; пустой массив означает, что ни один не должен быть получен.
Возвращает:: запрошенные атрибуты; никогда не null
Исключения:: NamingException - если возникает исключение при работе с именами

getAttributes

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

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

Параметры:: name - Имя объекта, из которого нужно получить атрибуты; attrIds - идентификаторы атрибутов для получения. null означает, что должны быть получены все атрибуты; пустой массив означает, что ни один не должен быть получен.
Возвращает:: запрошенные атрибуты; никогда не null
Исключения:: NamingException - если возникает исключение при работе с именами

modifyAttributes

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

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

Параметры:

name - имя объекта, атрибуты которого будут обновлены

mod_op - операция модификации, одна из: ADD_ATTRIBUTE, REPLACE_ATTRIBUTE, REMOVE_ATTRIBUTE.

attrs - атрибуты, используемые для модификации; не может быть null

Исключения:

AttributeModificationException - если модификация не может быть успешно завершена

NamingException - если возникает исключение при работе с именами

См. также:

modifyAttributes(Name, ModificationItem[])

modifyAttributes

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

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

Параметры:: name - имя объекта, атрибуты которого будут обновлены; mod_op - операция модификации, одна из: ADD_ATTRIBUTE, REPLACE_ATTRIBUTE, REMOVE_ATTRIBUTE.; attrs - атрибуты, используемые для модификации; не может быть null
Исключения:: AttributeModificationException - если модификация не может быть успешно завершена; NamingException - если возникает исключение при работе с именами

modifyAttributes

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

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

Параметры:

name - имя объекта, атрибуты которого будут обновлены

mods - упорядоченная последовательность модификаций, которые должны быть выполнены; не может быть null

Исключения:

AttributeModificationException - если модификации не могут быть успешно завершены

NamingException - если возникает исключение при работе с именами

См. также:

modifyAttributes(Name, int, Attributes)
ModificationItem

modifyAttributes

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

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

Параметры:: name - имя объекта, атрибуты которого будут обновлены; mods - упорядоченная последовательность модификаций, которые должны быть выполнены; не может быть null
Исключения:: AttributeModificationException - если модификации не могут быть успешно завершены; NamingException - если возникает исключение при работе с именами

bind

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

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

Parameters:

name - имя для привязки; не может быть пустым

obj - объект для привязки; может быть null

attrs - атрибуты для связывания с привязкой

Throws:

NameAlreadyBoundException - если имя уже привязано

InvalidAttributesException - если некоторые «обязательные» атрибуты привязки не заданы

NamingException - если возникло исключение именования

See Also:

bind

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

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

Parameters:: name - имя для привязки; не может быть пустым; obj - объект для привязки; может быть null; attrs - атрибуты для связывания с привязкой
Throws:: NameAlreadyBoundException - если имя уже привязано; InvalidAttributesException - если некоторые «обязательные» атрибуты привязки не заданы; NamingException - если возникло исключение именования

rebind

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 игнорируются.

Parameters:

name - имя для привязки; не может быть пустым

obj - объект для привязки; может быть null

attrs - атрибуты для связывания с привязкой

Throws:

InvalidAttributesException - если некоторые «обязательные» атрибуты привязки не заданы

NamingException - если возникло исключение именования

See Also:

rebind

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

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

Parameters:: name - имя для привязки; не может быть пустым; obj - объект для привязки; может быть null; attrs - атрибуты для связывания с привязкой
Throws:: InvalidAttributesException - если некоторые «обязательные» атрибуты привязки не заданы; NamingException - если возникло исключение именования

createSubcontext

DirContext createSubcontext(Name name, Attributes attrs) throws NamingException

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

Parameters:

name - имя создаваемого контекста; не может быть пустым

attrs - атрибуты для связывания с вновь созданным контекстом

Returns:

новый созданный контекст

Throws:

NameAlreadyBoundException - если имя уже привязано

InvalidAttributesException - если attrs не содержит всех обязательных атрибутов, необходимых для создания

NamingException - если возникло исключение именования

See Also:

Context.createSubcontext(Name)

createSubcontext

DirContext createSubcontext(String name, Attributes attrs) throws NamingException

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

Parameters:: name - имя создаваемого контекста; не может быть пустым; attrs - атрибуты для связывания с вновь созданным контекстом
Returns:: новый созданный контекст
Throws:: NameAlreadyBoundException - если имя уже привязано; InvalidAttributesException - если attrs не содержит всех обязательных атрибутов, необходимых для создания; NamingException - если возникло исключение именования

getSchema

DirContext getSchema(Name name) throws NamingException

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

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

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

Parameters:: name - имя объекта, схему которого нужно получить
Returns:: схема, связанная с контекстом; никогда не null
Throws:: OperationNotSupportedException - если схема не поддерживается; NamingException - если возникло исключение именования

getSchema

DirContext getSchema(String name) throws NamingException

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

Parameters:: name - имя объекта, схему которого нужно получить
Returns:: схема, связанная с контекстом; никогда не null
Throws:: OperationNotSupportedException - если схема не поддерживается; NamingException - если возникло исключение именования

getSchemaClassDefinition

DirContext getSchemaClassDefinition(Name name) throws NamingException

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

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

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

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

Parameters:: name - имя объекта, определение класса которого нужно получить
Returns:: DirContext, содержащий определения классов именованного объекта; никогда не null
Throws:: OperationNotSupportedException - если схема не поддерживается; NamingException - если возникло исключение именования

getSchemaClassDefinition

DirContext getSchemaClassDefinition(String name) throws NamingException

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

Parameters:: name - имя объекта, определение класса которого нужно получить
Returns:: DirContext содержащий определения классов именованного объекта; никогда не null
Throws:: OperationNotSupportedException - если схема не поддерживается; NamingException - если возникло исключение именования

поиск

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

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

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

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

Параметры:

name - имя контекста для поиска

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

attributesToReturn - атрибуты для возврата. null означает, что должны быть возвращены все атрибуты; пустой массив означает, что ни один не должен быть возвращён.

Возвращает:

непустое перечисление объектов SearchResult. Каждый объект SearchResult содержит атрибуты, определённые attributesToReturn, и имя соответствующего объекта, обозначенного относительно контекста, названного name.

Выбрасывает:

NamingException - если возникает исключение именования

См. также:

SearchControls
SearchResult
search(Name, String, Object[], SearchControls)

поиск

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

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

Параметры:: name - имя контекста для поиска; matchingAttributes - атрибуты для поиска; attributesToReturn - атрибуты для возврата
Возвращает:: непустое перечисление объектов SearchResult
Выбрасывает:: NamingException - если возникает исключение именования

поиск

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

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

Параметры:

name - имя контекста для поиска

matchingAttributes - атрибуты для поиска

Возвращает:

перечисление объектов SearchResult

Выбрасывает:

NamingException - если возникает исключение именования

См. также:

search(Name, Attributes, String[])

поиск

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

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

Параметры:: name - имя контекста для поиска; matchingAttributes - атрибуты для поиска
Возвращает:: перечисление объектов SearchResult
Выбрасывает:: NamingException - если возникает исключение именования

поиск

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 указал, что атрибуты должны быть возвращены.

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

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

Параметры:

name - имя контекста или объекта для поиска

filter - выражение фильтра, используемое для поиска; не может быть null

cons - параметры поиска, определяющие поведение поиска. Если null, используются параметры поиска по умолчанию (эквивалентно (new SearchControls())).

Возвращает:

перечисление объектов SearchResult объектов, удовлетворяющих фильтру; никогда не null

Выбрасывает:

InvalidSearchFilterException - если заданный фильтр поиска не поддерживается или не понят подчинённым каталогом

InvalidSearchControlsException - если параметры поиска содержат некорректные настройки

NamingException - если возникает исключение именования

См. также:

search(Name, String, Object[], SearchControls)
SearchControls
SearchResult

search

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

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

Parameters:: name - имя контекста или объекта для поиска; filter - выражение фильтра для поиска; не может быть null; cons - параметры поиска, которые контролируют поиск. Если null, используются параметры по умолчанию (эквивалентно (new SearchControls())).
Returns:: перечисление SearchResult для объектов, удовлетворяющих фильтру.
Throws:: InvalidSearchFilterException - если указанный фильтр поиска не поддерживается или не понят подлежащим каталогом; InvalidSearchControlsException - если параметры поиска содержат недопустимые настройки; NamingException - если возникает исключение в именовании

search

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] должен использоваться на этом месте. Такие переменные могут использоваться везде, где встречается производство attr, value или matchingrule в грамматике фильтра RFC 2254, раздел 4. При подстановке строкового аргумента фильтра вместо переменной фильтр интерпретируется так, как если бы строка была указана вместо переменной, а любые символы со специальным значением в фильтрах (например, '*') были экранированы в соответствии с правилами RFC 2254.

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

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

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

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

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

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

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

Parameters:

name - имя контекста или объекта для поиска

filterExpr - выражение фильтра для поиска. Выражение может содержать переменные вида "{i}", где i — неотрицательное целое число. Не может быть null.

filterArgs - массив аргументов для подстановки переменных в filterExpr. Значение filterArgs[i] заменит каждое вхождение "{i}". Если null, эквивалентно пустому массиву.

cons - параметры поиска, которые контролируют поиск. Если null, используются параметры по умолчанию (эквивалентно (new SearchControls())).

Returns:

перечисление SearchResult объектов, удовлетворяющих фильтру; никогда не null

Throws:

ArrayIndexOutOfBoundsException - если filterExpr содержит выражения {i}, где i находится за пределами границ массива filterArgs

InvalidSearchControlsException - если cons содержит недопустимые настройки

InvalidSearchFilterException - если filterExpr с filterArgs представляет недопустимый фильтр поиска

NamingException - если возникает исключение в именовании

See Also:

search(Name, Attributes, String[])
MessageFormat

search

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

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

Parameters:: name - имя контекста или объекта для поиска; filterExpr - выражение фильтра для поиска. Выражение может содержать переменные вида "{i}", где i — неотрицательное целое число. Не может быть null.; filterArgs - массив аргументов для подстановки переменных в filterExpr. Значение filterArgs[i] заменит каждое вхождение "{i}". Если null, эквивалентно пустому массиву.; cons - параметры поиска, которые контролируют поиск. Если null, используются параметры по умолчанию (эквивалентно (new SearchControls())).
Returns:: перечисление SearchResult объектов, удовлетворяющих фильтру; никогда не null
Throws:: ArrayIndexOutOfBoundsException - если filterExpr содержит выражения {i}, где i находится за пределами границ массива filterArgs; InvalidSearchControlsException - если cons содержит недопустимые настройки; InvalidSearchFilterException - если filterExpr с filterArgs представляет недопустимый фильтр поиска; NamingException - если возникает исключение в именовании

© 1993, 2021, 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.
https://docs.oracle.com/en/java/javase/17/docs/api/java.naming/javax/naming/directory/DirContext.html