javax.management.relation
Class RelationService

java.lang.Object
  |
  +--javax.management.NotificationBroadcasterSupport
        |
        +--javax.management.relation.RelationService
All Implemented Interfaces:
java.util.EventListener, MBeanRegistration, NotificationBroadcaster, NotificationListener, RelationServiceMBean

public class RelationService
extends NotificationBroadcasterSupport
implements RelationServiceMBean, MBeanRegistration, NotificationListener

An MBean that maintains the consistency of all relation types and all relation instances within a JMX agent. It provides query operations to fins related and associated mbeans and their roles in the relation.


Constructor Summary
RelationService(boolean purgeFlag)
          constructor
 
Method Summary
 void addRelation(javax.management.ObjectName relationMBeanObjectName)
          Add relation of a class that extends RelationSupport, is an external relation and can only be created with this method createRelation() is for internal relations only
 void addRelationType(javax.management.relation.RelationType relationType)
           
 java.lang.Integer checkRoleReading(java.lang.String roleName, java.lang.String relationTypeName)
           
 java.lang.Integer checkRoleWriting(javax.management.relation.Role role, java.lang.String relationTypeName, java.lang.Boolean isInitialized)
           
 void createRelation(java.lang.String relationId, java.lang.String relationTypeName, javax.management.relation.RoleList roleList)
           
 void createRelationType(java.lang.String relationTypeName, javax.management.relation.RoleInfo[] roleInfos)
           
 java.util.Map findAssociatedMBeans(javax.management.ObjectName mbeanObjectName, java.lang.String relationTypeName, java.lang.String roleName)
           
 java.util.Map findReferencingRelations(javax.management.ObjectName mbeanObjectName, java.lang.String relationTypeName, java.lang.String roleName)
           
 java.util.List findRelationsOfType(java.lang.String relationTypeName)
           
 java.util.List getAllRelationIds()
           
 java.util.List getAllRelationTypeNames()
           
 javax.management.relation.RoleResult getAllRoles(java.lang.String relationId)
           
 javax.management.MBeanNotificationInfo[] getNotificationInfo()
          Implement to return more info regarding Notification Types
 boolean getPurgeFlag()
           
 java.util.Map getReferencedMBeans(java.lang.String relationId)
           
 java.lang.String getRelationTypeName(java.lang.String relationId)
           
 java.util.List getRole(java.lang.String relationId, java.lang.String roleName)
           
 java.lang.Integer getRoleCardinality(java.lang.String relationId, java.lang.String roleName)
           
 javax.management.relation.RoleInfo getRoleInfo(java.lang.String relationTypeName, java.lang.String roleInfoName)
           
 java.util.List getRoleInfos(java.lang.String relationTypeName)
           
 javax.management.relation.RoleResult getRoles(java.lang.String relationId, java.lang.String[] roleNames)
           
 void handleNotification(javax.management.Notification notification, java.lang.Object handback)
          Called when a notification occurs.
 java.lang.Boolean hasRelation(java.lang.String relationId)
           
 void isActive()
           
 java.lang.String isRelation(javax.management.ObjectName objectName)
           
 javax.management.ObjectName isRelationMBean(java.lang.String relationId)
           
 void postDeregister()
          Called upon after the MBean has been de-registered.
 void postRegister(java.lang.Boolean registrationDone)
          Called upon after a registration ( successful or not ).
 void preDeregister()
          Called upon before an MBean will be de-registered by the MBeanServer.
 javax.management.ObjectName preRegister(javax.management.MBeanServer server, javax.management.ObjectName name)
          Allows the MBean to perform any operations before being registered to the MBeanServer.
 void purgeRelations()
           
 void removeRelation(java.lang.String relationId)
           
 void removeRelationType(java.lang.String relationTypeName)
           
 void sendRelationCreationNotification(java.lang.String relationId)
           
 void sendRelationRemovalNotification(java.lang.String relationId, java.util.List unregisteredMBeanList)
           
 void sendRoleUpdateNotification(java.lang.String relationId, javax.management.relation.Role newRole, java.util.List oldRoleValues)
           
 void setPurgeFlag(boolean purgeFlag)
           
 void setRole(java.lang.String relationId, javax.management.relation.Role role)
           
 javax.management.relation.RoleResult setRoles(java.lang.String relationId, javax.management.relation.RoleList roleList)
           
 void updateRoleMap(java.lang.String relationId, javax.management.relation.Role role, java.util.List oldRoleValues)
          Handles update of the RelationService role map for the update of given roles in a given relation
 
Methods inherited from class javax.management.NotificationBroadcasterSupport
addNotificationListener, removeNotificationListener, sendNotification
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

RelationService

public RelationService(boolean purgeFlag)
constructor

Parameters:
purgeFlag - - this is a flag, if true indicates an immediate update of relations is to be done when a notification is recieved for the unregistration of an MBean referenced in a relation - if false update of relations must be performed explicitly by calling purgeRelations()
See Also:
purgeRelations()
Method Detail

isActive

public void isActive()
              throws RelationServiceNotRegisteredException
Specified by:
isActive in interface RelationServiceMBean
Throws:
RelationServiceNotRegisteredException - - thrown if the RelationService is not registered in the MBeanServer

Currently this class must be registered in the MBeanServer before any relations can be created or added


getPurgeFlag

public boolean getPurgeFlag()
Specified by:
getPurgeFlag in interface RelationServiceMBean
Returns:
true - if the purgeFlag has been set, false if updates of a relation must be called explicitly
See Also:
purgeRelations()

setPurgeFlag

public void setPurgeFlag(boolean purgeFlag)
Specified by:
setPurgeFlag in interface RelationServiceMBean
Parameters:
purgeFlag - - a flag that when set to true indicates to the RelationService that it must update all relations when it recieves a unregistration notification if false this will not occur and purgeRelations must be called explicitly

createRelationType

public void createRelationType(java.lang.String relationTypeName,
                               javax.management.relation.RoleInfo[] roleInfos)
                        throws java.lang.IllegalArgumentException,
                               InvalidRelationTypeException
Specified by:
createRelationType in interface RelationServiceMBean
Parameters:
relationTypeName - - a string giving relations a type name this must be a unique name
Throws:
java.lang.IllegalArgumentException - thrown if any of the parameters are null
InvalidRelationTypeException - thrown if the role name, contained in the RoleInfo, already exists.

This method creates a relationType (a RelationTypeSupport Object) from the parameters passed in.

The RelationTypeSupport represents an internal relation


addRelationType

public void addRelationType(javax.management.relation.RelationType relationType)
                     throws java.lang.IllegalArgumentException,
                            InvalidRelationTypeException
Specified by:
addRelationType in interface RelationServiceMBean
Parameters:
relationType - - an Object implementing the RelationType interface a utility implementation is provided by the RelationTypeSupport class
Throws:
java.lang.IllegalArgumentException - if a null RelationType is passed in as a parameter or if that RelationType has no RoleInfo defined
InvalidRelationTypeException - if the RoleInfo obtained from the RelationType is - empty - null - the RoleName is already in use

This method makes an externally defined relation type available through the relationService

The RelationType is immutable, hence the returned values should never change while the relationType is registered with the realtion service


getAllRelationTypeNames

public java.util.List getAllRelationTypeNames()
Specified by:
getAllRelationTypeNames in interface RelationServiceMBean
Returns:
a list containing all the relationTypeNames registered with the relation service

getRoleInfos

public java.util.List getRoleInfos(java.lang.String relationTypeName)
                            throws java.lang.IllegalArgumentException,
                                   RelationTypeNotFoundException
Specified by:
getRoleInfos in interface RelationServiceMBean
Parameters:
relationTypeName - the string name representation of this RelationType
Returns:
List containing the RoleInfos for this RelationType Object
Throws:
java.lang.IllegalArgumentException - if the relationTypeName is null
RelationTypeNotFoundException - if the Relationtype for the given relationTypeName is not found

getRoleInfo

public javax.management.relation.RoleInfo getRoleInfo(java.lang.String relationTypeName,
                                                      java.lang.String roleInfoName)
                                               throws java.lang.IllegalArgumentException,
                                                      RelationTypeNotFoundException,
                                                      RoleInfoNotFoundException
Specified by:
getRoleInfo in interface RelationServiceMBean
Parameters:
relationTypeName - string name representing the RelationType
roleInfoName - string name representing the RoleInfo object
Returns:
the corresponding RoleInfo Object for the given parameters
Throws:
java.lang.IllegalArgumentException - if either the relationtypeName or the roleInfoName is null
RelationTypeNotFoundException - if the RelationType is not in the realtion service
RoleInfoNotFoundException - if the RoleInfo has not been found

removeRelationType

public void removeRelationType(java.lang.String relationTypeName)
                        throws java.lang.IllegalArgumentException,
                               RelationServiceNotRegisteredException,
                               RelationTypeNotFoundException
Specified by:
removeRelationType in interface RelationServiceMBean
Parameters:
relationTypeName - a string name representing the Relationtype Object
Throws:
java.lang.IllegalArgumentException - if the relationTypeName is null
RelationServiceNotRegisteredException - if the RelationService has not been registered in the MBeanServer
RelationTypeNotFoundException - if the RelationType has not been found

This method removes a RelationType, it's name(represented by the relationTypeName) and any relationIds associated with it, and all MBeans referenced in it's roles

Note: this will not remove any mbeans registered with the MBeanServer this must be done if required via the MBeanServer. Any Mbeans registered with the MBean server will continue to be accessed via the MBeanServer, they will no longer be able to be referenced, queried via the relation service though.


createRelation

public void createRelation(java.lang.String relationId,
                           java.lang.String relationTypeName,
                           javax.management.relation.RoleList roleList)
                    throws java.lang.IllegalArgumentException,
                           RelationServiceNotRegisteredException,
                           RoleNotFoundException,
                           InvalidRelationIdException,
                           RelationTypeNotFoundException,
                           InvalidRoleValueException
Specified by:
createRelation in interface RelationServiceMBean
Parameters:
relationId - the id through which this relation is referenced
relationTypeName - a unique name for the RelationType
roleList - a list of roles to be associated with this relation
Throws:
java.lang.IllegalArgumentException - - if the relationId, or relationTypeName is null
RelationServiceNotRegisteredException - - if the relationService has not been registered in the MBeanServer
RoleNotFoundException - - if a role defined in the RoleList is null or empty
InvalidRelationIdException - if the relationId is already in use.
RelationTypeNotFoundException
InvalidRoleValueException - - if cardinality is not correct i.e min cardinality is greater than max cardinality

According to the RI spec this method is used only to create internal relations - hence creates an InternalRelation

This creates a relation represented by a RelationSupport Object, and a RelationNotification, with type RELATION_BASIC_CREATION, is sent


addRelation

public void addRelation(javax.management.ObjectName relationMBeanObjectName)
                 throws java.lang.IllegalArgumentException,
                        RelationServiceNotRegisteredException,
                        java.lang.NoSuchMethodException,
                        InvalidRelationIdException,
                        InstanceNotFoundException,
                        InvalidRelationServiceException,
                        RelationTypeNotFoundException,
                        RoleNotFoundException,
                        InvalidRoleValueException
Add relation of a class that extends RelationSupport, is an external relation and can only be created with this method createRelation() is for internal relations only

Specified by:
addRelation in interface RelationServiceMBean
java.lang.IllegalArgumentException
RelationServiceNotRegisteredException
java.lang.NoSuchMethodException
InvalidRelationIdException
InstanceNotFoundException
InvalidRelationServiceException
RelationTypeNotFoundException
RoleNotFoundException
InvalidRoleValueException

isRelationMBean

public javax.management.ObjectName isRelationMBean(java.lang.String relationId)
                                            throws java.lang.IllegalArgumentException,
                                                   RelationNotFoundException
Specified by:
isRelationMBean in interface RelationServiceMBean
java.lang.IllegalArgumentException
RelationNotFoundException

isRelation

public java.lang.String isRelation(javax.management.ObjectName objectName)
                            throws java.lang.IllegalArgumentException
Specified by:
isRelation in interface RelationServiceMBean
java.lang.IllegalArgumentException

hasRelation

public java.lang.Boolean hasRelation(java.lang.String relationId)
                              throws java.lang.IllegalArgumentException
Specified by:
hasRelation in interface RelationServiceMBean
java.lang.IllegalArgumentException

getAllRelationIds

public java.util.List getAllRelationIds()
Specified by:
getAllRelationIds in interface RelationServiceMBean

checkRoleReading

public java.lang.Integer checkRoleReading(java.lang.String roleName,
                                          java.lang.String relationTypeName)
                                   throws java.lang.IllegalArgumentException,
                                          RelationTypeNotFoundException
Specified by:
checkRoleReading in interface RelationServiceMBean
java.lang.IllegalArgumentException
RelationTypeNotFoundException

checkRoleWriting

public java.lang.Integer checkRoleWriting(javax.management.relation.Role role,
                                          java.lang.String relationTypeName,
                                          java.lang.Boolean isInitialized)
                                   throws java.lang.IllegalArgumentException,
                                          RelationTypeNotFoundException
Specified by:
checkRoleWriting in interface RelationServiceMBean
java.lang.IllegalArgumentException
RelationTypeNotFoundException

sendRelationCreationNotification

public void sendRelationCreationNotification(java.lang.String relationId)
                                      throws java.lang.IllegalArgumentException,
                                             RelationNotFoundException
Specified by:
sendRelationCreationNotification in interface RelationServiceMBean
java.lang.IllegalArgumentException
RelationNotFoundException

sendRoleUpdateNotification

public void sendRoleUpdateNotification(java.lang.String relationId,
                                       javax.management.relation.Role newRole,
                                       java.util.List oldRoleValues)
                                throws java.lang.IllegalArgumentException,
                                       RelationNotFoundException
Specified by:
sendRoleUpdateNotification in interface RelationServiceMBean
java.lang.IllegalArgumentException
RelationNotFoundException

sendRelationRemovalNotification

public void sendRelationRemovalNotification(java.lang.String relationId,
                                            java.util.List unregisteredMBeanList)
                                     throws java.lang.IllegalArgumentException,
                                            RelationNotFoundException
Specified by:
sendRelationRemovalNotification in interface RelationServiceMBean
java.lang.IllegalArgumentException
RelationNotFoundException

updateRoleMap

public void updateRoleMap(java.lang.String relationId,
                          javax.management.relation.Role role,
                          java.util.List oldRoleValues)
                   throws java.lang.IllegalArgumentException,
                          RelationServiceNotRegisteredException,
                          RelationNotFoundException
Handles update of the RelationService role map for the update of given roles in a given relation

Specified by:
updateRoleMap in interface RelationServiceMBean
java.lang.IllegalArgumentException
RelationServiceNotRegisteredException
RelationNotFoundException

removeRelation

public void removeRelation(java.lang.String relationId)
                    throws java.lang.IllegalArgumentException,
                           RelationServiceNotRegisteredException,
                           RelationNotFoundException
Specified by:
removeRelation in interface RelationServiceMBean
java.lang.IllegalArgumentException
RelationServiceNotRegisteredException
RelationNotFoundException

purgeRelations

public void purgeRelations()
                    throws RelationServiceNotRegisteredException
Specified by:
purgeRelations in interface RelationServiceMBean
RelationServiceNotRegisteredException

findReferencingRelations

public java.util.Map findReferencingRelations(javax.management.ObjectName mbeanObjectName,
                                              java.lang.String relationTypeName,
                                              java.lang.String roleName)
                                       throws java.lang.IllegalArgumentException
Specified by:
findReferencingRelations in interface RelationServiceMBean
java.lang.IllegalArgumentException

findAssociatedMBeans

public java.util.Map findAssociatedMBeans(javax.management.ObjectName mbeanObjectName,
                                          java.lang.String relationTypeName,
                                          java.lang.String roleName)
                                   throws java.lang.IllegalArgumentException
Specified by:
findAssociatedMBeans in interface RelationServiceMBean
java.lang.IllegalArgumentException

findRelationsOfType

public java.util.List findRelationsOfType(java.lang.String relationTypeName)
                                   throws java.lang.IllegalArgumentException,
                                          RelationTypeNotFoundException
Specified by:
findRelationsOfType in interface RelationServiceMBean
java.lang.IllegalArgumentException
RelationTypeNotFoundException

getRole

public java.util.List getRole(java.lang.String relationId,
                              java.lang.String roleName)
                       throws java.lang.IllegalArgumentException,
                              RelationServiceNotRegisteredException,
                              RelationNotFoundException,
                              RoleNotFoundException
Specified by:
getRole in interface RelationServiceMBean
java.lang.IllegalArgumentException
RelationServiceNotRegisteredException
RelationNotFoundException
RoleNotFoundException

getRoles

public javax.management.relation.RoleResult getRoles(java.lang.String relationId,
                                                     java.lang.String[] roleNames)
                                              throws java.lang.IllegalArgumentException,
                                                     RelationNotFoundException,
                                                     RelationServiceNotRegisteredException
Specified by:
getRoles in interface RelationServiceMBean
java.lang.IllegalArgumentException
RelationNotFoundException
RelationServiceNotRegisteredException

getAllRoles

public javax.management.relation.RoleResult getAllRoles(java.lang.String relationId)
                                                 throws java.lang.IllegalArgumentException,
                                                        RelationNotFoundException,
                                                        RelationServiceNotRegisteredException
Specified by:
getAllRoles in interface RelationServiceMBean
java.lang.IllegalArgumentException
RelationNotFoundException
RelationServiceNotRegisteredException

getRoleCardinality

public java.lang.Integer getRoleCardinality(java.lang.String relationId,
                                            java.lang.String roleName)
                                     throws java.lang.IllegalArgumentException,
                                            RelationNotFoundException,
                                            RoleNotFoundException
Specified by:
getRoleCardinality in interface RelationServiceMBean
java.lang.IllegalArgumentException
RelationNotFoundException
RoleNotFoundException

setRole

public void setRole(java.lang.String relationId,
                    javax.management.relation.Role role)
             throws java.lang.IllegalArgumentException,
                    RelationServiceNotRegisteredException,
                    RelationNotFoundException,
                    RoleNotFoundException,
                    InvalidRoleValueException,
                    RelationTypeNotFoundException
Specified by:
setRole in interface RelationServiceMBean
java.lang.IllegalArgumentException
RelationServiceNotRegisteredException
RelationNotFoundException
RoleNotFoundException
InvalidRoleValueException
RelationTypeNotFoundException

setRoles

public javax.management.relation.RoleResult setRoles(java.lang.String relationId,
                                                     javax.management.relation.RoleList roleList)
                                              throws RelationServiceNotRegisteredException,
                                                     java.lang.IllegalArgumentException,
                                                     RelationNotFoundException
Specified by:
setRoles in interface RelationServiceMBean
RelationServiceNotRegisteredException
java.lang.IllegalArgumentException
RelationNotFoundException

getReferencedMBeans

public java.util.Map getReferencedMBeans(java.lang.String relationId)
                                  throws java.lang.IllegalArgumentException,
                                         RelationNotFoundException
Specified by:
getReferencedMBeans in interface RelationServiceMBean
java.lang.IllegalArgumentException
RelationNotFoundException

getRelationTypeName

public java.lang.String getRelationTypeName(java.lang.String relationId)
                                     throws java.lang.IllegalArgumentException,
                                            RelationNotFoundException
Specified by:
getRelationTypeName in interface RelationServiceMBean
java.lang.IllegalArgumentException
RelationNotFoundException

handleNotification

public void handleNotification(javax.management.Notification notification,
                               java.lang.Object handback)
Description copied from interface: NotificationListener
Called when a notification occurs.

Specified by:
handleNotification in interface NotificationListener
Parameters:
notification - The notification object
handback - Helps in associating information regarding the listener.

getNotificationInfo

public javax.management.MBeanNotificationInfo[] getNotificationInfo()
Implement to return more info regarding Notification Types

Specified by:
getNotificationInfo in interface NotificationBroadcaster
Overrides:
getNotificationInfo in class NotificationBroadcasterSupport
Returns:
MBeanNotificationInfo The NotificationInfo

preRegister

public javax.management.ObjectName preRegister(javax.management.MBeanServer server,
                                               javax.management.ObjectName name)
                                        throws java.lang.Exception
Description copied from interface: MBeanRegistration
Allows the MBean to perform any operations before being registered to the MBeanServer.

Any exception will cause the MBean not being registered.

Specified by:
preRegister in interface MBeanRegistration
Parameters:
server - The MBeanServer on which the MBean will be registered.
name - The ObjectName of the MBean.
Returns:
ObjectName The name of the registered MBean
Throws:
java.lang.Exception - Exception of the operation. Note that this is caught by the MBeanServer and re-thrown as an MBeanRegistrationException.

postRegister

public void postRegister(java.lang.Boolean registrationDone)
Description copied from interface: MBeanRegistration
Called upon after a registration ( successful or not ).

Specified by:
postRegister in interface MBeanRegistration
Parameters:
registrationDone - Evaluates to true of the registrations is successful, false otherwise.

preDeregister

public void preDeregister()
                   throws java.lang.Exception
Description copied from interface: MBeanRegistration
Called upon before an MBean will be de-registered by the MBeanServer.

Specified by:
preDeregister in interface MBeanRegistration
Throws:
java.lang.Exception - Would be caught by the MBeanServer and rethrown as an MBeanRegistrationException.

postDeregister

public void postDeregister()
Description copied from interface: MBeanRegistration
Called upon after the MBean has been de-registered.

Specified by:
postDeregister in interface MBeanRegistration