com.webobjects.appserver
Class WOMessage

java.lang.Object
  com.webobjects.appserver.WOMessage

All Implemented Interfaces:

NSKeyValueCoding, NSKeyValueCoding.ErrorHandling, NSKeyValueCodingAdditions

Direct Known Subclasses:

WORequest, WOResponse

public class WOMessage
extends Object
implements NSKeyValueCoding, NSKeyValueCoding.ErrorHandling, NSKeyValueCodingAdditions

WOMessage is the parent class for both WORequest and WOResponse,and implements much of the behavior that is generic to both. WOMessage represents a message with an HTTP header and either HTML or XML content. HTML content is typically used when interacting with a Web browser, while XML content can be used in messages that originate from or are destined for another application -- either an application that "speaks" XML or another WebObjects application.

The methods of the WOMessage class can be divided primarily into two groups, those that deal with a message's content and those that read and set header information. Most of the remaining WOMessage methods control how the content is encoded and allow you to attach arbitrary "user info" to the WOMessage objects in order to pass information about a given message to other objects within the application.

Note: Headers are case-insensitive. WebObjects enforces the HTTP specification, but you should avoid mixing the case of header keys.

Because WOMessage objects usually correspond to HTTP requests and responses and fulfil the same function as these, the data they represent is mostly the same as that contained in an equivalent HTTP message. Thus an understanding of HTTP requests and responses is important for a good understanding of WOMessage and its subclasses. Version 1.1 of the HTTP protocol and its request format can be found in RFC 2616. Documentation for WOMessage and its subclasses assumes you have a good understanding of the information contained in this RFC and the Netscape cookie specification.

Cookie headers are parsed and returned as instances of WOCookie. If malformed cookies are received, and the property WOAcceptMalformedCookies is false, an exception will be thrown during parsing. If WOAcceptMalformedCookies is true, any cookies successfully parsed will be returned, and the remainder will be discarded. To change this behavior, override the method handleMalformedCookieString on WOApplication.

Note: Only Cookie headers are parsed; if you are receiving requests containing Set-cookie headers, you will have to implement your own parsing code. The WOMessage class also contains three methods that allow construction and interpretation of messages whose content is formatted as XML. appendContentDOMDocumentFragment allows you to build up an XML message piece by piece. setContentDOMDocument, on the other hand, allows you to specify the message's content all at once. To obtain the content of a message that is formatted as XML, use contentAsDOMDocument.

The arguments to these methods are XML documents or document fragments as defined by the Document Object Model (DOM). Installed as a part of WebObjects is the com. ibm.xml.dom package (IBM's alphaWorks), which contains various XML parsers for Java written by IBM. The included DOM parser is used to generate document and document fragment objects from XML data, or to manipulate and/or generate XML data from a document object). For more information on the Document Object Model, there is online documentation at http://www.w3.org/DOM/

See Also:

WOMessage.contentEncoding(), WOMessage.setContentEncoding(String anEncoding), WOMessage.appendContentDOMDocumentFragment(org.w3c.dom.DocumentFragment aDocumentFragment), WOMessage.setContentDOMDocument(org.w3c.dom.Document aDocument), WOMessage.contentAsDOMDocument(), WORequest, WOResponse

Nested Class Summary

Nested classes/interfaces inherited from interface com.webobjects.foundation.NSKeyValueCodingAdditions

NSKeyValueCodingAdditions.DefaultImplementation, NSKeyValueCodingAdditions.Utility

Field Summary

static int	HTTP_STATUS_FORBIDDEN Integer value corresponding to the HTTP 1.1 status code for "Forbidden".
static int	HTTP_STATUS_FOUND Integer value corresponding to the HTTP 1.1 status code for "Found".
static int	HTTP_STATUS_INTERNAL_ERROR Integer value corresponding to the HTTP 1.1 status code for "Internal Server Error".
static int	HTTP_STATUS_MOVED_PERMANENTLY Integer value corresponding to the HTTP 1.1 status code for "Moved permanently".
static int	HTTP_STATUS_NO_CONTENT Integer value corresponding to the HTTP 1.1 status code for "No content".
static int	HTTP_STATUS_NOT_FOUND Integer value corresponding to the HTTP 1.1 status code for "Not found".
static int	HTTP_STATUS_OK Integer value corresponding to the HTTP 1.1 status code for "OK".
protected static boolean[]	map
protected static String	TheDefaultResponseEncoding This protected class variable contains a String identifying the default encoding to use when constructing responses, which is defined in WOMessage to be UTF8 (UTF-8).

Fields inherited from interface com.webobjects.foundation.NSKeyValueCodingAdditions

KeyPathSeparator

Constructor Summary

WOMessage()
Construct and initialize a WOMessage with HTTP version 1.0 and string encoding ISO8859_1 (ISO Latin 1).

Method Summary

void	addCookie(WOCookie aCookie) A convenience method that adds the specified WOCookie object to the WOMessage.
void	appendContentCharacter(char aCharacter) Appends the single ASCII character aCharacter to the message's content.
void	appendContentData(NSData someData) Appends the content of NSData someData to the message's content.
void	appendContentDOMDocumentFragment(DocumentFragment aDocumentFragment) Converts the supplied DOM document fragment to an XML string and appends it to the message's contents.
void	appendContentHTMLAttributeValue(String aString) Appends the HTML attribute value passed in as aString to the HTTP content.
void	appendContentHTMLString(String aString) Appends aString to the receiver's content.
void	appendContentString(String aString) Appends aString to the receiver's content.
void	appendHeader(String header, String key) Appends header to the list of header field-values in the receiver for the field-name key.
void	appendHeaders(List headers, String key) Appends headers to the list of header field-values in the receiver for the field-name key.
static boolean	canAccessFieldsDirectly() WOMessage's implementation of this static method returns true, indicating that key-value coding is allowed to access fields in this object if an appropriate method isn't present.
Object	clone()
NSData	content() Returns the HTML content of the receiver as an NSData object.If the content was set as a String, the NSData returned will contain the bytes of the String encoded using contentEncoding.
Document	contentAsDOMDocument() Returns the content of the receiver as a DOM document object.
String	contentEncoding() Returns a String representing the encoding used for the message content.
String	contentString() Returns the HTML content of the receiver as a String.
NSArray	cookies() A convenience method that returns an array of WOCookie objects to be included in the message, usually a WOResponse.
static String	defaultEncoding() Returns the default character encoding used to construct a new WOMessage.
static String	defaultHeaderEncoding() Encoding to be used when reading Http headers.
static String	defaultURLEncoding() Gets the default encoding to use when converting the parameter list that appears in a WebObjects generated URL from transcoded ASCII to Unicode and vice versa.
boolean	equals(Object aMessage) Returns true if the supplied Object is a WOMessage, or a subclass, whose headers and content equal those of the receiver.
Object	handleQueryWithUnboundKey(String key) Invoked from valueForKey when it finds no property binding for key.
void	handleTakeValueForUnboundKey(Object value, String key) Invoked from takeValueForKey when it finds no property binding for key.
boolean	hasHeaderForKey(Object aKey) Check if a header has been defined in the headers set
String	headerForKey(Object aKey) Returns the HTTP header field-value corresponding to the field-name aKey.
String	headerForKey(Object aKey, String defaultValue) Returns the HTTP header field-value corresponding to the field-name aKey.
NSArray	headerKeys() Return the field-names for all headers that have been set, or null if none exist.
NSDictionary	headers() Returns an NSDictionary containing the WOMessage's HTTP headers.
NSArray	headersForKey(Object aKey) Returns all HTTP header field-values corresponding to the field-name aKey.
String	httpVersion() Returns the version of HTTP used for the message (for example, "HTTP/1.0").
void	removeCookie(WOCookie aCookie) A convenience method that removes the specified WOCookie object from the WOMessage.
void	removeHeadersForKey(Object aKey) Removes all HTTP headers with the field-name aKey from the receiver.
protected static boolean	requiresHTMLEscaping(String aString, char[] charactersString) This protected class method takes a String and an array of characters and returns true if any of the characters in the character array are found in the String.
void	setContent(byte[] values) Sets the message content to the contents of the supplied byte array.
void	setContent(char[] someContent) Sets the message content to the contents of the supplied character array.
void	setContent(NSData someContent) Sets the message content to someContent.
void	setContent(String someContent) Sets the message content to the contents of the supplied String object.
void	setContentDOMDocument(Document aDocument) Sets the XML content of the response to the DOM document aDocument.
void	setContentEncoding(String anEncoding) Sets the encoding used for the message content.
static void	setDefaultEncoding(String aStringEncoding) Lets you specify the default character encoding to be used when constructing a new WOMessage.
static void	setDefaultHeaderEncoding(String headerEncoding) Set the Encoding to be used when reading Http headers.
static void	setDefaultURLEncoding(String anEncoding) Sets the default encoding to use when converting the parameter list that appears in a WebObjects generated URL from transcoded ASCII to Unicode and vice versa.
void	setHeader(String aString, String aKey) Sets an HTTP header in the receiver with field-name aKey and value aString.
void	setHeaders(List someStrings, String aKey) Sets an HTTP header in the receiver with field-name aKey and values someStrings.
void	setHeaders(Map headerDictionary) Sets the HTTP headers in the receiver to the contents of the supplied NSDictionary object.
void	setHTTPVersion(String aVersion) Sets the version of HTTP used for the message (for example, "HTTP/1.0").
void	setStorePageInBacktrackCache(boolean value) For WOAjaxHandlerRequests, the default is false.
void	setUserInfo(Map aDictionary) Sets a dictionary in the WOMessage object that can contain, as a convenience, any kind of information related to the current response.
void	setUserInfoForKey(Object value, String key) Sets the value for key in the user info dictionary
boolean	storePageInBacktrackCache() For WOAjaxHandlerRequests, this defaults to false.
static String	stringByEscapingHTMLAttributeValue(String aString) Takes a String and, if escaping is required, returns a new String with certain characters escaped out.
static String	stringByEscapingHTMLString(String aString) Takes a String and, if escaping is required, returns a new String with certain characters escaped out.
void	takeValueForKey(Object value, String key) Sets the value for the property identified by key to value.
void	takeValueForKeyPath(Object value, String keyPath) Sets the value for the property identified by keyPath to value.
String	toString() Returns a String representation of the receiver.
void	unableToSetNullForKey(String key) Invoked from takeValueForKey when it is given a null value for a scalar property (such as an int or a float).
NSDictionary	userInfo() Return the userInfo dictionary.
Object	userInfoForKey(String key) Return the value of the key in the user info dictionary
Object	valueForKey(String key) Retrieves the value of the property named by key.
Object	valueForKeyPath(String keyPath) Retrieves the value of a property of the object at the end of the key path (a key path is a string of the form "key1.key2").

Methods inherited from class java.lang.Object

finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

TheDefaultResponseEncoding

protected static String TheDefaultResponseEncoding

This protected class variable contains a String identifying the default encoding to use when constructing responses, which is defined in WOMessage to be UTF8 (UTF-8). Pre-5.4, ISO-8859-1 was the default encoding setting.

Since:

5.4

See Also:

Sun documentation on encodings

HTTP_STATUS_OK

public static final int HTTP_STATUS_OK

Integer value corresponding to the HTTP 1.1 status code for "OK".

See Also:

Constant Field Values

HTTP_STATUS_NO_CONTENT

public static final int HTTP_STATUS_NO_CONTENT

Integer value corresponding to the HTTP 1.1 status code for "No content".

See Also:

Constant Field Values

HTTP_STATUS_MOVED_PERMANENTLY

public static final int HTTP_STATUS_MOVED_PERMANENTLY

Integer value corresponding to the HTTP 1.1 status code for "Moved permanently".

See Also:

Constant Field Values

HTTP_STATUS_FOUND

public static final int HTTP_STATUS_FOUND

Integer value corresponding to the HTTP 1.1 status code for "Found".

See Also:

Constant Field Values

HTTP_STATUS_FORBIDDEN

public static final int HTTP_STATUS_FORBIDDEN

Integer value corresponding to the HTTP 1.1 status code for "Forbidden".

See Also:

Constant Field Values

HTTP_STATUS_NOT_FOUND

public static final int HTTP_STATUS_NOT_FOUND

Integer value corresponding to the HTTP 1.1 status code for "Not found".

See Also:

Constant Field Values

HTTP_STATUS_INTERNAL_ERROR

public static final int HTTP_STATUS_INTERNAL_ERROR

Integer value corresponding to the HTTP 1.1 status code for "Internal Server Error".

See Also:

Constant Field Values

map

protected static final boolean[] map

Constructor Detail

WOMessage

public WOMessage()

Construct and initialize a WOMessage with HTTP version 1.0 and string encoding ISO8859_1 (ISO Latin 1).

Method Detail

defaultEncoding

public static String defaultEncoding()

Returns the default character encoding used to construct a new WOMessage.

The default is UTF-8. Pre-5.4, ISO-8859-1 was the default encoding setting.

Returns:

the default character encoding

Since:

5.4

See Also:

WOMessage.contentEncoding(), WOMessage.setDefaultEncoding(java.lang.String), Sun documentation on encodings

setDefaultEncoding

public static void setDefaultEncoding(String aStringEncoding)

Lets you specify the default character encoding to be used when constructing a new WOMessage.

Parameters:

aStringEncoding - the default character encoding

See Also:

WOMessage.contentEncoding(), WOMessage.defaultEncoding(), Sun documentation on encodings

setDefaultURLEncoding

public static void setDefaultURLEncoding(String anEncoding)

Sets the default encoding to use when converting the parameter list that appears in a WebObjects generated URL from transcoded ASCII to Unicode and vice versa. The default is UTF-8, which will work for all languages. Unless you have good reasons for changing it, it is better to leave it alone. There might be one good reason for doing so:

• Compliance with bookmarked WebObjects generated URLs before 5.2. If your users have bookmarked an URL that contains a parameter list with ASCII characters of values greater than 127, then you would want to use this method to set encoding to "ISO-8859-1".

Parameters:

anEncoding - String the default encoding to use

Since:

5.4

See Also:

Sun documentation on encodings

defaultURLEncoding

public static String defaultURLEncoding()

Gets the default encoding to use when converting the parameter list that appears in a WebObjects generated URL from transcoded ASCII to Unicode and vice versa. The default is UTF-8.

Returns:

the default URL encoding

Since:

5.4

See Also:

WOMessage.setDefaultURLEncoding(java.lang.String), Sun documentation on encodings

defaultHeaderEncoding

public static String defaultHeaderEncoding()

Encoding to be used when reading Http headers. Default is UTF-8

Returns:

encoding

setDefaultHeaderEncoding

public static void setDefaultHeaderEncoding(String headerEncoding)

Set the Encoding to be used when reading Http headers.

Parameters:

header - encoding

clone

public Object clone()

Overrides:

clone in class Object

setHTTPVersion

public void setHTTPVersion(String aVersion)

Sets the version of HTTP used for the message (for example, "HTTP/1.0").

Parameters:

aVersion - the version of HTTP

See Also:

WOMessage.httpVersion()

httpVersion

public String httpVersion()

Returns the version of HTTP used for the message (for example, "HTTP/1.0").

Returns:

the version of HTTP used for the message as a String

See Also:

WOMessage.setHTTPVersion(String aVersion)

setUserInfo

public void setUserInfo(Map aDictionary)

Sets a dictionary in the WOMessage object that can contain, as a convenience, any kind of information related to the current response. Objects further down the appendToResponse method chain can retrieve this information by invoking userInfo.

This method unconditionally makes an immutable copy of aDictionary. This can be a problem if changes made elsewhere to the dictionary's contents need to be reflected in the userInfo dictionary.

If you need to pass in a mutable dictionary that can be changed by other objects down the chain, wrap the mutable dictionary in a read-only (immutable) dictionary and pass the immutable dictionary as the argument to this method. Be extremely careful doing this if your application is multi-threaded and the userInfo data may be accessed by multiple threads.

Parameters:

aDictionary - a dictionary that can contain any kind of information related to the current response

See Also:

WOMessage.userInfo()

userInfo

public NSDictionary userInfo()

Return the userInfo dictionary. An object further upstream in the appendToResponse method chain can set this dictionary in the WOMessage object as a way to pass information to other objects.

Returns:

a dictionary that can contain any kind of information related to the current response

See Also:

WOMessage.setUserInfo(Map), WOApplication.appendToResponse(WOResponse aResponse, WOContext aContext)

userInfoForKey

public Object userInfoForKey(String key)

Return the value of the key in the user info dictionary

Parameters:

key - to search for

Returns:

value for key

Since:

5.4

setUserInfoForKey

public void setUserInfoForKey(Object value,
                              String key)

Sets the value for key in the user info dictionary

Parameters:

value - to set

key - to set

Since:

5.4

setHeaders

public void setHeaders(List someStrings,
                       String aKey)

Sets an HTTP header in the receiver with field-name aKey and values someStrings. If there are one or more existing headers with the field-name aKey, they are replaced.

See RFC 2616 for more than you could possibly want to know about HTTP headers.

Parameters:

someStrings - the HTTP header field-values

aKey - the HTTP header field-name

See Also:

WOMessage.setHeader(String aString, String aKey), WOMessage.appendHeader(String header, String key), #appendHeaders(NSArray headers, String key), WOMessage.headerForKey(Object aKey), WOMessage.removeHeadersForKey(Object aKey)

setHeader

public void setHeader(String aString,
                      String aKey)

Sets an HTTP header in the receiver with field-name aKey and value aString. If there are one or more existing headers with the field-name aKey, they are replaced. This method is commonly used to set the type of content in a response, for example:

 aResponse.setHeader("text/html", "content-type");
 

.

See RFC 2616 for more than you could possibly want to know about HTTP headers.

Parameters:

aString - the HTTP header field-value

aKey - the HTTP header field-name

See Also:

WOMessage.setHeaders(List someStrings, String aKey), WOMessage.appendHeader(String header, String key), #appendHeaders(NSArray headers, String key), WOMessage.headerForKey(Object aKey), WOMessage.removeHeadersForKey(Object aKey)

appendHeader

public void appendHeader(String header,
                         String key)

Appends header to the list of header field-values in the receiver for the field-name key.

If there are no existing HTTP headers with field-name key, a new list is created, if there are one or more existing headers for key, the new value is appended to the existing list. See RFC 2616 for more than you could possibly want to know about HTTP headers.

Parameters:

header - the HTTP header field-value to be appended to the list of values

key - the HTTP header field-name of the header being appended

See Also:

WOMessage.headerKeys(), WOMessage.headersForKey(Object aKey), WOMessage.setHeaders(List someStrings, String aKey), #appendHeaders(NSArray headers, String key)

removeHeadersForKey

public void removeHeadersForKey(Object aKey)

Removes all HTTP headers with the field-name aKey from the receiver.

Parameters:

aKey - the HTTP header field-name of the headers being removed

See Also:

WOMessage.appendHeader(String header, String key), WOMessage.setHeader(String aString, String aKey)

headerKeys

public NSArray headerKeys()

Return the field-names for all headers that have been set, or null if none exist. You could easily test to see if a header is included by doing something similar to this:

 NSArray hKeys = aMessage.headerKeys();
 if (hKeys.containsObject("expires")) {
        // do something
 }
 

Returns:

NSArray containing the receiver's HTTP header field-names (keys are all lower cased)

See Also:

WOMessage.headers(), WOMessage.appendHeader(String header, String key), WOMessage.setHeader(String aString, String aKey), WOMessage.setHeaders(List headerList, String aKey)

headersForKey

public NSArray headersForKey(Object aKey)

Returns all HTTP header field-values corresponding to the field-name aKey.

Parameters:

aKey - the HTTP header field-name of the headers to return

Returns:

all HTTP headers with field-name aKey

See Also:

WOMessage.appendHeader(String header, String key), WOMessage.setHeader(String aHeader, String aKey), WOMessage.setHeaders(List headerList, String aKey)

headerForKey

public String headerForKey(Object aKey)

Returns the HTTP header field-value corresponding to the field-name aKey. If there are multiple headers with the same field-name, only the first one is returned. Returns null if there are no headers with field-name aKey

Parameters:

aKey - the HTTP header field-name of the header to return

Returns:

the HTTP header field-value for the header with field-name aKey

See Also:

WOMessage.appendHeader(String header, String key), WOMessage.setHeader(String aHeader, String aKey), WOMessage.setHeaders(List headerList, String aKey)

headerForKey

public String headerForKey(Object aKey,
                           String defaultValue)

Returns the HTTP header field-value corresponding to the field-name aKey. If there are multiple headers with the same field-name, only the first one is returned. Returns defaultValue if there are no headers with field-name aKey

Parameters:

aKey - the HTTP header field-name of the header to return

defaultValue - Value if the header is absent.

Returns:

the HTTP header field-value for the header with field-name aKey

Since:

5.4

See Also:

WOMessage.appendHeader(String header, String key), WOMessage.setHeader(String aHeader, String aKey), WOMessage.setHeaders(List headerList, String aKey)

hasHeaderForKey

public boolean hasHeaderForKey(Object aKey)

Check if a header has been defined in the headers set

Parameters:

aKey - the HTTP header field-name of the header to check

Returns:

true if header key exists

Since:

5.4

See Also:

WOMessage.appendHeader(String header, String key), WOMessage.setHeader(String aHeader, String aKey), WOMessage.setHeaders(List headerList, String aKey)

headers

public NSDictionary headers()

Returns an NSDictionary containing the WOMessage's HTTP headers.

Returns:

NSDictionary containing the WOMessage's HTTP headers.

See Also:

WOMessage.appendHeader(String header, String key), WOMessage.setHeader(String aHeader, String aKey)

setHeaders

public void setHeaders(Map headerDictionary)

Sets the HTTP headers in the receiver to the contents of the supplied NSDictionary object. This dictionary should be constructed such that its keys are the HTTP header field-names, and its values are NSMutableArrays containing the HTTP header field-values.

See RFC 2616 for more than you could possibly want to know about HTTP headers.

Parameters:

headerDictionary - an NSDictionary containing header field-names and field-values

See Also:

#appendHeaders(NSArray headerList, String aKey), WOMessage.headerKeys(), WOMessage.headersForKey(Object aKey), WOMessage.setHeaders(List headerList, String aKey)

appendHeaders

public void appendHeaders(List headers,
                          String key)

Appends headers to the list of header field-values in the receiver for the field-name key.

If there are no existing HTTP headers with field-name key, a new list is created, if there are one or more existing headers for key, the new values are appended to the existing list.

See RFC 2616 for more than you could possibly want to know about HTTP headers.

Parameters:

headers - the header values to be appended to the list of key

key - the header key

See Also:

WOMessage.headerKeys(), WOMessage.headersForKey(Object aKey), WOMessage.setHeaders(List headerList, String aKey)

setContent

public void setContent(byte[] values)

Sets the message content to the contents of the supplied byte array.

Parameters:

values - byte array containing the message content

See Also:

WOMessage.content(), WOMessage.setContent(NSData someContent), WOMessage.setContent(String someContent)

setContent

public void setContent(char[] someContent)

Sets the message content to the contents of the supplied character array.

Parameters:

someContent - character array containing the message content

See Also:

WOMessage.content(), WOMessage.setContent(NSData someContent), WOMessage.setContent(String someContent)

setContent

public void setContent(NSData someContent)

Sets the message content to someContent.

Parameters:

someContent - NSData containing the message content

See Also:

WOMessage.content(), WOMessage.setContent(char[] someContent), WOMessage.setContent(String someContent)

setContent

public void setContent(String someContent)

Sets the message content to the contents of the supplied String object.

Parameters:

someContent - String containing the message content

See Also:

WOMessage.content(), WOMessage.setContent(char[] someContent), WOMessage.setContent(NSData someContent)

contentString

public String contentString()

Returns the HTML content of the receiver as a String. If the content was set as an NSData, the String returned will be encoded using contentEncoding.

Returns:

the content of the receiver as a String

See Also:

WOMessage.content(), WOMessage.contentEncoding()

content

public NSData content()

Returns the HTML content of the receiver as an NSData object.If the content was set as a String, the NSData returned will contain the bytes of the String encoded using contentEncoding.

Returns:

the HTML content of the receiver as an NSData object

See Also:

WOMessage.contentString(), WOMessage.setContent(NSData someData), WOMessage.setContentEncoding(String anEncoding)

contentEncoding

public String contentEncoding()

Returns a String representing the encoding used for the message content. The current set of encodings supported is detailed at http://java.sun.com/j2se/1.3/docs/guide/intl/encoding.doc.html

For responses, you will want the response encoding to be the same as that used by the submitting form on the client browser. In this case it is preferable to use WORequest's formValueEncoding.

The default string encoding is ISO8859_1 (ISO Latin 1).

Returns:

a String representing the encoding used for the message's content

See Also:

WORequest.formValueEncoding(), WOMessage.setContent(NSData someData), WOMessage.setContentEncoding(String anEncoding)

setContentEncoding

public void setContentEncoding(String anEncoding)

Sets the encoding used for the message content. The current set of encodings supported is detailed at http://java.sun.com/j2se/1.3/docs/guide/intl/encoding.doc.html

For responses, you will want the response encoding to be the same as that used by the submitting form on the client browser. In this case it is preferable to use WORequest's formValueEncoding.

The default string encoding is ISO8859_1 (ISO Latin 1).

Parameters:

anEncoding - the encoding used for the message contents

See Also:

WOMessage.contentEncoding()

appendContentData

public void appendContentData(NSData someData)

Appends the content of NSData someData to the message's content.

Parameters:

someData - NSData to append to the message's content

See Also:

WOMessage.content(), WOMessage.setContent(NSData someData)

appendContentCharacter

public void appendContentCharacter(char aCharacter)

Appends the single ASCII character aCharacter to the message's content.

Should not be called if data has been added to the WOMessage's content using either setContent(NSData aData) or appendContent(NSData aData).

Parameters:

aCharacter - the single ASCII character to be appended

Since:

5.0

appendContentString

public void appendContentString(String aString)

Appends aString to the receiver's content. The special HTML characters "<", ">", "&", and double-quote are not escaped so a browser will interpret them as HTML.

Should not be called if data has been added to the WOMessage's content using either setContent(NSData aData) or appendContent(NSData aData).

Parameters:

aString - the string to be appended to the message's contents

Since:

5.0

requiresHTMLEscaping

protected static boolean requiresHTMLEscaping(String aString,
                                              char[] charactersString)

This protected class method takes a String and an array of characters and returns true if any of the characters in the character array are found in the String.

Parameters:

aString - the input string whose characters are to checked

charactersString - the input array of characters

Returns:

true if any of the characters in the character array are found in the String, false otherwise

Since:

5.0

appendContentHTMLString

public void appendContentHTMLString(String aString)

Appends aString to the receiver's content. Special HTML characters -- "<", ">", "&", and double quote -- are escaped so that the browser does not interpret them.

Should not be called if data has been added to the WOMessage's content using either setContent(NSData aData) or appendContent(NSData aData).

Parameters:

aString - an HTML string

Since:

5.0

appendContentHTMLAttributeValue

public void appendContentHTMLAttributeValue(String aString)

Appends the HTML attribute value passed in as aString to the HTTP content. Special HTML characters -- "<", ">", "&",\t,\n,\r, and double quote are escaped so that the browser does not interpret them.

Should not be called if data has been added to the WOMessage's content using either setContent(NSData aData) or appendContent(NSData aData).

Parameters:

aString - an HTML attribute value to be appended to the message content

Since:

5.0

toString

public String toString()

Returns a String representation of the receiver. This string representation is suitable for debugging. It details many of the WOMessage object's attributes and should not be confused with the contentString method.

Overrides:

toString in class Object

Returns:

String representation of the receiver

Since:

5.0

addCookie

public void addCookie(WOCookie aCookie)

A convenience method that adds the specified WOCookie object to the WOMessage.

Parameters:

aCookie - the WOCookie object that is to be added

Since:

5.0

See Also:

WOMessage.cookies(), WOMessage.removeCookie(WOCookie aCookie), WOCookie

removeCookie

public void removeCookie(WOCookie aCookie)

A convenience method that removes the specified WOCookie object from the WOMessage.

Parameters:

aCookie - the WOCookie object to remove

See Also:

WOMessage.addCookie(WOCookie aCookie), WOMessage.cookies(), WOCookie

cookies

public NSArray cookies()

A convenience method that returns an array of WOCookie objects to be included in the message, usually a WOResponse.

Returns:

NSArray of WOCookie objects to be included in the message

Since:

5.0

See Also:

WOMessage.addCookie(WOCookie aCookie), WOMessage.removeCookie(WOCookie aCookie), WOCookie

stringByEscapingHTMLString

public static String stringByEscapingHTMLString(String aString)

Takes a String and, if escaping is required, returns a new String with certain characters escaped out. If escaping is not required, no conversion is performed and the original string is returned. This method is used to escape strings which will appear in the visible part of an HTML file (that is, not inside a tag). The escaped characters are: "<", ">", "&", and double quote.

Parameters:

aString - String on which conversion is to be performed

Returns:

a new String with certain characters escaped out or if escaping is not required, returns the original String

Since:

5.0

stringByEscapingHTMLAttributeValue

public static String stringByEscapingHTMLAttributeValue(String aString)

Takes a String and, if escaping is required, returns a new String with certain characters escaped out. If escaping is not required, no conversion is performed and the original string is returned. This method is used to escape strings which will appear as attribute values of a tag. The escaped characters are: "<", ">", "&",\t,\n,\r, and double quote.

Parameters:

aString - String on which conversion is to be performed

Returns:

a new String with certain characters escaped out or If escaping is not required, returns the original String

Since:

5.0

equals

public boolean equals(Object aMessage)

Returns true if the supplied Object is a WOMessage, or a subclass, whose headers and content equal those of the receiver.

Overrides:

equals in class Object

Parameters:

aMessage - the object to be compared

Returns:

true if the supplied Object is a WOMessage or subclass whose headers and content equal those of the receiver

Since:

5.0

contentAsDOMDocument

public Document contentAsDOMDocument()
                              throws WODOMParserException

Returns the content of the receiver as a DOM document object.

Returns:

the content of the receiver as a DOM document object

Throws:

WODOMParserException - when DOM parser throws an exception

Since:

5.0

See Also:

WOMessage.appendContentDOMDocumentFragment(org.w3c.dom.DocumentFragment aDocumentFragment), WOMessage.setContentDOMDocument(org.w3c.dom.Document aDocument)

appendContentDOMDocumentFragment

public void appendContentDOMDocumentFragment(DocumentFragment aDocumentFragment)

Converts the supplied DOM document fragment to an XML string and appends it to the message's contents.

Should not be called if data has been added to the WOMessage's content using either setContent(NSData aData) or appendContent(NSData aData).

Parameters:

aDocumentFragment - the DOM document fragment to be converted

Since:

5.0

See Also:

WOMessage.contentAsDOMDocument(), WOMessage.setContentDOMDocument(org.w3c.dom.Document aDocument), WOMessage

setContentDOMDocument

public void setContentDOMDocument(Document aDocument)

Sets the XML content of the response to the DOM document aDocument.

Parameters:

aDocument - a DOM document

Since:

5.0

See Also:

WOMessage.appendContentDOMDocumentFragment(org.w3c.dom.DocumentFragment aDocumentFragment), WOMessage.contentAsDOMDocument()

canAccessFieldsDirectly

public static boolean canAccessFieldsDirectly()

WOMessage's implementation of this static method returns true, indicating that key-value coding is allowed to access fields in this object if an appropriate method isn't present.

Returns:

true in all cases

Since:

5.0

storePageInBacktrackCache

public boolean storePageInBacktrackCache()

For WOAjaxHandlerRequests, this defaults to false.

Since:

5.4

setStorePageInBacktrackCache

public void setStorePageInBacktrackCache(boolean value)

For WOAjaxHandlerRequests, the default is false.

Since:

5.4

valueForKey

public Object valueForKey(String key)

Description copied from interface: NSKeyValueCoding

Retrieves the value of the property named by key.

The default implementation provided by NSKeyValueCoding.DefaultImplementation works as follows:

1. Searches for a public accessor method based on key. For example, with a key of "lastName", the method looks for a method named getLastName, lastName, or isLastName.
2. If a public accessor method is not found, searches for a private accessor method based on key (a method preceded by an underbar). For example, with a key of "lastName", the method looks for a method named _getLastName, _lastName, or _isLastName
3. If an accessor method is not found and the static method canAccessFieldsDirectly returns true, the method searches for a field based on key and returns its value directly. For the key "lastName", this would be _lastName, _isLastName, lastName, or isLastName.
4. If neither an accessor method nor a field is found, the method invokes handleQueryWithUnboundKey (defined in NSKeyValueCoding.ErrorHandling).

Note: The default implementations have significant performance optimizations. To benefit from them, implement NSKeyValueCoding on a custom class as shown above by using the methods in NSKeyValueCoding.DefaultImplementation, or if your class inherits from an WebObjects class that implements NSKeyValueCoding, do not override the inherited implementation. Using a custom implementation incurs significant performance penalties.

Specified by:

valueForKey in interface NSKeyValueCoding

Parameters:

key - identifies the property to retrieve

Returns:

the value of the property identified by key. Depending on the object you invoke this method upon, null may be replaced with NullValue

See Also:

NSKeyValueCoding.NullValue, NSKeyValueCoding.takeValueForKey(java.lang.Object, java.lang.String), NSKeyValueCoding.DefaultImplementation, NSKeyValueCoding.ErrorHandling, NSKeyValueCoding.ErrorHandling.handleQueryWithUnboundKey(java.lang.String)

takeValueForKey

public void takeValueForKey(Object value,
                            String key)

Description copied from interface: NSKeyValueCoding

Sets the value for the property identified by key to value.

The default implementation provided by NSKeyValueCoding.DefaultImplementation works as follows:

1. Searches for a public accessor method of the form setKey, and invokes it if there is one.
2. If a public accessor method is not found, searches for a private accessor method of the form _setKey, and invokes it if there is one.
3. If an accessor method is not found and the static method canAccessFieldsDirectly returns true, searches for a field based on key and sets its value directly. For the key "lastName", this would be _lastName, _isLastName, lastName, or isLastName.
4. If the type of the value argument is not compatible with the underlying field or method parameter, the default implementation will make an effort to convert between different Java numeric types (Integer, Double, BigDecimal, etc) as well as between Boolean and Number (true = 1, false = 0). If any other conversion would be necessary, an exception is thrown.
5. If neither an accessor method nor a field is found, it is an error condition. It invokes handleTakeValueForUnboundKey if the object implements NSKeyValueCoding.ErrorHandling or throws NSKeyValueCoding.UnknownKeyException if the object does not.

Note: : The default implementations have significant performance optimizations. To benefit from them, implement NSKeyValueCoding on a custom class as shown above by using the methods in NSKeyValueCoding. DefaultImplementation, or if your class inherits from an WebObjects class that implements NSKeyValueCoding, do not override the inherited implementation. Using a custom implementation incurs significant performance penalties.

Specified by:

takeValueForKey in interface NSKeyValueCoding

Parameters:

value - the new value for the property named by key

key - identifies the property to change

See Also:

NSKeyValueCoding.NullValue, NSKeyValueCoding.valueForKey, NSKeyValueCoding.DefaultImplementation, NSKeyValueCoding.ErrorHandling, NSKeyValueCoding.ErrorHandling.handleTakeValueForUnboundKey(java.lang.Object, java.lang.String)

handleQueryWithUnboundKey

public Object handleQueryWithUnboundKey(String key)

Description copied from interface: NSKeyValueCoding.ErrorHandling

Invoked from valueForKey when it finds no property binding for key. The default implementation throws an NSKeyValueCoding.UnknownKeyException, with the target object(TargetObjectUserInfoKey) and key(UnknownUserInfokey) in the user info. An NSKeyValueCoding.ErrorHandling class can override this method to handle the query in some other way. The method can return a value, in which case that value is returned by the corresponding valueForKey invocation.

Specified by:

handleQueryWithUnboundKey in interface NSKeyValueCoding.ErrorHandling

Parameters:

key - the property name which generated this error

Returns:

any Object or null that the custom implementation desires. The default implementation throws an exception instead.

See Also:

NSKeyValueCoding.valueForKey, NSKeyValueCoding.UnknownKeyException, NSKeyValueCoding.DefaultImplementation

handleTakeValueForUnboundKey

public void handleTakeValueForUnboundKey(Object value,
                                         String key)

Description copied from interface: NSKeyValueCoding.ErrorHandling

Invoked from takeValueForKey when it finds no property binding for key. The default implementation throws an NSKeyValueCoding.UnknownKeyException, with the target object(TargetObjectUserInfoKey) and key(UnknownUserInfoKey) in the user info dictionary of the exception. An NSKeyValueCoding.ErrorHandling class can override this method to handle the error in some other way.

Specified by:

handleTakeValueForUnboundKey in interface NSKeyValueCoding.ErrorHandling

Parameters:

value - the new value which could not be set

key - the name of the property which generated this error

See Also:

NSKeyValueCoding.takeValueForKey, NSKeyValueCoding.UnknownKeyException, NSKeyValueCoding.DefaultImplementation

unableToSetNullForKey

public void unableToSetNullForKey(String key)

Description copied from interface: NSKeyValueCoding.ErrorHandling

Invoked from takeValueForKey when it is given a null value for a scalar property (such as an int or a float). The default implementation throws an IllegalArgumentException. You might want to implement the method (or override the inherited implementation) to handle the request in some other way, such as by substituting new Integer(0) or a sentinel value and invoking takeValueForKey again.

Specified by:

unableToSetNullForKey in interface NSKeyValueCoding.ErrorHandling

Parameters:

key - the name of the property which generated this error

See Also:

NSKeyValueCoding.takeValueForKey, NSKeyValueCoding.DefaultImplementation

valueForKeyPath

public Object valueForKeyPath(String keyPath)

Description copied from interface: NSKeyValueCodingAdditions

Retrieves the value of a property of the object at the end of the key path (a key path is a string of the form "key1.key2"). A key path has the form relationship.property (with one or more relationships); for example "movieRole.roleName" or "movieRole.talent.lastName". The default implementation of this method (provided by NSKeyValueCodingAdditions.DefaultImplementation) gets the destination object for each relationship using valueForKey, and returns the result of a valueForKey message to the final object.

Specified by:

valueForKeyPath in interface NSKeyValueCodingAdditions

Parameters:

keyPath - the keypath to evaluate

Returns:

the value for the derived property identified by keyPath

See Also:

NSKeyValueCoding.valueForKey(java.lang.String), NSKeyValueCodingAdditions.takeValueForKeyPath(java.lang.Object, java.lang.String), NSKeyValueCodingAdditions.DefaultImplementation

takeValueForKeyPath

public void takeValueForKeyPath(Object value,
                                String keyPath)

Description copied from interface: NSKeyValueCodingAdditions

Sets the value for the property identified by keyPath to value. A key path has the form relationship.property (with one or more relationships); for example "movieRole.roleName" or "movieRole.talent.lastName". The default implementation of this method (provided by NSKeyValueCodingAdditions.DefaultImplementation) gets the destination object for each relationship using valueForKey, and sends the final object a takeValueForKey message with value and property.

Specified by:

takeValueForKeyPath in interface NSKeyValueCodingAdditions

Parameters:

value - the property identified by keyPath is set to this

keyPath - identifies the property of an object

See Also:

NSKeyValueCoding.takeValueForKey(java.lang.Object, java.lang.String), NSKeyValueCodingAdditions.valueForKeyPath(java.lang.String), NSKeyValueCodingAdditions.DefaultImplementation