001: /*
002: * Locator.java February 2004
003: *
004: * Copyright (C) 2004, Niall Gallagher <niallg@users.sf.net>
005: *
006: * This library is free software; you can redistribute it and/or
007: * modify it under the terms of the GNU Lesser General Public
008: * License as published by the Free Software Foundation.
009: *
010: * This library is distributed in the hope that it will be useful,
011: * but WITHOUT ANY WARRANTY; without even the implied warranty of
012: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
013: * GNU Lesser General Public License for more details.
014: *
015: * You should have received a copy of the GNU Lesser General
016: * Public License along with this library; if not, write to the
017: * Free Software Foundation, Inc., 59 Temple Place, Suite 330,
018: * Boston, MA 02111-1307 USA
019: */
020:
021: package simple.http.serve;
022:
023: import java.util.Properties;
024: import java.io.File;
025: import java.net.URL;
026:
027: /**
028: * The <code>Locator</code> interface is used to locate resources
029: * outside the scope of a <code>Context</code>. This is required
030: * so that various configuration files and other resources can be
031: * located by the system. Resources such as XML files and Java
032: * properties files required to configure various objects can be
033: * discovered using an implementation of this interface.
034: * <p>
035: * This provides a set of methods similar to the methods provided
036: * by the <code>Context</code> object. However unlike that object
037: * resources are located with more flexibility as it does not have
038: * restricted scope. Also, this does not accept a URI target name
039: * to locate the files, instead this will typically be given the
040: * name of a resource. For example if an XML configuration file
041: * named <code>config.xml</code> was to be located then it could
042: * be located using an alias like <code>config</code> or possibly
043: * with the file name itself, without any path information.
044: * <p>
045: * For simplicity and portability an implementation of this should
046: * be able to cope with path information in the event that it is
047: * supplied. Paths in URI format like <code>/bin/config.xml</code>
048: * and also system dependant format (although not advisable) like
049: * <code>.\bin\config.xml</code> for a Windows system should be
050: * acceptable to an implementation.
051: *
052: * @author Niall Gallagher
053: */
054: public interface Locator {
055:
056: /**
057: * This is provided so that a <code>ClassLoader</code> can be
058: * used to load the named resource. This method enables the
059: * configuration information to be loaded from the specified
060: * class path, which enables the files to be stored within a
061: * JAR resource or at any desired location. This only needs
062: * the name of the resource, no path information is required,
063: * this keeps the code portable and simple.
064: *
065: * @param name the name of the resource that is to be located
066: *
067: * @return a <code>URL</code> referencing the named resource
068: *
069: * @exception LocateException thrown if the named resource
070: * could not be found after exhausting all lookup means
071: */
072: public URL getResource(String name) throws LocateException;
073:
074: /**
075: * This is used to discover the location of a resource using
076: * the name of the resource. This will return the location of
077: * the resource in a system specific path format. This mirrors
078: * the <code>Context.getRealPath</code> method, however it
079: * should be supplied with only the name of the resource with
080: * no path information, which keeps any code interacting with
081: * this portable across systems using different path formats.
082: *
083: * @param name the name of the resource that is to be located
084: *
085: * @return the location of the resource in the system format
086: *
087: * @exception LocateException thrown if the named resource
088: * could not be found after exhausting all lookup means
089: */
090: public String getLocation(String name) throws LocateException;
091:
092: /**
093: * This is used to produce a <code>File</code> object pointing
094: * to the location of the named resource. This method mirrors
095: * the <code>Context.getFile</code> method, however it should
096: * be supplied with only the name of the resource with no path
097: * information, which keeps any code interacting with this
098: * portable across systems using different path formats.
099: *
100: * @param name the name of the resource that is to be located
101: *
102: * @return a <code>File</code> referencing the named resource
103: *
104: * @exception LocateException thrown if the named resource
105: * could not be found after exhausting all lookup means
106: */
107: public File getFile(String name) throws LocateException;
108:
109: /**
110: * This is used to produce a <code>Properties</code> object
111: * that contains the contents of the named Java properties file.
112: * This mirrors the <code>Context.getProperties</code> method,
113: * however it should be supplied with only the name of the
114: * resource with no path information, which keeps any code
115: * interacting with this portable across different platforms.
116: *
117: * @param name the name of the resource that is to be located
118: *
119: * @return a <code>Properties</code> object for the resource
120: *
121: * @exception LocateException thrown if the named resource
122: * could not be found after exhausting all lookup means
123: */
124: public Properties getProperties(String name) throws LocateException;
125: }
|