WOMessage

Inherits from:
Object

Package:
com.webobjects.appserver

Class Description

WOMessage is the parent class for both WORequest and WOMessage,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 your WOMessage objects in order to pass information about a given message to other objects within your application.

Note: Headers are case-insensitive. WebObjects enforces the HTTP specification, but avoid mixing the case of header keys. See the HTTP specification or HTTP documentation for more information on the HTTP headers and version.

Content Encodings

You can set the string encoding used for the response content with setContentEncoding and you find out what the current encoding is with contentEncoding. An integer represents the type of encoding. The following table lists these integer values along with their WebObjects string-constant names.

int Value	WebObjects Name	Notes
1	NSASCIIStringEncoding	0 through 127
2	NSNEXTSTEPStringEncoding
3	NSJapaneseEUCStringEncoding
4	NSUTF8StringEncoding
5	NSISOLatin1StringEncoding	default
6	NSSymbolStringEncoding
7	NSNonLossyASCIIStringEncoding	7-bit verbose ASCII to represent all unichars
8	NSShiftJISStringEncoding
9	NSISOLatin2StringEncoding
10	NSUnicodeStringEncoding
11	NSWindowsCP1251StringEncoding	Cyrillic; same as AdobeStandardCyrillic
12	NSWindowsCP1252StringEncoding	Windows Latin1
13	NSWindowsCP1253StringEncoding	Windows Greek
14	NSWindowsCP1254StringEncoding	Windows Turkish
15	NSWindowsCP1250StringEncoding	Windows Latin2
21	NSISO2022JPStringEncoding	ISO 2022 Japanese encoding for electronic mail

Messages with XML Content

The WOMessage class contains three methods that allow you to construct and interpret 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, in the case of appendContentDOMDocumentFragment, a document fragment) 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, see the online documentation at http://www.w3.org/DOM/.

Constants

WOMessage declares these constants:

API	Description
`TheDefaultResponseEncoding`	This protected class variable contains a String identifying the default encoding to use when constructing responses (which is defined in WOMessage to be ISOLatin1).
`HTTP_STATUS_OK`	This constant contains an integer value (200) corresponding to the HTTP 1.1 status code for "OK".
`HTTP_STATUS_NO_CONTENT`	This constant contains an integer value (204) corresponding to the HTTP 1.1 status code for "No content".
`HTTP_STATUS_MOVED_PERMANENTLY`	This constant contains an integer value (301) corresponding to the HTTP 1.1 status code for "Moved permanently".
`HTTP_STATUS_FOUND`	This constant contains an integer value (302) corresponding to the HTTP 1.1 status code for "Found".
`HTTP_STATUS_FORBIDDEN`	This constant contains an integer value (403) corresponding to the HTTP 1.1 status code for "Forbidden".
`HTTP_STATUS_NOT_FOUND`	This constant contains an integer value (404) corresponding to the HTTP 1.1 status code for "Not found".

Method Types

Creation
WOMessage
Working with message headers
appendHeader
appendHeaders
headerForKey
headerKeys
headers
headersForKey
httpVersion
removeHeadersForKey
setHeader
setHeaders
setHTTPVersion
Working with message content
addCookie
appendContentCharacter
appendContentData
appendContentHTMLString
appendContentHTMLAttributeValue
appendContentString
appendContentDOMDocumentFragment
content
contentAsDOMDocument
contentString
cookies
removeCookie
setContent
setContentDOMDocument
setHeaders
stringByEscapingHTMLAttributeValue
stringByEscapingHTMLString
Controlling content encoding
defaultEncoding
setDefaultEncoding
contentEncoding
setContentEncoding
Working with user info
setUserInfo
userInfo

Constructors

WOMessage

public WOMessage()

Returns an initialized WOMessage instance. The default string encoding is set to ISO Latin 1.

Static Methods

defaultEncoding

public static String defaultEncoding()

Returns the default character encoding used to construct a new WOMessage which initially is NSISOLatin1. For more information, see "Content Encodings".

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.

setDefaultEncoding

public static void setDefaultEncoding(String aStringEncoding)

Lets you specify the character encoding to be used by default when construcing a new WOMessage. For more information, see "Content Encodings".

stringByEscapingHTMLAttributeValue

public static String stringByEscapingHTMLAttributeValue(String aString)

This class method 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. Use this method to escape strings which will appear as attribute values of a tag. The escaped characters are: "<", ">", "&", "\t", "\n", "\r", and double quote.

stringByEscapingHTMLString

public static String stringByEscapingHTMLString(String aString)

This class method 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. Use this method 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.

Instance Methods

addCookie

public void addCookie(WOCookie aCookie)

A convenience method that adds the specified WOCookie object to the message content.

See Also: cookies, removeCookie, WOCookie class specification

appendContentCharacter

public void appendContentCharacter(char aChar)

Appends a single ASCII character (aChar) to the message's contents.

appendContentData

public void appendContentData(NSData dataObject)

Appends a data-encapsulating object (dataObject) to the message's contents.

appendContentHTMLAttributeValue

public void appendContentHTMLAttributeValue(String aString)

Appends an HTML attribute value (passed in as a String) to the HTTP content after transforming the string argument into an NSData object using the receiver's content encoding. Special HTML characters ("<", ">", "&", "\t", "\n", "\r", and double quote) are escaped so that the browser does not interpret them.

appendContentHTMLString

public void appendContentHTMLString(String aString)

Appends an HTML string (passed in as a parameter) to the HTTP response after transforming the string paramenter into an NSData object using the receiver's content encoding. Special HTML characters ("<", ">", "&", and double quote) are escaped so that the browser does not interpret them.

appendContentString

public void appendContentString(String aString)

Appends a string to the content of the message's contents. The string is transformed into an NSData object using the receiver's content encoding. The special HTML characters "<", ">", "&", and double-quote are not escaped so a browser can interpret them as HTML.

appendContentDOMDocumentFragment

public void appendContentDOMDocumentFragment( org.w3c.dom.DocumentFragment aDocumentFragment)

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

appendHeader

public void appendHeader( String header, String aKey)

Appends header to the list of HTTP headers in the receiver and associates, for retrieval, the HTTP key aKey with the new header. If a header list doesn't already exist for the receiver, one is created before the new header is appended.

See Also: headerKeys, headersForKey, setHeaders

appendHeaders

public void appendHeaders( NSArray headerList, String aKey)

Appends headerList to the list of HTTP headers in the receiver and associates, for retrieval, the HTTP key aKey with the list of header elements. If a header list doesn't already exist for the receiver, one is created before the list of headers is appended.

See Also: headerKeys, headersForKey, setHeaders

clone

public Object clone()

Returns a new object that is a copy of the receiver.

content

public NSData content()

Returns the HTML content of the receiver as an NSData object.

An exception is raised if you attempt to get the content when all elements of the page have not had their chance to append HTML to the response. Thus, you should invoke this method in the application object's handleRequest: method, after super's handleRequest: has been invoked. (For scripted applications, handleRequest: is implemented in Application.wos). Note that at this point in the request-handling process, the components, pages, and session have already been put to sleep, so you won't have access to any context, session, or page information. If you need such information for your response, store it somewhere--such as in WOMessage's "user info" dictionary-at a point when you do have access to it. You may want to do this in your application's appendToResponse method, for example.

See Also: setContent, setContentEncoding

contentAsDOMDocument

public org.w3c.dom.Document contentAsDOMDocument() throws WODOMParserException

Returns the content of the receiver as a DOM document object. Throws a DOMParserException if the DOM parser throws an exception.

contentEncoding

public String contentEncoding()

Returns a String representing the encoding used for the message's content. See "Content Encodings" in the class description for a mapped list of supported encodings and their WebObjects names. 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 ISO Latin1.

See Also: setContent, setContentEncoding

contentString

public String contentString()

Returns the content of the receiver as a String object.

cookies

public NSArray cookies()

A convenience method that returns an array of WOCookie objects to be included in the message (which is uaually a WOMessage).

See Also: addCookie, removeCookie, WOCookie class specification

equals

public boolean equals(Object aMessage)

Inherited from java.lang.Object. Returns true if the supplied Object is a WOMessage (or a subclass) whose headers and content equal those of the receiver.

headerForKey

public String headerForKey(Object aKey)

Returns the HTTP header information identified by aKey. If there are multiple headers associated with the one key, only the first one is returned. Returns null if the message has no headers for the key.

See Also: setHeader

headerKeys

public NSArray headerKeys()

Returns an array of string keys associated with the receiver's HTTP headers. Returns null if there are no headers. You could easily test to see if a header is included by doing something similar to this:



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

See Also: setHeaders

headers

public NSDictionary headers()

Returns the header dictionary with which the message was initialized.

headersForKey

public NSArray headersForKey(Object aKey)

Returns all HTTP headers identified by aKey.

See Also: setHeaders

httpVersion

public String httpVersion()

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

See Also: setHTTPVersion

removeCookie

public void removeCookie(WOCookie aCookie)

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

See Also: cookies, removeCookie, WOCookie class specification

removeHeadersForKey

public void removeHeadersForKey(Object aKey)

Removes those headers from the receiver that correspond to the specified key.

setContent

public void setContent(NSData someData)

Sets the message contents to someData.

public void setContent(char[] someContent)

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

public void setContent(String someContent)

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

See Also: content

setContentDOMDocument

public void setContentDOMDocument(org.w3c.dom.Document aDocument)

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

setContentEncoding

public void setContentEncoding(String anEncoding)

Sets the encoding used for the message contents. See "Content Encodings" in the class description for a mapped list of supported encodings and their WebObjects names. The default string encoding is ISO Latin1.

See Also: contentEncoding

setHTTPVersion

public void setHTTPVersion(String aVersion)

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

See Also: httpVersion

setHeader

public void setHeader( String aHeader, String aKey)

Sets the HTTP header in the receiver to aHeader and associates, for retrieval, the HTTP key aKey with the header. This method is commonly used to set the type of content in a response, for example:


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

See Also: headerForKey

setHeaders

public void setHeaders( NSArray headerList, String aKey)

Sets the HTTP header in the receiver to headerList and associates, for retrieval, the HTTP key aKey with the list of header elements.

public void setHeaders(NSDictionary headerDictionary)

Sets the list of HTTP headers in the receiver to the contents of the supplied NSDictionary object.

See Also: appendHeaders, headerKeys, headersForKey

setUserInfo

public void setUserInfo(NSDictionary aDictionary)

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

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.

userInfo

public NSDictionary userInfo()

Returns a dictionary that, as a convenience, can contain any kind of information related to the current response. An object further "upstream" in the appendToResponse message "chain" can set this dictionary in the WOMessage object as a way to pass information to other objects.

See Also: setUserInfo