Интерфейс DirContext

Все суперинтерфейсы:
Context
Все известные подинтерфейсы:
EventDirContext, LdapContext
Все известные реализующие классы:
InitialDirContext, InitialLdapContext 
public interface DirContext
extends Context

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

Имена

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Параметры

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

Исключения

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

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

Поля

Модификатор и тип Поле Описание
static 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​(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.

См. также:
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).

Параметры:
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 - если возникает исключение в работе с именованием
См. также:
Context.bind(Name, Object), bind(Name, Object, Attributes)

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 — если возникло исключение при именовании
См. также:
Context.createSubcontext(Name)

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, возвращаются все объекты в целевом контексте.

Атрибут A1 в matchingAttributes считается соответствующим атрибуту A2 объекта, если A1 и A2 имеют один и тот же идентификатор, и каждое значение A1 равно какому-то значению A2. Это подразумевает, что порядок значений не имеет значения и что A2 может содержать «лишние» значения, отсутствующие в A1, не влияя на сравнение. Это также подразумевает, что если A1 не имеет значений, то проверка соответствия эквивалентна проверке наличия атрибута A2 с тем же идентификатором.

Точное определение «равенства», используемое при сравнении значений атрибутов, определяется подлежащей службой каталога. Она может использовать метод 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 в качестве параметра attributesToReturn методу 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.
https://docs.oracle.com/en/java/javase/11/docs/api/java.naming/javax/naming/directory/DirContext.html

Spec-Zone .ru
спецификации, руководства, описания, API