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

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

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

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

описание
описание;язык-en
описание;язык-de
описание;язык-fr

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

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

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

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

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

Параметры

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

Исключения

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

С момента:: 1.3
См. также:: Context

Поля

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

Поля, унаследованные от интерфейса javax.naming.Context

APPLET, AUTHORITATIVE, BATCHSIZE, DNS_URL, INITIAL_CONTEXT_FACTORY, LANGUAGE, OBJECT_FACTORIES, PROVIDER_URL, REFERRAL, SECURITY_AUTHENTICATION, SECURITY_CREDENTIALS, SECURITY_PRINCIPAL, SECURITY_PROTOCOL, STATE_FACTORIES, URL_PKG_PREFIXES

Методы

Модификатор и тип	Метод и описание
`void`	`bind(Name name, Object obj, Attributes attrs)` Связывает имя с объектом вместе с ассоциированными атрибутами.
`void`	`bind(String name, Object obj, Attributes attrs)` Связывает имя с объектом вместе с ассоциированными атрибутами.
`DirContext`	`createSubcontext(Name name, Attributes attrs)` Создаёт и связывает новый контекст вместе с ассоциированными атрибутами.
`DirContext`	`createSubcontext(String name, Attributes attrs)` Создаёт и связывает новый контекст вместе с ассоциированными атрибутами.
`Attributes`	`getAttributes(Name name)` Извлекает все атрибуты, связанные с именованным объектом.
`Attributes`	`getAttributes(Name name, String[] attrIds)` Извлекает выбранные атрибуты, связанные с именованным объектом.
`Attributes`	`getAttributes(String name)` Извлекает все атрибуты, связанные с именованным объектом.
`Attributes`	`getAttributes(String name, String[] attrIds)` Извлекает выбранные атрибуты, связанные с именованным объектом.
`DirContext`	`getSchema(Name name)` Извлекает схему, связанную с именованным объектом.
`DirContext`	`getSchema(String name)` Извлекает схему, связанную с именованным объектом.
`DirContext`	`getSchemaClassDefinition(Name name)` Извлекает контекст, содержащий объекты схемы определений классов именованного объекта.
`DirContext`	`getSchemaClassDefinition(String name)` Извлекает контекст, содержащий объекты схемы определений классов именованного объекта.
`void`	`modifyAttributes(Name name, int mod_op, Attributes attrs)` Изменяет атрибуты, связанные с именованным объектом.
`void`	`modifyAttributes(Name name, ModificationItem[] mods)` Изменяет атрибуты, связанные с именованным объектом, используя упорядоченный список изменений.
`void`	`modifyAttributes(String name, int mod_op, Attributes attrs)` Изменяет атрибуты, связанные с именованным объектом.
`void`	`modifyAttributes(String name, ModificationItem[] mods)` Изменяет атрибуты, связанные с именованным объектом, используя упорядоченный список изменений.
`void`	`rebind(Name name, Object obj, Attributes attrs)` Связывает имя с объектом вместе с ассоциированными атрибутами, перезаписывая любое существующее связывание.
`void`	`rebind(String name, Object obj, Attributes attrs)` Связывает имя с объектом вместе с ассоциированными атрибутами, перезаписывая любое существующее связывание.
`NamingEnumeration<SearchResult>`	`search(Name name, Attributes matchingAttributes)` Ищет в одном контексте объекты, содержащие указанный набор атрибутов.
`NamingEnumeration<SearchResult>`	`search(Name 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(String name, Attributes matchingAttributes)` Ищет в одном контексте объекты, содержащие указанный набор атрибутов.
`NamingEnumeration<SearchResult>`	`search(String name, Attributes matchingAttributes, String[] attributesToReturn)` Ищет в одном контексте объекты, содержащие указанный набор атрибутов, и извлекает выбранные атрибуты.
`NamingEnumeration<SearchResult>`	`search(String name, String filterExpr, Object[] filterArgs, SearchControls cons)` Ищет в указанном контексте или объекте записи, удовлетворяющие заданному фильтру поиска.
`NamingEnumeration<SearchResult>`	`search(String name, String filter, SearchControls cons)` Ищет в указанном контексте или объекте записи, удовлетворяющие заданному фильтру поиска.

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

См. также:: ModificationItem, modifyAttributes(javax.naming.Name, int, javax.naming.directory.Attributes), Значения константных полей

REPLACE_ATTRIBUTE

static final int REPLACE_ATTRIBUTE

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

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

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

См. также:: ModificationItem, modifyAttributes(javax.naming.Name, int, javax.naming.directory.Attributes), Значения константных полей

REMOVE_ATTRIBUTE

static final int REMOVE_ATTRIBUTE

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

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

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

См. также:: ModificationItem, modifyAttributes(javax.naming.Name, int, javax.naming.directory.Attributes), Значения константных полей

Методы

getAttributes

Attributes getAttributes(Name name)
                  throws NamingException

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

Параметры:: name - имя объекта, из которого извлекаются атрибуты
Возвращает:: набор атрибутов, связанных с name. Возвращает пустой набор атрибутов, если у имени нет атрибутов; никогда не null.
Исключения:: NamingException - если возникло исключение именования
См. также:: getAttributes(String), getAttributes(Name, String[])

getAttributes

Attributes getAttributes(String name)
                  throws NamingException

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

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

getAttributes

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

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

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

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

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

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

getAttributes

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

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

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

modifyAttributes

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

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

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

modifyAttributes

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

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

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

modifyAttributes

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

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

Параметры:: name - имя объекта, атрибуты которого будут обновлены; mods - упорядоченная последовательность изменений, которые нужно выполнить; не может быть null
Исключения:: AttributeModificationException - если изменения не могут быть выполнены успешно; NamingException - если возникло исключение именования
См. также:: modifyAttributes(Name, int, Attributes), ModificationItem

modifyAttributes

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

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

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

bind

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

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

Параметры:: name - имя для привязки; не может быть пустым; obj - объект для привязки; возможно null; attrs - атрибуты для ассоциации с привязкой
Исключения:: NameAlreadyBoundException - если имя уже связано; InvalidAttributesException - если некоторые «обязательные» атрибуты привязки не предоставлены; NamingException - если возникло исключение именования
См. также:: Context.bind(Name, Object), rebind(Name, Object, Attributes)

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:: Context.bind(Name, Object), bind(Name, Object, Attributes)

rebind

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

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

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

createSubcontext

DirContext createSubcontext(Name name,
                            Attributes attrs)
                     throws NamingException

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

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

createSubcontext

DirContext createSubcontext(String name,
                            Attributes attrs)
                     throws NamingException

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

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

getSchema

DirContext getSchema(Name name)
              throws NamingException

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

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

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

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

getSchema

DirContext getSchema(String name)
              throws NamingException

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

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

getSchemaClassDefinition

DirContext getSchemaClassDefinition(Name name)
                             throws NamingException

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

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

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

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

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

getSchemaClassDefinition

DirContext getSchemaClassDefinition(String name)
                             throws NamingException

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

Parameters:: name - имя объекта, определение класса объекта которого должно быть получено
Returns:: контекст, содержащий определения классов именованного объекта; никогда не null
Throws:: 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 - если возникает исключение именования
См. также:: SearchControls, SearchResult, search(Name, String, Object[], SearchControls)

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 в качестве параметра atributesToReturn методу search(Name, Attributes, String[]).
Полное описание см. в search(Name, Attributes, String[]).

Параметры:: name - имя контекста для поиска; matchingAttributes - атрибуты для поиска
Возвращает:: перечисление объектов SearchResult
Выбрасывает:: NamingException - если возникает исключение именования
См. также:: search(Name, Attributes, String[])

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(Name, String, Object[], SearchControls), SearchControls, SearchResult

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(Name, Attributes, String[]), MessageFormat

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, 2020, 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.