Интерфейс 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 (снова, это не подразумевает, что реализация должна это делать). Объекты, которые не являются DirContext, могут иметь атрибуты, при условии, что их родителями являются DirContext.

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

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

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

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

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

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

описание
описание;lang-en
описание;lang-de
описание;lang-fr

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

В некоторых каталогах существуют «операционные атрибуты», которые представляют собой атрибуты, связанные с объектом каталога для административных целей. Примером операционных атрибутов является список управления доступом для объекта.

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

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

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

Параметры

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

Исключения

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

С момента:

1.3

См. также:

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

Modifier and Type	Field	Description
`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

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

Modifier and Type	Method	Description
`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

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

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

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:

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 - если возникло исключение именования

См. также:

поиск

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 - если возникло исключение именования

См. также:

поиск

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

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

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

Параметры:: name - имя контекста или объекта для поиска; filter - выражение фильтра для поиска; не может быть null; cons - параметры управления поиском. Если null, используются стандартные параметры поиска (эквивалентно (new SearchControls())).
Возвращает:: перечисление SearchResult для объектов, удовлетворяющих фильтру.
Исключения:: 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] должен быть использован на этом месте. Такие переменные могут быть использованы там, где в грамматике фильтра RFC 2254, раздел 4, появляется продукция attr, value или matchingrule. Когда строковый аргумент фильтра подставляется вместо переменной, фильтр интерпретируется так, как если бы строка была указана вместо переменной, причем любые символы, имеющие специальное значение в фильтрах (например, '*'), были экранированы в соответствии с правилами RFC 2254.

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

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

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

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

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

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

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

Параметры:

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

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

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

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

Возвращает:

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

Исключения:

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

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

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

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

См. также:

search

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

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

© 1993, 2023, 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/21/docs/api/java.naming/javax/naming/directory/DirContext.html