/* ======================================================================
 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.List;

import javax.servlet.http.HttpServletRequest;

import org.bodington.server.BuildingServerException;
import org.bodington.servlet.Request;
import org.bodington.servlet.facilities.Facility;

// TODO: All the methods in this interface allow far too many BSE exceptions through.

public interface ResourceCreator
{

    public abstract Resource newResource();

    /**
     * Initialize the resource. This method enables a resource to be initialized
     * from form parameters within the request parameter. The basic properties
     * such as <i>title</i>, <i>introduction</i> and <i>description</i> are
     * handled by {@link Facility} itself. This method provides a point for
     * subclasses to override in order to handle the additional properties of
     * their corresponding resources. If this method returns <code>false</code>
     * then initialization of the resource is effectively terminated. This 
     * method should not attempt to save the resource itself.  
     * @param request the request object containing form parameters.
     * @param newResource the resource to be initialized.
     * @return <code>true</code> if the resource is initialized successfully, 
     * otherwise <code>false</code>.
     * @throws Exception
     */
    public abstract List initResource(HttpServletRequest request, Resource newResource)
        throws Exception;

    /**
     * Use the properties of an existing Resource to initialise a newly created
     * Resource.
     * @param original The resource with properties to copy.
     * @param new_resource The resource to initialise.
     * @return True if initialisation was OK.
     * @exception BuildingServerException Thrown if there is any problem
     *            initialising the resource.
     */
    public abstract boolean initResource(Resource original,
        Resource new_resource) throws BuildingServerException;

    /**
     * Default creation does nothing but other facilities can
     * check user input print errors and prevent resource creation
     * by returning false.
     * @param newResource
     * @return List of errors encountered during validation.
     * @throws BuildingServerException 
     */
    public abstract List validate(Resource newResource) throws BuildingServerException;

    /**
     * Called after a new resource is created and has been added to the ResourceTree.
     * This means it has an ACL so extra permissions can be added. This method 
     * shouldn't throw an exception as due to the lack of transactions we can't
     * easily remove resources from the tree.
     * @param breq The Request.
     * @param newResource The Resource that has just been added.
     * @return A list of problems that occurred.
     * @throws Exception This should be removed if the code gets tidied up.
     */
    public List postCreate(Request breq, Resource newResource) throws Exception;

}