001 // Copyright 2005 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.tapestry.asset;
016
017 import org.apache.hivemind.Location;
018 import org.apache.hivemind.Resource;
019 import org.apache.tapestry.IAsset;
020 import org.apache.tapestry.spec.IComponentSpecification;
021
022 import java.util.Locale;
023
024 /**
025 * A service which creates an asset. In some cases, the asset is selected based on the Resource
026 * (typically of the component or page specification).
027 *
028 * @author Howard M. Lewis Ship
029 * @since 4.0
030 */
031 public interface AssetFactory
032 {
033
034 /**
035 * Invoked to check if the factory instance can find a matching asset using the appropriate
036 * strategy specific to its implementation.
037 *
038 * @param spec The optional component specification to check the path against.
039 * @param baseResource The resource that the path may be relative to.
040 * @param path The asset path, relative to baseResource.
041 * @param locale Optional parameter when a localized version is desired. (may be null)
042 * @return True if the requested asset can be found, false otherwise.
043 */
044 boolean assetExists(IComponentSpecification spec, Resource baseResource, String path, Locale locale);
045
046 /**
047 * Creates a new asset relative to an existing asset.
048 *
049 * @param spec The optional component specification to check the path against.
050 *
051 * @param baseResource
052 * the base resource from which an asset path may be calculated. Each type of asset
053 * is linked to a particular implemenation of {@link Resource}, and generates a
054 * corresponding implementation of {@link org.apache.tapestry.IAsset}.
055 * @param path
056 * the path relative to the resource (if no leading slash), or an absolute path
057 * within the domain of the asset type (i.e, within the classpath, or within the web
058 * application).
059 * @param locale
060 * the desired locale of the asset; the closest match will be used.
061 * @param location
062 * the location to be associated with the returned asset, or null to not attempt to
063 * localize the asset
064 *
065 * @return The created asset.
066 * @throws org.apache.hivemind.ApplicationRuntimeException
067 * if no matching asset may be found.
068 */
069 IAsset createAsset(Resource baseResource, IComponentSpecification spec, String path, Locale locale, Location location);
070
071 /**
072 * Creates a new asset relative to the root of the domain defined by the type of asset.
073 *
074 * @param path
075 * the absolute path for the resource
076 * @param locale
077 * the locale to localize the asset to, or null for no localization
078 * @param location
079 * the location used to report any errors
080 * @return an {@link IAsset}
081 */
082 IAsset createAbsoluteAsset(String path, Locale locale, Location location);
083
084 /**
085 * Creates a new asset based on a known resource.
086 *
087 * @param resource
088 * The resource the asset will represent.
089 * @param location
090 * Location of the resource. (used for error reporting mostly)
091 *
092 * @return The created asset.
093 */
094
095 IAsset createAsset(Resource resource, Location location);
096 }