1 package com.bradmcevoy.http;
2
3 import com.bradmcevoy.http.exceptions.BadRequestException;
4 import java.io.IOException;
5 import java.io.OutputStream;
6 import java.util.Map;
7
8 import com.bradmcevoy.http.exceptions.NotAuthorizedException;
9
10 /**
11 * webDAV GET and HEAD
12 */
13 public interface GetableResource extends Resource {
14 /**
15 * Send the resource's content using the given output stream. Implementations
16 * should assume that bytes are being physically transmitted and that headers
17 * have already been committed, although this might not be the case with
18 * all web containers.
19 * <P/>
20 * This method will be used to serve GET requests, and also to generate
21 * content following POST requests (if they have not redirected)
22 * <P/>
23 * The Range argument is not-null for partial content requests. In this case
24 * implementations should (but are not required) to only send the data
25 * range requested.
26 * <P/>
27 * The contentType argument is that which was resolved by negotiation in
28 * the getContentType method. HTTP allows a given resource to have multiple
29 * representations on the same URL. For example, a data series could be retrieved
30 * as a chart as SVG, PNG, JPEG, or as text as CSV or XML. When the user agent
31 * requests the resource is specified what content types it can accept. These
32 * are matched against those that can be provided by the server and a preferred
33 * representation is selected. That contentType is set in the response header
34 * and is provided here so that the resource implementation can render itself
35 * appropriately.
36 *
37 * @param out - the output stream to send the content to
38 * @param range - null for normal GET's, not null for partial GET's. May be ignored
39 * @param params - request parameters
40 * @param contentType - the contentType selected by negotiation
41 * @throws java.io.IOException - if there is an exception writing content to the output stream. This
42 * indicates that the client has disconnected (as frequently occurs with http transfers). DO NOT
43 * throw an IOException if there was an internal error generating the response (eg if reading from a database)
44 * @throws com.bradmcevoy.http.exceptions.NotAuthorizedException
45 */
46 public void sendContent( OutputStream out, Range range, Map<String,String> params, String contentType ) throws IOException, NotAuthorizedException, BadRequestException;
47
48 /** How many seconds to allow the content to be cached for, or null if caching is not allowed
49 *
50 * The provided auth object allows this method to determine an appropriate caching
51 * time depending on authenticated context. For example, in a CMS in might
52 * be appropriate to have a short expiry time for logged in users who might
53 * be editing content, as opposed to non-logged in users who are just viewing the site.
54 */
55 Long getMaxAgeSeconds(Auth auth);
56
57 /**
58 * Given a comma separated listed of preferred content types acceptable for a client,
59 * return one content type which is the best.
60 * <P/>
61 * Returns the most preferred MIME type. E.g. text/html, image/jpeg, etc
62 * <P/>
63 * Must be IANA registered
64 * <P/>
65 * accepts is the accepts header. Eg: Accept: text/*, text/html, text/html;level=1
66 * <P/>
67 * See - http://www.iana.org/assignments/media-types/ for a list of content types
68 * See - http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html for details about the accept header
69 * <P/>
70 * If you can't handle accepts interpretation, just return a single content type - E.g. text/html
71 * <P/>
72 * But typically you should do something like this:
73 * <PRE>
74 * String mime = ContentTypeUtils.findContentTypes( this.file );
75 * return ContentTypeUtils.findAcceptableContentType( mime, preferredList );
76 * </PRE>
77 * @see com.bradmcevoy.common.ContentTypeUtils
78 *
79 */
80 String getContentType(String accepts);
81
82 /** The length of the content in this resource. If unknown return NULL
83 */
84 Long getContentLength();
85
86 }