001/*
002 *  Copyright 2016 Anyware Services
003 *
004 *  Licensed under the Apache License, Version 2.0 (the "License");
005 *  you may not use this file except in compliance with the License.
006 *  You may obtain a copy of the License at
007 *
008 *      http://www.apache.org/licenses/LICENSE-2.0
009 *
010 *  Unless required by applicable law or agreed to in writing, software
011 *  distributed under the License is distributed on an "AS IS" BASIS,
012 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 *  See the License for the specific language governing permissions and
014 *  limitations under the License.
015 */
016package org.ametys.core.resources;
017
018import java.io.IOException;
019import java.io.OutputStream;
020import java.io.Serializable;
021import java.util.Map;
022
023import org.apache.avalon.framework.parameters.Parameters;
024import org.apache.cocoon.ProcessingException;
025import org.apache.excalibur.source.Source;
026import org.apache.excalibur.source.SourceValidity;
027
028/**
029 * Interface used to handle resources
030 */
031public interface ResourceHandler
032{
033    /**
034     * Initialize the resource handler with a resource.
035     * @param source The source uri
036     * @param objectModel The object model
037     * @param par The parameters
038     * @param readForDownload if the resource is to be downloaded and not rendered.
039     * @return the resolved source
040     * @throws IOException If an error occurs
041     * @throws ProcessingException If an error occurs
042     */
043    public Source setup(String source, Map objectModel, Parameters par, boolean readForDownload) throws IOException, ProcessingException;
044    
045    /**
046     * Generate the resource configured during setup, and output it
047     * @param out The output stream to write to
048     * @throws IOException If an error occurs
049     * @throws ProcessingException If an error occurs
050     */
051    public void generate(OutputStream out) throws IOException, ProcessingException;
052    
053    /**
054     * Get the unique key for this resource, for cache purpose.
055     * @return The cache key.
056     */
057    public Serializable getKey();
058    
059    /**
060     * Get the resource validity, for cache purpose.
061     * @return The resource validity.
062     */
063    public SourceValidity getValidity();
064    
065    /**
066     * Get the resource size, if available.
067     * @return The resource size.
068     */
069    public long getLength();
070    
071    /**
072     * Get the resource last modified time
073     * @return The last modified
074     */
075    public long getLastModified();
076    
077    /**
078     * Return the mime type of the configured resource.
079     * @return The mime type.
080     */
081    public String getMimeType();
082
083    /**
084     * Returns true if the response Content-Length header should be set according to the source's length 
085     * (ie. the source is not transformed during processing).
086     * @return true if the source's length can be relied on
087     */
088    public default boolean shouldUseSourceContentLength()
089    {
090        return false;
091    }
092}