001: /*
002: * JBoss, Home of Professional Open Source.
003: * Copyright 2006, Red Hat Middleware LLC, and individual contributors
004: * as indicated by the @author tags. See the copyright.txt file in the
005: * distribution for a full listing of individual contributors.
006: *
007: * This is free software; you can redistribute it and/or modify it
008: * under the terms of the GNU Lesser General Public License as
009: * published by the Free Software Foundation; either version 2.1 of
010: * the License, or (at your option) any later version.
011: *
012: * This software is distributed in the hope that it will be useful,
013: * but WITHOUT ANY WARRANTY; without even the implied warranty of
014: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
015: * Lesser General Public License for more details.
016: *
017: * You should have received a copy of the GNU Lesser General Public
018: * License along with this software; if not, write to the Free
019: * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
020: * 02110-1301 USA, or see the FSF site: http://www.fsf.org.
021: */
022: package javax.management.relation;
023:
024: import javax.management.ObjectName;
025: import java.util.List;
026: import java.util.Map;
027:
028: /**
029: * This interface is implemented by an MBean that represents a relation.<p>
030: * <p/>
031: * Relations with only roles can be created by the relation service using
032: * a {@link RelationSupport} object.<p>
033: * <p/>
034: * More complicated relations have to implemented manually. The
035: * {@link RelationSupport} can be used to help in the implementation.<p>
036: * <p/>
037: * Any properties or methods must be exposed for management by the
038: * implementing MBean.
039: *
040: * @author <a href="mailto:Adrian.Brock@HappeningTimes.com">Adrian Brock</a>.
041: * @version $Revision: 57200 $
042: */
043: public interface Relation {
044: // Constants ---------------------------------------------------
045:
046: // Public ------------------------------------------------------
047:
048: /**
049: * Retrieves the role for the passed role name. The role
050: * must exist and be readable.<p>
051: * <p/>
052: * The return value is an ArrayList of object names in the role.
053: *
054: * @param roleName the role name.
055: * @return the role.
056: * @throws IllegalArgumentException for a null role name.
057: * @throws RoleNotFoundException when there is no such role or
058: * it is not readable.
059: * @throws RelationServiceNotRegisteredException
060: * when the relation service
061: * is not registered with an MBeanServer.
062: */
063: public List getRole(String roleName)
064: throws IllegalArgumentException, RoleNotFoundException,
065: RelationServiceNotRegisteredException;
066:
067: /**
068: * Retrieves the roles in this relation with the passed names.
069: *
070: * @param roleNames an array of role names
071: * @return the roles both resolved and unresolved.
072: * @throws IllegalArgumentException for a null role names.
073: * @throws RelationServiceNotRegisteredException
074: * when the relation service
075: * is not registered with an MBeanServer.
076: */
077: public RoleResult getRoles(String[] roleNames)
078: throws IllegalArgumentException,
079: RelationServiceNotRegisteredException;
080:
081: /**
082: * Retrieves the number of MBeans in a given role.
083: *
084: * @param roleName the role name.
085: * @return the number of MBeans.
086: * @throws IllegalArgumentException for a null role name.
087: * @throws RoleNotFoundException when there is no such role.
088: */
089: public Integer getRoleCardinality(String roleName)
090: throws IllegalArgumentException, RoleNotFoundException;
091:
092: /**
093: * Retrieves all the roles in this relation.
094: *
095: * @return the roles both resolved and unresolved.
096: * @throws RelationServiceNotRegisteredException
097: * when the relation service
098: * is not registered with an MBeanServer.
099: */
100: public RoleResult getAllRoles()
101: throws RelationServiceNotRegisteredException;
102:
103: /**
104: * Retrieve all the roles in this relation without checking the role mode.
105: *
106: * @return the list of roles.
107: */
108: public RoleList retrieveAllRoles();
109:
110: /**
111: * Sets the passed role for this relation.<p>
112: * <p/>
113: * The role is checked according to its role definition in the relation type.
114: * The role is not valid if there are the wrong number of MBeans, an MBean
115: * is of an incorrect class or an MBean does not exist.<p>
116: * <p/>
117: * The notification <i>RELATION_BASIC_UPDATE</i> is sent when the relation is
118: * not an MBean or <i>RELATION_MBEAN_UPDATE</i> when it is.<p>
119: *
120: * @param role the new role.
121: * @throws IllegalArgumentException for a null role.
122: * @throws InvalidRoleValueException if the role is not valid.
123: * @throws RoleNotFoundException if the role is not writable.
124: * This test is not performed at initialisation.
125: * @throws RelationServiceNotRegisteredException
126: * when the relation service
127: * is not registered with an MBeanServer.
128: * @throws RelationTypeNotFoundException when the relation type has
129: * not been registered in the relation service.
130: * @throws RelationNotFoundException when this method is called for
131: * for an MBean not registered with the relation service.
132: */
133: public void setRole(Role role) throws IllegalArgumentException,
134: RoleNotFoundException, RelationTypeNotFoundException,
135: InvalidRoleValueException,
136: RelationServiceNotRegisteredException,
137: RelationNotFoundException;
138:
139: /**
140: * Sets the roles.<p>
141: * <p/>
142: * The roles are checked according to its role definition in the relation type.
143: * The role is not valid if there are the wrong number of MBeans, an MBean
144: * is of an incorrect class or an MBean does not exist.<p>
145: * <p/>
146: * A notification <i>RELATION_BASIC_UPDATE</i> is sent when the relation is
147: * not an MBean or <i>RELATION_MBEAN_UPDATE</i> when it is for every updated
148: * role.<p>
149: * <p/>
150: * The return role result has a role list for successfully updated roles and
151: * an unresolved list for roles not set.
152: *
153: * @param roleList the new roles.
154: * @return the resulting role result.
155: * @throws IllegalArgumentException for a null role name.
156: * @throws RelationServiceNotRegisteredException
157: * when the relation service
158: * is not registered with an MBeanServer.
159: * @throws RelationTypeNotFoundException when the relation type has
160: * not been registered in the relation service.
161: * @throws RelationNotFoundException when this method is called for
162: * for an MBean not registered with the relation service.
163: */
164: public RoleResult setRoles(RoleList roleList)
165: throws IllegalArgumentException,
166: RelationServiceNotRegisteredException,
167: RelationTypeNotFoundException, RelationNotFoundException;
168:
169: /**
170: * The relation service will call this service when an MBean
171: * referenced in a role is unregistered.<p>
172: * <p/>
173: * The object name should be removed from the role.<p>
174: * <p/>
175: * <b>Calling this method manually may result in incorrect behaviour</b>
176: *
177: * @param objectName the object name unregistered.
178: * @param roleName the role the containing the object.
179: * @throws RoleNotFoundException if the role does exist or it is not
180: * writable.
181: * @throws InvalidRoleValueException when the role does not conform
182: * to the associated role info.
183: * @throws RelationServiceNotRegisteredException
184: * when the relation service
185: * is not registered with an MBeanServer.
186: * @throws RelationTypeNotFoundException when the relation type has
187: * not been registered in the relation service.
188: * @throws RelationNotFoundException when this method is called for
189: * for an MBean not registered with the relation service.
190: */
191: public void handleMBeanUnregistration(ObjectName objectName,
192: String roleName) throws IllegalArgumentException,
193: RoleNotFoundException, InvalidRoleValueException,
194: RelationServiceNotRegisteredException,
195: RelationTypeNotFoundException, RelationNotFoundException;
196:
197: /**
198: * Retrieves MBeans referenced by roles of this relation.<p>
199: * <p/>
200: * The return value is a map keyed by MBean object names. The objects
201: * are associated with an ArrayList that contains all the role names
202: * the MBean has within this relation.
203: *
204: * @return the map of object names and their roles.
205: */
206: public Map getReferencedMBeans();
207:
208: /**
209: * Retrieves the relation type for this relation.
210: *
211: * @return the relation type.
212: */
213: public String getRelationTypeName();
214:
215: /**
216: * Retrieves the object name of the relation service this relation
217: * is registered with.
218: *
219: * @return the relation service object name.
220: */
221: public ObjectName getRelationServiceName();
222:
223: /**
224: * Retrieves the relation id used to identify the relation within
225: * the relation service.
226: *
227: * @return the unique id.
228: */
229: public String getRelationId();
230:
231: }
|