    001// Copyright 2006, 2008, 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;
    016
    017import org.apache.tapestry5.internal.services.assets.ClasspathAssetRequestHandler;
    018import org.apache.tapestry5.ioc.Resource;
    019import org.apache.tapestry5.ioc.annotations.IncompatibleChange;
    020import org.apache.tapestry5.ioc.annotations.UsesMappedConfiguration;
    021
    022import java.util.Map;
    023
    024/**
    025 * Used as part of the support for classpath {@link org.apache.tapestry5.Asset}s, to convert the Asset's
    026 * {@link org.apache.tapestry5.ioc.Resource} to a URL that can be accessed by the client. The asset path, within the
    027 * classpath, is converted into a shorter virtual path. The term "alias" here is generally referred to as
    028 * "virtual folder" elsewhere.
    029 * <p/>
    030 * Service configuration is a map from folder aliases (short names) to complete paths. Names should not start or end end
    031 * with a slash. Generally, an alias should be a single name (not contain a slash). Paths should also not start or end
    032 * with a slash. An example mapping would be <code>mylib</code> to <code>com/example/mylib</code>.
    033 * <p/>
    034 * As originally envisioned, this service would simply <em>optimize</em> classpath assets, allowing the URL path for
    035 * such assets to be shortened (and have a version number added, important for caching); thus the word "alias" makes
    036 * sense ... it was responsible for creating an "alias" URL shorter than the default "classpath" URL.
    037 * <p/>
    038 * Starting in Tapestry 5.2, this changed; all classpath assets <strong>must</strong> be "aliased" to a shorter URL
    039 * path. Any URL that can not be shortened is now rejected. This simplifies creating new libraries, but also helps with
    040 * security concerns, as it limits which portions of the classpath can <em>ever</em> be exposed to the user agent.
    041 * <p/>
    042 * Tapestry automatically contributes a number of mappings: for the application root package itself (as alias "app") and
    043 * for each library (via {@link ComponentClassResolver#getFolderToPackageMapping()});
    044 *
    045 * @deprecated Deprecated in 5.4, with no replacement. This will no longer be used in Tapestry 5.5, as all classpath assets
    046 *             will need to be under the {@code META-INF/assets} folder (but may be maintained for compatibility reasons until 5.6).
    047 */
    048@UsesMappedConfiguration(String.class)
    049public interface ClasspathAssetAliasManager
    050{
    051    /**
    052     * Takes a classpath resource and determines the proper alias for it based on the mappings contributed to the service.
    053     *
    054     * @param resource
    055     *         classpath resource
    056     * @return URL ready to send to the client
    057     */
    058    @IncompatibleChange(release = "5.4", details = "parameter changed from String to Resource, renamed from toClientURL() to better identify purpose")
    059    AssetAlias extractAssetAlias(Resource resource);
    060
    061    /**
    062     * Returns the mappings used by the service: the keys are the folder aliases (i.e, "corelib")
    063     * and the values are the corresponding paths (i.e., "org/apache/tapestry5/corelib"). This
    064     * exists primarily so that {@link ClasspathAssetRequestHandler}s can be created automatically
    065     * for each mapping.
    066     *
    067     * @since 5.2.0
    068     */
    069    Map<String, String> getMappings();
    070}