    001// Copyright 2010, 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.annotations.IncompatibleChange;
    018
    019import java.io.IOException;
    020
    021/**
    022 * Encapsulates the logic or creating the path portion of an asset URL, including hooking the {@link org.apache.tapestry5.services.AssetPathConverter}
    023 * into the generation.
    024 *
    025 * @see org.apache.tapestry5.services.PathConstructor
    026 * @since 5.2.0
    027 */
    028public interface AssetPathConstructor
    029{
    030    /**
    031     * Constructs an asset URL path from the virtual folder and path (within the virtual folder).
    032     * After constructing the string (and honoring the {@link org.apache.tapestry5.SymbolConstants#ASSET_URL_FULL_QUALIFIED}
    033     * symbol), the result is passed through the {@link org.apache.tapestry5.services.AssetPathConverter}.
    034     *
    035     * @param virtualFolder
    036     *         corresponds to a {@link AssetRequestHandler} contributed to the AssetDispatcher service
    037     * @param path
    038     *         a path that can be used to identify the underlying {@link org.apache.tapestry5.commons.Resource} or
    039     *         or re-acquire the {@link StreamableResource}; this will be the final portion of the URL, after
    040     *         the appropriate prefix (based on whether the resource is compressed or not) and the checksum for the
    041     *         resource
    042     * @param resource
    043     *         underlying resource for the asset path; the checksum portion of the URL is obtained from the resource
    044     * @return path portion of asset URL, which is everything needed by the {@link org.apache.tapestry5.internal.services.AssetDispatcher}
    045     *         to find and stream the resource
    046     * @see StreamableResourceSource
    047     */
    048    @IncompatibleChange(release = "5.4", details = "resource parameter added, IOException may now be thrown")
    049    String constructAssetPath(String virtualFolder, String path, StreamableResource resource) throws IOException;
    050
    051}