/**
    * Copyright 2005-2006 the original author or authors.
    *
    * Licensed under the Gnu General Pubic License, Version 2.0 (the
    * "License"); you may not use this file except in compliance with
    * the License. You may obtain a copy of the License at
    *
    *      http://www.opensource.org/licenses/gpl-license.php
    *
   * This program 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 for more details.
   */
  package org.figure8.join.businessobjects.security;
  
  import org.figure8.join.core.SortableEntityObject;
  import org.figure8.join.core.InvalidParameterException;
  import org.figure8.join.services.security.PermissionResourceResolver;
  import org.figure8.join.util.LogUtil;
  
  import org.apache.commons.logging.Log;
  /**
   * This is an entity representing a security role into Join system.
   * Role can also be seen a permission type handler.
   * @author  <a href="mailto:laurent.broudoux@free.fr">Laurent Broudoux</a>
   * @version $Revision: 1.1 $
   *
   * @hibernate.class table="join_roles"
   * @hibernate.cache usage="read-write"
   *
   * @hibernate.query name="join.role_findByName"
   *    query="from Role rol where rol.name = :roleName"
   */
  public class Role extends SortableEntityObject{
  
     // Static -------------------------------------------------------------------
  
     /** Get a commons logger. */
     private static final Log log = LogUtil.getLog(Role.class);
  
     /** Default role name for Join administation */
     public static final String DEFAULT_ADMIN_ROLE = "admin";
     /** Default role name for integration team members */
     public static final String DEFAULT_JOINER_ROLE = "joiner";
     /** Default role name for software project architect */
     public static final String DEFAULT_ARCHITECT_ROLE = "architect";
     /** Default role name for deliverables supplier */
     public static final String DEFAULT_SUPPLIER_ROLE = "supplier";
  
  
     // Attributes ---------------------------------------------------------------
  
     /** Role name */
     private String name;
     /** Role decription */
     private String description;
     /** Java class used to resolve resource subject to permissions within this role */
     private String permissionResourceResolverClass;
  
     /** The resolver instance of type <b>permissionResourceResolverClass</b> */
     private PermissionResourceResolver resourceResolver = null;
  
  
     // Constructors -------------------------------------------------------------
  
     /** Creates a new instance of Role */
     public Role(){
     }
  
     /**
      * Creates a new instance of Role with mandatory fields
      * @param name Name of this new role (must be unique)
      * @param description Description of this new role
      */
     public Role(String name, String description){
        this.name = name;
        this.description = description;
        this.permissionResourceResolverClass = null;
     }
     
     
     // Public -------------------------------------------------------------------
  
     /**
      * @hibernate.property column="s_name"
      *    not-null="true" unique="true"
      *    length="20" update="false"
      * @return This role name
      */
     public String getName(){
        return name;
     }
     /** @param name The name of this role */
     public void setName(String name){
        this.name = name;
     }
  
     /**
     * @hibernate.property column="s_description"
     *    not-null="true" length="60"
     * @return The decription of this role
     */
    public String getDescription(){
       return description;
    }
    /** @param description Description of this role (tips: use a key for localization) */
    public void setDescription(String description){
       this.description = description;
    }
 
    /**
     * @hibernate.property column="s_permtypeclass" length="200"
     * @return The FQN of the Java class used for managing permissions within this role
     */
    public String getPermissionResourceResolverClass(){
       return permissionResourceResolverClass;
    }
    /**
     * Give a resource resolver to this role. ie : an helper object that allows to retrieve resources
     * to whom should apply security permission within this role. This parameter must be the name of a
     * Java class that implements <code>org.figure8.join.services.security.PermissionResourceResolver</code>
     * @param permissionResourceResolverClass FQN of Java class
     * @throws InvalidParameterException if the <b>permissionResourceResolverClass</b> is not valid
     */
    public void setPermissionResourceResolverClass(String permissionResourceResolverClass) throws InvalidParameterException{
       if (permissionResourceResolverClass != null && !permissionResourceResolverClass.equals("")){
          this.permissionResourceResolverClass = permissionResourceResolverClass;
          // Try instantiating resource resolver now.
          instantiateResourceResolver();
       }
    }
 
    /**
     * Get the <code>PermissionResourceResolver</code> asssociated to this role (if any).
     * @throws InvalidParameterException if the <b>permissionResourceResolverClass</b> inner field is not valid
     * @return The resolver instance or null if no resolver is associated to this role
     */
    public PermissionResourceResolver getPermissionResourceResolver() throws InvalidParameterException{
       // Only available if there's a resource resolver.
       if (permissionResourceResolverClass != null){
          // Instantiate it if not already done.
          if (resourceResolver == null)
             instantiateResourceResolver();
          return resourceResolver;
       }
       return null;
    }
 
 
    // Protected ----------------------------------------------------------------
 
    /**
     * Try to instantiate the <code>PermissionResourceResolver</code>
     * associated with this role (if any ...)
     * @throws InvalidParameterException if the <b>permissionResourceResolverClass</b> inner field is not valid
     */
    protected void instantiateResourceResolver() throws InvalidParameterException{
       if (permissionResourceResolverClass != null && resourceResolver == null){
          try{
             // Load class from context class loader and retrieve new instance.
             Class clazz = Thread.currentThread().getContextClassLoader().loadClass(permissionResourceResolverClass);
             resourceResolver = (PermissionResourceResolver)clazz.newInstance();
          }
          catch (Exception e){
             // Log and wrap within an InvalidParameterException.
             log.error("Exception while trying to instantiate permissionResourceResolver for role '" + name + "'");
             log.error("Here's the exception message : " + e.getMessage());
             throw new InvalidParameterException("'" + permissionResourceResolverClass + "' cannot be found or does not extend PermissionResourceResolver", e);
          }
       }
    }
 
 
    // Implementation of SortableEntityObject -----------------------------------
 
    /**
     * Get the comparison criterion as a string. Criterion is the name.
     * @return The string representation of comparison and sort criterion
     */
    public String getStringForComparison(){
       return name;
    }
 }