001: /*
002: * Format.java March 2002
003: *
004: * Copyright (C) 2001, 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: /**
024: * The <code>Format</code> class is used to provide a specified format to
025: * pages retrived by the <code>ResourceEngine</code>. Every instance of
026: * the <code>ResourceEngine</code> operates using a <code>Context</code>
027: * object. The <code>Context</code> object provides a view of the
028: * underlying file system. Each <code>Context</code> contains a
029: * <code>Format</code> object. This is used to generate HTML messages
030: * for the specific resource.
031: * <p>
032: * The <code>Format</code> object is responsible for generating pages
033: * for specific resources and error messages. So when a web browser
034: * contacts the web server that is using a <code>ResourceEngine</code>
035: * the resource engine can defer to the <code>Format</code> object.
036: * <pre>
037: * format.getContents(context, "/example/");
038: * </pre>
039: * This method invocation will allow the <code>Format</code> object to
040: * create a directory listing for the target "/example/" relative
041: * to the context path which for example on DOS could be "c:\winnt".
042: *
043: * @author Niall Gallagher
044: */
045: public interface Format {
046:
047: /**
048: * This is used to produce the contents of the specified resource.
049: * If the path does not represent a resource then this may throw
050: * a <code>FormatException</code>. If however this does represent
051: * a resource the <code>Context</code> object is used to aquire the
052: * <code>File</code> object that represents the request URI path
053: * on the system. This can then be used to generate a page the
054: * provides a view of the contents of the resource.
055: * <p>
056: * The path given is the request URI path that normally comes with
057: * a HTTP/1.x request. The request URI is the string that identifies
058: * the resource on the host that is required. The context is used
059: * to convert that request URI into the system dependant name. The
060: * request URI is similar to a UNIX path like /usr/bin/README. For
061: * example if the browser requests http://some.host/pub/index.html
062: * then the request URI could be /pub/index.html it also could be
063: * the full URI as http://some.host/pub/index.html required by the
064: * specification RFC 2616.
065: *
066: * @param context provides the format with a view of the system
067: * @param path the request URI that came with the HTTP request
068: *
069: * @return this returns a byte array containing the contents of
070: * the generated page
071: *
072: * @exception FormatException if this cannot produce a page that
073: * represents the required resource
074: */
075: public byte[] getContents(Context context, String path)
076: throws FormatException;
077:
078: /**
079: * The HTTP protocol defines certain status codes that are to be sent
080: * with descriptive message bodys, this method is used to create the
081: * message body for that status code. This method will generate a
082: * message body that describes the error defined by the status code.
083: * See the HTTP/1.1 specification for a description of the status
084: * codes, RFC 2616.
085: * <p>
086: * The path given is the request URI path that normally comes with
087: * a HTTP/1.x request. The request URI is the string that identifies
088: * the resource on the host that is required. The context is used
089: * to convert that request URI into the system dependant name. The
090: * request URI is similar to a UNIX path like /usr/bin/README. For
091: * example if the browser requests http://some.host/pub/index.html
092: * then the request URI could be /pub/index.html it also could be
093: * the full URI as http://some.host/pub/index.html required by the
094: * specification RFC 2616.
095: * <p>
096: * The implementation of the <code>getMessage</code> method should
097: * recieve a report describing the error that has occured. If there
098: * was no direct cause for the error then the report should not
099: * provide a detailed <code>getCause</code> message, instead it
100: * can simply return an empty string. However, in the event that
101: * an exception caused the error the stack track could be provided.
102: *
103: * @param context provides the format with a view of the system
104: * @param path the request URI that came with the HTTP request
105: * @param report this provides information that can be used by the
106: * specific implementation to present the page
107: *
108: * @return this returns a byte array containing the contents of
109: * the generated page
110: *
111: * @exception FormatException if this cannot produce a page that
112: * represents the required message
113: */
114: public byte[] getMessage(Context context, String path, Report report)
115: throws FormatException;
116:
117: /**
118: * The contents generated by this object may not be in HTML format,
119: * this is used to retrive the content type. This is nessecary so
120: * that if the contents generated by this <code>Format</code> is
121: * not HTML that the correct MIME type is returned. This will
122: * typically return strings like "text/html; charset=UTF-8".
123: *
124: * @return this returns the MIME type of the resulting contents
125: */
126: public String getContentType();
127: }
|