PATH Documentation > WebObjects 4.5 > WebObjects Reference

WOMessage

Inherits from: NSObject

Package: com.apple.yellow.webobjects

Class Description

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 your WOMessage objects in order to pass information about a given message to other objects within your application.

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.

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.

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/.

Note that the XML parser is a Java package, and that WOMessage doesn't provide corresponding Objective-C versions of appendContentDOMDocumentFragment, contentAsDOMDocument, and setContentDOMDocument.

Method Types

Creation

WOMessage

Working with message headers

appendHeader

appendHeaders

headerForKey

headerKeys

headers

headersForKey

httpVersion

setHeader

setHeaders

setHTTPVersion

Working with message content

addCookie

appendContentCharacter

appendContentData

appendContentString

appendContentDOMDocumentFragment

content

contentAsDOMDocument

cookies

removeCookie

setContent

setContentDOMDocument

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 int defaultEncoding()

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

setDefaultEncoding

public static void setDefaultEncoding(int aStringEncoding)

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

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(byte 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.

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 aHeader, String aKey)

Appends the HTTP header aHeader in the receiver 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.appendHeader("text/html", "content-type");

See Also: headerForKey, setHeader

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 headerList is appended.

See Also: headerKeys, headersForKey, setHeaders

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()

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

contentEncoding

public int contentEncoding()

Returns an integer 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

cookies

public NSArray cookies()

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

See Also: addCookie, removeCookie, WOCookie class specification

headerForKey

public String headerForKey(String 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(String 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

setContent

public void setContent(NSData someData)

Sets the message contents to someData.

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(int 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 aHeader in the receiver 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: appendHeader, headerForKey

setHeaders

public void setHeaders( NSArray headerList, String aKey)

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

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.

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