1 /*
2 * Copyright 2000-2006 Sun Microsystems, Inc. All Rights Reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Sun designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Sun in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
22 * CA 95054 USA or visit www.sun.com if you need additional information or
23 * have any questions.
24 */
25
26 package javax.management.relation;
27
28 import java.util.List;
29 import java.util.Map;
30
31 import javax.management.ObjectName;
32
33 /**
34 * This interface has to be implemented by any MBean class expected to
35 * represent a relation managed using the Relation Service.
36 * <P>Simple relations, i.e. having only roles, no properties or methods, can
37 * be created directly by the Relation Service (represented as RelationSupport
38 * objects, internally handled by the Relation Service).
39 * <P>If the user wants to represent more complex relations, involving
40 * properties and/or methods, he has to provide his own class implementing the
41 * Relation interface. This can be achieved either by inheriting from
42 * RelationSupport class, or by implementing the interface (fully or delegation to
43 * a RelationSupport object member).
44 * <P>Specifying such user relation class is to introduce properties and/or
45 * methods. Those have to be exposed for remote management. So this means that
46 * any user relation class must be a MBean class.
47 *
48 * @since 1.5
49 */
50 public interface Relation {
51
52 /**
53 * Retrieves role value for given role name.
54 * <P>Checks if the role exists and is readable according to the relation
55 * type.
56 *
57 * @param roleName name of role
58 *
59 * @return the ArrayList of ObjectName objects being the role value
60 *
61 * @exception IllegalArgumentException if null role name
62 * @exception RoleNotFoundException if:
63 * <P>- there is no role with given name
64 * <P>- the role is not readable.
65 * @exception RelationServiceNotRegisteredException if the Relation
66 * Service is not registered in the MBean Server
67 *
68 * @see #setRole
69 */
70 public List<ObjectName> getRole(String roleName)
71 throws IllegalArgumentException,
72 RoleNotFoundException,
73 RelationServiceNotRegisteredException;
74
75 /**
76 * Retrieves values of roles with given names.
77 * <P>Checks for each role if it exists and is readable according to the
78 * relation type.
79 *
80 * @param roleNameArray array of names of roles to be retrieved
81 *
82 * @return a RoleResult object, including a RoleList (for roles
83 * successfully retrieved) and a RoleUnresolvedList (for roles not
84 * retrieved).
85 *
86 * @exception IllegalArgumentException if null role name
87 * @exception RelationServiceNotRegisteredException if the Relation
88 * Service is not registered in the MBean Server
89 *
90 * @see #setRoles
91 */
92 public RoleResult getRoles(String[] roleNameArray)
93 throws IllegalArgumentException,
94 RelationServiceNotRegisteredException;
95
96 /**
97 * Returns the number of MBeans currently referenced in the given role.
98 *
99 * @param roleName name of role
100 *
101 * @return the number of currently referenced MBeans in that role
102 *
103 * @exception IllegalArgumentException if null role name
104 * @exception RoleNotFoundException if there is no role with given name
105 */
106 public Integer getRoleCardinality(String roleName)
107 throws IllegalArgumentException,
108 RoleNotFoundException;
109
110 /**
111 * Returns all roles present in the relation.
112 *
113 * @return a RoleResult object, including a RoleList (for roles
114 * successfully retrieved) and a RoleUnresolvedList (for roles not
115 * readable).
116 *
117 * @exception RelationServiceNotRegisteredException if the Relation
118 * Service is not registered in the MBean Server
119 */
120 public RoleResult getAllRoles()
121 throws RelationServiceNotRegisteredException;
122
123 /**
124 * Returns all roles in the relation without checking read mode.
125 *
126 * @return a RoleList.
127 */
128 public RoleList retrieveAllRoles();
129
130 /**
131 * Sets the given role.
132 * <P>Will check the role according to its corresponding role definition
133 * provided in relation's relation type
134 * <P>Will send a notification (RelationNotification with type
135 * RELATION_BASIC_UPDATE or RELATION_MBEAN_UPDATE, depending if the
136 * relation is a MBean or not).
137 *
138 * @param role role to be set (name and new value)
139 *
140 * @exception IllegalArgumentException if null role
141 * @exception RoleNotFoundException if there is no role with the supplied
142 * role's name or if the role is not writable (no test on the write access
143 * mode performed when initializing the role)
144 * @exception InvalidRoleValueException if value provided for
145 * role is not valid, i.e.:
146 * <P>- the number of referenced MBeans in given value is less than
147 * expected minimum degree
148 * <P>- the number of referenced MBeans in provided value exceeds expected
149 * maximum degree
150 * <P>- one referenced MBean in the value is not an Object of the MBean
151 * class expected for that role
152 * <P>- a MBean provided for that role does not exist.
153 * @exception RelationServiceNotRegisteredException if the Relation
154 * Service is not registered in the MBean Server
155 * @exception RelationTypeNotFoundException if the relation type has not
156 * been declared in the Relation Service.
157 * @exception RelationNotFoundException if the relation has not been
158 * added in the Relation Service.
159 *
160 * @see #getRole
161 */
162 public void setRole(Role role)
163 throws IllegalArgumentException,
164 RoleNotFoundException,
165 RelationTypeNotFoundException,
166 InvalidRoleValueException,
167 RelationServiceNotRegisteredException,
168 RelationNotFoundException;
169
170 /**
171 * Sets the given roles.
172 * <P>Will check the role according to its corresponding role definition
173 * provided in relation's relation type
174 * <P>Will send one notification (RelationNotification with type
175 * RELATION_BASIC_UPDATE or RELATION_MBEAN_UPDATE, depending if the
176 * relation is a MBean or not) per updated role.
177 *
178 * @param roleList list of roles to be set
179 *
180 * @return a RoleResult object, including a RoleList (for roles
181 * successfully set) and a RoleUnresolvedList (for roles not
182 * set).
183 *
184 * @exception IllegalArgumentException if null role list
185 * @exception RelationServiceNotRegisteredException if the Relation
186 * Service is not registered in the MBean Server
187 * @exception RelationTypeNotFoundException if the relation type has not
188 * been declared in the Relation Service.
189 * @exception RelationNotFoundException if the relation MBean has not been
190 * added in the Relation Service.
191 *
192 * @see #getRoles
193 */
194 public RoleResult setRoles(RoleList roleList)
195 throws IllegalArgumentException,
196 RelationServiceNotRegisteredException,
197 RelationTypeNotFoundException,
198 RelationNotFoundException;
199
200 /**
201 * Callback used by the Relation Service when a MBean referenced in a role
202 * is unregistered.
203 * <P>The Relation Service will call this method to let the relation
204 * take action to reflect the impact of such unregistration.
205 * <P>BEWARE. the user is not expected to call this method.
206 * <P>Current implementation is to set the role with its current value
207 * (list of ObjectNames of referenced MBeans) without the unregistered
208 * one.
209 *
210 * @param objectName ObjectName of unregistered MBean
211 * @param roleName name of role where the MBean is referenced
212 *
213 * @exception IllegalArgumentException if null parameter
214 * @exception RoleNotFoundException if role does not exist in the
215 * relation or is not writable
216 * @exception InvalidRoleValueException if role value does not conform to
217 * the associated role info (this will never happen when called from the
218 * Relation Service)
219 * @exception RelationServiceNotRegisteredException if the Relation
220 * Service is not registered in the MBean Server
221 * @exception RelationTypeNotFoundException if the relation type has not
222 * been declared in the Relation Service.
223 * @exception RelationNotFoundException if this method is called for a
224 * relation MBean not added in the Relation Service.
225 */
226 public void handleMBeanUnregistration(ObjectName objectName,
227 String roleName)
228 throws IllegalArgumentException,
229 RoleNotFoundException,
230 InvalidRoleValueException,
231 RelationServiceNotRegisteredException,
232 RelationTypeNotFoundException,
233 RelationNotFoundException;
234
235 /**
236 * Retrieves MBeans referenced in the various roles of the relation.
237 *
238 * @return a HashMap mapping:
239 * <P> ObjectName -> ArrayList of String (role names)
240 */
241 public Map<ObjectName,List<String>> getReferencedMBeans();
242
243 /**
244 * Returns name of associated relation type.
245 *
246 * @return the name of the relation type.
247 */
248 public String getRelationTypeName();
249
250 /**
251 * Returns ObjectName of the Relation Service handling the relation.
252 *
253 * @return the ObjectName of the Relation Service.
254 */
255 public ObjectName getRelationServiceName();
256
257 /**
258 * Returns relation identifier (used to uniquely identify the relation
259 * inside the Relation Service).
260 *
261 * @return the relation id.
262 */
263 public String getRelationId();
264 }
Save This Page