PATH Documentation > WebObjects

Table of Contents

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.

See Also: contentAsDOMDocument, setContentDOMDocument, Messages with XML Content



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.

See Also: appendContentDOMDocumentFragment, setContentDOMDocument



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.

See Also: appendContentDOMDocumentFragment, contentAsDOMDocument



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



© 2001 Apple Computer, Inc. (Last Published April 15, 2001)


Table of Contents