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    /** Minimum priority. */
034    public static final int MIN_PRIORITY = Integer.MIN_VALUE;
035    /** Maximum priority. */
036    public static final int MAX_PRIORITY = Integer.MAX_VALUE;
037    
038    /**
039     * Initialize the resource handler with a resource.
040     * @param source The source uri
041     * @param objectModel The object model
042     * @param par The parameters
043     * @param additionalParameters Additional parameters that can be filled, and will be transmitted to getKey, getValidity and generateResource
044     * @return the resolved source
045     * @throws IOException If an error occurs
046     * @throws ProcessingException If an error occurs
047     */
048    public Source setup(String source, Map objectModel, Parameters par, Map<String, Object> additionalParameters) throws IOException, ProcessingException;
049    
050    /**
051     * Generate the resource configured during setup, and output it
052     * @param source The source
053     * @param out The output stream to write to
054     * @param objectModel The object model
055     * @param parameters The sitemap parameters
056     * @param additionalParameters Additional parameters
057     * @throws IOException If an error occurs
058     * @throws ProcessingException If an error occurs
059     */
060    public void generateResource(Source source, OutputStream out, Map objectModel, Parameters parameters, Map<String, Object> additionalParameters) throws IOException, ProcessingException;
061    
062    /**
063     * Determines if the resource is supported by this handler
064     * @param src The uri of resource
065     * @return <code>true</code> if the resource is supported
066     */
067    public boolean isSupported(String src);
068    
069    /**
070     * Get the priority of this handler
071     * @return the priority. The bigger the highest priority
072     */
073    public int getPriority();
074    
075    /**
076     * Return the mime type of the configured resource.
077     * @param source The source
078     * @param parameters The parameters
079     * @return The mime type.
080     */
081    public String getMimeType(Source source, Parameters parameters);
082    
083    /**
084     * Get the unique key for this resource, for cache purpose.
085     * @param source The source
086     * @param objectModel The object model
087     * @param parameters The parameters
088     * @param additionalParameters Additional parameters
089     * @return The cache key.
090     */
091    public Serializable getKey(Source source, Map objectModel, Parameters parameters, Map<String, Object> additionalParameters);
092    
093    /**
094     * Get the resource validity, for cache purpose.
095     * @param source The source
096     * @param objectModel The object model
097     * @param parameters The parameters
098     * @param additionalParameters Additional parameters
099     * @return The resource validity.
100     */
101    public SourceValidity getValidity(Source source, Map objectModel, Parameters parameters, Map<String, Object> additionalParameters);
102    
103    /**
104     * Get the resource size, if available.
105     * @param source The source
106     * @param parameters The parameters
107     * @return The resource size.
108     */
109    public long getSize(Source source, Parameters parameters);
110    
111    /**
112     * Get the resource last modified time
113     * @param source The source
114     * @param parameters The parameters
115     * @return The last modified
116     */
117    public long getLastModified(Source source, Parameters parameters);
118}