| // Copyright 2004 The Apache Software Foundation |
| // |
| // Licensed under the Apache License, Version 2.0 (the "License"); |
| // you may not use this file except in compliance with the License. |
| // You may obtain a copy of the License at |
| // |
| // http://www.apache.org/licenses/LICENSE-2.0 |
| // |
| // Unless required by applicable law or agreed to in writing, software |
| // distributed under the License is distributed on an "AS IS" BASIS, |
| // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| // See the License for the specific language governing permissions and |
| // limitations under the License. |
| |
| package org.apache.tapestry; |
| |
| import java.net.URL; |
| import java.util.Locale; |
| |
| /** |
| * Describes the location of a resource, such as a specification |
| * or template. Resources may be located within the classpath, |
| * or within the Web context root or somewhere else entirely. |
| * |
| * <p> |
| * Resources may be either base or localized. A localized |
| * version of a base resource may be obtained |
| * via {@link #getLocalization(Locale)}. |
| * |
| * <p> |
| * Resource locations are used as Map keys, they must |
| * implement {@link java.lang.Object#hashCode()} and |
| * {@link java.lang.Object#equals(java.lang.Object)} |
| * properly. |
| * |
| * <p> |
| * Resource locations are valid even if the corresponding |
| * resource <i>doesn't exist</i>. To verify if a localization |
| * actually exists, use {@link #getResourceURL()}, which returns |
| * null if the resource doesn't exist. {@link #getLocalization(Locale)} |
| * returns only real resource locations, where the resource exists. |
| * |
| * <p> |
| * Folders must be represented with a trailing slash. |
| * |
| * @author Howard Lewis Ship |
| * @version $Id$ |
| * @since 3.0 |
| * |
| **/ |
| |
| public interface IResourceLocation |
| { |
| /** |
| * Returns a URL for the resource. |
| * |
| * @return the URL for the resource if it exists, or null if it does not |
| * |
| **/ |
| |
| public URL getResourceURL(); |
| |
| /** |
| * Returns the file name portion of the resource location. |
| * |
| **/ |
| |
| public String getName(); |
| |
| /** |
| * Returns a localized version of this resource (or this resource, if no |
| * appropriate localization is found). Should only be invoked |
| * on a base resource. |
| * |
| * @param locale to localize for, or null for no localization. |
| * @return a localized version of this resource, of null if the resource |
| * itself does not exist. |
| * |
| **/ |
| |
| public IResourceLocation getLocalization(Locale locale); |
| |
| /** |
| * Returns at a relative location to this resource. |
| * The new resource may or may not exist; this can be determined |
| * via {@link #getResourceURL()}. |
| * |
| * @param name name of new resource, possibly as a relative path, or |
| * as an absolute path (starting with a slash). |
| * |
| **/ |
| |
| public IResourceLocation getRelativeLocation(String name); |
| |
| /** |
| * Returns the path that represents the resource. This should |
| * only be used when the type of resource is known. |
| * |
| **/ |
| |
| public String getPath(); |
| |
| /** |
| * Returns the locale for which this resource has been localized |
| * or null if the resource has not been localized. This should |
| * only be used when the type of resource is known. |
| * |
| * This locale is the same or more general than the locale for which localization |
| * was requested. For example, if the requested locale was en_US, but only the file |
| * Home_en was found, this locale returned would be en. |
| **/ |
| |
| public Locale getLocale(); |
| } |