308 lines
12 KiB
Java
308 lines
12 KiB
Java
|
/*
|
||
|
|
* Copyright (c) 2008,2009 Declarative Engineering LLC.
|
||
|
|
* All rights reserved. This program and the accompanying materials
|
||
|
|
* are made available under the terms of the Declarative Engineering LLC
|
||
|
|
* verson 1 which accompanies this distribution, and is available at
|
||
|
|
* http://declarativeengineering.com/legal/DE_Developer_License_v1.txt
|
||
|
|
*/
|
||
|
|
package com.foundation.web.interfaces;
|
||
|
|
|
||
|
|
import java.io.InputStream;
|
||
|
|
import java.nio.ByteBuffer;
|
||
|
|
import java.util.Date;
|
||
|
|
|
||
|
|
public interface IRequest {
|
||
|
|
public static final int TYPE_GET = 0;
|
||
|
|
public static final int TYPE_POST = 1;
|
||
|
|
public static final int TYPE_PUT = 2;
|
||
|
|
public static final int TYPE_HEAD = 3; //HEAD is the same as GET, but the caller is requesting header only info. The response shouldn't contain a message body - so no content is sent.//
|
||
|
|
public static final int TYPE_OPTIONS = 4;
|
||
|
|
//Can find info on web dav protocol at http://en.wikipedia.org/wiki/PROPFIND.//
|
||
|
|
public static final int TYPE_WEBDAV_PROPFIND = 5;
|
||
|
|
public static final int TYPE_WEBDAV_PROPPATCH = 6;
|
||
|
|
public static final int TYPE_WEBDAV_MKCOL = 7;
|
||
|
|
public static final int TYPE_WEBDAV_COPY = 8;
|
||
|
|
public static final int TYPE_WEBDAV_MOVE = 9;
|
||
|
|
public static final int TYPE_WEBDAV_LOCK = 10;
|
||
|
|
public static final int TYPE_WEBDAV_UNLOCK = 11;
|
||
|
|
|
||
|
|
/** The content type code for application/x-www-form-urlencoded. */
|
||
|
|
public static final int CONTENT_TYPE_URL_ENCODED = 0;
|
||
|
|
/** The content type code for multipart/form-data. */
|
||
|
|
public static final int CONTENT_TYPE_MULTI_PART_FORM_DATA = 1;
|
||
|
|
/** The content type code for application/xml or text/xml. */
|
||
|
|
public static final int CONTENT_TYPE_XML = 2;
|
||
|
|
/** The content type code for customized content such as application/pdf. */
|
||
|
|
public static final int CONTENT_TYPE_CUSTOM = 3;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Defines the metadata interface for a single part of a multi part request.
|
||
|
|
*/
|
||
|
|
public interface IContentPart {
|
||
|
|
/**
|
||
|
|
* Gets the content dispositon type.
|
||
|
|
* @return The type of content disposition (expect "form-data").
|
||
|
|
*/
|
||
|
|
public String getContentDisposition();
|
||
|
|
/**
|
||
|
|
* Gets the name if provided in the content disposition attributes.
|
||
|
|
* @return The name of the part (usually the form input's name).
|
||
|
|
*/
|
||
|
|
public String getName();
|
||
|
|
/**
|
||
|
|
* Gets the set of parameter keys.
|
||
|
|
* @return The parameter keys.
|
||
|
|
*/
|
||
|
|
public String[] getParameterKeys();
|
||
|
|
/**
|
||
|
|
* Gets the value for the associated key.
|
||
|
|
* @param key The key of the parameter whose value is to be retrieved.
|
||
|
|
* @return The value, or null if the parameter was not part of the request. The result if non-null will be a String if the contentTypeCode == CONTENT_TYPE_URL_ENCODED, otherwise it will be an IContentPart instance.
|
||
|
|
*/
|
||
|
|
public String getParameter(String key);
|
||
|
|
/**
|
||
|
|
* Gets the content type.
|
||
|
|
* @return The type of the content.
|
||
|
|
*/
|
||
|
|
public String getContentType();
|
||
|
|
/**
|
||
|
|
* Gets the part's data length.
|
||
|
|
* @return The number of data bytes for this part within the request's data.
|
||
|
|
*/
|
||
|
|
public long getContentSize();
|
||
|
|
/**
|
||
|
|
* Gets the content of the message.
|
||
|
|
* @return The content stream. The formatting depends on the content type.
|
||
|
|
*/
|
||
|
|
public InputStream getContent();
|
||
|
|
}//IContentPart//
|
||
|
|
/**
|
||
|
|
* Gets the header text as received by the server.
|
||
|
|
* @return The exact text for the request header.
|
||
|
|
*/
|
||
|
|
public String getHeaderText();
|
||
|
|
/**
|
||
|
|
* Gets the web application associated with the request.
|
||
|
|
* <p>Note for web server internal use: This should not be called outside the increment and decrement counter calls on the application container.</p>
|
||
|
|
* @return The web application associated with the request.
|
||
|
|
*/
|
||
|
|
public IWebApplication getWebApplication();
|
||
|
|
/**
|
||
|
|
* Gets the first line in the header which is the request sent by the client.
|
||
|
|
* @return The request line as received by the server.
|
||
|
|
*/
|
||
|
|
public String getHeaderRequest();
|
||
|
|
/**
|
||
|
|
* Gets the ordered list of header field names.
|
||
|
|
* @return The list of field names used in the header in order received.
|
||
|
|
*/
|
||
|
|
public String[] getHeaderFieldNames();
|
||
|
|
/**
|
||
|
|
* Gets the header field value for the given name.
|
||
|
|
* @param fieldName The field name. See getHeaderFieldNames().
|
||
|
|
* @return The field value for the given field name, or null if the key is not used.
|
||
|
|
*/
|
||
|
|
public String getHeaderFieldValue(String fieldName);
|
||
|
|
/**
|
||
|
|
* Gets the IP address of the requesting machine.
|
||
|
|
* @return The requester's IP address.
|
||
|
|
*/
|
||
|
|
public String getAddress();
|
||
|
|
/**
|
||
|
|
* Gets the set of cookie keys.
|
||
|
|
* @return The cookie keys.
|
||
|
|
*/
|
||
|
|
public String[] getCookieKeys();
|
||
|
|
/**
|
||
|
|
* Gets the value for the associated key.
|
||
|
|
* @param key The key of the cookie whose value is to be retrieved.
|
||
|
|
* @return The cookie value, or null if the cookie was not part of the request.
|
||
|
|
*/
|
||
|
|
public String getCookie(String key);
|
||
|
|
/**
|
||
|
|
* Gets the set of parameter keys.
|
||
|
|
* @return The parameter keys.
|
||
|
|
*/
|
||
|
|
public String[] getParameterKeys();
|
||
|
|
/**
|
||
|
|
* Gets the value for the associated key.
|
||
|
|
* @param key The key of the parameter whose value is to be retrieved.
|
||
|
|
* @return The value, or null if the parameter was not part of the request. The result if non-null will be a String or IList if the contentTypeCode == CONTENT_TYPE_URL_ENCODED, otherwise it will be an IContentPart instance. IList instances will be used to hold multiple values with the same key.
|
||
|
|
*/
|
||
|
|
public Object getParameter(String key);
|
||
|
|
/**
|
||
|
|
* Gets the value for the associated key as a string.
|
||
|
|
* @param key The key of the parameter whose value is to be retrieved.
|
||
|
|
* @param defaultValue The value to use if the parameter doesn't exist, or if there is a conversion error.
|
||
|
|
* @return The value.
|
||
|
|
*/
|
||
|
|
public String getParameterAsString(String key, String defaultValue);
|
||
|
|
/**
|
||
|
|
* Gets the value for the associated key as a string.
|
||
|
|
* @param key The key of the parameter whose value is to be retrieved.
|
||
|
|
* @param defaultValue The value to use if the parameter doesn't exist, or if there is a conversion error.
|
||
|
|
* @param emptySameAsNull Whether an empty string is the same as null.
|
||
|
|
* @param trim Whether the value should be trimed prior to being returned or checked for being empty.
|
||
|
|
* @return The value.
|
||
|
|
*/
|
||
|
|
public String getParameterAsString(String key, String defaultValue, boolean emptySameAsNull, boolean trim);
|
||
|
|
/**
|
||
|
|
* Gets the value for the associated key as an integer.
|
||
|
|
* @param key The key of the parameter whose value is to be retrieved.
|
||
|
|
* @param defaultValue The value to use if the parameter doesn't exist, or if there is a conversion error.
|
||
|
|
* @return The value.
|
||
|
|
*/
|
||
|
|
public Integer getParameterAsInteger(String key, Integer defaultValue);
|
||
|
|
/**
|
||
|
|
* Gets the value for the associated key as a long number.
|
||
|
|
* @param key The key of the parameter whose value is to be retrieved.
|
||
|
|
* @param defaultValue The value to use if the parameter doesn't exist, or if there is a conversion error.
|
||
|
|
* @return The value.
|
||
|
|
*/
|
||
|
|
public Long getParameterAsLong(String key, Long defaultValue);
|
||
|
|
/**
|
||
|
|
* Gets the value for the associated key as a string.
|
||
|
|
* @param key The key of the parameter whose value is to be retrieved.
|
||
|
|
* @param defaultValue The value to use if the parameter doesn't exist, or if there is a conversion error.
|
||
|
|
* @return The value.
|
||
|
|
*/
|
||
|
|
public Boolean getParameterAsBoolean(String key, Boolean defaultValue);
|
||
|
|
/**
|
||
|
|
* Determines whether the parameter with the given key exists in the request.
|
||
|
|
* @param key The key for the parameter.
|
||
|
|
* @return Whether the parameter is specified in the request.
|
||
|
|
*/
|
||
|
|
public boolean hasParameter(String key);
|
||
|
|
/**
|
||
|
|
* Gets the parameter string that was part of the URI request including the question mark.
|
||
|
|
* @return The parameter string portion of the client's request. This will be null if there were no parameters or if the parameters were encoded.
|
||
|
|
*/
|
||
|
|
public String getParameterString();
|
||
|
|
/**
|
||
|
|
* Gets the client's cached response timestamp useable by the server to send a not modified message if the resource has not changed.
|
||
|
|
* @return The cached response date that the client passed indicating that a 304 Not Modified message should be sent if the resource hasn't changed since the date.
|
||
|
|
*/
|
||
|
|
public Date getCacheDate();
|
||
|
|
/**
|
||
|
|
* Gets the textual range requested.
|
||
|
|
* @return
|
||
|
|
*/
|
||
|
|
public String getRange();
|
||
|
|
/**
|
||
|
|
* Gets the lower value of the range for a download. If not set then the download should start at the beginning of the content.
|
||
|
|
* @return
|
||
|
|
*/
|
||
|
|
public Long getLowerRange();
|
||
|
|
/**
|
||
|
|
* Gets the upper value of the range for a download. If not set then the download should end at the last byte of the content.
|
||
|
|
* @return
|
||
|
|
*/
|
||
|
|
public Long getUpperRange();
|
||
|
|
/**
|
||
|
|
* Gets the date associated with the byte range. The byte range will only be valid (for resumed downloads) if the file modification date is older than the unmodified-since date.
|
||
|
|
* @return
|
||
|
|
*/
|
||
|
|
public Date getUnmodifiedSinceDate();
|
||
|
|
/**
|
||
|
|
* Gets the content buffer.
|
||
|
|
* @return The buffer used for temporary storage of the content. This will be null if a file channel is provided, or if there is no content to the request.
|
||
|
|
*/
|
||
|
|
public ByteBuffer getContent();
|
||
|
|
/**
|
||
|
|
* Gets the length of the message content.
|
||
|
|
* @return The message content byte count.
|
||
|
|
*/
|
||
|
|
public int getContentLength();
|
||
|
|
/**
|
||
|
|
* Gets the mime type for the content.
|
||
|
|
* @return The mime type name that identifies the encoding of the content, or null if there isn't any content (including any encoded in the uri).
|
||
|
|
*/
|
||
|
|
public String getContentType();
|
||
|
|
/**
|
||
|
|
* Gets the mime type code for the content.
|
||
|
|
* @return The mime type code that identifies the encoding of the content. One of the CONTENT_TYPE_xxx identifiers.
|
||
|
|
*/
|
||
|
|
public int getContentTypeCode();
|
||
|
|
/**
|
||
|
|
* Gets the character set name used to encode the parameters of the request (used with POST type requests that use the application/x-www-form-urlencoded encoding.
|
||
|
|
* @return The character set specificed, otherwise UTF-8. This value will never be null.
|
||
|
|
*/
|
||
|
|
public String getParameterCharacterSet();
|
||
|
|
/**
|
||
|
|
* Gets the input stream that can be used to access the content regardless of whether it is stored in a file or a memory buffer.
|
||
|
|
* <p>Note that a request that contains binary data may have properties for the data as well, but the properties will only house metadata. This method must be called to access the actual data.</p>
|
||
|
|
* @return The stream containing the content bytes.
|
||
|
|
* @throws java.io.IOException
|
||
|
|
*/
|
||
|
|
public InputStream getContentStream() throws java.io.IOException;
|
||
|
|
/**
|
||
|
|
* Gets the URL of the page that made the request if available.
|
||
|
|
* @return The full URL of the requesting page.
|
||
|
|
*/
|
||
|
|
public String getReferer();
|
||
|
|
/**
|
||
|
|
* Gets the URI which is the path to the requested resource.
|
||
|
|
* @return The requested resource's univeral resource identifier.
|
||
|
|
*/
|
||
|
|
public String getUri();
|
||
|
|
/**
|
||
|
|
* Whether the request was made over an SSL connection.
|
||
|
|
* @return Whether an SSL socket was used for the request.
|
||
|
|
*/
|
||
|
|
public boolean getIsSsl();
|
||
|
|
/**
|
||
|
|
* Gets the host ip or domain used to access the server.
|
||
|
|
* @return The host name used by the client.
|
||
|
|
*/
|
||
|
|
public String getHost();
|
||
|
|
/**
|
||
|
|
* Gets the version of HTTP being used by the client - most likely HTTP/1.1 or HTTP/1.0.
|
||
|
|
* @return The http version string passed by the client.
|
||
|
|
*/
|
||
|
|
public String getHttpVersion();
|
||
|
|
/**
|
||
|
|
* Gets the type code for the request.
|
||
|
|
* @return One of the TYPE_xxx identifiers.
|
||
|
|
*/
|
||
|
|
public int getRequestType();
|
||
|
|
/**
|
||
|
|
* Gets the identifier supplied by the browser that describes its self.
|
||
|
|
* @return The browser identifier string.
|
||
|
|
*/
|
||
|
|
public String getBrowser();
|
||
|
|
/**
|
||
|
|
* Gets the ISO language code for the language the client is using.
|
||
|
|
* @return The language used by the client.
|
||
|
|
*/
|
||
|
|
public String getLanguage();
|
||
|
|
/**
|
||
|
|
* Gets the message encodings used by the client.
|
||
|
|
* @return The transfer encodings used on the message (in order of application).
|
||
|
|
*/
|
||
|
|
public String getTransferEncoding();
|
||
|
|
/**
|
||
|
|
* Determines whether the CLIENT thought it was logged in at the time of the request.
|
||
|
|
* @return Whether the client thought it had logged in at the time of the request - useful in determining what to do if the session was stale.
|
||
|
|
*/
|
||
|
|
public boolean isLoggedIn();
|
||
|
|
/**
|
||
|
|
* Gets the session id that is derived from a cookie set in a previous response.
|
||
|
|
* @return The session id passed in the request.
|
||
|
|
*/
|
||
|
|
public String getSessionId();
|
||
|
|
/**
|
||
|
|
* Gets the secure session id that is derived from a cookie set in a previous response.
|
||
|
|
* @return The secure session id passed in the request.
|
||
|
|
*/
|
||
|
|
public String getSecureSessionId();
|
||
|
|
/**
|
||
|
|
* Gets the session object that the request is operating within.
|
||
|
|
* @return The session for this request. This may be null if one was not assigned.
|
||
|
|
*/
|
||
|
|
public ISession getSession();
|
||
|
|
/**
|
||
|
|
* Gets the exact bytes sent by the client that form this request.
|
||
|
|
* @return The bytes for the request as sent by the client. Will be null if the web application did not request the bytes be saved. See com.foundation.web.ISessionLifecycleAware and com.foundation.web.WebOptions.
|
||
|
|
*/
|
||
|
|
public ByteBuffer getRequestBytes();
|
||
|
|
}//IRequest//
|