001// Copyright 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.services.assets;
016
017import org.apache.tapestry5.ioc.Resource;
018
019import java.io.IOException;
020import java.io.InputStream;
021import java.io.OutputStream;
022
023/**
024 * An object, derived from a {@link Resource}, that can be streamed (ultimately, to a client web browser). In addition,
025 * a StreamableResource may be transformed (by the stack of interceptors around {@link StreamableResourceSource}: this
026 * includes transforming a Resource (example: CoffeeScript to JavaScript compilation), as well as aggregation
027 * and compression.
028 *
029 * @since 5.3
030 */
031public interface StreamableResource
032{
033    /**
034     * Describes the underlying {@link Resource} (or resources} for this streamable resource; expressly used
035     * as part of the object's {@code toString()}.
036     */
037    String getDescription();
038
039    /**
040     * Indicates if the content is compressed, or compressable.
041     */
042    CompressionStatus getCompression();
043
044    /**
045     * Returns the MIME content type, for example, "image/jpeg".
046     */
047    String getContentType();
048
049    /**
050     * The size, in bytes, of the underlying bytestream.
051     */
052    int getSize();
053
054    /**
055     * Streams the resource's content to the provided stream. The caller is responsible for flushing or closing
056     * the output stream.
057     */
058    void streamTo(OutputStream os) throws IOException;
059
060    /**
061     * Opens the content of the resource as an input stream; the caller is responsible for closing the stream
062     * after reading it.
063     *
064     * @return stream of the contents of the resource
065     * @throws IOException
066     */
067    InputStream openStream() throws IOException;
068
069    /**
070     * Returns the time the resource was last modified, with accuracy to one second (so as to match
071     * the HTTP request/response date headers).
072     */
073    long getLastModified();
074
075    /**
076     * Compute and return the checksum of the content for this asset; the checksum should be computed
077     * based on the uncompressed content.
078     *
079     * @return checksum for uncompressed content
080     * @since 5.4
081     * @see AssetChecksumGenerator#generateChecksum(StreamableResource)
082     */
083    String getChecksum() throws IOException;
084}