/*
    * Copyright (C) 2003-2007 eXo Platform SAS.
    *
    * This program is free software; you can redistribute it and/or
    * modify it under the terms of the GNU Affero General Public License
    * as published by the Free Software Foundation; either version 3
    * of the License, or (at your option) any later version.
    *
    * 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.
   *
   * You should have received a copy of the GNU General Public License
   * along with this program; if not, see<http://www.gnu.org/licenses/>.
   */
  package org.exoplatform.services.cms.taxonomy;
  
  import java.util.List;
  import java.util.Map;
  
  import javax.jcr.Node;
  import javax.jcr.RepositoryException;
  
  import org.exoplatform.container.component.ComponentPlugin;
  import org.exoplatform.services.cms.taxonomy.impl.TaxonomyAlreadyExistsException;
  import org.exoplatform.services.cms.taxonomy.impl.TaxonomyNodeAlreadyExistsException;
  import org.exoplatform.services.cms.taxonomy.impl.TaxonomyPlugin;
  
  /**
   * Is used to work with taxonomies. In this service,
   * there are many functions that enable you to add, find, or delete taxonomies from a node.
   *
   * @LevelAPI Experimental
   */
  public interface TaxonomyService {
    
    /**
     * Gets a taxonomy tree.
     *
     * @param taxonomyName Name of the taxonomy tree.
     * @param system If "true", the system session is used.
     * If "false", the user session is used.
     * @return The taxonomy tree node.
     * @throws RepositoryException if the taxonomy tree could not be found.
     */
    public Node getTaxonomyTree(String taxonomyName, boolean system)
        throws RepositoryException;
    
    /**
     * Gets a taxonomy tree using the user session.
     *
     * @param taxonomyName Name of the taxonomy tree.
     * @return The taxonomy tree node.
     * @throws RepositoryException if the taxonomy tree could not be found.
     */
    public Node getTaxonomyTree(String taxonomyName) throws RepositoryException;  
  
    /**
     * Gets all taxonomy trees.
     *
     * @param system If "true", the system session is used.
     * If "false", the user session is used.
     * @return The taxonomy tree nodes.
     * @throws RepositoryException if the taxonomy trees could not be found.
     */
    public List<Node> getAllTaxonomyTrees(boolean system)
        throws RepositoryException;  
  
    /**
     * Gets all taxonomy trees using the user session.
     *
     * @return The taxonomy tree nodes.
     * @throws RepositoryException if the taxonomies could not be found.
     */
    public List<Node> getAllTaxonomyTrees() throws RepositoryException;  
  
    /**
     * Checks if a taxonomy tree with the given name has already been defined.
     *
     * @param taxonomyName Name of the taxonomy tree to be checked.
     * @return "True" if the taxonomy tree exists. Otherwise, it returns "false".
     * @throws RepositoryException if the taxonomy name could not be checked.
     */
    public boolean hasTaxonomyTree(String taxonomyName) throws RepositoryException;
  
    /**
     * Creates a new taxonomy tree.
     *
     * @param taxonomyTree The taxonomy tree to be created.
     * @throws TaxonomyAlreadyExistsException if a taxonomy with the same name has
     *           already been defined.
     * @throws RepositoryException if the taxonomy tree could not be defined.
     */
    public void addTaxonomyTree(Node taxonomyTree) throws RepositoryException,
        TaxonomyAlreadyExistsException;
  
    /**
     * Updates a taxonomy tree.
    *
    * @param taxonomyName Name of the taxonomy.
    * @param taxonomyTree The taxonomy tree to be updated.
    * @throws RepositoryException if the taxonomy tree could not be updated.
    */
   public void updateTaxonomyTree(String taxonomyName, Node taxonomyTree) throws RepositoryException;
 
   /**
    * Removes a taxonomy tree.
    *
    * @param taxonomyName Name of the taxonomy to be removed.
    * @throws RepositoryException if the taxonomy tree could not be removed.
    */
   public void removeTaxonomyTree(String taxonomyName) throws RepositoryException;
 
   /**
    * Adds a new taxonomy node at the given location.
    *
    * @param workspace Name of the workspace to which the taxonomy node is added.
    * @param parentPath The place where the taxonomy node will be added.
    * @param taxoNodeName Name of the taxonomy node.
    * @param creator The user who created the taxonomy node.
    * @throws TaxonomyNodeAlreadyExistsException if a taxonomy node with the same
    *           name has already been added.
    * @throws RepositoryException if the taxonomy node could not be added.
    */
   public void addTaxonomyNode(String workspace,
                               String parentPath,
                               String taxoNodeName,
                               String creator) throws RepositoryException,
                                              TaxonomyNodeAlreadyExistsException;
   
   /**
    * Removes a taxonomy node located at the given absolute path.
    *
    * @param workspace Name of the workspace from which the taxonomy node is removed.
    * @param absPath The given absolute path.
    * @throws RepositoryException if the taxonomy node could not be removed.
    */
   public void removeTaxonomyNode(String workspace, String absPath)
       throws RepositoryException;  
 
   /**
    * Copies or cuts the taxonomy node from source path to destination path.
    * The parameter type indicates if the node is cut or copied.
    * 
    * @param workspace Name of the workspace which contains the taxonomy node.
    * @param srcPath Source path of the taxonomy node.
    * @param destPath Destination path of the taxonomy node.
    * @param type Type of moving: copy or cut.
    * @throws RepositoryException if the taxonomy node could not be moved.
    */
   public void moveTaxonomyNode(String workspace, String srcPath, String destPath, String type) throws RepositoryException;
 
   /**
    * Checks if a category node exists in a given taxonomy by using the user session.
    *
    * @param node The category node to be checked.
    * @param taxonomyName Name of the given taxonomy.
    * @throws RepositoryException if the category cannot be checked.
    */
   public boolean hasCategories(Node node, String taxonomyName) throws RepositoryException;
 
   /**
    * Checks if a category node exists in a given taxonomy.
    *
    * @param node The category node to be checked.
    * @param taxonomyName Name of the given taxonomy.
    * @param system If "true", the system session is used. If "false", the user session is used.
    * @return "True" if the category exists. Otherwise, it returns "false".
    * @throws RepositoryException if the category cannot be checked.
    */
   public boolean hasCategories(Node node, String taxonomyName, boolean system) throws RepositoryException;
 
   /**
    * Gets all categories that contain a given node under a taxonomy tree.
    *
    * @param node The given node.
    * @param taxonomyName The taxonomy tree where categories are got.
    * @return The list of category nodes.
    * @throws RepositoryException if the categories cannot be retrieved.
    */
   public List<Node> getCategories(Node node, String taxonomyName) throws RepositoryException;
 
   /**
    * Gets all categories that contain a given node under a taxonomy tree.
    *
    * @param node The given node.
    * @param taxonomyName The taxonomy tree where categories are got.
    * @param system If "true", the system session is used. If "false", the user session is used.
    * @return The list of category nodes.
    * @throws RepositoryException if the categories cannot be retrieved.
    */
   public List<Node> getCategories(Node node, String taxonomyName, boolean system) throws RepositoryException;
 
   /**
    * Gets all categories that contain a given node under all taxonomy trees.
    *
    * @param node The given node.
    * @return The list of category nodes.
    * @throws RepositoryException
    */
   public List<Node> getAllCategories(Node node) throws RepositoryException;
 
   /**
    * Gets all categories that contain a given node under all taxonomy trees.
    *
    * @param node The given node.
    * @param system If "true", the system session is used. If "false", the user session is used.
    * @return The list of category nodes.
    * @throws RepositoryException
    */
   public List<Node> getAllCategories(Node node, boolean system) throws RepositoryException;
 
   /**
    * Removes a category from a given node.
    *
    * @param node The given node.
    * @param taxonomyName The taxonomy tree that contains the removed category.
    * @param categoryPath Path of the removed category.
    * @throws RepositoryException if the category cannot be removed.
    */
   public void removeCategory(Node node, String taxonomyName, String categoryPath)
       throws RepositoryException;
 
   /**
    * Removes a category from a given node.
    *
    * @param node The given node.
    * @param taxonomyName The taxonomy tree that contains the removed category.
    * @param categoryPath Path of the removed category.
    * @param system If "true", the system session is used. If "false", the user session is used.
    * @throws RepositoryException if the category cannot be removed.
    */
   public void removeCategory(Node node, String taxonomyName, String categoryPath, boolean system)
       throws RepositoryException;
 
   /**
    * Adds categories to a given node.
    *
    * @param node The given node.
    * @param taxonomyName The taxonomy tree that contains the added category.
    * @param categoryPaths Paths of the added categories.
    * @throws RepositoryException if the categories cannot be added.
    */
   public void addCategories(Node node, String taxonomyName, String[] categoryPaths)
       throws RepositoryException;
 
   /**
    * Adds categories to a given node.
    *
    * @param node The given node.
    * @param taxonomyName The taxonomy tree that contains the added category.
    * @param categoryPaths Paths of the added categories.
    * @param system If "true", the system session is used. If "false", the user session is used.
    * @throws RepositoryException if the categories cannot be added.
    */
   public void addCategories(Node node, String taxonomyName, String[] categoryPaths, boolean system)
       throws RepositoryException;
 
   /**
    * Adds a new category to a given node.
    *
    * @param node The given node.
    * @param taxonomyName The taxonomy tree that contains the added category.
    * @param categoryPath Path of the added category.
    * @throws RepositoryException if the category cannot be added.
    */
   public void addCategory(Node node, String taxonomyName, String categoryPath)
       throws RepositoryException;
 
   /**
    * Adds a new category to a given node.
    *
    * @param node The given node.
    * @param taxonomyName The taxonomy tree that contains the added category.
    * @param categoryPath Path of the added category.
    * @param system If "true", the system session is used. If "false", the user session is used.
    * @throws RepositoryException if the category cannot be added.
    */
   public void addCategory(Node node, String taxonomyName, String categoryPath, boolean system)
       throws RepositoryException;
 
   /**
    * Gets default permissions of a taxonomy tree.
    *
    * @return Map that shows permissions of the taxonomy tree.
    */
   public Map<String, String[]> getTaxonomyTreeDefaultUserPermission();
   
   /**
   * Gets the limited length of a category name.
   */
   public String getCategoryNameLength();
 
   /**
    * Adds a new taxonomy plugin to the Taxonomy Service.
    *
    * @param plugin The plugin to be added.
    */
   public void addTaxonomyPlugin(ComponentPlugin plugin);
   
   /**
    * Initializes all taxonomy plugins that have been set in the configuration files.
    *
    * @see TaxonomyPlugin
    * @throws Exception
    */
   public void init() throws Exception;  
 }