--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/jdk/src/share/classes/javax/management/relation/Relation.java Sat Dec 01 00:00:00 2007 +0000
@@ -0,0 +1,264 @@
+/*
+ * Copyright 2000-2006 Sun Microsystems, Inc. All Rights Reserved.
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ *
+ * This code is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation. Sun designates this
+ * particular file as subject to the "Classpath" exception as provided
+ * by Sun in the LICENSE file that accompanied this code.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
+ * CA 95054 USA or visit www.sun.com if you need additional information or
+ * have any questions.
+ */
+
+package javax.management.relation;
+
+import java.util.List;
+import java.util.Map;
+
+import javax.management.ObjectName;
+
+/**
+ * This interface has to be implemented by any MBean class expected to
+ * represent a relation managed using the Relation Service.
+ * <P>Simple relations, i.e. having only roles, no properties or methods, can
+ * be created directly by the Relation Service (represented as RelationSupport
+ * objects, internally handled by the Relation Service).
+ * <P>If the user wants to represent more complex relations, involving
+ * properties and/or methods, he has to provide his own class implementing the
+ * Relation interface. This can be achieved either by inheriting from
+ * RelationSupport class, or by implementing the interface (fully or delegation to
+ * a RelationSupport object member).
+ * <P>Specifying such user relation class is to introduce properties and/or
+ * methods. Those have to be exposed for remote management. So this means that
+ * any user relation class must be a MBean class.
+ *
+ * @since 1.5
+ */
+public interface Relation {
+
+ /**
+ * Retrieves role value for given role name.
+ * <P>Checks if the role exists and is readable according to the relation
+ * type.
+ *
+ * @param roleName name of role
+ *
+ * @return the ArrayList of ObjectName objects being the role value
+ *
+ * @exception IllegalArgumentException if null role name
+ * @exception RoleNotFoundException if:
+ * <P>- there is no role with given name
+ * <P>- the role is not readable.
+ * @exception RelationServiceNotRegisteredException if the Relation
+ * Service is not registered in the MBean Server
+ *
+ * @see #setRole
+ */
+ public List<ObjectName> getRole(String roleName)
+ throws IllegalArgumentException,
+ RoleNotFoundException,
+ RelationServiceNotRegisteredException;
+
+ /**
+ * Retrieves values of roles with given names.
+ * <P>Checks for each role if it exists and is readable according to the
+ * relation type.
+ *
+ * @param roleNameArray array of names of roles to be retrieved
+ *
+ * @return a RoleResult object, including a RoleList (for roles
+ * successfully retrieved) and a RoleUnresolvedList (for roles not
+ * retrieved).
+ *
+ * @exception IllegalArgumentException if null role name
+ * @exception RelationServiceNotRegisteredException if the Relation
+ * Service is not registered in the MBean Server
+ *
+ * @see #setRoles
+ */
+ public RoleResult getRoles(String[] roleNameArray)
+ throws IllegalArgumentException,
+ RelationServiceNotRegisteredException;
+
+ /**
+ * Returns the number of MBeans currently referenced in the given role.
+ *
+ * @param roleName name of role
+ *
+ * @return the number of currently referenced MBeans in that role
+ *
+ * @exception IllegalArgumentException if null role name
+ * @exception RoleNotFoundException if there is no role with given name
+ */
+ public Integer getRoleCardinality(String roleName)
+ throws IllegalArgumentException,
+ RoleNotFoundException;
+
+ /**
+ * Returns all roles present in the relation.
+ *
+ * @return a RoleResult object, including a RoleList (for roles
+ * successfully retrieved) and a RoleUnresolvedList (for roles not
+ * readable).
+ *
+ * @exception RelationServiceNotRegisteredException if the Relation
+ * Service is not registered in the MBean Server
+ */
+ public RoleResult getAllRoles()
+ throws RelationServiceNotRegisteredException;
+
+ /**
+ * Returns all roles in the relation without checking read mode.
+ *
+ * @return a RoleList.
+ */
+ public RoleList retrieveAllRoles();
+
+ /**
+ * Sets the given role.
+ * <P>Will check the role according to its corresponding role definition
+ * provided in relation's relation type
+ * <P>Will send a notification (RelationNotification with type
+ * RELATION_BASIC_UPDATE or RELATION_MBEAN_UPDATE, depending if the
+ * relation is a MBean or not).
+ *
+ * @param role role to be set (name and new value)
+ *
+ * @exception IllegalArgumentException if null role
+ * @exception RoleNotFoundException if there is no role with the supplied
+ * role's name or if the role is not writable (no test on the write access
+ * mode performed when initializing the role)
+ * @exception InvalidRoleValueException if value provided for
+ * role is not valid, i.e.:
+ * <P>- the number of referenced MBeans in given value is less than
+ * expected minimum degree
+ * <P>- the number of referenced MBeans in provided value exceeds expected
+ * maximum degree
+ * <P>- one referenced MBean in the value is not an Object of the MBean
+ * class expected for that role
+ * <P>- a MBean provided for that role does not exist.
+ * @exception RelationServiceNotRegisteredException if the Relation
+ * Service is not registered in the MBean Server
+ * @exception RelationTypeNotFoundException if the relation type has not
+ * been declared in the Relation Service.
+ * @exception RelationNotFoundException if the relation has not been
+ * added in the Relation Service.
+ *
+ * @see #getRole
+ */
+ public void setRole(Role role)
+ throws IllegalArgumentException,
+ RoleNotFoundException,
+ RelationTypeNotFoundException,
+ InvalidRoleValueException,
+ RelationServiceNotRegisteredException,
+ RelationNotFoundException;
+
+ /**
+ * Sets the given roles.
+ * <P>Will check the role according to its corresponding role definition
+ * provided in relation's relation type
+ * <P>Will send one notification (RelationNotification with type
+ * RELATION_BASIC_UPDATE or RELATION_MBEAN_UPDATE, depending if the
+ * relation is a MBean or not) per updated role.
+ *
+ * @param roleList list of roles to be set
+ *
+ * @return a RoleResult object, including a RoleList (for roles
+ * successfully set) and a RoleUnresolvedList (for roles not
+ * set).
+ *
+ * @exception IllegalArgumentException if null role list
+ * @exception RelationServiceNotRegisteredException if the Relation
+ * Service is not registered in the MBean Server
+ * @exception RelationTypeNotFoundException if the relation type has not
+ * been declared in the Relation Service.
+ * @exception RelationNotFoundException if the relation MBean has not been
+ * added in the Relation Service.
+ *
+ * @see #getRoles
+ */
+ public RoleResult setRoles(RoleList roleList)
+ throws IllegalArgumentException,
+ RelationServiceNotRegisteredException,
+ RelationTypeNotFoundException,
+ RelationNotFoundException;
+
+ /**
+ * Callback used by the Relation Service when a MBean referenced in a role
+ * is unregistered.
+ * <P>The Relation Service will call this method to let the relation
+ * take action to reflect the impact of such unregistration.
+ * <P>BEWARE. the user is not expected to call this method.
+ * <P>Current implementation is to set the role with its current value
+ * (list of ObjectNames of referenced MBeans) without the unregistered
+ * one.
+ *
+ * @param objectName ObjectName of unregistered MBean
+ * @param roleName name of role where the MBean is referenced
+ *
+ * @exception IllegalArgumentException if null parameter
+ * @exception RoleNotFoundException if role does not exist in the
+ * relation or is not writable
+ * @exception InvalidRoleValueException if role value does not conform to
+ * the associated role info (this will never happen when called from the
+ * Relation Service)
+ * @exception RelationServiceNotRegisteredException if the Relation
+ * Service is not registered in the MBean Server
+ * @exception RelationTypeNotFoundException if the relation type has not
+ * been declared in the Relation Service.
+ * @exception RelationNotFoundException if this method is called for a
+ * relation MBean not added in the Relation Service.
+ */
+ public void handleMBeanUnregistration(ObjectName objectName,
+ String roleName)
+ throws IllegalArgumentException,
+ RoleNotFoundException,
+ InvalidRoleValueException,
+ RelationServiceNotRegisteredException,
+ RelationTypeNotFoundException,
+ RelationNotFoundException;
+
+ /**
+ * Retrieves MBeans referenced in the various roles of the relation.
+ *
+ * @return a HashMap mapping:
+ * <P> ObjectName -> ArrayList of String (role names)
+ */
+ public Map<ObjectName,List<String>> getReferencedMBeans();
+
+ /**
+ * Returns name of associated relation type.
+ *
+ * @return the name of the relation type.
+ */
+ public String getRelationTypeName();
+
+ /**
+ * Returns ObjectName of the Relation Service handling the relation.
+ *
+ * @return the ObjectName of the Relation Service.
+ */
+ public ObjectName getRelationServiceName();
+
+ /**
+ * Returns relation identifier (used to uniquely identify the relation
+ * inside the Relation Service).
+ *
+ * @return the relation id.
+ */
+ public String getRelationId();
+}