Интерфейс DirContext

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

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

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

public interface DirContext extends Context

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

Имена

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

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

См. Context для обсуждения интерпретации аргумента name в методах Context. Эти же правила применяются к аргументу name в методах 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 в качестве списка возвращаемых атрибутов. Возвращаемые атрибуты не включают операционные атрибуты. Для получения операционных атрибутов необходимо явно указать их имена.

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

В некоторых методах имя должно быть разрешено в контекст (например, при поиске в контексте одного уровня). В документации таких методов используется термин именованный контекст для описания параметра name. Для этих методов, если названный объект не является 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`	Эта константа указывает на замену атрибута указанными значениями.

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

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

Parameters:: name - имя объекта, атрибуты которого будут обновлены; mods - упорядоченная последовательность выполняемых изменений; не может быть null
Throws:: 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, содержащий все определения классов указанного объекта.

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

Возвращает:

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

Исключения:

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

См. также:

search

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

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

Параметры:: name - имя контекста для поиска; matchingAttributes - атрибуты для поиска; attributesToReturn - атрибуты для возврата
Возвращает:: непустое перечисление объектов 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 - если возникло исключение при именовании

поиск

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

См. также:

поиск

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

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

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

поиск

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

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

Параметры:: 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://download.java.net/java/early_access/jdk24/docs/api/java.naming/javax/naming/directory/DirContext.html