Класс 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 — имя роли

Возвращает:

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

Исключения:

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

RoleNotFoundException — если:

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

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

RelationServiceNotRegisteredException — если служба отношений не зарегистрирована в сервере MBean

См. также:

setRole(javax.management.relation.Role)

getRoles

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

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

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

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

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

Параметры:

roleNameArray — массив имён ролей для получения

Возвращает:

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

Исключения:

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

RelationServiceNotRegisteredException — если служба отношений не зарегистрирована в сервере MBean

См. также:

setRoles(javax.management.relation.RoleList)

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 — если отношение не добавлено в службу отношений.

См. также:

getRole(java.lang.String)

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 отношения не добавлен в службу отношений.

См. также:

getRoles(java.lang.String[])

handleMBeanUnregistration

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

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

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

ВНИМАНИЕ. пользователю не следует вызывать этот метод.

Текущая реализация заключается в установке роли со значением её текущего состояния (список ObjectNames ссылающихся 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()

Извлекает MBean, на которые ссылаются различные роли связи.

Указано в:: 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. В этом случае этот метод должен вернуть 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, 2021, 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/17/docs/api/java.management/javax/management/relation/RelationSupport.html