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}