package com.bradmcevoy.http; import com.bradmcevoy.http.exceptions.BadRequestException; import java.io.IOException; import java.io.OutputStream; import java.util.Map; import com.bradmcevoy.http.exceptions.NotAuthorizedException; /** * webDAV GET and HEAD */ public interface GetableResource extends Resource { /** * Send the resource's content using the given output stream. Implementations * should assume that bytes are being physically transmitted and that headers * have already been committed, although this might not be the case with * all web containers. * <P/> * This method will be used to serve GET requests, and also to generate * content following POST requests (if they have not redirected) * <P/> * The Range argument is not-null for partial content requests. In this case * implementations should (but are not required) to only send the data * range requested. * <P/> * The contentType argument is that which was resolved by negotiation in * the getContentType method. HTTP allows a given resource to have multiple * representations on the same URL. For example, a data series could be retrieved * as a chart as SVG, PNG, JPEG, or as text as CSV or XML. When the user agent * requests the resource is specified what content types it can accept. These * are matched against those that can be provided by the server and a preferred * representation is selected. That contentType is set in the response header * and is provided here so that the resource implementation can render itself * appropriately. * * @param out - the output stream to send the content to * @param range - null for normal GET's, not null for partial GET's. May be ignored * @param params - request parameters * @param contentType - the contentType selected by negotiation * @throws java.io.IOException * @throws com.bradmcevoy.http.exceptions.NotAuthorizedException */ public void sendContent( OutputStream out, Range range, Map<String,String> params, String contentType ) throws IOException, NotAuthorizedException, BadRequestException; /** How many seconds to allow the content to be cached for, or null if caching is not allowed * * The provided auth object allows this method to determine an appropriate caching * time depending on authenticated context. For example, in a CMS in might * be appropriate to have a short expiry time for logged in users who might * be editing content, as opposed to non-logged in users who are just viewing the site. */ Long getMaxAgeSeconds(Auth auth); /** * Given a comma separated listed of preferred content types acceptable for a client, * return one content type which is the best. * <P/> * Returns the most preferred MIME type. E.g. text/html, image/jpeg, etc * <P/> * Must be IANA registered * <P/> * accepts is the accepts header. Eg: Accept: text/*, text/html, text/html;level=1 * <P/> * See - http://www.iana.org/assignments/media-types/ for a list of content types * See - http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html for details about the accept header * <P/> * If you can't handle accepts interpretation, just return a single content type - E.g. text/html * <P/> * But typically you should do something like this: * <PRE> * String mime = ContentTypeUtils.findContentTypes( this.file ); * return ContentTypeUtils.findAcceptableContentType( mime, preferredList ); * </PRE> * @see com.bradmcevoy.common.ContentTypeUtils * */ String getContentType(String accepts); /** The length of the content in this resource. If unknown return NULL */ Long getContentLength(); }