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     * Returns true if this {@link ResourceHandler} handles "Range" requests. false by default.
047     * @return true if this {@link ResourceHandler} handles "Range" requests.
048     */
049    public default boolean acceptRanges()
050    {
051        return false;
052    }
053    
054    /**
055     * Generate the resource configured during setup, and output it
056     * @param out The output stream to write to
057     * @throws IOException If an error occurs
058     * @throws ProcessingException If an error occurs
059     */
060    public void generate(OutputStream out) throws IOException, ProcessingException;
061    
062    /**
063     * Generate the resource configured during setup in the context of a range request.
064     * @param out The output stream to write to
065     * @param offset the first byte to send
066     * @param length the stream length to send
067     * @throws IOException If an error occurs
068     * @throws ProcessingException If an error occurs
069     */
070    public default void generate(OutputStream out, long offset, long length) throws IOException, ProcessingException
071    {
072        throw new UnsupportedOperationException("Ranges requests are not supported");
073    }
074    
075    /**
076     * Get the unique key for this resource, for cache purpose.
077     * @return The cache key.
078     */
079    public Serializable getKey();
080    
081    /**
082     * Get the resource validity, for cache purpose.
083     * @return The resource validity.
084     */
085    public SourceValidity getValidity();
086    
087    /**
088     * Get the resource size, if available. -1 if unknown.
089     * @return The resource size.
090     */
091    public default long getLength()
092    {
093        return -1;
094    }
095    
096    /**
097     * Get the resource last modified time
098     * @return The last modified
099     */
100    public long getLastModified();
101    
102    /**
103     * Return the mime type of the configured resource.
104     * @return The mime type.
105     */
106    public String getMimeType();
107
108    /**
109     * Returns true if the response Content-Length header should be set according to the source's length 
110     * (ie. the source is not transformed during processing).
111     * @return true if the source's length can be relied on
112     */
113    public default boolean shouldUseSourceContentLength()
114    {
115        return false;
116    }
117}