001: /* Copyright (c) 2001 - 2007 TOPP - www.openplans.org. All rights reserved.
002: * This code is licensed under the GPL 2.0 license, availible at the root
003: * application directory.
004: */
005: package org.vfny.geoserver;
006:
007: import org.vfny.geoserver.global.GeoServer;
008: import org.vfny.geoserver.global.Service;
009: import java.io.IOException;
010: import java.io.OutputStream;
011: import java.util.HashMap;
012:
013: /**
014: * The Response interface serves as a common denominator for all service
015: * operations that generates content.
016: *
017: * <p>
018: * The work flow for this kind of objects is divided in two parts: the first is
019: * executing a request and the second writing the result to an OuputStream.
020: * </p>
021: *
022: * <ol>
023: * <li>
024: * Execute: execute(Request)
025: *
026: * <ul>
027: * <li>
028: * Executing the request means taking a Request object and, based on it's set
029: * of request parameters, do any heavy processing necessary to produce the
030: * response.
031: * </li>
032: * <li>
033: * Once the execution has been made, the Response object should be ready to
034: * send the response content to an output stream with minimal risk of
035: * generating an exception.
036: * </li>
037: * <li>
038: * Anyway, it is not required, even recomended, that the execution process
039: * generates the response content itself; just that it performs any query or
040: * processing that should generate a trapable error.
041: * </li>
042: * <li>
043: * Execute may throw a ServiceException if they wish to supply a specific
044: * response in error. As an example the WFSTransaction process has a defined
045: * Transaction Document with provisions for reporting error information.
046: * </li>
047: * </ul>
048: *
049: * </li>
050: * <li>
051: * ContentType: getContentType()
052: *
053: * <ul>
054: * <li>
055: * Called to set the response type. Depending on the stratagy used by
056: * AbstractService the framework may be commited to returning this type.
057: * </li>
058: * </ul>
059: *
060: * </li>
061: * <li>
062: * Writing: writeTo(OutputStream)
063: *
064: * <ul>
065: * <li>
066: * Write the response to the provided output stream.
067: * </li>
068: * <li>
069: * Any exceptions thrown by this writeTo method may never reach the end user in
070: * useable form. You should assume you are writing directly to the client.
071: * </li>
072: * </ul>
073: *
074: * </li>
075: * </ol>
076: *
077: * <p>
078: * <b>Note:</b> abort() will be called as part of error handling giving your
079: * response subclass a chance to clean up any temporary resources it may have
080: * required in execute() for use in writeTo().
081: * </p>
082: *
083: * <p>
084: * This is specially usefull for streamed responses such as wfs GetFeature or
085: * WMS GetMap, where the execution process can be used to parse parameters,
086: * execute queries upon the corresponding data sources and leave things ready
087: * to generate a streamed response when the consumer calls writeTo.
088: * </p>
089: *
090: * <p></p>
091: *
092: * @author Gabriel Rold?n
093: * @version $Id: Response.java 6326 2007-03-15 18:36:40Z jdeolive $
094: */
095: public interface Response {
096: /**
097: * Excecutes a request. If this method finalizes without throwing an
098: * Exception, the Response instance should be ready to write the response
099: * content through the writeTo method with the minimal posible risk of
100: * failure other than not beeing able to write to the output stream due to
101: * external reassons
102: *
103: * <p>
104: * We should clarify when a ServiceException is thrown? I would assume that
105: * a "failed" request should still result in a Response that we could
106: * write out.
107: * </p>
108: *
109: * @param request a Request object that implementations should cast to it's
110: * Request specialization, wich must contain the parsed and ready
111: * to use parameters sent by the calling client. In general, such a
112: * Request will be created by either a KVP or XML request reader;
113: * resulting in a Request object more usefull than a set of raw
114: * parameters, as can be the list of feature types requested as a
115: * set of FeatureTypeInfo objects rather than just a list of String
116: * type names
117: *
118: * @throws ServiceException
119: */
120: public void execute(Request request) throws ServiceException;
121:
122: /**
123: * MIME type of this Response - example <code>"text/xml"</code>.
124: *
125: * <p>
126: * thinked to be called after excecute(), this method must return the MIME
127: * type of the response content that will be writen when writeTo were
128: * called
129: * </p>
130: *
131: * <p>
132: * an implementation of this interface is required to throw an
133: * IllegalStateException if execute has not been called yet, to indicate
134: * that an inconsistence in the work flow that may result in an
135: * inconsistence between the response content and the content type
136: * declared for it, if such an implementation can return different
137: * contents based on the request that has originated it. i.e. a WMS GetMap
138: * response will return different content encodings based on the FORMAT
139: * requested, so it would be impossible to it knowing the exact MIME
140: * response type if it has not processed the request yet.
141: * </p>
142: *
143: * <p>
144: * There is some MIME stuff in JDK for reference:
145: *
146: * <ul>
147: * <li>
148: * java.awt.datatransfer package
149: * </li>
150: * <li>
151: * javax.mail.internet
152: * </li>
153: * <li>
154: * and a few other places as well.
155: * </li>
156: * </ul>
157: * </p>
158: *
159: * @return the MIME type of the generated or ready to generate response
160: * content
161: *
162: * @throws IllegalStateException if this method is called and execute has
163: * not been called yet
164: */
165: public String getContentType(GeoServer gs)
166: throws IllegalStateException;
167:
168: /**
169: * Returns any special content encoding this response will encode its
170: * contents to, such as "gzip" or "deflate"
171: *
172: * @return the content encoding writeTo will encode with, or null if none
173: */
174: public String getContentEncoding();
175:
176: /**
177: * Returns any special content disposition this response will encode its
178: * contents to, such as "filename" and "attachement"
179: *
180: * @return the content disposition writeTo will encode with, or null if none
181: *
182: * @uml.property name="contentDisposition" multiplicity="(0 1)"
183: */
184: public String getContentDisposition();
185:
186: /**
187: * Returns any extra headers that this Response might wish to have set in the
188: * HTTP response object.
189: *
190: * In particular, a WMS might wish to have some external caching information added
191: * to the HTTP response, so that caches can hang onto this map for a while and ligten
192: * the load on geoserver.
193: * @return
194: */
195: public HashMap getResponseHeaders();
196:
197: /**
198: * Writes this respone to the provided output stream.
199: *
200: * <p>
201: * To implememt streaming, execution is sometimes delayed until the write
202: * opperation (for example of this see FeatureResponse). Hopefully this is
203: * okay? GR:the idea for minimize risk error at writing time, is that
204: * execute performs any needed query/processing, leaving to this method
205: * just the risk of encountering an uncaught or IO exception. i.e.
206: * FeatureResponse should execute the queries inside the execute method,
207: * and have a set of FeatureReader's (or results) ready to be streamed
208: * here. This approach fits well with the Chirs' idea of configuring
209: * geoserver for speed or full conformance, wich ends in just writing
210: * directly to the http response output stream or to a
211: * ByteArrayOutputStream
212: * </p>
213: * JG: Consider using a Writer here? GR: I don't think so, because not all
214: * responses will be char sequences, such as an image in a WMS GetImage
215: * response.
216: *
217: * @param out
218: *
219: * @throws ServiceException wrapping of any unchecked exception or other
220: * predictable exception except an IO error while writing to
221: * <code>out</code>
222: * @throws IOException ONLY if an error occurs trying to write content to
223: * the passed OutputStream. By this way, we'll can control the
224: * very common situation of a java.net.SocketException product of
225: * the client closing the connection (like a user pressing it's
226: * refresh browser button many times)
227: */
228: public void writeTo(OutputStream out) throws ServiceException,
229: IOException;
230:
231: /**
232: * Called when things go horriably wrong.
233: *
234: * <p>
235: * Used try and restore application state when things go wrong. This is
236: * called by AbstractAction to try and recover when sending out a
237: * ServiceException.
238: * </p>
239: *
240: * <p>
241: * Allows a Response a chance to clean up after its self when
242: * AbstractionAction is error handling.
243: * </p>
244: */
245: public void abort(Service gs);
246: }
|