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(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(RelationType relationType)
           
 java.lang.Integer checkRoleReading(java.lang.String roleName, java.lang.String relationTypeName)
           
 java.lang.Integer checkRoleWriting(Role role, java.lang.String relationTypeName, java.lang.Boolean isInitialized)
           
 void createRelation(java.lang.String relationId, java.lang.String relationTypeName, RoleList roleList)
           
 void createRelationType(java.lang.String relationTypeName, RoleInfo[] roleInfos)
           
 java.util.Map findAssociatedMBeans(ObjectName mbeanObjectName, java.lang.String relationTypeName, java.lang.String roleName)
           
 java.util.Map findReferencingRelations(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()
           
 RoleResult getAllRoles(java.lang.String relationId)
           
 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)
           
 RoleInfo getRoleInfo(java.lang.String relationTypeName, java.lang.String roleInfoName)
           
 java.util.List getRoleInfos(java.lang.String relationTypeName)
           
 RoleResult getRoles(java.lang.String relationId, java.lang.String[] roleNames)
           
 void handleNotification(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(ObjectName objectName)
           
 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.
 ObjectName preRegister(MBeanServer server, 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, Role newRole, java.util.List oldRoleValues)
           
 void setPurgeFlag(boolean purgeFlag)
           
 void setRole(java.lang.String relationId, Role role)
           
 RoleResult setRoles(java.lang.String relationId, RoleList roleList)
           
 void updateRoleMap(java.lang.String relationId, 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,
                               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
roleInfo[] - - an array of RoleInfo objects. Which are used to define the roles a relation plays a part in. It defines attributes such as cardinality, role reading and writing... The RelationService will then use these RoleInfo to maintain the relation
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(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 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,
                           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(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

isRelationMBean

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

isRelation

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

hasRelation

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

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

checkRoleWriting

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

sendRelationCreationNotification

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

sendRoleUpdateNotification

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

sendRelationRemovalNotification

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

updateRoleMap

public void updateRoleMap(java.lang.String relationId,
                          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

removeRelation

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

purgeRelations

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

findReferencingRelations

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

findAssociatedMBeans

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

findRelationsOfType

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

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

getRoles

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

getAllRoles

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

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

setRole

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

setRoles

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

getReferencedMBeans

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

getRelationTypeName

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

handleNotification

public void handleNotification(Notification notification,
                               java.lang.Object handback)
Description copied from interface: NotificationListener
Called when a notification occurs.
Specified by:
handleNotification in interface NotificationListener
Following copied from interface: javax.management.NotificationListener
Parameters:
notification - The notification object
handback - Helps in associating information regarding the listener.

getNotificationInfo

public MBeanNotificationInfo[] getNotificationInfo()
Implement to return more info regarding Notification Types
Overrides:
getNotificationInfo in class NotificationBroadcasterSupport
Following copied from interface: javax.management.NotificationBroadcaster
Returns:
MBeanNotificationInfo The NotificationInfo

preRegister

public ObjectName preRegister(MBeanServer server,
                              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
Following copied from interface: javax.management.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
Following copied from interface: javax.management.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
Following copied from interface: javax.management.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


Copyright © 2001-2002 MX4J Team. All Rights Reserved.