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