001// Copyright 2006-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.Asset; 018import org.apache.tapestry5.ComponentResources; 019import org.apache.tapestry5.ioc.Resource; 020import org.apache.tapestry5.ioc.annotations.UsesMappedConfiguration; 021import org.apache.tapestry5.ioc.services.SymbolSource; 022import org.apache.tapestry5.ioc.services.ThreadLocale; 023 024import java.util.Locale; 025 026/** 027 * Used to find or create an {@link org.apache.tapestry5.Asset} with a given path. 028 * <p/> 029 * Assets are defined with a domain, and the domain is indicated by a prefix. The two builtin domains are "context:" 030 * (for files inside the web application context) and "classpath:" for files stored on the classpath (typically, inside 031 * a JAR, such as a component library). Other domains can be defined via contributions to the AssetSource service. 032 * <p/> 033 * Since 5.1.0.0, is is preferred that 034 * {@link org.apache.tapestry5.services.AssetFactory#createAsset(org.apache.tapestry5.ioc.Resource)} return an instance 035 * of {@link org.apache.tapestry5.Asset2}. 036 */ 037@UsesMappedConfiguration(AssetFactory.class) 038public interface AssetSource 039{ 040 /** 041 * Finds the asset. The path may either be a simple file name or a relative path (relative to the base resource) 042 * <em>or</em> it may have a prefix, such as "context:" or "classpath:", in which case it is treated as a complete 043 * path within the indicated domain. The resulting Resource is then localized (to the provided Locale) and returned 044 * as an Asset. 045 * <p/> 046 * The AssetSource caches its results, so a single Asset instance may be shared among many different components. 047 * 048 * @param baseResource 049 * base resource for computing relative paths, or null to search the classpath 050 * @param path 051 * relative to the base resource 052 * @param locale 053 * locale to localize the final resource to, or null for the thread's current locale 054 * @return the asset 055 * @throws RuntimeException 056 * if the asset can not be found 057 */ 058 Asset getAsset(Resource baseResource, String path, Locale locale); 059 060 /** 061 * Finds the asset, either on the classpath or (if prefixed), within the indicated domain. The result is not 062 * localized. The underlying Asset may not exist. 063 * 064 * @param path 065 * to the resource to provide as an Asset 066 * @return Resource for the path (the Resource may not exist) 067 * @since 5.1.0.0 068 */ 069 Resource resourceForPath(String path); 070 071 /** 072 * Convenience for finding assets on the classpath. 073 * 074 * @param path 075 * path to the base resource, relative to classpath root 076 * @param locale 077 * to localize the resource to 078 * @return the asset 079 * @throws RuntimeException 080 * if the asset can not be found 081 */ 082 Asset getClasspathAsset(String path, Locale locale); 083 084 /** 085 * Convenience for finding assets in the context. 086 * 087 * @param path 088 * path relative to the base resource (the context root) 089 * @param locale 090 * to localize the resource to, or null for the locale for the current request 091 * @return the asset 092 * @throws RuntimeException 093 * if the asset can not be found 094 * @since 5.1.0.0 095 */ 096 Asset getContextAsset(String path, Locale locale); 097 098 /** 099 * Obtains a classpath asset in the current locale (as defined by the {@link ThreadLocale} service). 100 * 101 * @param path 102 * relative to the classpath root 103 * @return the asset 104 * @throws RuntimeException 105 * if the asset can not be found 106 */ 107 Asset getClasspathAsset(String path); 108 109 /** 110 * Find an asset but does not attempt to localize it. If the path has no prefix, it is assumed to 111 * be on the classpath. 112 * 113 * @throws RuntimeException 114 * if the asset can not be found 115 * @since 5.2.0 116 */ 117 Asset getUnlocalizedAsset(String path); 118 119 /** 120 * As with {@link #getUnlocalizedAsset(String)}, but {@linkplain SymbolSource#expandSymbols(String) symbols} 121 * in the path are expanded}. 122 * 123 * @since 5.2.0 124 */ 125 Asset getExpandedAsset(String path); 126 127 /** 128 * Gets an asset that is used with, or injected into, a component, that will be exposed to the client. 129 * This encapsulates the new, in 5.4, standard that assets should all be stored in (sub-folders of) 130 * <code>META-INF/assets/<em>library-name</em>/</code>. 131 * This is the preferred location in 5.4, with compatibility for 5.3 that allows assets to be stored on the classpath 132 * alongside Java classes and server-only resources such as templates and message catalogs. 133 * 134 * @param resources 135 * resources, used to identify starting location of asset (if path does not include a asset prefix). 136 * @param path 137 * path to the resource; either fully qualified (with an asset prefix such as "context:"), or relative to the 138 * component's library asset folder (the 5.4 and beyond way), or the to the component's Java class file (the 5.3 and earlier 139 * way, still supported until at least 5.5). 140 * Symbols in the path are {@linkplain org.apache.tapestry5.ioc.services.SymbolSource#expandSymbols(String) expanded}. 141 * @return the Asset 142 * @throws RuntimeException 143 * if Asset can not be found 144 * @since 5.4 145 */ 146 Asset getComponentAsset(ComponentResources resources, String path); 147}