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