13.2 Operations of the Relation Service

In addition to the creation and removal methods for relation types and instances, the relation service provides operations for finding related MBeans, determining the role of a given MBean, and accessing the MBeans of a given role or relation.

13.2.1 Query Operations

Once relations have been defined, the relation service allows you to do searches based on the association of objects that the relations represent. The following operations perform queries on the relations:

• findAssociatedMBeans: Returns a list of all object names referenced in any relation where a given object name appears; each of these object names is mapped to the list of relation identifiers where the two MBeans are related, since the pair can be related through different relation instances.

  Two optional parameters let you specify a relation type and role name. When either or both of these are specified, the only relations to be considered are those of the given type and/or where the given object name appears in the named role.

• findReferencingRelations: Takes an object name and returns the list of relation identifiers where it is referenced; each identifier is mapped to the list of roles in which the corresponding MBean appears in that relation; again, you can specify the relation type and/or role name in which the given MBean must appear.

• getReferencedMBeans: Returns a list of all MBeans currently in a given relation; their object names are mapped to the role names where they are referenced, since the same MBean can appear in more than one role of the same relation.

• findRelationsOfType: Returns the list of identifiers of all relations that were created or added with a given relation type.

• getRelationTypeName: This method is the inverse of the previous, returning the relation type name of the relation with a given identifier.

13.2.2 Accessing Roles

Once you have a relation identifier, you will probably want to access its role values. The relation service provides getters and setters for roles, as well as bulk operations to get or set several or all roles in a relation. Remember that the value of a role is a list of MBeans, and a role is identified by a name string.

Input parameters to setter operations are the same Role and RoleList classes that are used to create relations. Bulk getters and setters return a RoleResult object that contains separate lists for successful and failed individual role operations.

Inside a role result, the list of roles and values that were successfully accessed are given in a RoleList instance. The information about roles that could not be read or written is returned in a RoleUnresolvedList. This list contains RoleUnresolved objects that name the role that could not be accessed and an error code explaining the reason, such as an invalid role name or the wrong cardinality for a role. The error codes are defined as static final fields in the RoleStatus class.

13.2.3 Maintaining Consistency

All relation service operations that set the role of a relation always verify that the role value fulfills its definition in the relation type. An incorrect MBean type, the wrong cardinality of the role, or an unknown role name will prevent that role from being modified, guaranteeing that the relation always fulfills it relation type.

As we shall see in 13.3 Objects Representing Relations, relations and relation types can also be objects that are external to the relation service. In this case, they are responsible for maintaining their own role-consistency. The relation service MBean exposes methods to assist these objects in verifying that their roles conform to their defined relation type. In all cases of an external implementation of a relation, the object designer is responsible for ensuring its coherence.

Removing a relation type can cause existing relations to cease to have a defining type. The policy of the removeRelationType operation is to assume that the caller is aware of existing relations of the given type. Instead of forbidding the operation, this method removes the relations that were defined by the given type. It is the designer's responsibility to first call the findRelationsOfType operation to determine if any existing relations will be affected.

MBeans participating in a relation can be removed from the MBean server by some other management operation, thereby modifying the cardinality of a role where they were referenced. In order to maintain consistency in this case, the relation service must remove all relations in which a role no longer has the cardinality defined in its relation type. The process of determining invalid relations and removing them is called purging.

The relation service listens for unregistration notifications of the MBean server delegate, and will need to purge its MBeans whenever one is received. It must determine if the MBean removed was involved in any relations, and if so, whether its removal violates the cardinality of each role where it appears. The relation service exposes the boolean PurgeFlag attribute that the programmer must set to determine whether purges are done automatically or not.

When the purge flag is true, the relation service will purge its data immediately after every unregistration notification. However, the purge operation can be resource intensive for large sets of relation data. In this case the managing application can set the purge flag to false and only call the purgeRelations operation to purge the data when needed.

For example, if there are many MBean unregistrations and few relation operations, it might make sense to only purge the relation service manually before each operation. Or the automatic purge flag can be temporarily set to false while executing time-critical operations that need to remove MBeans, but that will not access the relation service.

There are two possible consequences of an unpurged relation service. Roles in a relation can reference object names that no longer have an associated MBean. Or worse, the object name might have been reassigned to another MBean, leading to a totally incoherent state. The designer of the management solution is responsible for setting the purge policy so that operations will always access consistent relation values.

13.2.4 Relation Service Notifications

The relation service is a notification broadcaster that notifies listeners of events affecting relations. It sends RelationNotification objects in the following cases:

• A new relation is created: The notification contains its identifier and its relation type

• An existing relation is updated: In addition to the relation identifier and type, the notification contains the list of names, the list of new values, and the list of old values for all roles that have been modified

• A relation is removed: The notification contains its identifier and its relation type

There are three equivalent notification types for events affecting relations defined as external MBeans (see 13.3 Objects Representing Relations). In addition to the role and relation information, these notifications contain the object name of this MBean.