/* ======================================================================
   Parts Copyright 2006 University of Leeds, Oxford University, University of the Highlands and Islands.

   Licensed under the Apache 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.apache.org/licenses/LICENSE-2.0

   Unless required by applicable law or agreed to in writing, software
   distributed under the License is distributed on an "AS IS" BASIS,
   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   See the License for the specific language governing permissions and
   limitations under the License.

====================================================================== */

package org.bodington.server.resources;

import java.util.Vector;

import org.bodington.database.PrimaryKey;
import org.bodington.server.BuildingServerException;

/**
 * Class for managing to hierarchy of resources.
 * This class should really have a delete method that removes a resource as it
 * has the idea if a resource is deleted.
 * @author Jon Maber
 * @author buckett
 */
public interface ResourceTree
{

    /**
     * Locate a resource in the resource tree by giving a path from the root of
     * the resource tree.
     * @param delimited_name The name of the resource from the root delimited 
     * by / characters.
     * @return The located resource or <code>null</code> if the resource couldn't
     * be found.
     * @see #findResource(String[]) 
     */
    Resource findResource(String delimited_name) throws BuildingServerException;

    /**
     * Locate a resource in the resource tree by giving the names of all the 
     * parent resources from the root of the tree.
     * @param names The names of all the resources.
     * @return The located resource or <code>null</code> if the resource couldn't
     * be found.
     * @throws BuildingServerException
     */
    Resource findResource(String[] names) throws BuildingServerException;

    /**
     * Count the number of children this resource has. If the supplied resource
     * has no children then 0 is returned. This method include childrens children
     * until a resource has no children.
     * @param resource_id The resource ID to find all the children of· 
     * @return The number of descendents.
     */
    int countDescendents(PrimaryKey resource_id) throws BuildingServerException;

    /**
     * Loads resources needed by the resource tree to function.
     * If you change the root resource while Bodington is running you should 
     * call this method the reset the ResourceTree.
     * @exception BuildingServerException If data base error or if more than one
     * root resource is found.
     */
    void loadResources() throws BuildingServerException;

    /**
     * Takes a resource (or whole branch of tree) and moves
     * it to a new place.
     * @param newparent The new location.
     * @param resource The resource to move.
     * @exception org.bodington.server.BuildingServerException If data base error.
     */
    void moveResource(Resource newparent, Resource resource)
        throws BuildingServerException;

    /**
     * Sorts sibling resources.
     * @param parent - the parent of the resources being sorted.
     * @param siblings - vector containing the resources to be sorted (in their final order
     * @exception org.bodington.server.BuildingServerException If data base error.
     */
    void sortResources(Resource parent, Vector siblings)
        throws BuildingServerException;

    /**
     * Adds a newly instantiated resource to the tree.
     * The methods will also set up an ACL for the resource
     * too.
     * @param parent The location of the new resource.
     * @param newresource The (unsaved) resource to add in. It gets saved as part
     * of the method.
     * @exception BuildingServerException If data base error.
     */
    void addResource(Resource parent, Resource newresource)
        throws BuildingServerException;

    /**
     * Removes resource and all its children from the tree.
     * It must only called when rolling back the addition of
     * a resource because it doesn't attempt to close up the
     * gap in the left and right indices of the resources
     *
     * @param r The resource to remove.
     * @exception BuildingServerException
     */

    void removeResource(Resource r) throws BuildingServerException;

    /**
     * Find the resource at the root of the resource tree.
     * @return A resource from which all resource are children.
     */
    Resource findRootResource() throws BuildingServerException;

    /**
     * Uses URLs to check if resource one resource is inside another.
     * @param a The inside Resource.
     * @param b The containing Resource.
     */
    boolean isInside(Resource a, Resource b) throws BuildingServerException;
    
    /**
     * Check to see if the resource is deleted.
     * @param resource The resource to check.
     * @return <code>true</code> if the supplied resource is deleted.
     */
    boolean isDeleted(Resource resource) throws BuildingServerException;

}