simple.http.serve
Class FileContext

java.lang.Object
  extended by simple.http.serve.FileContext
All Implemented Interfaces:
Context
Direct Known Subclasses:
FactoryContext

public class FileContext
extends java.lang.Object
implements Context

The FileContext provides an implementation of the Context object that provides a direct mapping from a request URI as defined in RFC 2616 to an OS specific target. This uses a File object to define the mapping for the request URI paths. Using a File object allows the FileContext to be easily used with both DOS and UNIX systems.

This Indexer implementation uses an MIME database to obtain mappings for the getContentType method. The file used is "Content.properties", which is packaged within simple.http.serve. This determines the MIME type of the request URI by matching file extension of the resource with the MIME type as defined in the "Content.properties" file. The mappings in the "Content.properties" file can be overridden by any XML file named "Content.xml" within reach of the Locator object, this configuration file requires the mappings to be in the form of wild card patterns.


 <?xml version="1.0" encoding="UTF-8"?>
 <content>
    <resolve match="*.jpg" type="image/jpeg">
    <resolve match="/gif/*" type="image/gif">
 </content>

 
For example, taking the XML configuration file described above, this will match all files ending with the ".jpg" extenstion to the MIME type "image/jpeg". Also, all files within the "/gif/" folder will be considered GIF images with a MIME type of "image/gif". By default most of the common file extensions already have mappings, however overriding these can be useful.

Author:
Niall Gallagher
See Also:
FileIndexer

Field Summary
protected  java.io.File base
          This will be used to fetch the real OS system paths.
protected  Format format
          This is the format instance used by this instance.
protected  simple.http.serve.FileIndexer indexer
          This is used to extract any user specified MIME types.
protected  Locator locator
          This is used to locate the configuration information.
 
Constructor Summary
FileContext()
          Constructor for creating an instance that operates from the given current working path.
FileContext(java.io.File base)
          Constructor for creating an instance that operates from the given OS specific base path.
FileContext(java.io.File base, java.io.File path)
          Constructor for creating an instance that operates from the given OS specific base path.
FileContext(java.io.File base, java.io.File[] list)
          Constructor for creating an instance that operates from the given OS specific base path.
FileContext(java.io.File base, Locator locator)
          Constructor for creating an instance that operates from the given OS specific base path.
 
Method Summary
 java.lang.String getBasePath()
          This is used to retrieve the base path of the context.
 Content getContent(java.lang.String target)
          This retrieves a Content instance that wraps the specified resource.
 java.lang.String getContentType(java.lang.String target)
          This method will extract the type attribute of this URI.
 java.io.File getDirectory(java.lang.String target)
          This is used to translate the HTTP request URI into the File object that it represent the parent directory of the URI.
 java.io.File getFile(java.lang.String target)
          This is used to translate the HTTP request URI into the File object that it represents.
 Format getFormat()
          Each Context object must be coupled with an instance of the Format object.
 Index getIndex(java.lang.String target)
          This is an all in one method that allows all the information on the target URI to be gathered at once.
 java.util.Locale getLocale(java.lang.String target)
          This will parse the HTTP request URI specified and return the Locale for that resource.
 Locator getLocator()
          Each Context must supply a Locator to enable the system to locate configuration information and other resources that reside outside the context path.
 java.lang.String getName(java.lang.String target)
          This will parse and return the file name that this request URI references.
 Path getPath(java.lang.String target)
          This is used to translate the HTTP request URI into the Path object that it represents.
 java.util.Properties getProperties(java.lang.String target)
          This provides a convenient way for an XML configuration file to be loaded.
 java.lang.String getRealPath(java.lang.String target)
          This is used to translate the HTTP request URI into the OS specific path that it represents.
 java.lang.String getRequestPath(java.lang.String target)
          This is used to translate the HTTP request URI into the URI path normalized and without query or parameter parts.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

indexer

protected simple.http.serve.FileIndexer indexer
This is used to extract any user specified MIME types.


locator

protected Locator locator
This is used to locate the configuration information.


format

protected Format format
This is the format instance used by this instance.


base

protected java.io.File base
This will be used to fetch the real OS system paths.

Constructor Detail

FileContext

public FileContext()
Constructor for creating an instance that operates from the given current working path. This instance will use the current path to translate the HTTP request URIs into the OS specific path. This will load configuration files from the current working directory.


FileContext

public FileContext(java.io.File base)
Constructor for creating an instance that operates from the given OS specific base path. This instance will use the given base path to translate the HTTP request URIs into the OS specific path. This will load configuration files from the specified directory path.

Parameters:
base - this is the OS specific base path for this

FileContext

public FileContext(java.io.File base,
                   java.io.File path)
Constructor for creating an instance that operates from the given OS specific base path. This instance will use the given base path to translate the HTTP request URIs into the OS specific path. This allows configuration files to be loaded from the file directory provided.

Parameters:
base - this is the OS specific base path for this
path - this is the path used to load configuration

FileContext

public FileContext(java.io.File base,
                   java.io.File[] list)
Constructor for creating an instance that operates from the given OS specific base path. This instance will use the given base path to translate the HTTP request URIs into the OS specific path. This allows configuration files to be loaded from the file range provided.

Parameters:
base - this is the OS specific base path for this
list - this path list used to load configuration

FileContext

public FileContext(java.io.File base,
                   Locator locator)
Constructor for creating an instance that operates from the given OS specific base path. This instance will use the given base path to translate the HTTP request URIs into the OS specific path. This uses the locator object provided, which can be used to acquire configuration.

Parameters:
base - this is the OS specific base path for this
locator - this is the configuration file locator
Method Detail

getBasePath

public java.lang.String getBasePath()
This is used to retrieve the base path of the context. The base path of the context is that path that that this will retrieve system information from. This represents a base that the request URI paths are served from on the system. For instance a base of "c:\path" would translate a URI path of "/index.html" into "c:\path\index.html". Every resource request must be relative to the context path this allows the FileEngine to map the URIs onto the specific OS. The base path is the OS file system specific path. So on UNIX it could be "/home/user/" and on a DOS system it could be "c:\web\html" for example.

Specified by:
getBasePath in interface Context
Returns:
this returns the base path of the context

getRealPath

public java.lang.String getRealPath(java.lang.String target)
This is used to translate the HTTP request URI into the OS specific path that it represents. This will convert the URI to a format that the system can use and also represents the resource path on that system. So if for example the context path was "c:\path" on a DOS system and the HTTP URI given was "/index.html" this returns "c:\path\index.html". If a UNIX system was running the VM and the context base was for example "/home/" then this would return the UNIX path "/home/index.html" for the same request URI.

Specified by:
getRealPath in interface Context
Parameters:
target - this is the HTTP request URI path that is to be translated into the OS specific path
Returns:
this returns the OS specific path name for the translate request URI

getRequestPath

public java.lang.String getRequestPath(java.lang.String target)
This is used to translate the HTTP request URI into the URI path normalized and without query or parameter parts. This is used so that the resource requested by the client can be discovered. For example this will convert the HTTP request URI "http://hostname/bin;param=value/../index.html?query" into the relative URI path /index.html. This is useful if a logging mechanism requires the name of the resource that was requested, it can also be used help find the resource.

Specified by:
getRequestPath in interface Context
Parameters:
target - this is the HTTP request URI that is to be converted into a normalized relative URI path
Returns:
the HTTP request URI as a normalized relative path

getFile

public java.io.File getFile(java.lang.String target)
This is used to translate the HTTP request URI into the File object that it represents. This will convert the URI to a format that the system can use and then create the File object for that path. So if for example the context path was "c:\path" on a DOS system and the HTTP URI given was "/index.html" this returns the File "c:\path\index.html". This is basically for convenience as the same could be achieved using the getRealPath and then creating the File from that OS specific path.

Specified by:
getFile in interface Context
Parameters:
target - this is the HTTP request URI path that is used to retrieve the File object
Returns:
returns the File for the given path

getDirectory

public java.io.File getDirectory(java.lang.String target)
This is used to translate the HTTP request URI into the File object that it represent the parent directory of the URI. This will convert the URI to a format that the host system can use and then create the File object for that path. So if for example the context path was "c:\path" on a DOS system and the HTTP URI given was "/index.html" this returns the File "c:\path\". This is basically for convenience as the same could be achieved using the file retrieved from getFile and acquiring the parent.

Specified by:
getDirectory in interface Context
Parameters:
target - this is the HTTP request URI path that is used to retrieve the File object
Returns:
returns the File for the directory

getPath

public Path getPath(java.lang.String target)
This is used to translate the HTTP request URI into the Path object that it represents. This enables the HTTP request URI to be examined thoroughly an allows various other files to be examined relative to it. For example if the URI referenced a path "/usr/bin/file" and some resource in the same directory is required then the Path can be used to acquire the relative path. This is useful if links within a HTML page are to be dynamically generated. The Path.getRelative provides this functionality.

Specified by:
getPath in interface Context
Parameters:
target - this is the HTTP request URI path that is used to retrieve the Path object
Returns:
returns the Path for the given path

getLocale

public java.util.Locale getLocale(java.lang.String target)
This will parse the HTTP request URI specified and return the Locale for that resource. The Locale is extracted from the target by examining the path segment of the HTTP request URI. The path segment is the abs_path token defined in RFC 2396. It is extracted from a second extension in the file name. So for example if the HTTP request URI was "http://some.host/usr;param=value/index.en_US.html" then the file name "index.en_US.html" would have the second file extension en_US converted into a Locale. This will not interfere if the file name was "compressed.tar.gz", it will simply ignore the "tar" second file extension and return Locale.getDefault.

Specified by:
getLocale in interface Context
Parameters:
target - the request URI to be parsed for its locale
Returns:
this will return the locale for the specified URI

getContentType

public java.lang.String getContentType(java.lang.String target)
This method will extract the type attribute of this URI. The MIME type of the request URI is extracted from the name of the target. The name for the Context is the last path segment in the token defined by RFC 2396 as path_segments. So for example if the target was "some.host:8080/bin/index.html" then the name for that resource would be "index.html". Once the name has been extracted the MIME is defined by the file extension, which for the example is text/html. The MIME type mappings can be directly specified in a configuration file named either "Content.xml" or "content.xml".

Specified by:
getContentType in interface Context
Parameters:
target - the request URI to be parsed for its type
Returns:
the type of the given request URI path refers to

getName

public java.lang.String getName(java.lang.String target)
This will parse and return the file name that this request URI references. The name for the Context is the last path segment is the token defined by RFC 2396 as path_segments. So for example if the target was "some.host:8080/home/user/" then the name for that resource would be "user". If the path references the root path "/" then null should be returned.

Specified by:
getName in interface Context
Parameters:
target - the request URI to be parsed for its name
Returns:
this will return the name that this references

getIndex

public Index getIndex(java.lang.String target)
This is an all in one method that allows all the information on the target URI to be gathered at once. The motivation for this method is primarily convenience. However it is also used to increase the performance of the FileEngine when the Context implementation is synchronized. This will enable the FileEngine to gather the information on the target by acquiring the lock for the object instance only once.

Specified by:
getIndex in interface Context
Parameters:
target - this is the request URI that is to be parsed

getContent

public Content getContent(java.lang.String target)
                   throws java.io.IOException
This retrieves a Content instance that wraps the specified resource. This returns a Content instance that transfers the contents of the referenced file in one kilobyte chunks. This does not cache the file, however if the files need to be cached the FileContentFactory can be used to act as a hot spot cache for heavly accessed files.

Specified by:
getContent in interface Context
Parameters:
target - this is the request URI that identifies the file
Returns:
this returns the specified resource wrapped in the Content interface
Throws:
java.io.IOException - this is thrown if the file resource does not exist or cannot be accessed

getProperties

public java.util.Properties getProperties(java.lang.String target)
                                   throws java.io.IOException
This provides a convenient way for an XML configuration file to be loaded. This resolves the target URI to a relative file within the context to be the same as the getFile method would return. Once the file has been acquired the Java properties file is loaded, each time, there is no caching of the loaded properties. This ensures that changes to a loaded object does not affect other users of the properties file.

Specified by:
getProperties in interface Context
Parameters:
target - the request URI that refers to the properties
Returns:
returns a populated Properties object using the specified Java properties file
Throws:
java.io.IOException - this is thrown if the resource does not exist or cannot be accessed

getLocator

public Locator getLocator()
Each Context must supply a Locator to enable the system to locate configuration information and other resources that reside outside the context path. This is useful when there are Java properties and XML configuration files required by objects interacting with a Context. The Locator employs a search to locate resources, which are identified either by name or using aliases.

Specified by:
getLocator in interface Context
Returns:
this returns the locator used by this context object

getFormat

public Format getFormat()
Each Context object must be coupled with an instance of the Format object. This is required because each FileEngine needs to serve the directory listing and the error messages in a consistent format. The resources of the instances can thus be pooled by comparing the equality of the various Context objects. When there is an object that requires a FileEngine it can create an instance of the Context and using the static factory method FileEngine.getInstance with the context object there is a search for an active instance of the FileEngine. If one is found that uses a similar context object then it is returned to the caller. This enables instances and thus resources to be shared transparently.

Specified by:
getFormat in interface Context
Returns:
this returns the format used with this context object