001 // Copyright (c) 2001 Hursh Jain (http://www.mollypages.org)
002 // The Molly framework is freely distributable under the terms of an
003 // MIT-style license. For details, see the molly pages web site at:
004 // http://www.mollypages.org/. Use, modify, have fun !
005
006 package fc.web.page;
007
008 import java.io.*;
009 import java.util.*;
010
011 import javax.servlet.*;
012 import javax.servlet.http.*;
013
014 /**
015 A page is a cool and sane replacement for JSP's with much better syntax.
016 <p>
017 Server side pages implement this interface via the concrete
018 {@link PageImpl} class. This class has some additional utility
019 methods as well that page authors may find useful.
020
021 @author hursh jain
022 */
023 public interface Page
024 {
025 //all pages result in java files with this package name;
026 public static String PACKAGE_NAME = "molly.pages";
027
028 //not used: public static String DEFAULT_ERROR_PAGE = "/molly/error.mp";
029 public static int DEFAULT_BUFFER_SIZE = 8048;
030
031 /**
032 The default mime-type for each page. Usually, there should be no reason
033 to change this. However, if need be, this can be changed via a page
034 compiler directive or turned off entirely. If it's turned off, then the
035 mime-type should be manually specified via the {@link
036 javax.servlet.ServletResponse.setContentType} method.
037 */
038 public static String DEFAULT_MIME_TYPE = "text/html";
039
040 /**
041 The default encoding of the page, specified in the header sent back to
042 the client. This can be changed to utf-8, utf-16 or any other coding by
043 a page directive. Alternately, this can be set to an empty string and a
044 different encoding can also be specified in the <head> section of
045 the html document, for example:
046 <pre>
047 <head><meta http-equiv=content-type content='text/html; charset=UTF-8'></head>
048 </pre>
049 <font color=red>Encodings can be tricky. We are first compiling
050 a page into a java source file, then running the source file and
051 sending it's output to the browser. <b>Read the page
052 <a href="http://www.mollypages.org/page/charset.mp">encoding
053 and charsets</a> if you are using any non-us-ascii or non-
054 ISO-8859-1</b> characters in your molly source page.</font>
055 */
056 public static String DEFAULT_ENCODING = "ISO-8859-1";
057
058 public static String DEFAULT_CONTENT_TYPE =
059 DEFAULT_MIME_TYPE + ";" + DEFAULT_ENCODING;
060
061 public void render(HttpServletRequest req, HttpServletResponse res) throws Exception;
062
063 /**
064 This method is invoked whenever a page is created and before it
065 is run.
066 <p>
067 Pages should override this method to instantiate/set-up page
068 variables as needed. (pages have no-arg constructors so like
069 most of the servlet API, setup is done in a init method instead).
070 <p>
071 When overriding this class, you must remember to
072 call: <tt>super.init</tt>
073 <p>
074 The page class is reloaded if the page is modified. Variables
075 should therefore be cleaned up in the {@link destory} method
076 as needed.
077 */
078 public void init(PageServlet servlet, String contextRelativePagePath);
079
080 /**
081 This method is invoked whenever a page is destoryed/unloaded
082 */
083 public void destroy();
084
085 /**
086 Returns the path to this page from the web servers <i>document root</i>.
087 <p>So for example, if the page is at <code>foo/bar.mp</code> and is running
088 under the webapp context of <code>context1</code>, then the page path
089 will be: <code>/context1/foo/bar.mp</code>. If there is no specific
090 web app (i.e., the most common case of a default "" webapp), then the page
091 path will be <code>/foo/bar.mp</code>
092 <p>
093 This page path is essentially what needs to be typed in the browsers
094 URL window to invoke the page. It's also useful as form action parameters.
095 For example, in a molly page:
096 <blockquote>
097 <pre>
098 ..
099 <form action="[=getPagePath(req)]" method="post">
100 ..
101 </form>
102 </pre>
103 </blockquote>
104 This will submit the form to the same page where the form is defined. This
105 can be hard coded of course but by using <code>getPagePath</code>, the html
106 does not have to be changed if the name of the page changes on disk.
107 */
108 public String getPagePath(HttpServletRequest req);
109
110 /**
111 Returns the real absolute directory path for the {@link #getPagePath PagePath}.
112 <p>
113 So, for example, for a webserver document root at
114 <code>/web/sites/default/</code> and a page located in
115 <code>foo/bar.mp</code>, the real path will be:
116 <code>/web/sites/default/foo/bar.mp</code>
117 */
118 public String getRealPath(HttpServletRequest req);
119
120 /**
121 Redirects the client to the new page location. This is a thin wrapper
122 around the {@link HttpServletResponse.sendRedirect} method (possibly
123 easier to remember).
124
125 @param req the current request
126 @param res the current response
127 @param location See
128 {@link javax.servlet.http.HttpResponse#sendRedirect}.
129 Essentially, the location can be relative to the
130 specified request's URI or relative to the
131 context root if it contains a leading '/'
132 */
133 public void clientRedirect(HttpServletRequest req, HttpServletResponse res, String newLocation) throws IOException;
134
135 /**
136 Returns a thread specific CharArrayWriter that can be passed to this method
137 as various points in the page. The contents of this writer can then be
138 printed on the page when desired.
139 <p>
140 Note: The writer is <b>not</b> reset or flushed when it is retrieved. It
141 must be <font color=blue>reset manually</font> via calling the {@link
142 java.io.CharArrayWriter#reset} method. This design-decision allows request
143 threads to collect debugging data across multiple pages.
144 <p>
145 The suggested usage idiom is:
146 <blockquote>
147 <pre>
148 dbg(true);
149 CharArrayWriter cw = getThreadLocalWriter():
150 bug(cw, "some message");
151 ...
152 bug(cw, "other message");
153 ...
154 <font color=blue>
155 pw.writeTo(out);
156 pw.reset();
157 </font>
158 </pre>
159 </blockquote>
160 */
161 public CharArrayWriter getThreadLocalWriter();
162
163 /*
164 These are in PageImpl but do they need to be in the Page
165 interface as well ? Subject to change so prolly not, thus
166 commented out. hj
167
168 public void startTimer();
169 public long getTime();
170 public void dbg(boolean val);
171 public void dbgPrefix(String dbg_prefix);
172 public void dbgSuffix(String dbg_suffix);
173 public void bug(final Writer writer, final Object str1) throws IOException;
174 public void bug(final Writer writer, final Object str1, final Object str2) throws IOException;
175 public void bug(final Writer writer, final Object str1, final Object str2, final Object str3) throws IOException;
176 public void bug(final Writer writer, final Object str1, final Object str2, final Object str3, final Object... args) throws IOException;
177 */
178 }