simple.http.serve
Interface Locator

All Known Implementing Classes:
FileLocator

public interface Locator

The Locator interface is used to locate resources outside the scope of a Context. This is required so that various configuration files and other resources can be located by the system. Resources such as XML files and Java properties files required to configure various objects can be discovered using an implementation of this interface.

This provides a set of methods similar to the methods provided by the Context object. However unlike that object resources are located with more flexibility as it does not have restricted scope. Also, this does not accept a URI target name to locate the files, instead this will typically be given the name of a resource. For example if an XML configuration file named config.xml was to be located then it could be located using an alias like config or possibly with the file name itself, without any path information.

For simplicity and portability an implementation of this should be able to cope with path information in the event that it is supplied. Paths in URI format like /bin/config.xml and also system dependant format (although not advisable) like .\bin\config.xml for a Windows system should be acceptable to an implementation.

Author:
Niall Gallagher

Method Summary
 java.io.File getFile(java.lang.String name)
          This is used to produce a File object pointing to the location of the named resource.
 java.lang.String getLocation(java.lang.String name)
          This is used to discover the location of a resource using the name of the resource.
 java.util.Properties getProperties(java.lang.String name)
          This is used to produce a Properties object that contains the contents of the named Java properties file.
 java.net.URL getResource(java.lang.String name)
          This is provided so that a ClassLoader can be used to load the named resource.
 

Method Detail

getResource

java.net.URL getResource(java.lang.String name)
                         throws LocateException
This is provided so that a ClassLoader can be used to load the named resource. This method enables the configuration information to be loaded from the specified class path, which enables the files to be stored within a JAR resource or at any desired location. This only needs the name of the resource, no path information is required, this keeps the code portable and simple.

Parameters:
name - the name of the resource that is to be located
Returns:
a URL referencing the named resource
Throws:
LocateException - thrown if the named resource could not be found after exhausting all lookup means

getLocation

java.lang.String getLocation(java.lang.String name)
                             throws LocateException
This is used to discover the location of a resource using the name of the resource. This will return the location of the resource in a system specific path format. This mirrors the Context.getRealPath method, however it should be supplied with only the name of the resource with no path information, which keeps any code interacting with this portable across systems using different path formats.

Parameters:
name - the name of the resource that is to be located
Returns:
the location of the resource in the system format
Throws:
LocateException - thrown if the named resource could not be found after exhausting all lookup means

getFile

java.io.File getFile(java.lang.String name)
                     throws LocateException
This is used to produce a File object pointing to the location of the named resource. This method mirrors the Context.getFile method, however it should be supplied with only the name of the resource with no path information, which keeps any code interacting with this portable across systems using different path formats.

Parameters:
name - the name of the resource that is to be located
Returns:
a File referencing the named resource
Throws:
LocateException - thrown if the named resource could not be found after exhausting all lookup means

getProperties

java.util.Properties getProperties(java.lang.String name)
                                   throws LocateException
This is used to produce a Properties object that contains the contents of the named Java properties file. This mirrors the Context.getProperties method, however it should be supplied with only the name of the resource with no path information, which keeps any code interacting with this portable across different platforms.

Parameters:
name - the name of the resource that is to be located
Returns:
a Properties object for the resource
Throws:
LocateException - thrown if the named resource could not be found after exhausting all lookup means