001: /* JFox, the OpenSource J2EE Application Server
002: *
003: * Copyright (C) 2002 huihoo.org
004: * Distributable under GNU LGPL license
005: * See the GNU Lesser General Public License for more details.
006: */
007:
008: package javax.management.relation;
009:
010: import java.util.List;
011: import java.util.Map;
012: import javax.management.ObjectName;
013:
014: /**
015: *
016: * @author <a href="mailto:young_yy@hotmail.org">Young Yang</a>
017: */
018:
019: /**
020: * This interface has to be implemented by any MBean class expected to
021: * represent a relation managed using the Relation Service.
022: * <P>Simple relations, i.e. having only roles, no properties or methods, can
023: * be created directly by the Relation Service (represented as RelationSupport
024: * objects, internally handled by the Relation Service).
025: * <P>If the user wants to represent more complex relations, involving
026: * properties and/or methods, he has to provide his own class implementing the
027: * Relation interface. This can be achieved either by inheriting from
028: * RelationSupport class, or by implementing the interface (fully or delegation to
029: * a RelationSupport object member).
030: * <P>Specifying such user relation class is to introduce properties and/or
031: * methods. Those have to be exposed for remote management. So this means that
032: * any user relation class must be a MBean class.
033: */
034: public interface Relation {
035:
036: /**
037: * Retrieves role value for given role name.
038: * <P>Checks if the role exists and is readable according to the relation
039: * type.
040: *
041: * @param roleName name of role
042: *
043: * @return the ArrayList of ObjectName objects being the role value
044: *
045: * @exception IllegalArgumentException if null role name
046: * @exception RoleNotFoundException if:
047: * <P>- there is no role with given name
048: * <P>- the role is not readable.
049: * @exception RelationServiceNotRegisteredException if the Relation
050: * Service is not registered in the MBean Server
051: */
052: public List getRole(String roleName)
053: throws IllegalArgumentException, RoleNotFoundException,
054: RelationServiceNotRegisteredException;
055:
056: /**
057: * Retrieves values of roles with given names.
058: * <P>Checks for each role if it exists and is readable according to the
059: * relation type.
060: *
061: * @param roleNameArray array of names of roles to be retrieved
062: *
063: * @return a RoleResult object, including a RoleList (for roles
064: * succcessfully retrieved) and a RoleUnresolvedList (for roles not
065: * retrieved).
066: *
067: * @exception IllegalArgumentException if null role name
068: * @exception RelationServiceNotRegisteredException if the Relation
069: * Service is not registered in the MBean Server
070: */
071: public RoleResult getRoles(String[] roleNameArray)
072: throws IllegalArgumentException,
073: RelationServiceNotRegisteredException;
074:
075: /**
076: * Returns the number of MBeans currently referenced in the given role
077: *
078: * @param roleName name of role
079: *
080: * @return the number of currently referenced MBeans in that role
081: *
082: * @exception IllegalArgumentException if null role name
083: * @exception RoleNotFoundException if there is no role with given name
084: */
085: public Integer getRoleCardinality(String roleName)
086: throws IllegalArgumentException, RoleNotFoundException;
087:
088: /**
089: * Returns all roles present in the relation
090: *
091: * @return a RoleResult object, including a RoleList (for roles
092: * succcessfully retrieved) and a RoleUnresolvedList (for roles not
093: * readable).
094: *
095: * @exception RelationServiceNotRegisteredException if the Relation
096: * Service is not registered in the MBean Server
097: */
098: public RoleResult getAllRoles()
099: throws RelationServiceNotRegisteredException;
100:
101: /**
102: * Returns all roles in the relation without checking read mode
103: *
104: * @return a RoleList
105: */
106: public RoleList retrieveAllRoles();
107:
108: /**
109: * Sets the given role.
110: * <P>Will check the role according to its corresponding role definition
111: * provided in relation's relation type
112: * <P>Will send a notification (RelationNotification with type
113: * RELATION_BASIC_UPDATE or RELATION_MBEAN_UPDATE, depending if the
114: * relation is a MBean or not).
115: *
116: * @param role role to be set (name and new value)
117: *
118: * @exception IllegalArgumentException if null role
119: * @exception RoleNotFoundException if the role is not writable (no
120: * test on the write access mode performed when initialising the role)
121: * @exception InvalidRoleValueException if value provided for
122: * role is not valid, i.e.:
123: * <P>- the number of referenced MBeans in given value is less than
124: * expected minimum degree
125: * <P>- the number of referenced MBeans in provided value exceeds expected
126: * maximum degree
127: * <P>- one referenced MBean in the value is not an Object of the MBean
128: * class expected for that role
129: * <P>- a MBean provided for that role does not exist
130: * @exception RelationServiceNotRegisteredException if the Relation
131: * Service is not registered in the MBean Server
132: * @exception RelationTypeNotFoundException if the relation type has not
133: * been declared in the Relation Service.
134: */
135: public void setRole(Role role) throws IllegalArgumentException,
136: RoleNotFoundException, RelationTypeNotFoundException,
137: InvalidRoleValueException,
138: RelationServiceNotRegisteredException,
139: RelationTypeNotFoundException, RelationNotFoundException;
140:
141: /**
142: * Sets the given roles.
143: * <P>Will check the role according to its corresponding role definition
144: * provided in relation's relation type
145: * <P>Will send one notification (RelationNotification with type
146: * RELATION_BASIC_UPDATE or RELATION_MBEAN_UPDATE, depending if the
147: * relation is a MBean or not) per updated role.
148: *
149: * @param roleList list of roles to be set
150: *
151: * @return a RoleResult object, including a RoleList (for roles
152: * succcessfully set) and a RoleUnresolvedList (for roles not
153: * set).
154: *
155: * @exception IllegalArgumentException if null role name
156: * @exception RelationServiceNotRegisteredException if the Relation
157: * Service is not registered in the MBean Server
158: * @exception RelationTypeNotFoundException if the relation type has not
159: * been declared in the Relation Service.
160: * @exception RelationNotFoundException if the relation MBean has not been
161: * added in the Relation Service.
162: */
163: public RoleResult setRoles(RoleList roleList)
164: throws IllegalArgumentException,
165: RelationServiceNotRegisteredException,
166: RelationTypeNotFoundException, RelationNotFoundException;
167:
168: /**
169: * Callback used by the Relation Service when a MBean referenced in a role
170: * is unregistered.
171: * <P>The Relation Service will call this method to let the relation
172: * take action to reflect the impact of such unregistration.
173: * <P>BEWARE. the user is not expected to call this method.
174: * <P>Current implementation is to set the role with its current value
175: * (list of ObjectNames of referenced MBeans) without the unregistered
176: * one.
177: *
178: * @param objectName ObjectName of unregistered MBean
179: * @param roleName name of role where the MBean is referenced
180: *
181: * @exception IllegalArgumentException if null parameter
182: * @exception RoleNotFoundException if role does not exist in the
183: * relation or is not writable
184: * @exception InvalidRoleValueException if role value does not conform to
185: * the associated role info (this will never happen when called from the
186: * Relation Service)
187: * @exception RelationServiceNotRegisteredException if the Relation
188: * Service is not registered in the MBean Server
189: * @exception RelationTypeNotFoundException if the relation type has not
190: * been declared in the Relation Service.
191: * @exception RelationNotFoundException if this method is called for a
192: * relation MBean not added in the Relation Service.
193: */
194: public void handleMBeanUnregistration(ObjectName objectName,
195: String roleName) throws IllegalArgumentException,
196: RoleNotFoundException, InvalidRoleValueException,
197: RelationServiceNotRegisteredException,
198: RelationTypeNotFoundException, RelationNotFoundException;
199:
200: /**
201: * Retrieves MBeans referenced in the various roles of the relation.
202: *
203: * @return a HashMap mapping:
204: * <P> ObjectName -> ArrayList of String (role names)
205: */
206: public Map getReferencedMBeans();
207:
208: /**
209: * Returns name of associated relation type.
210: */
211: public String getRelationTypeName();
212:
213: /**
214: * Returns ObjectName of the Relation Service handling the relation
215: */
216: public ObjectName getRelationServiceName();
217:
218: /**
219: * Returns relation identifier (used to uniquely identify the relation
220: * inside the Relation Service)
221: */
222: public String getRelationId();
223: }
|