Интерфейс контекста

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

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

public interface Context

Данный интерфейс представляет собой контекст именования, состоящий из набора связей «имя-объект». Он содержит методы для проверки и обновления этих связей.

Имена

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

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

В системах, поддерживающих федерацию, аргументы имен String в методах Context являются составными именами. Аргументы имен, являющиеся экземплярами CompositeName, обрабатываются как составные имена, в то время как аргументы Name, которые не являются экземплярами CompositeName, обрабатываются как составные имена (которые могут быть экземплярами CompoundName или других реализаций составных имён). Это позволяет использовать результаты NameParser.parse() в качестве аргументов методов Context. До версии JNDI 1.2 все аргументы имён обрабатывались как составные имена.

Кроме того, в системах, поддерживающих федерацию, все имена, возвращаемые в NamingEnumeration из list() и listBindings(), являются составными именами, представленными в виде строк. Синтаксис строк имён см. в CompositeName.

В системах, которые не поддерживают федерацию, аргументы имён (в формате Name или String) и имена, возвращаемые в NamingEnumeration, могут быть именами в собственном пространстве имён, а не именами в составном пространстве имён, по усмотрению поставщика услуг.

Исключения

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

Одновременный доступ

Экземпляр Context не гарантируется синхронизированным против одновременного доступа нескольких потоков. Потоки, которым требуется одновременный доступ к одному экземпляру Context, должны синхронизироваться между собой и предоставить необходимую блокировку. Несколько потоков, манипулирующих разными экземплярами Context, не нуждаются в синхронизации. Обратите внимание, что метод lookup, когда ему передано пустое имя, вернёт новый экземпляр Context, представляющий тот же контекст именования.

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

Параметры

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

Свойства окружения

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

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

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

Любой объект, имеющий ссылку на контекст, может просмотреть среду этого контекста. Чувствительная информация, такая как пароли в открытом тексте, не должна храниться там, если не известно, что реализация защищает её.

Файлы ресурсов

Для упрощения задачи настройки среды, необходимой для приложения JNDI, компоненты приложения и поставщики услуг могут поставляться вместе с файлами ресурсов. Файл ресурсов JNDI — это файл в формате файла свойств (см. java.util.Properties), содержащий список пар «ключ-значение». Ключ — это имя свойства (например, «java.naming.factory.object»), а значение — строка в формате, определённом для данного свойства. Вот пример файла ресурсов JNDI:

java.naming.factory.object=com.sun.jndi.ldap.AttrsToCorba:com.wiz.from.Person java.naming.factory.state=com.sun.jndi.ldap.CorbaToAttrs:com.wiz.from.Person java.naming.factory.control=com.sun.jndi.ldap.ResponseControlFactory

Библиотека классов JNDI читает файлы ресурсов и делает значения свойств доступными. Таким образом, файлы ресурсов JNDI следует считать «доступными для чтения всем», и чувствительная информация, такая как пароли в открытом тексте, не должна храниться там.

Существует два типа файлов ресурсов JNDI: поставщика и приложения.

Файлы ресурсов поставщика

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

[prefix/]jndiprovider.properties

, где префикс — имя пакета реализации контекста поставщика, при этом каждая точка (".") заменяется слешем ("/"). Например, предположим, что поставщик услуг определяет реализацию контекста с именем класса com.sun.jndi.ldap.LdapCtx. Файл ресурсов поставщика для этого поставщика называется com/sun/jndi/ldap/jndiprovider.properties. Если класс не находится в пакете, имя ресурса просто jndiprovider.properties.

Некоторые методы библиотеки классов JNDI используют стандартные свойства JNDI, определяющие списки фабрик JNDI:

java.naming.factory.object
java.naming.factory.state
java.naming.factory.control
java.naming.factory.url.pkgs

Библиотека JNDI обратится к файлу ресурсов поставщика при определении значений этих свойств. Другие свойства могут быть установлены в файле ресурсов поставщика по усмотрению поставщика услуг. Документация поставщика услуг должна чётко указывать разрешённые свойства; другие свойства в файле будут проигнорированы.

Файлы ресурсов приложения

При развертывании приложения, как правило, в его пути класса находится несколько каталогов кода и JAR-файлов. JNDI находит (используя ClassLoader.getResources()) все файлы ресурсов приложения с именем jndi.properties в пути класса. Кроме того, если в каталоге установки Java содержится встроенный файл свойств, обычно conf/jndi.properties, JNDI обрабатывает его как дополнительный файл ресурсов приложения. Все свойства, содержащиеся в этих файлах, помещаются в среду начального контекста. Эта среда затем наследуется другими контекстами.

Для каждого свойства, найденного более чем в одном файле ресурсов приложения, JNDI использует первое найденное значение или, в некоторых случаях, где это имеет смысл, объединяет все значения (подробности приведены ниже). Например, если свойство «java.naming.factory.object» найдено в трёх файлах ресурсов jndi.properties , список фабрик объектов — это конкатенация значений свойства из всех трёх файлов. Используя эту схему, каждый компонент, подлежащий развертыванию, отвечает за указание экспортируемых фабрик. JNDI автоматически собирает и использует все эти списки экспорта при поиске классов фабрик.

Алгоритм поиска свойств

При создании начального контекста JNDI среда контекста инициализируется свойствами, определёнными в параметре среды, переданном конструктору, системными свойствами и файлами ресурсов приложения. Подробности см. в InitialContext. Эта начальная среда затем наследуется другими экземплярами контекста.

Когда библиотека JNDI нуждается в определении значения свойства, она делает это путём объединения значений из двух следующих источников, в порядке их перечисления:

Среда контекста, с которым выполняются операции.
Файл ресурсов поставщика (jndiprovider.properties) для контекста, с которым выполняются операции.

Для каждого свойства, найденного в обоих источниках, JNDI определяет значение свойства следующим образом. Если свойство является одним из стандартных свойств JNDI, определяющих список фабрик JNDI (перечисленных выше), значения объединяются в один список, разделённый двоеточием. Для других свойств используется только первое найденное значение.

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

Таким образом, каждый разработчик поставщика услуг может указать список фабрик, которые будут использоваться с этим поставщиком услуг. Эти фабрики могут быть изменены ресурсами приложения, указанными разработчиком приложения, которые, в свою очередь, могут быть изменены пользователем.

С момента:: 1.3

Поля

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

Методы

Модификатор и тип	Метод	Описание
`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)`	Отвязывает именованный объект.

Поля

INITIAL_CONTEXT_FACTORY

static final String INITIAL_CONTEXT_FACTORY

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

Значение этой константы равно "java.naming.factory.initial".

См. также:: InitialContext, InitialDirContext, NamingManager.getInitialContext(java.util.Hashtable<?, ?>), InitialContextFactory, NoInitialContextException, addToEnvironment(String, Object), removeFromEnvironment(String), Значения константных полей

OBJECT_FACTORIES

static final String OBJECT_FACTORIES

Константа, содержащая имя свойства среды для указания списка фабрик объектов для использования. Значение свойства должно быть списком фабрик объектов, разделённых двоеточием, с полными квалифицированными именами классов фабрики классов, которые создадут объект на основе информации об объекте. Это свойство может быть указано в среде, системном свойстве или одном или нескольких файлах ресурсов.

Значение этой константы равно "java.naming.factory.object".

См. также:: NamingManager.getObjectInstance(java.lang.Object, javax.naming.Name, javax.naming.Context, java.util.Hashtable<?, ?>), ObjectFactory, addToEnvironment(String, Object), removeFromEnvironment(String), Значения константных полей

STATE_FACTORIES

static final String STATE_FACTORIES

Константа, содержащая имя свойства среды для указания списка фабрик состояний для использования. Значение свойства должно быть списком, разделённым двоеточием, полных квалифицированных имён классов фабрик состояний, которые будут использоваться для получения состояния объекта на основе самого объекта. Это свойство может быть указано в среде, системном свойстве или одном или нескольких файлах ресурсов.

Значение этой константы равно "java.naming.factory.state".

С момента:: 1.3
См. также:: NamingManager.getStateToBind(java.lang.Object, javax.naming.Name, javax.naming.Context, java.util.Hashtable<?, ?>), StateFactory, addToEnvironment(String, Object), removeFromEnvironment(String), Значения константных полей

URL_PKG_PREFIXES

static final String URL_PKG_PREFIXES

Константа, содержащая имя свойства среды для указания списка префиксов пакетов для использования при загрузке фабрик контекстов URL. Значение свойства должно быть списком префиксов пакетов, разделённых двоеточием, для имени класса фабрики, которая создаст фабрику контекста URL. Это свойство может быть указано в среде, системном свойстве или одном или нескольких файлах ресурсов. Префикс com.sun.jndi.url всегда добавляется к возможно пустому списку префиксов пакетов.

Значение этой константы равно "java.naming.factory.url.pkgs".

См. также:: NamingManager.getObjectInstance(java.lang.Object, javax.naming.Name, javax.naming.Context, java.util.Hashtable<?, ?>), NamingManager.getURLContext(java.lang.String, java.util.Hashtable<?, ?>), ObjectFactory, addToEnvironment(String, Object), removeFromEnvironment(String), Значения константных полей

PROVIDER_URL

static final String PROVIDER_URL

Константа, содержащая имя свойства среды для указания конфигурационной информации для используемого поставщика услуг. Значение свойства должно содержать строку URL (например, "ldap://somehost:389"). Это свойство может быть указано в среде, системном свойстве или файле ресурсов. Если оно не указано ни в одном из этих источников, то конфигурация по умолчанию определяется поставщиком услуг.

Значение этой константы равно "java.naming.provider.url".

См. также:: addToEnvironment(String, Object), removeFromEnvironment(String), Значения константных полей

DNS_URL

static final String DNS_URL

Константа, содержащая имя свойства среды для указания имен хоста и домена DNS для использования в контексте JNDI URL (например, "dns://somehost/wiz.com"). Это свойство может быть указано в среде, системном свойстве или файле ресурсов. Если оно не указано ни в одном из этих источников, и программа пытается использовать JNDI URL, содержащий имя DNS, будет выброшено исключение ConfigurationException.

Значение этой константы равно "java.naming.dns.url".

См. также:: addToEnvironment(String, Object), removeFromEnvironment(String), Значения константных полей

AUTHORITATIVE

static final String AUTHORITATIVE

Константа, содержащая имя свойства среды для указания авторитетности запрошенной службы. Если значение свойства — строка "true", это означает, что доступ осуществляется к самому авторитетному источнику (т.е. обход кэша или репликам). Если значение — что-либо другое, то источник не обязан быть (но может быть) авторитетным. Если не указано, значение по умолчанию — "false".

Значение этой константы равно "java.naming.authoritative".

См. также:: addToEnvironment(String, Object), removeFromEnvironment(String), Значения константных полей

BATCHSIZE

static final String BATCHSIZE

Константа, содержащая имя свойства среды для указания размера пакета для возврата данных через протокол службы. Это подсказка для поставщика о возврате результатов операций пакетами указанного размера, что позволяет поставщику оптимизировать производительность и использование ресурсов. Значение свойства — строковое представление целого числа. Если не указано, размер пакета определяется поставщиком услуг.

Значение этой константы равно "java.naming.batchsize".

См. также:: addToEnvironment(String, Object), removeFromEnvironment(String), Значения константных полей

REFERRAL

static final String REFERRAL

Константа, содержащая имя свойства среды для указания способа обработки рефератов, встречающихся поставщиком услуг. Значение свойства — одна из следующих строк:

"follow": следовать рефератам автоматически
"ignore": игнорировать рефераты
"throw": бросить исключение ReferralException при встрече реферата.

Если это свойство не указано, по умолчанию используется поведение поставщика.

Значение этой константы равно "java.naming.referral".

См. также:: addToEnvironment(String, Object), removeFromEnvironment(String), Значения константных полей

SECURITY_PROTOCOL

static final String SECURITY_PROTOCOL

Константа, содержащая имя свойства среды для указания используемого протокола безопасности. Его значение — строка, определяемая поставщиком услуг (например, "ssl"). Если это свойство не указано, поведение определяется поставщиком услуг.

Значение этой константы равно "java.naming.security.protocol".

См. также:: addToEnvironment(String, Object), removeFromEnvironment(String), Значения константных полей

SECURITY_AUTHENTICATION

static final String SECURITY_AUTHENTICATION

Константа, содержащая имя свойства среды для указания используемого уровня безопасности. Его значение — одна из следующих строк: "none", "simple", "strong". Если это свойство не указано, поведение определяется поставщиком услуг.

Значение этой константы равно "java.naming.security.authentication".

См. также:: addToEnvironment(String, Object), removeFromEnvironment(String), Значения константных полей

SECURITY_PRINCIPAL

static final String SECURITY_PRINCIPAL

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

Значение этой константы равно "java.naming.security.principal".

См. также:: addToEnvironment(String, Object), removeFromEnvironment(String), Значения постоянных полей

SECURITY_CREDENTIALS

static final String SECURITY_CREDENTIALS

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

Значение этой константы равно "java.naming.security.credentials".

См. также:: addToEnvironment(String, Object), removeFromEnvironment(String), Значения постоянных полей

LANGUAGE

static final String LANGUAGE

Константа, содержащая имя свойства среды для указания предпочтительного языка для использования с сервисом. Значение свойства представляет собой список языковых тегов, разделенных двоеточиями, как определено в RFC 1766. Если это свойство не указано, предпочтение языка определяется поставщиком сервиса.

Значение этой константы равно "java.naming.language".

См. также:: addToEnvironment(String, Object), removeFromEnvironment(String), Значения постоянных полей

APPLET

@Deprecated
static final String APPLET

Устарело.

Свойство среды с этим именем игнорируется при построении контекста начального уровня. Эта константа изначально использовалась как имя свойства для указания Applet для извлечения параметров при создании начального контекста. В настоящее время любые свойства апплета, которые необходимо передать в начальный контекст, должны быть скопированы в таблицу хешей среды:

Hashtable env = new Hashtable();
     env.put(Context.INITIAL_CONTEXT_FACTORY,
       ((Applet) this).getParameter(Context.INITIAL_CONTEXT_FACTORY));
     env.put(Context.PROVIDER_URL,
       ((Applet) this).getParameter(Context.PROVIDER_URL));
     // ... other properties ...

     Context ctx = new InitialContext(env);

С:: 1.3
См. также:: Значения постоянных полей

Методы

lookup

Object lookup(Name name)
       throws NamingException

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

Параметры:: name - имя искомого объекта
Возвращает:: объект, связанный с name
Исключения:: NamingException - если возникает исключение именования
См. также:: lookup(String), lookupLink(Name)

lookup

Object lookup(String name)
       throws NamingException

Извлекает объект по имени. Подробнее см. lookup(Name).

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

bind

void bind(Name name,
          Object obj)
   throws NamingException

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

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

bind

void bind(String name,
          Object obj)
   throws NamingException

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

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

rebind

void rebind(Name name,
            Object obj)
     throws NamingException

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

Если объект является DirContext, все существующие атрибуты, связанные с именем, заменяются атрибутами объекта. В противном случае любые существующие атрибуты, связанные с именем, остаются неизменными.

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

rebind

void rebind(String name,
            Object obj)
     throws NamingException

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

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

unbind

void unbind(Name name)
     throws NamingException

Удаляет объект по имени. Удаляет конечное атомное имя в name из целевого контекста — контекста, определяемого всеми, кроме конечной атомной части name.

Этот метод идемпотентен. Он успешно выполняется, даже если конечное атомное имя не связано в целевом контексте, но выбрасывает NameNotFoundException если какой-либо из промежуточных контекстов не существует.

Любые атрибуты, связанные с именем, удаляются. Промежуточные контексты не изменяются.

Параметры:: name - имя для удаления; не должно быть пустым
Исключения:: NameNotFoundException - если промежуточный контекст не существует; NamingException - если возникает исключение именования
См. также:: unbind(String)

unbind

void unbind(String name)
     throws NamingException

Удаляет объект по имени. Подробнее см. unbind(Name).

Параметры:: name - имя для удаления; не должно быть пустым
Исключения:: NameNotFoundException - если промежуточный контекст не существует; NamingException - если возникает исключение именования

rename

void rename(Name oldName,
            Name newName)
     throws NamingException

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

Параметры:: oldName - имя существующего связывания; не должно быть пустым; newName - имя нового связывания; не должно быть пустым
Исключения:: NameAlreadyBoundException - если newName уже связано; NamingException - если возникает исключение именования
См. также:: rename(String, String), bind(Name, Object), rebind(Name, Object)

rename

void rename(String oldName,
            String newName)
     throws NamingException

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

Параметры:: oldName - имя существующего связывания; не должно быть пустым; newName - имя нового связывания; не должно быть пустым
Исключения:: NameAlreadyBoundException - если newName уже связано; NamingException - если возникает исключение именования

list

NamingEnumeration<NameClassPair> list(Name name)
                               throws NamingException

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

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

Параметры:: name - имя контекста для перечисления
Возвращает:: перечисление имен и имён классов связываний в этом контексте. Каждый элемент перечисления является типа NameClassPair.
Исключения:: NamingException - если возникает исключение именования
См. также:: list(String), listBindings(Name), NameClassPair

list

NamingEnumeration<NameClassPair> list(String name)
                               throws NamingException

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

Параметры:: name - имя контекста для перечисления
Возвращает:: перечисление имен и имён классов связываний в этом контексте. Каждый элемент перечисления является типа NameClassPair.
Исключения:: NamingException - если возникает исключение именования

listBindings

NamingEnumeration<Binding> listBindings(Name name)
                                 throws NamingException

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

Параметры:: name - имя контекста для перечисления
Возвращает:: перечисление связываний в этом контексте. Каждый элемент перечисления является типа Binding.
Исключения:: NamingException - если возникает исключение именования
См. также:: listBindings(String), list(Name), Binding

listBindings

NamingEnumeration<Binding> listBindings(String name)
                                 throws NamingException

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

Параметры:: name - имя контекста для перечисления
Возвращает:: перечисление связываний в этом контексте. Каждый элемент перечисления является типа Binding.
Исключения:: NamingException - если возникает исключение именования

destroySubcontext

void destroySubcontext(Name name)
                throws NamingException

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

Этот метод идемпотентен. Он завершается успешно, даже если конечное атомарное имя не привязано в целевом контексте, но выбрасывает NameNotFoundException если какой-либо из промежуточных контекстов не существует.

В федеративной системе именования контекст из одной системы именования может быть привязан к имени в другой. Затем можно выполнить поиск и операции над внешним контекстом, используя составное имя. Однако попытка уничтожить контекст с помощью этого составного имени завершится ошибкой NotContextException, поскольку внешний контекст не является «подконтекстом» контекста, в котором он привязан. Вместо этого используйте unbind() для удаления привязки внешнего контекста. Уничтожение внешнего контекста требует выполнения destroySubcontext() в контексте из «родной» системы именования внешнего контекста.

Parameters:: name - имя контекста, подлежащего уничтожению; не может быть пустым
Throws:: NameNotFoundException - если промежуточный контекст не существует; NotContextException - если имя привязано, но не является именем контекста или не является именем контекста соответствующего типа; ContextNotEmptyException - если контекст с указанным именем не пуст; NamingException - если возникло исключение именования
See Also:: destroySubcontext(String)

destroySubcontext

void destroySubcontext(String name)
                throws NamingException

Уничтожает контекст с указанным именем и удаляет его из пространства имён. Подробности см. в destroySubcontext(Name).

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

createSubcontext

Context createSubcontext(Name name)
                  throws NamingException

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

Parameters:: name - имя контекста для создания; не может быть пустым
Returns:: созданный контекст
Throws:: NameAlreadyBoundException - если имя уже привязано; InvalidAttributesException - если для создания подконтекста требуется указать обязательные атрибуты; NamingException - если возникло исключение именования
See Also:: createSubcontext(String), DirContext.createSubcontext(javax.naming.Name, javax.naming.directory.Attributes)

createSubcontext

Context createSubcontext(String name)
                  throws NamingException

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

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

lookupLink

Object lookupLink(Name name)
           throws NamingException

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

Parameters:: name - имя объекта для поиска
Returns:: объект, привязанный к name, без следования конечной ссылке (если таковая есть).
Throws:: NamingException - если возникло исключение именования
See Also:: lookupLink(String)

lookupLink

Object lookupLink(String name)
           throws NamingException

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

Parameters:: name - имя объекта для поиска
Returns:: объект, привязанный к name, без следования конечной ссылке (если таковая есть)
Throws:: NamingException - если возникло исключение именования

getNameParser

NameParser getNameParser(Name name)
                  throws NamingException

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

Parameters:: name - имя контекста, из которого получить парсер
Returns:: парсер имён, который может разбить составные имена на атомарные компоненты
Throws:: NamingException - если возникло исключение именования
See Also:: getNameParser(String), CompoundName

getNameParser

NameParser getNameParser(String name)
                  throws NamingException

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

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

composeName

Name composeName(Name name,
                 Name prefix)
          throws NamingException

Компонует имя этого контекста с именем, относительным к этому контексту. Учитывая имя (name) относительно этого контекста и имя (prefix) этого контекста относительно одного из его предков, этот метод возвращает композицию двух имён, используя синтаксис, соответствующий используемой(ым) системе(ам) именования. То есть, если name называет объект относительно этого контекста, результат — имя того же объекта, но относительно контекста предка. Ни одно из имён не может быть null.

Например, если этот контекст имеет имя «wiz.com» относительно начального контекста, то

composeName("east", "wiz.com")

может вернуть "east.wiz.com". Если же этот контекст имеет имя «org/research», то

composeName("user/jane", "org/research")

может вернуть "org/research/user/jane", в то время как

composeName("user/jane", "research")

возвращает "research/user/jane".

Parameters:: name - имя, относительное к этому контексту; prefix - имя этого контекста относительно одного из его предков
Returns:: композиция prefix и name
Throws:: NamingException - если возникло исключение именования
See Also:: composeName(String, String)

composeName

String composeName(String name,
                   String prefix)
            throws NamingException

Компонует имя этого контекста с именем, относительным к этому контексту. Подробности см. в composeName(Name, Name).

Parameters:: name - имя, относительное к этому контексту; prefix - имя этого контекста относительно одного из его предков
Returns:: композиция prefix и name
Throws:: NamingException - если возникло исключение именования

addToEnvironment

Object addToEnvironment(String propName,
                        Object propVal)
                 throws NamingException

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

Parameters:: propName - имя свойства среды для добавления; не может быть null; propVal - значение свойства для добавления; не может быть null
Returns:: предыдущее значение свойства или null, если свойство отсутствовало в среде ранее
Throws:: NamingException - если возникло исключение именования
See Also:: getEnvironment(), removeFromEnvironment(String)

removeFromEnvironment

Object removeFromEnvironment(String propName)
                      throws NamingException

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

Parameters:: propName - имя свойства среды для удаления; не может быть null
Returns:: предыдущее значение свойства или null, если свойство отсутствовало в среде
Throws:: NamingException - если возникло исключение именования
See Also:: getEnvironment(), addToEnvironment(String, Object)

getEnvironment

Hashtable<?,?> getEnvironment()
                             throws NamingException

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

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

Returns:: среда этого контекста; никогда не null
Throws:: NamingException - если возникло исключение именования
See Also:: addToEnvironment(String, Object), removeFromEnvironment(String)

close

void close()
    throws NamingException

Закрывает этот контекст. Этот метод немедленно освобождает ресурсы этого контекста вместо ожидания их автоматического освобождения сборщиком мусора.

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

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

getNameInNamespace

String getNameInNamespace()
                   throws NamingException

Возвращает полное имя этого контекста в его собственном пространстве имен.

Многие службы именования имеют понятие «полного имени» для объектов в своих пространствах имен. Например, запись LDAP имеет имя отличия, а запись DNS — полное доменное имя. Этот метод позволяет прикладному программному обеспечению получить это имя. Строка, возвращаемая этим методом, не является составным именем JNDI и не должна передаваться напрямую методам контекста. В системах именования, для которых понятие полного имени не имеет смысла, выбрасывается OperationNotSupportedException.

Возвращаемое значение:: имя контекста в его собственном пространстве имен; никогда не null
Исключения:: OperationNotSupportedException - если система именования не имеет понятия полного имени; NamingException - если возникает исключение именования
С:: 1.3

© 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/Context.html