Module org.bzdev.ejws

Package org.bzdev.ejws

Class WebMap.Info

java.lang.Object

org.bzdev.ejws.WebMap.Info

All Implemented Interfaces:

HttpServerResponse

Enclosing class:

WebMap

public static class WebMap.Info
extends Object
implements HttpServerResponse

Info for accessing a resource. an Instance of this class is returned by the WebMap methods getWebxml, getWelcomeInfo, getInfoFromPath, getErrorInfo, and getInfo. This class can be used in two modes:

• In the first mode, for successful requests, the Info object will provide an InputStream that will allow an object to be read. If the response is an HTTP redirect, the input stream should be null and the length should be -1, and the location should not be null. The method setRedirect(boolean) must be called with an argument equal to true if the response is an HTTP redirect. If a content-encoding (e.g., gzip) is used, the method setEncoding(String) must be called. The input stream must then provide encoded data. All the other values can be set using the constructor Info(InputStream,long,String,String).
• In the second mode, one will create an instance of WebMap.Info by calling the constructor Info(RequestInfo), and then using several methods to create a response:
  • setHeader(String,String) or addHeader(String,String) as many times as needed to create most response headers.
  • sendResponseHeaders(int,long) to create the content-length header and to set the response code (this should be done after the other headers were created).
  • getOutputStream() to get the output stream used to write the response. The length of the response must match the one provided in the (previous) call to sendResponseHeaders(int,long), and the stream should be closed when the response has been written.

Generally, one mode or the other will be more convenient for programming. The first mode is preferred in a simple GET request where the response data is going to be read from an input stream. Additional WebMap.Info methods are used by FileHandler and typically not by subclasses of WebMap. When compatibility with servlets is desired, the second mode should be used, and the methods used should be those that are specified by the interface HttpServerResponse.

Constructor Summary

Constructors

Constructor	Description
Info(InputStream is, long length, String mimeType, String location)	Constructor.
Info(WebMap.RequestInfo rinfo)	Constructor given a WebMap.RequestInfo instance.

Method Summary

Modifier and Type	Method	Description
void	addCookie(ServerCookie cookie)	Add a cookie to the response headers.
void	addHeader(String key, String value)	Add a response header.
boolean	containsHeader(String name)	Determine if a response header with the specified name exists.
String	encodeRedirectURL(String url)	Encode a URL for use in HttpServerResponse.sendRedirect(String).
String	encodeURL(String url)	Encode a URL so that it includes a session ID if necessary.
boolean	getEncoded()	Indicate if a response uses compression.
String	getEncoding()	Get the current encoding.
Collection<String>	getHeaderNames()	Get the names of the current response header names.
Collection<String>	getHeaders(String name)	Get the headers with a given name.
InputStream	getInputStream()	Get an input stream to read a resource
long	getLength()	Get the length of a resource.
String	getLocation()	Get a location for an HTTP redirect.
String	getMIMEType()	Get the MIME type associated with a resource.
OutputStream	getOutputStream()	Get the output stream for responses.
boolean	getRedirect()	Indicate if a response is an HTTP redirect.
boolean	handledResponse()	Check if the response was generated and sent.
boolean	isCommitted()	Determine if this response has been committed.
void	sendError(int rc)	Sends a response with a given HTML response code for an error with no content.
void	sendRedirect(String location)	Sends an HTTP redirect response with a given location.
void	sendResponseHeaders(int code, long length)	Set the response code and content length.
void	setEncoding(String encoding)	Set whether or not a response uses compression or some other transfer encoding.
void	setHeader(String key, String value)	Set the value of a response header that has a single value.
void	setRedirect(boolean value)	Specify if the response is an HTTP redirect.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface org.bzdev.net.HttpServerResponse

addDateHeader, addIntHeader, setDateHeader, setIntHeader

Constructor Details

Info

public Info(InputStream is,
 long length,
 String mimeType,
 String location)

Constructor. For an HTTP redirect, the location must not be null, the length should be -1, the input stream should be null, and setRedirect(boolean) must be called.

Parameters:

is - an input stream provided an HTML resource

length - the number of bytes in the resource; 0 if unknown and -1 if no response data will be sent

mimeType - the media type of the resource

location - the location for an HTTP redirect; null if there is none

Info

public Info(WebMap.RequestInfo rinfo)

Constructor given a WebMap.RequestInfo instance.

Parameters:

rinfo - a WebMap.RequestInfo used to complete an HTTP transaction

Method Details

setRedirect

public void setRedirect(boolean value)

Specify if the response is an HTTP redirect. The default value is false. The value set is ignored if the constructor Info(org.bzdev.ejws.WebMap.RequestInfo) was used so that sendResponseHeaders(int,long) sets the response status code.

Parameters:

value - true if the response is an HTTP redirect; false otherwise

getRedirect

public boolean getRedirect()

Indicate if a response is an HTTP redirect. The value returned is ignored if the constructor Info(org.bzdev.ejws.WebMap.RequestInfo) was used so that sendResponseHeaders(int,long) sets the response status code.

Returns:

true if the response is a redirect; false otherwise.

setEncoding

public void setEncoding(String encoding)

Set whether or not a response uses compression or some other transfer encoding.

Specified by:

setEncoding in interface HttpServerResponse

Parameters:

encoding - the encoding ("identity", "gzip", "compress", and "deflate" are standard values); null defaults to "identity"

getEncoded

public boolean getEncoded()

Indicate if a response uses compression.

Returns:

true if the response uses gzip compression; false otherwise

getEncoding

public String getEncoding()

Get the current encoding.

Returns:

the current encoding; null if there is none defined.

setHeader

public void setHeader(String key,
 String value)
               throws IllegalStateException

Set the value of a response header that has a single value.

Specified by:

setHeader in interface HttpServerResponse

Parameters:

key - the key for the header

value - the value for the header

Throws:

IllegalStateException - this object's constructor's argument was not an instance of WebMap.RequestInfo

addHeader

public void addHeader(String key,
 String value)
               throws IllegalStateException

Add a response header. A new header will be added in addition to any headers with the same name.

Specified by:

addHeader in interface HttpServerResponse

Parameters:

key - the key for the header

value - a value to add to the header

Throws:

IllegalStateException - this object's constructor's argument was not an instance of WebMap.RequestInfo

encodeURL

public String encodeURL(String url)

Description copied from interface: HttpServerResponse

Encode a URL so that it includes a session ID if necessary. This method is needed by the Servlet specification where encoding may be necessary to include a session ID.

Specified by:

encodeURL in interface HttpServerResponse

Parameters:

url - the URL

Returns:

the encoded URL

encodeRedirectURL

public String encodeRedirectURL(String url)

Description copied from interface: HttpServerResponse

Encode a URL for use in HttpServerResponse.sendRedirect(String). This method is needed by the Servlet specification where encoding may be necessary to include a session ID.

Specified by:

encodeRedirectURL in interface HttpServerResponse

Parameters:

url - the URL

Returns:

the encoded URL

getHeaders

public Collection<String> getHeaders(String name)
                              throws IllegalStateException

Description copied from interface: HttpServerResponse

Get the headers with a given name.

Specified by:

getHeaders in interface HttpServerResponse

Parameters:

name - the name

Returns:

a collection of the header values for a given name

Throws:

IllegalStateException - an implementation-dependent error occurred (for WebMap.Info the constructor was not given an instance of WebMap.RequestInfo)

getHeaderNames

public Collection<String> getHeaderNames()
                                  throws IllegalStateException

Description copied from interface: HttpServerResponse

Get the names of the current response header names.

Specified by:

getHeaderNames in interface HttpServerResponse

Returns:

a collection of the response header names

Throws:

IllegalStateException - an implementation-dependent error occurred (for WebMap.Info the constructor was not given an instance of WebMap.RequestInfo)

containsHeader

public boolean containsHeader(String name)
                       throws IllegalStateException

Description copied from interface: HttpServerResponse

Determine if a response header with the specified name exists.

Specified by:

containsHeader in interface HttpServerResponse

Parameters:

name - the header name

Returns:

true if the header exists; false otherwise

Throws:

IllegalStateException - an implementation-dependent error occurred (for WebMap.Info the constructor was not given an instance of WebMap.RequestInfo)

addCookie

public void addCookie(ServerCookie cookie)
               throws IllegalStateException

Description copied from interface: HttpServerResponse

Add a cookie to the response headers.

Specified by:

addCookie in interface HttpServerResponse

Parameters:

cookie - the cookie

Throws:

IllegalStateException - an implementation-dependent error occurred (for WebMap.Info the constructor was not given an instance of WebMap.RequestInfo)

sendRedirect

public void sendRedirect(String location)
                  throws IllegalStateException

Description copied from interface: HttpServerResponse

Sends an HTTP redirect response with a given location.

Specified by:

sendRedirect in interface HttpServerResponse

Parameters:

location - a URL providing the location

Throws:

IllegalStateException - an implementation-dependent error occurred (for WebMap.Info the constructor was not given an instance of WebMap.RequestInfo)

sendError

public void sendError(int rc)
               throws IllegalStateException

Description copied from interface: HttpServerResponse

Sends a response with a given HTML response code for an error with no content. If this method is called, HttpServerResponse.sendResponseHeaders(int,long) should not be called.

Specified by:

sendError in interface HttpServerResponse

Parameters:

rc - the response code

Throws:

IllegalStateException - an implementation-dependent error occurred (for WebMap.Info the constructor was not given an instance of WebMap.RequestInfo)

sendResponseHeaders

public void sendResponseHeaders(int code,
 long length)
                         throws IllegalStateException

Set the response code and content length. If the length is 0, indicating that the length is not known, chunked transfer encoding is automatically used. As a result, one should generally avoid the explicit use of the transfer-encoding header.

Specified by:

sendResponseHeaders in interface HttpServerResponse

Parameters:

code - the response code

length - the length of the response; 0 if the length is not known, and -1 if there is no response.

Throws:

IllegalStateException - this object's constructor's argument was not an instance of WebMap.RequestInfo

isCommitted

public boolean isCommitted()

Description copied from interface: HttpServerResponse

Determine if this response has been committed. A response is committed if its status code and headers have been written.

Specified by:

isCommitted in interface HttpServerResponse

Returns:

true if this response has been committed; false otherwise

getOutputStream

public OutputStream getOutputStream()
                             throws IllegalStateException,
IOException

Get the output stream for responses.

If the request method was HEAD, everything written to this stream will be discarded.

Specified by:

getOutputStream in interface HttpServerResponse

Returns:

the output stream.

Throws:

IllegalStateException - this object's constructor's argument was not an instance of WebMap.RequestInfo

IOException - an IO error occurred

handledResponse

public boolean handledResponse()

Check if the response was generated and sent.

Returns:

true if the response was sent; false otherwise

getLength

public long getLength()

Get the length of a resource.

Returns:

the resource length; 0 if unknown and -1 if no response is sent.

getInputStream

public InputStream getInputStream()

Get an input stream to read a resource

Returns:

an input stream; null if not found or if an HTTP redirect should be used instead or if handledResponse() would return true

getMIMEType

public String getMIMEType()

Get the MIME type associated with a resource.

Returns:

the MIME type; null if unknown

getLocation

public String getLocation()

Get a location for an HTTP redirect.

Returns:

the location; null if there is none