PATH  Documentation > WebObjects 4.5 > WebObjects Reference

Table of Contents

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.

See Also: contentAsDOMDocument, setContentDOMDocument, Messages with XML Content



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.

See Also: appendContentDOMDocumentFragment, setContentDOMDocument



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.

See Also: appendContentDOMDocumentFragment, contentAsDOMDocument



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




Table of Contents