001// Copyright 2006, 2008, 2011, 2013 The Apache Software Foundation
002//
003// Licensed under the Apache License, Version 2.0 (the "License");
004// you may not use this file except in compliance with the License.
005// You may obtain a copy of the License at
006//
007// http://www.apache.org/licenses/LICENSE-2.0
008//
009// Unless required by applicable law or agreed to in writing, software
010// distributed under the License is distributed on an "AS IS" BASIS,
011// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
012// See the License for the specific language governing permissions and
013// limitations under the License.
014
015package org.apache.tapestry5.internal.services;
016
017import org.apache.tapestry5.commons.Resource;
018import org.apache.tapestry5.services.assets.StreamableResource;
019import org.apache.tapestry5.services.assets.StreamableResourceSource;
020
021import javax.servlet.http.HttpServletResponse;
022import java.io.IOException;
023import java.util.EnumSet;
024import java.util.Set;
025
026/**
027 * Responsible for streaming the contents of a resource to the client. This is sometimes a simple
028 * {@link Resource} (often from the {@link org.apache.tapestry5.internal.services.javascript.ModuleDispatcher},
029 * or more frequently an asset represented as a {@link StreamableResource} (via {@link AssetDispatcher}, {@link org.apache.tapestry5.services.assets.AssetRequestHandler},
030 * and {@link StreamableResourceSource}). As of 5.4, the ResourceStreamer handles ETag support, as well as
031 * validation of the checksum (provided in the URL).
032 *
033 * @since 5.1.0.0
034 */
035public interface ResourceStreamer
036{
037    /**
038     * Used to customize the behavior of {@link #streamResource(org.apache.tapestry5.commons.Resource, java.lang.String, java.util.Set)}.
039     *
040     * @since 5.4
041     */
042    enum Options
043    {
044        /**
045         * Omit the normal expiration date header; this is appropriate for JavaScript modules, which cannot include
046         * their own checksum in the URL (instead, we rely on ETags to prevent unwanted data transfer).
047         */
048        OMIT_EXPIRATION
049    }
050
051    static final Set<Options> DEFAULT_OPTIONS = EnumSet.noneOf(Options.class);
052
053    /**
054     * Streams the content of the resource to the client (or sends
055     * an alternative response such as {@link HttpServletResponse#SC_NOT_MODIFIED}). Encapsulates logic for compression
056     * and for caching.
057     *
058     * @param resource
059     *         to stream
060     * @param providedChecksum
061     *         checksum from URL (or null to not validate against checksum, which is normal for modules)
062     * @param options
063     *         enable or disable certain features
064     * @see StreamableResourceSource
065     */
066    boolean streamResource(Resource resource, String providedChecksum, Set<Options> options) throws IOException;
067
068    /**
069     * Streams a resource that has been assembled elsewhere.  The StreamableResource may reflect either a normal
070     * or a compressed stream, depending on the type of resource and the capabilities of the client.
071     *
072     * @param resource
073     *         content to stream
074     * @param providedChecksum
075     *         checksum provided (in the URL) to validate against the {@linkplain org.apache.tapestry5.services.assets.StreamableResource#getChecksum()} actual checksum}
076     *         for the resource, may be blank to not validate against the checksum
077     * @param options
078     *         enable or disable certain features
079     * @return true if the request was handled (even if sending a {@link HttpServletResponse#SC_NOT_MODIFIED} response),
080     *         or false if the request was not handled (because the provided checksum did not match the actual checksum).
081     * @throws IOException
082     * @since 5.4
083     */
084    boolean streamResource(StreamableResource resource, String providedChecksum, Set<Options> options) throws IOException;
085}