/*

 * Copyright (c) 2000, 2008, Oracle and/or its affiliates. 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.  Oracle designates this

 * particular file as subject to the "Classpath" exception as provided

 * by Oracle 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 Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA

 * or visit www.oracle.com if you need additional information or have any

 * questions.

 */

package javax.management.relation;

import java.util.ArrayList;

import java.util.HashMap;

import java.util.Iterator;

import java.util.Map;

import java.util.List;

import java.util.concurrent.atomic.AtomicBoolean;

import static com.sun.jmx.defaults.JmxProperties.RELATION_LOGGER;

import static com.sun.jmx.mbeanserver.Util.cast;

import javax.management.InstanceNotFoundException;

import javax.management.MBeanException;

import javax.management.MBeanRegistration;

import javax.management.MBeanServer;

import javax.management.ObjectName;

import javax.management.ReflectionException;

/**

 * A RelationSupport object is used internally by the Relation Service to

 * represent simple relations (only roles, no properties or methods), with an

 * unlimited number of roles, of any relation type. As internal representation,

 * it is not exposed to the user.

 * <P>RelationSupport class conforms to the design patterns of standard MBean. So

 * the user can decide to instantiate a RelationSupport object himself as

 * a MBean (as it follows the MBean design patterns), to register it in the

 * MBean Server, and then to add it in the Relation Service.

 * <P>The user can also, when creating his own MBean relation class, have it

 * extending RelationSupport, to retrieve the implementations of required

 * interfaces (see below).

 * <P>It is also possible to have in a user relation MBean class a member

 * being a RelationSupport object, and to implement the required interfaces by

 * delegating all to this member.

 * <P> RelationSupport implements the Relation interface (to be handled by the

 * Relation Service).

 * <P>It implements also the MBeanRegistration interface to be able to retrieve

 * the MBean Server where it is registered (if registered as a MBean) to access

 * to its Relation Service.

 *

 * @since 1.5

 */

public class RelationSupport

    implements RelationSupportMBean, MBeanRegistration {

    //

    // Private members

    //

    // Relation identifier (expected to be unique in the Relation Service where

    // the RelationSupport object will be added)

    private String myRelId = null;

    // ObjectName of the Relation Service where the relation will be added

    // REQUIRED if the RelationSupport is created by the user to be registered as

    // a MBean, as it will have to access the Relation Service via the MBean

    // Server to perform the check regarding the relation type.

    // Is null if current object is directly created by the Relation Service,

    // as the object will directly access it.

    private ObjectName myRelServiceName = null;

    // Reference to the MBean Server where the Relation Service is

    // registered

    // REQUIRED if the RelationSupport is created by the user to be registered as

    // a MBean, as it will have to access the Relation Service via the MBean

    // Server to perform the check regarding the relation type.

    // If the Relationbase object is created by the Relation Service (use of

    // createRelation() method), this is null as not needed, direct access to

    // the Relation Service.

    // If the Relationbase object is created by the user and registered as a

    // MBean, this is set by the preRegister() method below.

    private MBeanServer myRelServiceMBeanServer = null;

    // Relation type name (must be known in the Relation Service where the

    // relation will be added)

    private String myRelTypeName = null;

    // Role map, mapping <role-name> -> <Role>

    // Initialized by role list in the constructor, then updated:

    // - if the relation is a MBean, via setRole() and setRoles() methods, or

    //   via Relation Service setRole() and setRoles() methods

    // - if the relation is internal to the Relation Service, via

    //   setRoleInt() and setRolesInt() methods.

    private final Map<String,Role> myRoleName2ValueMap = new HashMap<String,Role>();

    // Flag to indicate if the object has been added in the Relation Service

    private final AtomicBoolean myInRelServFlg = new AtomicBoolean();

    //

    // Constructors

    //

    /**

     * Creates a {@code RelationSupport} object.

     * <P>This constructor has to be used when the RelationSupport object will

     * be registered as a MBean by the user, or when creating a user relation

     * MBean whose class extends RelationSupport.

     * <P>Nothing is done at the Relation Service level, i.e.

     * the {@code RelationSupport} object is not added to the

     * {@code RelationService} and no checks are performed to

     * see if the provided values are correct.

     * The object is always created, EXCEPT if:

     * <P>- any of the required parameters is {@code null}.

     * <P>- the same name is used for two roles.

     * <P>To be handled as a relation, the {@code RelationSupport} object has

     * to be added to the Relation Service using the Relation Service method

     * addRelation().

     *

     * @param relationId  relation identifier, to identify the relation in the

     * Relation Service.

     * <P>Expected to be unique in the given Relation Service.

     * @param relationServiceName  ObjectName of the Relation Service where

     * the relation will be registered.

     * <P>This parameter is required as it is the Relation Service that is

     * aware of the definition of the relation type of the given relation,

     * so that will be able to check update operations (set).

     * @param relationTypeName  Name of relation type.

     * <P>Expected to have been created in the given Relation Service.

     * @param list  list of roles (Role objects) to initialize the

     * relation. Can be {@code null}.

     * <P>Expected to conform to relation info in associated relation type.

     *

     * @exception InvalidRoleValueException  if the same name is used for two

     * roles.

     * @exception IllegalArgumentException  if any of the required parameters

     * (relation id, relation service ObjectName, or relation type name) is

     * {@code null}.

     */

    public RelationSupport(String relationId,

                        ObjectName relationServiceName,

                        String relationTypeName,

                        RoleList list)

        throws InvalidRoleValueException,

               IllegalArgumentException {

        super();

        RELATION_LOGGER.entering(RelationSupport.class.getName(),

                "RelationSupport");

        // Can throw InvalidRoleValueException and IllegalArgumentException

        initMembers(relationId,

                    relationServiceName,

                    null,

                    relationTypeName,

                    list);

        RELATION_LOGGER.exiting(RelationSupport.class.getName(),

                "RelationSupport");

    }

    /**

     * Creates a {@code RelationSupport} object.

     * <P>This constructor has to be used when the user relation MBean

     * implements the interfaces expected to be supported by a relation by

     * delegating to a RelationSupport object.

     * <P>This object needs to know the Relation Service expected to handle the

     * relation. So it has to know the MBean Server where the Relation Service

     * is registered.

     * <P>According to a limitation, a relation MBean must be registered in the

     * same MBean Server as the Relation Service expected to handle it. So the

     * user relation MBean has to be created and registered, and then the

     * wrapped RelationSupport object can be created within the identified MBean

     * Server.

     * <P>Nothing is done at the Relation Service level, i.e.

     * the {@code RelationSupport} object is not added to the

     * {@code RelationService} and no checks are performed to

     * see if the provided values are correct.

     * The object is always created, EXCEPT if:

     * <P>- any of the required parameters is {@code null}.

     * <P>- the same name is used for two roles.

     * <P>To be handled as a relation, the {@code RelationSupport} object has

     * to be added to the Relation Service using the Relation Service method

     * addRelation().

     *

     * @param relationId  relation identifier, to identify the relation in the

     * Relation Service.

     * <P>Expected to be unique in the given Relation Service.

     * @param relationServiceName  ObjectName of the Relation Service where

     * the relation will be registered.

     * <P>This parameter is required as it is the Relation Service that is

     * aware of the definition of the relation type of the given relation,

     * so that will be able to check update operations (set).

     * @param relationServiceMBeanServer  MBean Server where the wrapping MBean

     * is or will be registered.

     * <P>Expected to be the MBean Server where the Relation Service is or will

     * be registered.

     * @param relationTypeName  Name of relation type.

     * <P>Expected to have been created in the given Relation Service.

     * @param list  list of roles (Role objects) to initialize the

     * relation. Can be {@code null}.

     * <P>Expected to conform to relation info in associated relation type.

     *

     * @exception InvalidRoleValueException  if the same name is used for two

     * roles.

     * @exception IllegalArgumentException  if any of the required parameters

     * (relation id, relation service ObjectName, relation service MBeanServer,

     * or relation type name) is {@code null}.

     */

    public RelationSupport(String relationId,

                        ObjectName relationServiceName,

                        MBeanServer relationServiceMBeanServer,

                        String relationTypeName,

                        RoleList list)

        throws InvalidRoleValueException,

               IllegalArgumentException {

        super();

        if (relationServiceMBeanServer == null) {

            String excMsg = "Invalid parameter.";

            throw new IllegalArgumentException(excMsg);

        }

        RELATION_LOGGER.entering(RelationSupport.class.getName(),

                "RelationSupport");

        // Can throw InvalidRoleValueException and

        // IllegalArgumentException

        initMembers(relationId,

                    relationServiceName,

                    relationServiceMBeanServer,

                    relationTypeName,

                    list);

        RELATION_LOGGER.exiting(RelationSupport.class.getName(),

                "RelationSupport");

    }

    //

    // Relation Interface

    //

    /**

     * 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 {

        if (roleName == null) {

            String excMsg = "Invalid parameter.";

            throw new IllegalArgumentException(excMsg);

        }

        RELATION_LOGGER.entering(RelationSupport.class.getName(),

                "getRole", roleName);

        // Can throw RoleNotFoundException and

        // RelationServiceNotRegisteredException

        List<ObjectName> result = cast(

            getRoleInt(roleName, false, null, false));

        RELATION_LOGGER.exiting(RelationSupport.class.getName(), "getRole");

        return result;

    }

    /**

     * 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 {

        if (roleNameArray == null) {

            String excMsg = "Invalid parameter.";

            throw new IllegalArgumentException(excMsg);

        }

        RELATION_LOGGER.entering(RelationSupport.class.getName(), "getRoles");

        // Can throw RelationServiceNotRegisteredException

        RoleResult result = getRolesInt(roleNameArray, false, null);

        RELATION_LOGGER.exiting(RelationSupport.class.getName(), "getRoles");

        return result;

    }

    /**

     * 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 {

        RELATION_LOGGER.entering(RelationSupport.class.getName(),

                "getAllRoles");

        RoleResult result = null;

        try {

            result = getAllRolesInt(false, null);

        } catch (IllegalArgumentException exc) {

            // OK : Invalid parameters, ignore...

        }

        RELATION_LOGGER.exiting(RelationSupport.class.getName(), "getAllRoles");

        return result;

    }

    /**

     * Returns all roles in the relation without checking read mode.

     *

     * @return a RoleList

     */

    public RoleList retrieveAllRoles() {

        RELATION_LOGGER.entering(RelationSupport.class.getName(),

                "retrieveAllRoles");

        RoleList result;

        synchronized(myRoleName2ValueMap) {

            result =

                new RoleList(new ArrayList<Role>(myRoleName2ValueMap.values()));

        }

        RELATION_LOGGER.exiting(RelationSupport.class.getName(),

                "retrieveAllRoles");

        return result;

    }

    /**

     * 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 {

        if (roleName == null) {

            String excMsg = "Invalid parameter.";

            throw new IllegalArgumentException(excMsg);

        }

        RELATION_LOGGER.entering(RelationSupport.class.getName(),

                "getRoleCardinality", roleName);

        // Try to retrieve the role

        Role role;

        synchronized(myRoleName2ValueMap) {

            // No null Role is allowed, so direct use of get()

            role = (myRoleName2ValueMap.get(roleName));

        }

        if (role == null) {

            int pbType = RoleStatus.NO_ROLE_WITH_NAME;

            // Will throw a RoleNotFoundException

            //

            // Will not throw InvalidRoleValueException, so catch it for the

            // compiler

            try {

                RelationService.throwRoleProblemException(pbType,

                                                          roleName);

            } catch (InvalidRoleValueException exc) {

                // OK : Do not throw InvalidRoleValueException as

                //      a RoleNotFoundException will be thrown.

            }

        }

        List<ObjectName> roleValue = role.getRoleValue();

        RELATION_LOGGER.exiting(RelationSupport.class.getName(),

                "getRoleCardinality");

        return roleValue.size();

    }

    /**

     * 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 {

        if (role == null) {

            String excMsg = "Invalid parameter.";

            throw new IllegalArgumentException(excMsg);

        }

        RELATION_LOGGER.entering(RelationSupport.class.getName(),

                "setRole", role);

        // Will return null :)

        Object result = setRoleInt(role, false, null, false);

        RELATION_LOGGER.exiting(RelationSupport.class.getName(), "setRole");

        return;

    }

    /**

     * 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 list  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 list)

        throws IllegalArgumentException,

               RelationServiceNotRegisteredException,

               RelationTypeNotFoundException,

               RelationNotFoundException {

        if (list == null) {

            String excMsg = "Invalid parameter.";

            throw new IllegalArgumentException(excMsg);

        }

        RELATION_LOGGER.entering(RelationSupport.class.getName(),

                "setRoles", list);