001: // Copyright 2004, 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.hivemind;
016:
017: import java.net.URL;
018: import java.util.Locale;
019:
020: /**
021: * Describes the location of a resource, such as a module deployment
022: * descriptor, or a messages file.
023: *
024: * <p>
025: * Resources may be either base or localized. A localized
026: * version of a base resource may be obtained
027: * via {@link #getLocalization(Locale)}.
028: *
029: * <p>
030: * Resource locations are used as Map keys, they must
031: * implement {@link java.lang.Object#hashCode()} and
032: * {@link java.lang.Object#equals(java.lang.Object)}
033: * properly.
034: *
035: * <p>
036: * Resource locations are valid even if the corresponding
037: * resource <i>doesn't exist</i>. To verify if a localization
038: * actually exists, use {@link #getResourceURL()}, which returns
039: * null if the resource doesn't exist. {@link #getLocalization(Locale)}
040: * returns only real resource locations, where the resource exists.
041: *
042: * <p>
043: * Folders must be represented with a trailing slash.
044: *
045: * @author Howard Lewis Ship
046: *
047: **/
048:
049: public interface Resource {
050: /**
051: * Returns a URL for the resource.
052: *
053: * @return the URL for the resource if it exists, or null if it does not
054: *
055: */
056:
057: public URL getResourceURL();
058:
059: /**
060: * Returns the file name portion of the resource location.
061: *
062: */
063:
064: public String getName();
065:
066: /**
067: * Returns a localized version of this resource (or this resource, if no
068: * appropriate localization is found). Should only be invoked
069: * on a base resource.
070: *
071: * @param locale to localize for, or null for no localization.
072: * @return a localized version of this resource, of null if the resource
073: * itself does not exist.
074: *
075: */
076:
077: public Resource getLocalization(Locale locale);
078:
079: /**
080: * Returns at a relative location to this resource.
081: * The new resource may or may not exist; this can be determined
082: * via {@link #getResourceURL()}.
083: *
084: * @param name name of new resource, possibly as a relative path, or
085: * as an absolute path (starting with a slash).
086: *
087: */
088:
089: public Resource getRelativeResource(String name);
090:
091: /**
092: * Returns the path that represents the resource. This should
093: * only be used when the type of resource is known.
094: *
095: */
096:
097: public String getPath();
098:
099: /**
100: * Returns the locale for which this resource has been localized
101: * or null if the resource has not been localized. This should
102: * only be used when the type of resource is known.
103: *
104: * This locale is the same or more general than the locale for which localization
105: * was requested. For example, if the requested locale was en_US, but only the file
106: * Home_en was found, this locale returned would be en.
107: */
108:
109: public Locale getLocale();
110: }
|