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

При наследовании атрибутов атрибуты определяются в иерархии классов. Например, в некоторых каталогах атрибут «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

См. также:

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

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

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

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)`	Выполняет поиск в одном контексте объектов, содержащих заданный набор атрибутов, и получает выбранные атрибуты.

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

Параметры:

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

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

attrs — атрибуты, связываемые с привязкой

Вызывает:

NameAlreadyBoundException — если имя уже связано

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

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

См. также:

bind

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

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

Параметры:: name — имя для привязки; не может быть пустым; obj — объект для привязки; может быть null; attrs — атрибуты, связываемые с привязкой
Вызывает:: 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 игнорируются.

Параметры:

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

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

attrs — атрибуты, связываемые с привязкой

Вызывает:

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

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

См. также:

rebind

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

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

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

createSubcontext

DirContext createSubcontext(Name name, Attributes attrs) throws NamingException

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

Параметры:

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

attrs — атрибуты, связываемые с созданным контекстом

Возвращает:

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

Вызывает:

NameAlreadyBoundException — если имя уже связано

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

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

См. также:

createSubcontext

DirContext createSubcontext(String name, Attributes attrs) throws NamingException

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

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

getSchema

DirContext getSchema(Name name) throws NamingException

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

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

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

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

getSchema

DirContext getSchema(String name) throws NamingException

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

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

getSchemaClassDefinition

DirContext getSchemaClassDefinition(Name name) throws NamingException

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

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

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

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

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

getSchemaClassDefinition

DirContext getSchemaClassDefinition(String name) throws NamingException

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

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

search

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

Возвращает:

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

Вызывает:

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

См. также:

search

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

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

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

search

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

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

Параметры:

name — имя контекста, в котором выполняется поиск

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

Возвращает:

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

Вызывает:

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

См. также:

search

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

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

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

search

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

Параметры:: 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, это эквивалентно пустому массиву.

Возвращает:

перечисление объектов 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, 2025, 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/25/docs/api/java.naming/javax/naming/directory/DirContext.html