001 /*
002 * Copyright 2000-2006 Sun Microsystems, Inc. All Rights Reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation. Sun designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Sun in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022 * CA 95054 USA or visit www.sun.com if you need additional information or
023 * have any questions.
024 */
025
026 package javax.management.relation;
027
028 import java.util.List;
029 import java.util.Map;
030
031 import javax.management.ObjectName;
032
033 /**
034 * This interface has to be implemented by any MBean class expected to
035 * represent a relation managed using the Relation Service.
036 * <P>Simple relations, i.e. having only roles, no properties or methods, can
037 * be created directly by the Relation Service (represented as RelationSupport
038 * objects, internally handled by the Relation Service).
039 * <P>If the user wants to represent more complex relations, involving
040 * properties and/or methods, he has to provide his own class implementing the
041 * Relation interface. This can be achieved either by inheriting from
042 * RelationSupport class, or by implementing the interface (fully or delegation to
043 * a RelationSupport object member).
044 * <P>Specifying such user relation class is to introduce properties and/or
045 * methods. Those have to be exposed for remote management. So this means that
046 * any user relation class must be a MBean class.
047 *
048 * @since 1.5
049 */
050 public interface Relation {
051
052 /**
053 * Retrieves role value for given role name.
054 * <P>Checks if the role exists and is readable according to the relation
055 * type.
056 *
057 * @param roleName name of role
058 *
059 * @return the ArrayList of ObjectName objects being the role value
060 *
061 * @exception IllegalArgumentException if null role name
062 * @exception RoleNotFoundException if:
063 * <P>- there is no role with given name
064 * <P>- the role is not readable.
065 * @exception RelationServiceNotRegisteredException if the Relation
066 * Service is not registered in the MBean Server
067 *
068 * @see #setRole
069 */
070 public List<ObjectName> getRole(String roleName)
071 throws IllegalArgumentException, RoleNotFoundException,
072 RelationServiceNotRegisteredException;
073
074 /**
075 * Retrieves values of roles with given names.
076 * <P>Checks for each role if it exists and is readable according to the
077 * relation type.
078 *
079 * @param roleNameArray array of names of roles to be retrieved
080 *
081 * @return a RoleResult object, including a RoleList (for roles
082 * successfully retrieved) and a RoleUnresolvedList (for roles not
083 * retrieved).
084 *
085 * @exception IllegalArgumentException if null role name
086 * @exception RelationServiceNotRegisteredException if the Relation
087 * Service is not registered in the MBean Server
088 *
089 * @see #setRoles
090 */
091 public RoleResult getRoles(String[] roleNameArray)
092 throws IllegalArgumentException,
093 RelationServiceNotRegisteredException;
094
095 /**
096 * Returns the number of MBeans currently referenced in the given role.
097 *
098 * @param roleName name of role
099 *
100 * @return the number of currently referenced MBeans in that role
101 *
102 * @exception IllegalArgumentException if null role name
103 * @exception RoleNotFoundException if there is no role with given name
104 */
105 public Integer getRoleCardinality(String roleName)
106 throws IllegalArgumentException, RoleNotFoundException;
107
108 /**
109 * Returns all roles present in the relation.
110 *
111 * @return a RoleResult object, including a RoleList (for roles
112 * successfully retrieved) and a RoleUnresolvedList (for roles not
113 * readable).
114 *
115 * @exception RelationServiceNotRegisteredException if the Relation
116 * Service is not registered in the MBean Server
117 */
118 public RoleResult getAllRoles()
119 throws RelationServiceNotRegisteredException;
120
121 /**
122 * Returns all roles in the relation without checking read mode.
123 *
124 * @return a RoleList.
125 */
126 public RoleList retrieveAllRoles();
127
128 /**
129 * Sets the given role.
130 * <P>Will check the role according to its corresponding role definition
131 * provided in relation's relation type
132 * <P>Will send a notification (RelationNotification with type
133 * RELATION_BASIC_UPDATE or RELATION_MBEAN_UPDATE, depending if the
134 * relation is a MBean or not).
135 *
136 * @param role role to be set (name and new value)
137 *
138 * @exception IllegalArgumentException if null role
139 * @exception RoleNotFoundException if there is no role with the supplied
140 * role's name or if the role is not writable (no test on the write access
141 * mode performed when initializing the role)
142 * @exception InvalidRoleValueException if value provided for
143 * role is not valid, i.e.:
144 * <P>- the number of referenced MBeans in given value is less than
145 * expected minimum degree
146 * <P>- the number of referenced MBeans in provided value exceeds expected
147 * maximum degree
148 * <P>- one referenced MBean in the value is not an Object of the MBean
149 * class expected for that role
150 * <P>- a MBean provided for that role does not exist.
151 * @exception RelationServiceNotRegisteredException if the Relation
152 * Service is not registered in the MBean Server
153 * @exception RelationTypeNotFoundException if the relation type has not
154 * been declared in the Relation Service.
155 * @exception RelationNotFoundException if the relation has not been
156 * added in the Relation Service.
157 *
158 * @see #getRole
159 */
160 public void setRole(Role role) throws IllegalArgumentException,
161 RoleNotFoundException, RelationTypeNotFoundException,
162 InvalidRoleValueException,
163 RelationServiceNotRegisteredException,
164 RelationNotFoundException;
165
166 /**
167 * Sets the given roles.
168 * <P>Will check the role according to its corresponding role definition
169 * provided in relation's relation type
170 * <P>Will send one notification (RelationNotification with type
171 * RELATION_BASIC_UPDATE or RELATION_MBEAN_UPDATE, depending if the
172 * relation is a MBean or not) per updated role.
173 *
174 * @param roleList list of roles to be set
175 *
176 * @return a RoleResult object, including a RoleList (for roles
177 * successfully set) and a RoleUnresolvedList (for roles not
178 * set).
179 *
180 * @exception IllegalArgumentException if null role list
181 * @exception RelationServiceNotRegisteredException if the Relation
182 * Service is not registered in the MBean Server
183 * @exception RelationTypeNotFoundException if the relation type has not
184 * been declared in the Relation Service.
185 * @exception RelationNotFoundException if the relation MBean has not been
186 * added in the Relation Service.
187 *
188 * @see #getRoles
189 */
190 public RoleResult setRoles(RoleList roleList)
191 throws IllegalArgumentException,
192 RelationServiceNotRegisteredException,
193 RelationTypeNotFoundException, RelationNotFoundException;
194
195 /**
196 * Callback used by the Relation Service when a MBean referenced in a role
197 * is unregistered.
198 * <P>The Relation Service will call this method to let the relation
199 * take action to reflect the impact of such unregistration.
200 * <P>BEWARE. the user is not expected to call this method.
201 * <P>Current implementation is to set the role with its current value
202 * (list of ObjectNames of referenced MBeans) without the unregistered
203 * one.
204 *
205 * @param objectName ObjectName of unregistered MBean
206 * @param roleName name of role where the MBean is referenced
207 *
208 * @exception IllegalArgumentException if null parameter
209 * @exception RoleNotFoundException if role does not exist in the
210 * relation or is not writable
211 * @exception InvalidRoleValueException if role value does not conform to
212 * the associated role info (this will never happen when called from the
213 * Relation Service)
214 * @exception RelationServiceNotRegisteredException if the Relation
215 * Service is not registered in the MBean Server
216 * @exception RelationTypeNotFoundException if the relation type has not
217 * been declared in the Relation Service.
218 * @exception RelationNotFoundException if this method is called for a
219 * relation MBean not added in the Relation Service.
220 */
221 public void handleMBeanUnregistration(ObjectName objectName,
222 String roleName) throws IllegalArgumentException,
223 RoleNotFoundException, InvalidRoleValueException,
224 RelationServiceNotRegisteredException,
225 RelationTypeNotFoundException, RelationNotFoundException;
226
227 /**
228 * Retrieves MBeans referenced in the various roles of the relation.
229 *
230 * @return a HashMap mapping:
231 * <P> ObjectName -> ArrayList of String (role names)
232 */
233 public Map<ObjectName, List<String>> getReferencedMBeans();
234
235 /**
236 * Returns name of associated relation type.
237 *
238 * @return the name of the relation type.
239 */
240 public String getRelationTypeName();
241
242 /**
243 * Returns ObjectName of the Relation Service handling the relation.
244 *
245 * @return the ObjectName of the Relation Service.
246 */
247 public ObjectName getRelationServiceName();
248
249 /**
250 * Returns relation identifier (used to uniquely identify the relation
251 * inside the Relation Service).
252 *
253 * @return the relation id.
254 */
255 public String getRelationId();
256 }
|