    001    // Copyright 2006, 2007, 2008, 2009, 2010 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 org.apache.tapestry5.Asset;
    018    import org.apache.tapestry5.ioc.Resource;
    019    import org.apache.tapestry5.ioc.annotations.UsesMappedConfiguration;
    020    import org.apache.tapestry5.ioc.services.SymbolSource;
    021    import org.apache.tapestry5.ioc.services.ThreadLocale;
    022
    023    import java.util.Locale;
    024
    025    /**
    026     * Used to find or create an {@link org.apache.tapestry5.Asset} with a given path.
    027     * <p/>
    028     * Assets are defined with a domain, and the domain is indicated by a prefix. The two builtin domains are "context:"
    029     * (for files inside the web application context) and "classpath:" for files stored on the classpath (typically, inside
    030     * a JAR, such as a component library). Other domains can be defined via contributions to the AssetSource service.
    031     * <p/>
    032     * Since 5.1.0.0, is is preferred that
    033     * {@link org.apache.tapestry5.services.AssetFactory#createAsset(org.apache.tapestry5.ioc.Resource)} return an instance
    034     * of {@link org.apache.tapestry5.Asset2}.
    035     */
    036    @UsesMappedConfiguration(AssetFactory.class)
    037    public interface AssetSource
    038    {
    039        /**
    040         * Finds the asset. The path may either be a simple file name or a relative path (relative to the base resource)
    041         * <em>or</em> it may have a prefix, such as "context:" or "classpath:", in which case it is treated as a complete
    042         * path within the indicated domain. The resulting Resource is then localized (to the provided Locale) and returned
    043         * as an Asset.
    044         * <p/>
    045         * The AssetSource caches its results, so a single Asset instance may be shared among many different components.
    046         *
    047         * @param baseResource
    048         *            base resource for computing relative paths, or null to search the classpath
    049         * @param path
    050         *            relative to the base resource
    051         * @param locale
    052         *            locale to localize the final resource to, or null for the thread's current locale
    053         * @return the asset
    054         * @throws RuntimeException
    055         *             if the asset can not be found
    056         */
    057        Asset getAsset(Resource baseResource, String path, Locale locale);
    058
    059        /**
    060         * Finds the asset, either on the classpath or (if prefixed), within the indicated domain. The result is not
    061         * localized. The underlying Asset may not exist.
    062         *
    063         * @param path
    064         *            to the resource to provide as an Asset
    065         * @return Resource for the path (the Resource may not exist)
    066         * @since 5.1.0.0
    067         */
    068        Resource resourceForPath(String path);
    069
    070        /**
    071         * Convienience for finding assets on the classpath.
    072         *
    073         * @param path
    074         *            path to the base resource, relative to classpath root
    075         * @param locale
    076         *            to localize the resource to
    077         * @return the asset
    078         * @throws RuntimeException
    079         *             if the asset can not be found
    080         */
    081        Asset getClasspathAsset(String path, Locale locale);
    082
    083        /**
    084         * Convienience for finding assets in the context.
    085         *
    086         * @param path
    087         *            path relative to the base resource (the context root)
    088         * @param locale
    089         *            to localize the resource to, or null for the locale for the current request
    090         * @return the asset
    091         * @throws RuntimeException
    092         *             if the asset can not be found
    093         * @since 5.1.0.0
    094         */
    095        Asset getContextAsset(String path, Locale locale);
    096
    097        /**
    098         * Obtains a classpath alias in the current locale (as defined by the {@link ThreadLocale} service).
    099         *
    100         * @param path
    101         *            relative to the classpath root
    102         * @return the asset
    103         * @throws RuntimeException
    104         *             if the asset can not be found
    105         */
    106        Asset getClasspathAsset(String path);
    107
    108        /**
    109         * Find an asset but does not attempt to localize it. If the path has no prefix, it is assumed to
    110         * be on the classpath.
    111         *
    112         * @since 5.2.0
    113         * @throws RuntimeException
    114         *             if the asset can not be found
    115         */
    116        Asset getUnlocalizedAsset(String path);
    117
    118        /**
    119         * As with {@link #getUnlocalizedAsset(String)}, but {@linkplain SymbolSource#expandSymbols(String) symbols
    120         * in the path are expanded}.
    121         *
    122         * @since 5.2.0
    123         */
    124        Asset getExpandedAsset(String path);
    125    }