    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/blank 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 null/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}