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