001: /**
002: * The XMOJO Project 5
003: * Copyright © 2003 XMOJO.org. All rights reserved.
004:
005: * NO WARRANTY
006:
007: * BECAUSE THE LIBRARY IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR
008: * THE LIBRARY, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN
009: * OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
010: * PROVIDE THE LIBRARY "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
011: * OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
012: * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS
013: * TO THE QUALITY AND PERFORMANCE OF THE LIBRARY IS WITH YOU. SHOULD THE
014: * LIBRARY PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
015: * REPAIR OR CORRECTION.
016:
017: * IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL
018: * ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE
019: * THE LIBRARY AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY
020: * GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE
021: * USE OR INABILITY TO USE THE LIBRARY (INCLUDING BUT NOT LIMITED TO LOSS OF
022: * DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
023: * PARTIES OR A FAILURE OF THE LIBRARY TO OPERATE WITH ANY OTHER SOFTWARE),
024: * EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
025: * SUCH DAMAGES.
026: **/package javax.management.relation;
027:
028: import java.util.Map;
029: import java.util.List;
030:
031: import javax.management.ObjectName;
032:
033: /**
034: * This interface has to be implemented by any MBean class expected to represent
035: * a relation managed using the Relation Service.
036: * Simple relations, i.e. having only roles, no properties or methods, can be
037: * created directly by the Relation Service (represented as RelationSupport
038: * objects, internally handled by the Relation Service).
039: * If the user wants to represent more complex relations, involving properties
040: * and/or methods, he has to provide his own class implementing the Relation
041: * interface. This can be achieved either by inheriting from RelationSupport
042: * class, or by implementing the interface (fully or delegation to a
043: * RelationSupport object member).
044: * Specifying such user relation class is to introduce properties and/or methods.
045: * Those have to be exposed for remote management. So this means that any user
046: * relation class must be a MBean class.
047: */
048: public interface Relation {
049: /**
050: * Returns all roles present in the relation
051: *
052: * @return a RoleResult object, including a RoleList (for roles
053: * succcessfully retrieved) and a RoleUnresolvedList
054: * (for roles not readable).
055: *
056: * @throws RelationServiceNotRegisteredException - if the Relation Service
057: * is not registered in the MBean Server
058: */
059: public RoleResult getAllRoles()
060: throws RelationServiceNotRegisteredException;
061:
062: /**
063: * Retrieves MBeans referenced in the various roles of the relation.
064: *
065: * @return a HashMap mapping:
066: * ObjectName -> ArrayList of String (role names)
067: */
068: public Map getReferencedMBeans();
069:
070: /**
071: * Returns relation identifier (used to uniquely identify the relation
072: * inside the Relation Service)
073: *
074: * @return This will return the identifier
075: */
076: public String getRelationId();
077:
078: /**
079: * Returns ObjectName of the Relation Service handling the relation
080: *
081: * @return This returns the object name of the relation service
082: */
083: public ObjectName getRelationServiceName();
084:
085: /**
086: * Returns name of associated relation type.
087: *
088: * @return Name of associated relation type.
089: */
090: public String getRelationTypeName();
091:
092: /**
093: * Retrieves role value for given role name.
094: * Checks if the role exists and is readable according to the relation type.
095: *
096: * @param theRoleName - name of role
097: *
098: * @return the ArrayList of ObjectName objects being the role value
099: *
100: * @throws java.lang.IllegalArgumentException - if null role name
101: *
102: * @throws RoleNotFoundException - if:
103: * - there is no role with given name
104: * - the role is not readable.
105: *
106: * @throws RelationServiceNotRegisteredException - if the Relation Service
107: * is not registered in the MBean Server
108: */
109: public List getRole(String theRoleName)
110: throws IllegalArgumentException, RoleNotFoundException,
111: RelationServiceNotRegisteredException;
112:
113: /**
114: * Returns the number of MBeans currently referenced in the given role.
115: *
116: * @param theRoleName - name of role
117: *
118: * @return the number of currently referenced MBeans in that role
119: *
120: * @throws java.lang.IllegalArgumentException - if null role name
121: *
122: * @throws RoleNotFoundException - if there is no role with given name
123: */
124: public Integer getRoleCardinality(String theRoleName)
125: throws IllegalArgumentException, RoleNotFoundException;
126:
127: /**
128: * Retrieves values of roles with given names.
129: * Checks for each role if it exists and is readable according to the
130: * relation type.
131: *
132: * @param theRoleNameArray - array of names of roles to be retrieved
133: *
134: * @return a RoleResult object, including a RoleList (for roles
135: * succcessfully retrieved) and a RoleUnresolvedList
136: * (for roles not retrieved).
137: *
138: * @throws java.lang.IllegalArgumentException - if null role name
139: *
140: * @throws RelationServiceNotRegisteredException - if the Relation Service
141: * is not registered in the MBean Server
142: */
143: public RoleResult getRoles(String[] theRoleNameArray)
144: throws IllegalArgumentException,
145: RelationServiceNotRegisteredException;
146:
147: /**
148: * Callback used by the Relation Service when a MBean referenced in a role
149: * is unregistered. The Relation Service will call this method to let the
150: * relation take action to reflect the impact of such unregistration.
151: * BEWARE. the user is not expected to call this method.
152: * Current implementation is to set the role with its current value
153: * (list of ObjectNames of referenced MBeans) without the unregistered one.
154: *
155: * @param theObjName - ObjectName of unregistered MBean
156: *
157: * @param theRoleName - name of role where the MBean is referenced
158: *
159: * @throws java.lang.IllegalArgumentException - if null parameter
160: *
161: * @throws RoleNotFoundException - if role does not exist in the relation
162: * or is not writable
163: *
164: * @throws InvalidRoleValueException - if role value does not conform to
165: * the associated role info (this will never happen when
166: * called from the Relation Service)
167: *
168: * @throws RelationServiceNotRegisteredException - if the Relation Service
169: * is not registered in the MBean Server
170: *
171: * @throws RelationTypeNotFoundException - if the relation type has not
172: * been declared in the Relation Service.
173: *
174: * @throws RelationNotFoundException - if this method is called for a
175: * relation MBean not added in the Relation Service.
176: */
177: public void handleMBeanUnregistration(ObjectName theObjName,
178: String theRoleName) throws IllegalArgumentException,
179: RoleNotFoundException, InvalidRoleValueException,
180: RelationServiceNotRegisteredException,
181: RelationTypeNotFoundException, RelationNotFoundException;
182:
183: /**
184: * Returns all roles in the relation without checking read mode
185: * @return a RoleList
186: */
187: public RoleList retrieveAllRoles();
188:
189: /**
190: * Sets the given role.
191: * Will check the role according to its corresponding role definition
192: * provided in relation's relation type will send a notification
193: * (RelationNotification with type RELATION_BASIC_UPDATE or
194: * RELATION_MBEAN_UPDATE, depending if the relation is a MBean or not).
195: *
196: * @param theRole - role to be set (name and new value)
197: *
198: * @throws java.lang.IllegalArgumentException - if null role
199: *
200: * @throws RoleNotFoundException - if the role is not writable (no test on
201: * the write access mode performed when initialising the role)
202: *
203: * @throws InvalidRoleValueException - if value provided for role is not
204: * valid, i.e.:
205: * - the number of referenced MBeans in given value is less
206: * than expected minimum degree
207: * - the number of referenced MBeans in provided value exceeds
208: * expected maximum degree
209: * - one referenced MBean in the value is not an Object of the
210: * MBean class expected for that role
211: * - a MBean provided for that role does not exist
212: *
213: * @throws RelationServiceNotRegisteredException - if the Relation Service
214: * is not registered in the MBean Server
215: *
216: * @throws RelationTypeNotFoundException - if the relation type has not
217: * been declared in the Relation Service.
218: */
219: public void setRole(Role theRole) throws IllegalArgumentException,
220: RoleNotFoundException, InvalidRoleValueException,
221: RelationServiceNotRegisteredException,
222: RelationTypeNotFoundException, RelationNotFoundException;
223:
224: /**
225: * Sets the given roles.
226: * Will check the role according to its corresponding role definition
227: * provided in relation's relation type will send one notification
228: * (RelationNotification with type RELATION_BASIC_UPDATE or
229: * RELATION_MBEAN_UPDATE, depending if the relation is a MBean or not) per
230: * updated role.
231: *
232: * @param theRoleList - list of roles to be set
233: *
234: * @return a RoleResult object, including a RoleList (for roles
235: * succcessfully set) and a RoleUnresolvedList (for roles not set).
236: *
237: * @throws java.lang.IllegalArgumentException - if null role name
238: *
239: * @throws RelationServiceNotRegisteredException - if the Relation Service
240: * is not registered in the MBean Server
241: *
242: * @throws RelationTypeNotFoundException - if the relation type has not
243: * been declared in the Relation Service.
244: *
245: * @throws RelationNotFoundException - if the relation MBean has not been
246: * added in the Relation Service.
247: */
248: public RoleResult setRoles(RoleList theRoleList)
249: throws IllegalArgumentException,
250: RelationServiceNotRegisteredException,
251: RelationTypeNotFoundException, RelationNotFoundException;
252: }
|