PATH |
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()
Static Methods
defaultEncoding
public static String defaultEncoding()
requiresHTMLEscaping
protected static boolean requiresHTMLEscaping( String aString, char[] charactersString)
true
if any of the characters in the character array are found in the String.
setDefaultEncoding
public static void setDefaultEncoding(String aStringEncoding)
stringByEscapingHTMLAttributeValue
public static String stringByEscapingHTMLAttributeValue(String aString)
stringByEscapingHTMLString
public static String stringByEscapingHTMLString(String aString)
Instance Methods
addCookie
public void addCookie(WOCookie aCookie)
See Also: cookies, removeCookie, WOCookie class specification
appendContentCharacter
public void appendContentCharacter(char aChar)
appendContentData
public void appendContentData(NSData dataObject)
appendContentHTMLAttributeValue
public void appendContentHTMLAttributeValue(String aString)
appendContentHTMLString
public void appendContentHTMLString(String aString)
appendContentString
public void appendContentString(String aString)
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)
See Also: headerKeys, headersForKey, setHeaders
appendHeaders
public void appendHeaders( NSArray headerList, String aKey)
See Also: headerKeys, headersForKey, setHeaders
clone
public Object clone()
content
public NSData content()
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()
The default string encoding is ISO Latin1.
See Also: setContent, setContentEncoding
contentString
public String contentString()
cookies
public NSArray cookies()
See Also: addCookie, removeCookie, WOCookie class specification
equals
public boolean equals(Object aMessage)
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)
null
if the message has no headers for the key.
See Also: setHeader
headerKeys
public NSArray headerKeys()
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()
headersForKey
public NSArray headersForKey(Object aKey)
See Also: setHeaders
httpVersion
public String httpVersion()
See Also: setHTTPVersion
removeCookie
public void removeCookie(WOCookie aCookie)
See Also: cookies, removeCookie, WOCookie class specification
removeHeadersForKey
public void removeHeadersForKey(Object aKey)
setContent
public void setContent(NSData someData)
public void setContent(char[] someContent)
public void setContent(String someContent)
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)
See Also: contentEncoding
setHTTPVersion
public void setHTTPVersion(String aVersion)
See Also: httpVersion
setHeader
public void setHeader( String aHeader, String aKey)
aResponse.setHeader("text/html", "content-type");
See Also: headerForKey
setHeaders
public void setHeaders( NSArray headerList, String aKey)
public void setHeaders(NSDictionary headerDictionary)
See Also: appendHeaders, headerKeys, headersForKey
setUserInfo
public void setUserInfo(NSDictionary aDictionary)
toString
public String toString()
userInfo
public NSDictionary userInfo()
See Also: setUserInfo
© 2001 Apple Computer, Inc. (Last Published April 15, 2001)