Класс RelationSupport

java.lang.Object

javax.management.relation.RelationSupport

Все реализуемые интерфейсы:: MBeanRegistration, Relation, RelationSupportMBean

public class RelationSupport extends Object implements RelationSupportMBean, MBeanRegistration

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

Класс RelationSupport соответствует шаблонам проектирования стандартных MBean. Поэтому пользователь может самостоятельно создать объект RelationSupport как MBean (так как он следует шаблонам проектирования MBean), зарегистрировать его в сервере MBean и затем добавить его в службу отношений.

Пользователь также может, при создании собственного класса отношения MBean, расширить RelationSupport для получения реализаций необходимых интерфейсов (см. ниже).

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

RelationSupport реализует интерфейс Relation (для обработки службой отношений).

Он также реализует интерфейс MBeanRegistration для возможности получения сервера MBean, где он зарегистрирован (если зарегистрирован как MBean), для доступа к его службе отношений.

C:: 1.5

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

Конструктор	Описание
`RelationSupport(String relationId, ObjectName relationServiceName, String relationTypeName, RoleList list)`	Создаёт объект `RelationSupport`.
`RelationSupport(String relationId, ObjectName relationServiceName, MBeanServer relationServiceMBeanServer, String relationTypeName, RoleList list)`	Создаёт объект `RelationSupport`.

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

Модификатор и тип	Метод	Описание
`RoleResult`	`getAllRoles()`	Возвращает все роли, присутствующие в отношении.
`Map<ObjectName,List<String>>`	`getReferencedMBeans()`	Получает MBean, на которые ссылаются различные роли отношения.
`String`	`getRelationId()`	Возвращает идентификатор отношения (используется для уникальной идентификации отношения внутри службы отношений).
`ObjectName`	`getRelationServiceName()`	Возвращает имя объекта ObjectName службы отношений, обрабатывающей отношение.
`String`	`getRelationTypeName()`	Возвращает имя связанного типа отношения.
`List<ObjectName>`	`getRole(String roleName)`	Получает значение роли для заданного имени роли.
`Integer`	`getRoleCardinality(String roleName)`	Возвращает количество MBean, которые в данный момент ссылаются на заданную роль.
`RoleResult`	`getRoles(String[] roleNameArray)`	Получает значения ролей с заданными именами.
`void`	`handleMBeanUnregistration(ObjectName objectName, String roleName)`	Обратный вызов, используемый службой отношений, когда MBean, на который ссылается роль, снимается с регистрации.
`Boolean`	`isInRelationService()`	Возвращает внутренний флаг, указывающий, обрабатывается ли объект службой отношений.
`void`	`postDeregister()`	Разрешает MBean выполнять любые необходимые операции после того, как он был снят с регистрации на сервере MBean.
`void`	`postRegister(Boolean registrationDone)`	Разрешает MBean выполнять любые необходимые операции после регистрации на сервере MBean или после того, как регистрация завершилась неудачно.
`void`	`preDeregister()`	Разрешает MBean выполнить любые операции, которые ему нужны перед тем, как он будет снят с регистрации на сервере MBean.
`ObjectName`	`preRegister(MBeanServer server, ObjectName name)`	Разрешает MBean выполнить любые операции, которые ему нужны перед тем, как он будет зарегистрирован на сервере MBean.
`RoleList`	`retrieveAllRoles()`	Возвращает все роли в отношении без проверки режима чтения.
`void`	`setRelationServiceManagementFlag(Boolean flag)`	Указывает, обрабатывается ли это отношение службой отношений.
`void`	`setRole(Role role)`	Устанавливает заданную роль.
`RoleResult`	`setRoles(RoleList list)`	Устанавливает заданные роли.

Методы, объявленные в классе java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

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

RelationSupport

public RelationSupport(String relationId, ObjectName relationServiceName, String relationTypeName, RoleList list) throws InvalidRoleValueException, IllegalArgumentException

Создаёт объект RelationSupport.

Этот конструктор необходимо использовать, когда объект RelationSupport будет зарегистрирован как MBean пользователем или при создании пользовательского MBean отношения, класс которого расширяет RelationSupport.

На уровне сервиса отношений ничего не выполняется, т. е. объект RelationSupport не добавляется в RelationService и не проверяется корректность предоставленных значений. Объект всегда создаётся, ЗА исключением случаев:

- любой из необходимых параметров null.

- одно и то же имя используется для двух ролей.

Чтобы объект RelationSupport обрабатывался как отношение, его необходимо добавить в сервис отношений, используя метод addRelation() сервиса отношений.

Параметры:: relationId - идентификатор отношения для его идентификации в сервисе отношений.
Ожидается уникальность в данном сервисе отношений.; relationServiceName - ObjectName сервиса отношений, в котором будет зарегистрировано отношение.
Этот параметр обязателен, так как именно сервис отношений осведомлён о определении типа отношения данного отношения, чтобы иметь возможность проверять операции обновления (set).; relationTypeName - имя типа отношения.
Ожидается, что оно уже создано в данном сервисе отношений.; list - список ролей (объекты Role) для инициализации отношения. Может быть null.
Ожидается соответствие информации об отношении в соответствующем типе отношения.
Исключения:: InvalidRoleValueException - если одно и то же имя используется для двух ролей.; IllegalArgumentException - если любой из необходимых параметров (идентификатор отношения, ObjectName сервиса отношений или имя типа отношения) null.

RelationSupport

public RelationSupport(String relationId, ObjectName relationServiceName, MBeanServer relationServiceMBeanServer, String relationTypeName, RoleList list) throws InvalidRoleValueException, IllegalArgumentException

Создаёт объект RelationSupport.

Этот конструктор необходимо использовать, когда пользовательский MBean отношения реализует интерфейсы, ожидаемые от поддерживаемого отношения, делегируя задачу объекту RelationSupport.

Данному объекту необходим сервис отношений, который ожидает обработки отношения. Поэтому он должен знать сервер MBean, в котором зарегистрирован сервис отношений.

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

- любой из необходимых параметров null.

- одно и то же имя используется для двух ролей.

Параметры:: relationId - идентификатор отношения для его идентификации в сервисе отношений.
Ожидается уникальность в данном сервисе отношений.; relationServiceName - ObjectName сервиса отношений, в котором будет зарегистрировано отношение.
Этот параметр обязателен, так как именно сервис отношений осведомлён о определении типа отношения данного отношения, чтобы иметь возможность проверять операции обновления (set).; relationServiceMBeanServer - сервер MBean, где зарегистрирован или будет зарегистрирован обернутый MBean.
Ожидается, что это сервер MBean, где зарегистрирован или будет зарегистрирован сервис отношений.; relationTypeName - имя типа отношения.
Ожидается, что оно уже создано в данном сервисе отношений.; list - список ролей (объекты Role) для инициализации отношения. Может быть null.
Ожидается соответствие информации об отношении в соответствующем типе отношения.
Исключения:: InvalidRoleValueException - если одно и то же имя используется для двух ролей.; IllegalArgumentException - если любой из необходимых параметров (идентификатор отношения, ObjectName сервиса отношений, сервер MBean сервиса отношений или имя типа отношения) null.

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

getRole

public List<ObjectName> getRole(String roleName) throws IllegalArgumentException, RoleNotFoundException, RelationServiceNotRegisteredException

Возвращает значение роли для заданного имени роли.

Проверяет существование роли и её читаемость в соответствии с типом отношения.

Унаследовано от:

getRole в интерфейсе Relation

Параметры:

roleName - имя роли

Возвращает:

список ArrayList объектов ObjectName, являющихся значением роли

Исключения:

IllegalArgumentException - если имя роли null

RoleNotFoundException - если:

- роли с заданным именем нет

- роль недоступна для чтения.

RelationServiceNotRegisteredException - если сервис отношений не зарегистрирован в сервере MBean

См. также:

getRoles

public RoleResult getRoles(String[] roleNameArray) throws IllegalArgumentException, RelationServiceNotRegisteredException

Возвращает значения ролей с заданными именами.

Для каждой роли проверяется её существование и читаемость в соответствии с типом отношения.

Унаследовано от:

getRoles в интерфейсе Relation

Параметры:

roleNameArray - массив имён ролей для извлечения

Возвращает:

объект RoleResult, включающий RoleList (для успешно извлечённых ролей) и RoleUnresolvedList (для ролей, которые не были извлечены).

Исключения:

IllegalArgumentException - если имя роли null

RelationServiceNotRegisteredException - если сервис отношений не зарегистрирован в сервере MBean

См. также:

getAllRoles

public RoleResult getAllRoles() throws RelationServiceNotRegisteredException

Возвращает все роли, присутствующие в отношении.

Унаследовано от:: getAllRoles в интерфейсе Relation
Возвращает:: объект RoleResult, содержащий RoleList (для успешно извлеченных ролей) и RoleUnresolvedList (для ролей, недоступных для чтения).
Исключения:: RelationServiceNotRegisteredException - если сервис отношений не зарегистрирован в сервере MBean

retrieveAllRoles

public RoleList retrieveAllRoles()

Возвращает все роли в отношении без проверки режима чтения.

Унаследовано от:: retrieveAllRoles в интерфейсе Relation
Возвращает:: RoleList

getRoleCardinality

public Integer getRoleCardinality(String roleName) throws IllegalArgumentException, RoleNotFoundException

Возвращает количество MBean, текущих ссылаемых в заданной роли.

Унаследовано от:: getRoleCardinality в интерфейсе Relation
Параметры:: roleName - имя роли
Возвращает:: количество текущих ссылаемых MBean в данной роли
Исключения:: IllegalArgumentException - если имя роли null; RoleNotFoundException - если роли с заданным именем нет

setRole

public void setRole(Role role) throws IllegalArgumentException, RoleNotFoundException, RelationTypeNotFoundException, InvalidRoleValueException, RelationServiceNotRegisteredException, RelationNotFoundException

Устанавливает заданную роль.

Проверит роль согласно её определению, предоставленному в типе отношения

Отправит уведомление (RelationNotification с типом RELATION_BASIC_UPDATE или RELATION_MBEAN_UPDATE, в зависимости от того, является ли отношение MBean или нет).

Унаследовано от:

setRole в интерфейсе Relation

Параметры:

role - роль для установки (имя и новое значение)

Исключения:

IllegalArgumentException - если роль null

RoleNotFoundException - если роли с заданным именем нет или роль недоступна для записи (проверка доступа к записи не выполняется при инициализации роли)

InvalidRoleValueException - если предоставленное значение для роли некорректно, т.е.:

- количество ссылаемых MBean в данном значении меньше ожидаемого минимального степени

- количество ссылаемых MBean в предоставленном значении превышает ожидаемую максимальную степень

- один из ссылаемых MBean в значении не является объектом ожидаемого класса MBean для этой роли

- предоставленный MBean для этой роли не существует

RelationServiceNotRegisteredException - если сервис отношений не зарегистрирован в сервере MBean

RelationTypeNotFoundException - если тип отношения не объявлен в сервисе отношений

RelationNotFoundException - если отношение не добавлено в сервис отношений.

См. также:

setRoles

public RoleResult setRoles(RoleList list) throws IllegalArgumentException, RelationServiceNotRegisteredException, RelationTypeNotFoundException, RelationNotFoundException

Устанавливает заданные роли.

Проверит роль согласно её определению, предоставленному в типе отношения

Отправит по одному уведомлению (RelationNotification с типом RELATION_BASIC_UPDATE или RELATION_MBEAN_UPDATE, в зависимости от того, является ли отношение MBean или нет) за каждую обновлённую роль.

Унаследовано от:

setRoles в интерфейсе Relation

Параметры:

list - список ролей для установки

Возвращает:

объект RoleResult, включающий RoleList (для успешно установленных ролей) и RoleUnresolvedList (для ролей, которые не были установлены).

Исключения:

IllegalArgumentException - если список ролей null

RelationServiceNotRegisteredException - если сервис отношений не зарегистрирован в сервере MBean

RelationTypeNotFoundException - если тип отношения не объявлен в сервисе отношений.

RelationNotFoundException - если MBean отношения не добавлен в сервис отношений.

См. также:

Обработка отмены регистрации MBean

public void handleMBeanUnregistration(ObjectName objectName, String roleName) throws IllegalArgumentException, RoleNotFoundException, InvalidRoleValueException, RelationServiceNotRegisteredException, RelationTypeNotFoundException, RelationNotFoundException

Обратный вызов, используемый службой Relation при отмене регистрации MBean, указанного в роли.

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

ВНИМАНИЕ. Пользователь не должен вызывать этот метод.

Текущая реализация заключается в установке роли со своим текущим значением (списком ObjectName зарегистрированных ссылаемых MBean) без отмененного.

Указано в:: handleMBeanUnregistration в интерфейсе Relation
Параметры:: objectName - ObjectName отмененного MBean; roleName - имя роли, где ссылается на MBean
Исключение:: IllegalArgumentException - если параметр null; RoleNotFoundException - если роль не существует в связи или не доступна для записи; InvalidRoleValueException - если значение роли не соответствует связанной информации о роли (это никогда не произойдет при вызове из службы Relation); RelationServiceNotRegisteredException - если служба Relation не зарегистрирована в сервере MBean; RelationTypeNotFoundException - если тип связи не объявлен в службе Relation.; RelationNotFoundException - если этот метод вызывается для MBean связи, не добавленной в службу Relation.

getReferencedMBeans

public Map<ObjectName,List<String>> getReferencedMBeans()

Возвращает MBeans, на которые ссылаются различные роли связи.

Указано в:: getReferencedMBeans в интерфейсе Relation
Возвращает:: a HashMap отображающее:
ObjectName -> ArrayList имен ролей

getRelationTypeName

public String getRelationTypeName()

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

Указано в:: getRelationTypeName в интерфейсе Relation
Возвращает:: имя типа связи.

getRelationServiceName

public ObjectName getRelationServiceName()

Возвращает ObjectName службы Relation, обрабатывающей связь.

Указано в:: getRelationServiceName в интерфейсе Relation
Возвращает:: ObjectName службы Relation.

getRelationId

public String getRelationId()

Возвращает идентификатор связи (используется для уникальной идентификации связи внутри службы Relation).

Указано в:: getRelationId в интерфейсе Relation
Возвращает:: идентификатор связи.

preRegister

public ObjectName preRegister(MBeanServer server, ObjectName name) throws Exception

Описание скопировано из интерфейса: MBeanRegistration

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

Указано в:: preRegister в интерфейсе MBeanRegistration
Параметры:: server - сервер MBean, в котором будет зарегистрирован MBean.; name - имя объекта MBean. Это значение null, если параметр name для одного из createMBean или registerMBean методов в интерфейсе MBeanServer равен null. В этом случае этот метод должен вернуть non-null ObjectName для нового MBean.
Возвращает:: Имя, под которым должен быть зарегистрирован MBean. Это значение не должно быть null. Если параметр name не null, это обычно, но не обязательно, возвращаемое значение.
Исключение:: Exception - Это исключение будет перехвачено сервером MBean и повторно выброшено как MBeanRegistrationException.

postRegister

public void postRegister(Boolean registrationDone)

Описание скопировано из интерфейса: MBeanRegistration

Позволяет MBean выполнить любые необходимые операции после регистрации в сервере MBean или после того, как регистрация завершилась неудачно.

Если реализация этого метода вызывает RuntimeException или Error, сервер MBean повторно выбросит их внутри RuntimeMBeanException или RuntimeErrorException соответственно. Однако, выброс исключения в postRegister не изменит состояние MBean: если MBean уже зарегистрирован (registrationDone равно true), MBean останется зарегистрированным.

Это может быть запутанным для кода, вызывающего createMBean() или registerMBean(), так как такой код может предположить, что регистрация MBean завершилась неудачно, когда такое исключение возникает. Поэтому рекомендуется, чтобы реализации postRegister не генерировали исключения Runtime или ошибки, если это возможно.

Указано в:: postRegister в интерфейсе MBeanRegistration
Параметры:: registrationDone - Указывает, зарегистрирован ли MBean в сервере MBean успешно. Значение false означает, что фаза регистрации завершилась неудачно.

preDeregister

public void preDeregister() throws Exception

Описание скопировано из интерфейса: MBeanRegistration

Позволяет MBean выполнить любые операции, необходимые перед его отченой регистрации сервером MBean.

Указано в:: preDeregister в интерфейсе MBeanRegistration
Исключение:: Exception - Это исключение будет перехвачено сервером MBean и повторно выброшено как MBeanRegistrationException.

postDeregister

public void postDeregister()

Описание скопировано из интерфейса: MBeanRegistration

Позволяет MBean выполнить любые необходимые операции после отмены регистрации в сервере MBean.

Если реализация этого метода вызывает RuntimeException или Error, сервер MBean повторно выбросит их внутри RuntimeMBeanException или RuntimeErrorException соответственно. Однако, выброс исключения в postDeregister не изменит состояние MBean: MBean уже успешно был дезарегистрован и останется таким.

Это может быть запутанным для кода, вызывающего unregisterMBean(), так как он может предположить, что отмена регистрации MBean завершилась неудачно. Поэтому рекомендуется, чтобы реализации postDeregister не генерировали исключения Runtime или ошибки, если это возможно.

Указано в:: postDeregister в интерфейсе MBeanRegistration

isInRelationService

public Boolean isInRelationService()

Возвращает внутренний флаг, указывающий, обрабатывает ли объект служба Relation.

Указано в:: isInRelationService в интерфейсе RelationSupportMBean
Возвращает:: булево значение, равное Boolean.TRUE, если объект все еще обрабатывается службой Relation, и Boolean.FALSE в противном случае.

setRelationServiceManagementFlag

public void setRelationServiceManagementFlag(Boolean flag) throws IllegalArgumentException

Описание скопировано из интерфейса: RelationSupportMBean

Указывает, обрабатывается ли эта связь службой Relation.

ВНИМАНИЕ, этот метод должен быть доступен, так как служба Relation будет обращаться к связи через свой интерфейс управления. РЕКОМЕНДУЕТСЯ НЕ использовать этот метод. Его использование не влияет на регистрацию объекта связи в службе Relation, но предоставит неверную информацию о нем!

Указано в:: setRelationServiceManagementFlag в интерфейсе RelationSupportMBean
Параметры:: flag - обрабатывается ли связь службой Relation.
Исключение:: IllegalArgumentException - если параметр null

© 1993, 2023, 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/21/docs/api/java.management/javax/management/relation/RelationSupport.html