01: /*
02: * Content.java December 2002
03: *
04: * Copyright (C) 2002, Niall Gallagher <niallg@users.sf.net>
05: *
06: * This library is free software; you can redistribute it and/or
07: * modify it under the terms of the GNU Lesser General Public
08: * License as published by the Free Software Foundation.
09: *
10: * This library is distributed in the hope that it will be useful,
11: * but WITHOUT ANY WARRANTY; without even the implied warranty of
12: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13: * GNU Lesser General Public License for more details.
14: *
15: * You should have received a copy of the GNU Lesser General
16: * Public License along with this library; if not, write to the
17: * Free Software Foundation, Inc., 59 Temple Place, Suite 330,
18: * Boston, MA 02111-1307 USA
19: */
20:
21: package simple.http.serve;
22:
23: import java.io.OutputStream;
24: import java.io.IOException;
25:
26: /**
27: * The <code>Content</code> interface is used to provide an interface
28: * to content within a <code>Context</code>. The contents represented
29: * by the <code>Content</code> implementation could be dynamic or
30: * static depending on the <code>Context</code> that served it.
31: * <p>
32: * Static content represented by resources on the underlying file
33: * system such as files are represented as <code>Content</code>
34: * objects to provide a simple means of writing that content to HTTP
35: * clients using an <code>OutputStream</code>.
36: * <p>
37: * The <code>Content</code> interface can also be used to provide a
38: * means for writing dynamic content. Dynamic content such as that
39: * produced by <code>simple.template.Document</code> objects can be
40: * implemented as a <code>Content</code>. The implementation can then
41: * be presented to the client using the <code>write</code> methods.
42: *
43: * @author Niall Gallagher
44: *
45: * @see simple.http.serve.ContentFactory
46: */
47: public interface Content {
48:
49: /**
50: * This writes the contents of the instance to the issued stream.
51: * This provides a means for the <code>Content</code> to write
52: * its contents to an <code>OutputStream</code>. Typically this
53: * is used by <code>Service</code> objects when data is to be
54: * provided to the client using the <code>Response</code>. Any
55: * problems in writing the contents results in an exception.
56: *
57: * @param out this is the stream to write the content with
58: *
59: * @exception IOException thrown if there is an I/O problem
60: */
61: public void write(OutputStream out) throws IOException;
62:
63: /**
64: * The content that is dynamically generated by the object
65: * us written as a specific MIME type, including charset
66: * information which determines the content encoding. For
67: * example if the output was HTML written using UTF-8
68: * format then this would return "text/html; charset=utf-8".
69: *
70: * @return returns the MIME type of the generated content
71: */
72: public String getContentType();
73:
74: /**
75: * This method is used to embed the generated contents into
76: * other strings and capture the value of the content as a
77: * string. In order to manipulate the contents of a file it
78: * is necessary to acquire a handle on its contents. This
79: * method allows such a handle. The contents returned by
80: * this will typically be UTF-8, however the encoding of a
81: * content object is independant as is the MIME type.
82: *
83: * @return returns the contents of the generated content
84: */
85: public String toString();
86: }
|