    001// Licensed under the Apache License, Version 2.0 (the "License");
    002// you may not use this file except in compliance with the License.
    003// You may obtain a copy of the License at
    004//
    005// http://www.apache.org/licenses/LICENSE-2.0
    006//
    007// Unless required by applicable law or agreed to in writing, software
    008// distributed under the License is distributed on an "AS IS" BASIS,
    009// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    010// See the License for the specific language governing permissions and
    011// limitations under the License.
    012
    013package org.apache.tapestry5.services.assets;
    014
    015import org.apache.tapestry5.ContentType;
    016import org.apache.tapestry5.ioc.Resource;
    017import org.apache.tapestry5.ioc.annotations.IncompatibleChange;
    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 resource's content type.
    046     */
    047    @IncompatibleChange(release = "5.4", details = "Changed from type String to ContentType")
    048    ContentType getContentType();
    049
    050    /**
    051     * The size, in bytes, of the underlying bytestream.
    052     */
    053    int getSize();
    054
    055    /**
    056     * Streams the resource's content to the provided stream. The caller is responsible for flushing or closing
    057     * the output stream.
    058     */
    059    void streamTo(OutputStream os) throws IOException;
    060
    061    /**
    062     * Opens the content of the resource as an input stream; the caller is responsible for closing the stream
    063     * after reading it.
    064     *
    065     * @return stream of the contents of the resource
    066     * @throws IOException
    067     */
    068    InputStream openStream() throws IOException;
    069
    070    /**
    071     * Returns the time the resource was last modified, with accuracy to one second (so as to match
    072     * the HTTP request/response date headers).
    073     */
    074    long getLastModified();
    075
    076    /**
    077     * Compute and return the checksum of the content for this asset; the checksum should be computed
    078     * based on the uncompressed content.
    079     *
    080     * @return checksum for uncompressed content
    081     * @see AssetChecksumGenerator#generateChecksum(StreamableResource)
    082     * @since 5.4
    083     */
    084    String getChecksum() throws IOException;
    085
    086
    087    /**
    088     * Returns a new StreamableResource that includes the provided customizer. Customizers are invoked
    089     * in the order they are added.
    090     *
    091     * @since 5.4
    092     */
    093    StreamableResource addResponseCustomizer(ResponseCustomizer customizer);
    094
    095    /**
    096     * Returns the customizer, if any, for this resource.  This may represent an aggregate customizer.
    097     *
    098     * @since 5.4
    099     */
    100    ResponseCustomizer getResponseCustomizer();
    101
    102    /**
    103     * Returns a new StreamableResource instance with the new content type.
    104     *
    105     * @param newContentType
    106     * @since 5.4
    107     */
    108    StreamableResource withContentType(ContentType newContentType);
    109}