simple.http.serve
Interface Format


public interface Format

The Format class is used to provide a specified format to pages retrived by the ResourceEngine. Every instance of the ResourceEngine operates using a Context object. The Context object provides a view of the underlying file system. Each Context contains a Format object. This is used to generate HTML messages for the specific resource.

The Format object is responsible for generating pages for specific resources and error messages. So when a web browser contacts the web server that is using a ResourceEngine the resource engine can defer to the Format object.

    format.getContents(context, "/example/");
 
This method invocation will allow the Format object to create a directory listing for the target "/example/" relative to the context path which for example on DOS could be "c:\winnt".

Author:
Niall Gallagher

Method Summary
 byte[] getContents(Context context, java.lang.String path)
          This is used to produce the contents of the specified resource.
 java.lang.String getContentType()
          The contents generated by this object may not be in HTML format, this is used to retrive the content type.
 byte[] getMessage(Context context, java.lang.String path, Report report)
          The HTTP protocol defines certain status codes that are to be sent with descriptive message bodys, this method is used to create the message body for that status code.
 

Method Detail

getContents

byte[] getContents(Context context,
                   java.lang.String path)
                   throws FormatException
This is used to produce the contents of the specified resource. If the path does not represent a resource then this may throw a FormatException. If however this does represent a resource the Context object is used to aquire the File object that represents the request URI path on the system. This can then be used to generate a page the provides a view of the contents of the resource.

The path given is the request URI path that normally comes with a HTTP/1.x request. The request URI is the string that identifies the resource on the host that is required. The context is used to convert that request URI into the system dependant name. The request URI is similar to a UNIX path like /usr/bin/README. For example if the browser requests http://some.host/pub/index.html then the request URI could be /pub/index.html it also could be the full URI as http://some.host/pub/index.html required by the specification RFC 2616.

Parameters:
context - provides the format with a view of the system
path - the request URI that came with the HTTP request
Returns:
this returns a byte array containing the contents of the generated page
Throws:
FormatException - if this cannot produce a page that represents the required resource

getMessage

byte[] getMessage(Context context,
                  java.lang.String path,
                  Report report)
                  throws FormatException
The HTTP protocol defines certain status codes that are to be sent with descriptive message bodys, this method is used to create the message body for that status code. This method will generate a message body that describes the error defined by the status code. See the HTTP/1.1 specification for a description of the status codes, RFC 2616.

The path given is the request URI path that normally comes with a HTTP/1.x request. The request URI is the string that identifies the resource on the host that is required. The context is used to convert that request URI into the system dependant name. The request URI is similar to a UNIX path like /usr/bin/README. For example if the browser requests http://some.host/pub/index.html then the request URI could be /pub/index.html it also could be the full URI as http://some.host/pub/index.html required by the specification RFC 2616.

The implementation of the getMessage method should recieve a report describing the error that has occured. If there was no direct cause for the error then the report should not provide a detailed getCause message, instead it can simply return an empty string. However, in the event that an exception caused the error the stack track could be provided.

Parameters:
context - provides the format with a view of the system
path - the request URI that came with the HTTP request
report - this provides information that can be used by the specific implementation to present the page
Returns:
this returns a byte array containing the contents of the generated page
Throws:
FormatException - if this cannot produce a page that represents the required message

getContentType

java.lang.String getContentType()
The contents generated by this object may not be in HTML format, this is used to retrive the content type. This is nessecary so that if the contents generated by this Format is not HTML that the correct MIME type is returned. This will typically return strings like "text/html; charset=UTF-8".

Returns:
this returns the MIME type of the resulting contents