Интерфейс DirContext

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

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

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

public interface DirContext extends Context

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

Имена

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Параметры

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

Исключения

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

Начиная с версии:

1.3

См. также:

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

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

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

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

Модификатор и тип	Поле	Описание
`static final String`	`AUTHORITATIVE`	Константа, содержащая имя свойства среды, задающего авторитетность запрошенной службы.
`static final String`	`BATCHSIZE`	Константа, содержащая имя свойства среды, задающего размер пакета данных, возвращаемых по протоколу службы.
`static final String`	`DNS_URL`	Константа, содержащая имя свойства среды, задающего имена DNS-хоста и домена для контекста URL JNDI (например, "dns://somehost/wiz.com").
`static final String`	`INITIAL_CONTEXT_FACTORY`	Константа, содержащая имя свойства среды, задающего используемую фабрику начального контекста.
`static final String`	`LANGUAGE`	Константа, содержащая имя свойства среды, задающего предпочтительный язык для работы со службой.
`static final String`	`OBJECT_FACTORIES`	Константа, содержащая имя свойства среды, задающего список используемых фабрик объектов.
`static final String`	`PROVIDER_URL`	Константа, содержащая имя свойства среды, задающего сведения о конфигурации для поставщика службы.
`static final String`	`REFERRAL`	Константа, содержащая имя свойства среды, задающего способ обработки переадресаций, обнаруженных поставщиком службы.
`static final String`	`SECURITY_AUTHENTICATION`	Константа, содержащая имя свойства среды, задающего используемый уровень безопасности.
`static final String`	`SECURITY_CREDENTIALS`	Константа, содержащая имя свойства среды, задающего учётные данные субъекта для аутентификации вызывающего в службе.
`static final String`	`SECURITY_PRINCIPAL`	Константа, содержащая имя свойства среды, задающего идентификатор субъекта для аутентификации вызывающего в службе.
`static final String`	`SECURITY_PROTOCOL`	Константа, содержащая имя свойства среды, задающего используемый протокол безопасности.
`static final String`	`STATE_FACTORIES`	Константа, содержащая имя свойства среды, задающего список используемых фабрик состояний.
`static final String`	`URL_PKG_PREFIXES`	Константа, содержащая имя свойства среды, задающего список префиксов пакетов, используемых при загрузке фабрик контекстов URL.

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

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

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

addToEnvironment, bind, bind, close, composeName, composeName, createSubcontext, createSubcontext, destroySubcontext, destroySubcontext, getEnvironment, getNameInNamespace, getNameParser, getNameParser, list, list, listBindings, listBindings, lookup, lookup, lookupLink, lookupLink, rebind, rebind, removeFromEnvironment, rename, rename, unbind, unbind

Модификатор и тип	Метод	Описание
`Object`	`addToEnvironment(String propName, Object propVal)`	Добавляет новое свойство среды в среду этого контекста.
`void`	`bind(String name, Object obj)`	Связывает имя с объектом.
`void`	`bind(Name name, Object obj)`	Связывает имя с объектом.
`void`	`close()`	Закрывает этот контекст.
`String`	`composeName(String name, String prefix)`	Составляет имя этого контекста с именем, относительным к этому контексту.
`Name`	`composeName(Name name, Name prefix)`	Составляет имя этого контекста с именем, относительным к этому контексту.
`Context`	`createSubcontext(String name)`	Создаёт и связывает новый контекст.
`Context`	`createSubcontext(Name name)`	Создаёт и связывает новый контекст.
`void`	`destroySubcontext(String name)`	Уничтожает именованный контекст и удаляет его из пространства имён.
`void`	`destroySubcontext(Name name)`	Уничтожает именованный контекст и удаляет его из пространства имён.
`Hashtable<?,?>`	`getEnvironment()`	Получает среду, действующую для этого контекста.
`String`	`getNameInNamespace()`	Получает полное имя этого контекста в его собственном пространстве имён.
`NameParser`	`getNameParser(String name)`	Получает анализатор, связанный с именованным контекстом.
`NameParser`	`getNameParser(Name name)`	Получает анализатор, связанный с именованным контекстом.
`NamingEnumeration<NameClassPair>`	`list(String name)`	Перечисляет имена, связанные в именованном контексте, а также имена классов связанных с ними объектов.
`NamingEnumeration<NameClassPair>`	`list(Name name)`	Перечисляет имена, связанные в именованном контексте, а также имена классов связанных с ними объектов.
`NamingEnumeration<Binding>`	`listBindings(String name)`	Перечисляет имена, связанные в именованном контексте, а также связанные с ними объекты.
`NamingEnumeration<Binding>`	`listBindings(Name name)`	Перечисляет имена, связанные в именованном контексте, а также связанные с ними объекты.
`Object`	`lookup(String name)`	Получает именованный объект.
`Object`	`lookup(Name name)`	Получает именованный объект.
`Object`	`lookupLink(String name)`	Получает именованный объект, переходя по ссылкам, за исключением конечного атомарного компонента имени.
`Object`	`lookupLink(Name name)`	Получает именованный объект, переходя по ссылкам, за исключением конечного атомарного компонента имени.
`void`	`rebind(String name, Object obj)`	Связывает имя с объектом, заменяя существующую привязку.
`void`	`rebind(Name name, Object obj)`	Связывает имя с объектом, заменяя существующую привязку.
`Object`	`removeFromEnvironment(String propName)`	Удаляет свойство среды из среды этого контекста.
`void`	`rename(String oldName, String newName)`	Связывает новое имя с объектом, связанным со старым именем, и отменяет привязку старого имени.
`void`	`rename(Name oldName, Name newName)`	Связывает новое имя с объектом, связанным со старым именем, и отменяет привязку старого имени.
`void`	`unbind(String name)`	Отменяет привязку именованного объекта.
`void`	`unbind(Name name)`	Отменяет привязку именованного объекта.

Подробное описание полей

ADD_ATTRIBUTE

static final int ADD_ATTRIBUTE

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

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

Значение этой константы — 1.

См. также:

REPLACE_ATTRIBUTE

static final int REPLACE_ATTRIBUTE

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

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

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

См. также:

REMOVE_ATTRIBUTE

static final int REMOVE_ATTRIBUTE

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

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

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

См. также:

Подробное описание методов

getAttributes

Attributes getAttributes(Name name) throws NamingException

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

Параметры:

name — имя объекта, атрибуты которого требуется получить

Возвращает:

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

Вызывает:

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

См. также:

getAttributes

Attributes getAttributes(String name) throws NamingException

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

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

getAttributes

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

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

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

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

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

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

getAttributes

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

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

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

modifyAttributes

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

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

Параметры:

name — имя объекта, атрибуты которого будут обновлены

mod_op — операция изменения, одна из следующих: ADD_ATTRIBUTE, REPLACE_ATTRIBUTE, REMOVE_ATTRIBUTE.

attrs — атрибуты, используемые для изменения; не может быть null

Вызывает:

AttributeModificationException — если изменение не удалось успешно завершить

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

См. также:

modifyAttributes

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

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

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

modifyAttributes

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

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

Параметры:

name — имя объекта, атрибуты которого будут обновлены

mods — упорядоченная последовательность изменений; не может быть null

Вызывает:

AttributeModificationException — если изменения не удалось успешно завершить

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

См. также:

modifyAttributes

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

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

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

bind

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

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

Параметры:

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

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

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

Вызывает:

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

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

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

См. также:

bind

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

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

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

rebind

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

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

Параметры:

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

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

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

Вызывает:

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

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

См. также:

rebind

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

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

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

createSubcontext

DirContext createSubcontext(Name name, Attributes attrs) throws NamingException

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

Параметры:

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

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

Возвращает:

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

Вызывает:

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

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

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

См. также:

createSubcontext

DirContext createSubcontext(String name, Attributes attrs) throws NamingException

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

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

getSchema

DirContext getSchema(Name name) throws NamingException

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

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

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

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

getSchema

DirContext getSchema(String name) throws NamingException

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

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

getSchemaClassDefinition

DirContext getSchemaClassDefinition(Name name) throws NamingException

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

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

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

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

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

getSchemaClassDefinition

DirContext getSchemaClassDefinition(String name) throws NamingException

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

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

search

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

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

Чтобы объект был выбран, каждый атрибут из matchingAttributes должен соответствовать некоторому атрибуту объекта. Если matchingAttributes пуст или равен null, возвращаются все объекты в целевом контексте.

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

Точное определение «равенства», используемого при сравнении значений атрибутов, задаётся базовой службой каталогов. Например, может использоваться метод Object.equals или схема может задавать другую операцию равенства. Для поиска с использованием операций, отличных от равенства (например, сравнения подстрок), используйте вариант метода search, принимающий фильтр.

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

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

Параметры:

name — имя контекста для поиска

matchingAttributes — атрибуты для поиска. Если список пуст или равен null, возвращаются все объекты в целевом контексте.

attributesToReturn — атрибуты для возврата. Значение null означает, что нужно вернуть все атрибуты; пустой массив означает, что не нужно возвращать ни одного атрибута.

Возвращает:

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

search

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

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

Формат и интерпретация filter соответствуют RFC 2254 с учетом следующих трактовок attr и value, упомянутых в RFC.

attr — это идентификатор атрибута.

value — строковое представление значения атрибута. Преобразование этого строкового представления в значение атрибута зависит от каталога.

Например, для утверждения "someCount=127" attr — это "someCount", а value — это "127". Поставщик определяет на основании идентификатора атрибута ("someCount") (и, возможно, его схемы), что значение атрибута является целым числом. Затем он соответствующим образом анализирует строку "127".

Любые символы фильтра, не входящие в ASCII, следует представлять соответствующими символами Java (Unicode), а не кодировать в виде октетов UTF-8. В качестве альтернативы можно использовать нотацию «обратная косая черта — шестнадцатеричный код», описанную в RFC 2254.

Если каталог не поддерживает строковое представление некоторых или всех своих атрибутов, вместо этого можно использовать форму search, принимающую аргументы фильтра в виде объектов. Поставщик службы для такого каталога преобразует аргументы фильтра в представление, специфичное для службы, для оценки фильтра. См. search(Name, String, Object[], SearchControls).

RFC 2254 определяет для фильтра несколько операторов, в том числе поиск по подстроке, равенство, приблизительное совпадение, «больше чем» и «меньше чем». Эти операторы сопоставляются с операторами базового каталога, имеющими соответствующую семантику. Например, для оператора равенства предположим, что в каталоге имеется правило сопоставления, определяющее «равенство» атрибутов в фильтре. Это правило будет использоваться для проверки равенства атрибутов, указанных в фильтре, атрибутам объектов каталога. Аналогично, если в каталоге имеется правило сопоставления для упорядочивания, оно будет использоваться для сравнений «больше чем» и «меньше чем».

Не все операторы, определенные в RFC 2254, применимы ко всем атрибутам. Если оператор неприменим, возникает исключение InvalidSearchFilterException.

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

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

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

Параметры:

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

filter — выражение фильтра для поиска; не может быть null

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

Возвращает:

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

Вызывает:

InvalidSearchFilterException — если указанный фильтр поиска не поддерживается базовым каталогом или не распознается им

InvalidSearchControlsException — если элементы управления поиском содержат недопустимые настройки

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

См. также:

search

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

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

search

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

Интерпретация filterExpr основана на RFC 2254. Кроме того, выражение может содержать переменные вида {i}, где i — целое число, которые ссылаются на объекты в массиве filterArgs. В остальном интерпретация filterExpr идентична интерпретации параметра filter метода search(Name, String, SearchControls).

Переменная {i} в фильтре поиска указывает, что на этом месте следует использовать аргумент фильтра filterArgs[i]. Такие переменные можно использовать везде, где в грамматике фильтра раздела 4 RFC 2254 встречаются конструкции attr, value или matchingrule. При подстановке строкового аргумента фильтра вместо переменной фильтр интерпретируется так, как если бы строка была указана вместо переменной, а все символы, имеющие специальное значение в фильтрах (например, '*'), были экранированы согласно правилам RFC 2254.

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

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

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

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

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

Параметры:

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

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

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

Возвращает:

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

Вызывает:

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

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

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

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

См. также:

search

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

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

© 1993, 2025, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.