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 }