WebObjects 5.4.2

com.webobjects.appserver
Class WOMessage

java.lang.Object
  extended by com.webobjects.appserver.WOMessage
All Implemented Interfaces:
NSKeyValueCoding, NSKeyValueCoding.ErrorHandling, NSKeyValueCodingAdditions
Direct Known Subclasses:
WORequest, WOResponse

public class WOMessage
extends Object
implements NSKeyValueCoding, NSKeyValueCoding.ErrorHandling, NSKeyValueCodingAdditions

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

Note: Headers are case-insensitive. WebObjects enforces the HTTP specification, but you should avoid mixing the case of header keys.

Because WOMessage objects usually correspond to HTTP requests and responses and fulfil the same function as these, the data they represent is mostly the same as that contained in an equivalent HTTP message. Thus an understanding of HTTP requests and responses is important for a good understanding of WOMessage and its subclasses. Version 1.1 of the HTTP protocol and its request format can be found in RFC 2616. Documentation for WOMessage and its subclasses assumes you have a good understanding of the information contained in this RFC and the Netscape cookie specification.

Cookie headers are parsed and returned as instances of WOCookie. If malformed cookies are received, and the property WOAcceptMalformedCookies is false, an exception will be thrown during parsing. If WOAcceptMalformedCookies is true, any cookies successfully parsed will be returned, and the remainder will be discarded. To change this behavior, override the method handleMalformedCookieString on WOApplication.

Note: Only Cookie headers are parsed; if you are receiving requests containing Set-cookie headers, you will have to implement your own parsing code. The WOMessage class also contains three methods that allow construction and interpretation of 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 document fragments 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, there is online documentation at http://www.w3.org/DOM/

See Also:
WOMessage.contentEncoding(), WOMessage.setContentEncoding(String anEncoding), WOMessage.appendContentDOMDocumentFragment(org.w3c.dom.DocumentFragment aDocumentFragment), WOMessage.setContentDOMDocument(org.w3c.dom.Document aDocument), WOMessage.contentAsDOMDocument(), WORequest, WOResponse

Nested Class Summary
 
Nested classes/interfaces inherited from interface com.webobjects.foundation.NSKeyValueCodingAdditions
NSKeyValueCodingAdditions.DefaultImplementation, NSKeyValueCodingAdditions.Utility
 
Field Summary
static int HTTP_STATUS_FORBIDDEN
          Integer value corresponding to the HTTP 1.1 status code for "Forbidden".
static int HTTP_STATUS_FOUND
          Integer value corresponding to the HTTP 1.1 status code for "Found".
static int HTTP_STATUS_INTERNAL_ERROR
          Integer value corresponding to the HTTP 1.1 status code for "Internal Server Error".
static int HTTP_STATUS_MOVED_PERMANENTLY
          Integer value corresponding to the HTTP 1.1 status code for "Moved permanently".
static int HTTP_STATUS_NO_CONTENT
          Integer value corresponding to the HTTP 1.1 status code for "No content".
static int HTTP_STATUS_NOT_FOUND
          Integer value corresponding to the HTTP 1.1 status code for "Not found".
static int HTTP_STATUS_OK
          Integer value corresponding to the HTTP 1.1 status code for "OK".
protected static boolean[] map
           
protected static String TheDefaultResponseEncoding
          This protected class variable contains a String identifying the default encoding to use when constructing responses, which is defined in WOMessage to be UTF8 (UTF-8).
 
Fields inherited from interface com.webobjects.foundation.NSKeyValueCodingAdditions
KeyPathSeparator
 
Constructor Summary
WOMessage()
          Construct and initialize a WOMessage with HTTP version 1.0 and string encoding ISO8859_1 (ISO Latin 1).
 
Method Summary
 void addCookie(WOCookie aCookie)
          A convenience method that adds the specified WOCookie object to the WOMessage.
 void appendContentCharacter(char aCharacter)
          Appends the single ASCII character aCharacter to the message's content.
 void appendContentData(NSData someData)
          Appends the content of NSData someData to the message's content.
 void appendContentDOMDocumentFragment(DocumentFragment aDocumentFragment)
          Converts the supplied DOM document fragment to an XML string and appends it to the message's contents.
 void appendContentHTMLAttributeValue(String aString)
          Appends the HTML attribute value passed in as aString to the HTTP content.
 void appendContentHTMLString(String aString)
          Appends aString to the receiver's content.
 void appendContentString(String aString)
          Appends aString to the receiver's content.
 void appendHeader(String header, String key)
          Appends header to the list of header field-values in the receiver for the field-name key.
 void appendHeaders(List headers, String key)
          Appends headers to the list of header field-values in the receiver for the field-name key.
static boolean canAccessFieldsDirectly()
          WOMessage's implementation of this static method returns true, indicating that key-value coding is allowed to access fields in this object if an appropriate method isn't present.
 Object clone()
           
 NSData content()
          Returns the HTML content of the receiver as an NSData object.If the content was set as a String, the NSData returned will contain the bytes of the String encoded using contentEncoding.
 Document contentAsDOMDocument()
          Returns the content of the receiver as a DOM document object.
 String contentEncoding()
          Returns a String representing the encoding used for the message content.
 String contentString()
          Returns the HTML content of the receiver as a String.
 NSArray cookies()
          A convenience method that returns an array of WOCookie objects to be included in the message, usually a WOResponse.
static String defaultEncoding()
          Returns the default character encoding used to construct a new WOMessage.
static String defaultHeaderEncoding()
          Encoding to be used when reading Http headers.
static String defaultURLEncoding()
          Gets the default encoding to use when converting the parameter list that appears in a WebObjects generated URL from transcoded ASCII to Unicode and vice versa.
 boolean equals(Object aMessage)
          Returns true if the supplied Object is a WOMessage, or a subclass, whose headers and content equal those of the receiver.
 Object handleQueryWithUnboundKey(String key)
          Invoked from valueForKey when it finds no property binding for key.
 void handleTakeValueForUnboundKey(Object value, String key)
          Invoked from takeValueForKey when it finds no property binding for key.
 boolean hasHeaderForKey(Object aKey)
          Check if a header has been defined in the headers set
 String headerForKey(Object aKey)
          Returns the HTTP header field-value corresponding to the field-name aKey.
 String headerForKey(Object aKey, String defaultValue)
          Returns the HTTP header field-value corresponding to the field-name aKey.
 NSArray headerKeys()
          Return the field-names for all headers that have been set, or null if none exist.
 NSDictionary headers()
          Returns an NSDictionary containing the WOMessage's HTTP headers.
 NSArray headersForKey(Object aKey)
          Returns all HTTP header field-values corresponding to the field-name aKey.
 String httpVersion()
          Returns the version of HTTP used for the message (for example, "HTTP/1.0").
 void removeCookie(WOCookie aCookie)
          A convenience method that removes the specified WOCookie object from the WOMessage.
 void removeHeadersForKey(Object aKey)
          Removes all HTTP headers with the field-name aKey from the receiver.
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.
 void setContent(byte[] values)
          Sets the message content to the contents of the supplied byte array.
 void setContent(char[] someContent)
          Sets the message content to the contents of the supplied character array.
 void setContent(NSData someContent)
          Sets the message content to someContent.
 void setContent(String someContent)
          Sets the message content to the contents of the supplied String object.
 void setContentDOMDocument(Document aDocument)
          Sets the XML content of the response to the DOM document aDocument.
 void setContentEncoding(String anEncoding)
          Sets the encoding used for the message content.
static void setDefaultEncoding(String aStringEncoding)
          Lets you specify the default character encoding to be used when constructing a new WOMessage.
static void setDefaultHeaderEncoding(String headerEncoding)
          Set the Encoding to be used when reading Http headers.
static void setDefaultURLEncoding(String anEncoding)
          Sets the default encoding to use when converting the parameter list that appears in a WebObjects generated URL from transcoded ASCII to Unicode and vice versa.
 void setHeader(String aString, String aKey)
          Sets an HTTP header in the receiver with field-name aKey and value aString.
 void setHeaders(List someStrings, String aKey)
          Sets an HTTP header in the receiver with field-name aKey and values someStrings.
 void setHeaders(Map headerDictionary)
          Sets the HTTP headers in the receiver to the contents of the supplied NSDictionary object.
 void setHTTPVersion(String aVersion)
          Sets the version of HTTP used for the message (for example, "HTTP/1.0").
 void setStorePageInBacktrackCache(boolean value)
          For WOAjaxHandlerRequests, the default is false.
 void setUserInfo(Map aDictionary)
          Sets a dictionary in the WOMessage object that can contain, as a convenience, any kind of information related to the current response.
 void setUserInfoForKey(Object value, String key)
          Sets the value for key in the user info dictionary
 boolean storePageInBacktrackCache()
          For WOAjaxHandlerRequests, this defaults to false.
static String stringByEscapingHTMLAttributeValue(String aString)
          Takes a String and, if escaping is required, returns a new String with certain characters escaped out.
static String stringByEscapingHTMLString(String aString)
          Takes a String and, if escaping is required, returns a new String with certain characters escaped out.
 void takeValueForKey(Object value, String key)
          Sets the value for the property identified by key to value.
 void takeValueForKeyPath(Object value, String keyPath)
          Sets the value for the property identified by keyPath to value.
 String toString()
          Returns a String representation of the receiver.
 void unableToSetNullForKey(String key)
          Invoked from takeValueForKey when it is given a null value for a scalar property (such as an int or a float).
 NSDictionary userInfo()
          Return the userInfo dictionary.
 Object userInfoForKey(String key)
          Return the value of the key in the user info dictionary
 Object valueForKey(String key)
          Retrieves the value of the property named by key.
 Object valueForKeyPath(String keyPath)
          Retrieves the value of a property of the object at the end of the key path (a key path is a string of the form "key1.key2").
 
Methods inherited from class java.lang.Object
finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

TheDefaultResponseEncoding

protected static String TheDefaultResponseEncoding
This protected class variable contains a String identifying the default encoding to use when constructing responses, which is defined in WOMessage to be UTF8 (UTF-8). Pre-5.4, ISO-8859-1 was the default encoding setting.

Since:
5.4
See Also:
Sun documentation on encodings

HTTP_STATUS_OK

public static final int HTTP_STATUS_OK
Integer value corresponding to the HTTP 1.1 status code for "OK".

See Also:
Constant Field Values

HTTP_STATUS_NO_CONTENT

public static final int HTTP_STATUS_NO_CONTENT
Integer value corresponding to the HTTP 1.1 status code for "No content".

See Also:
Constant Field Values

HTTP_STATUS_MOVED_PERMANENTLY

public static final int HTTP_STATUS_MOVED_PERMANENTLY
Integer value corresponding to the HTTP 1.1 status code for "Moved permanently".

See Also:
Constant Field Values

HTTP_STATUS_FOUND

public static final int HTTP_STATUS_FOUND
Integer value corresponding to the HTTP 1.1 status code for "Found".

See Also:
Constant Field Values

HTTP_STATUS_FORBIDDEN

public static final int HTTP_STATUS_FORBIDDEN
Integer value corresponding to the HTTP 1.1 status code for "Forbidden".

See Also:
Constant Field Values

HTTP_STATUS_NOT_FOUND

public static final int HTTP_STATUS_NOT_FOUND
Integer value corresponding to the HTTP 1.1 status code for "Not found".

See Also:
Constant Field Values

HTTP_STATUS_INTERNAL_ERROR

public static final int HTTP_STATUS_INTERNAL_ERROR
Integer value corresponding to the HTTP 1.1 status code for "Internal Server Error".

See Also:
Constant Field Values

map

protected static final boolean[] map
Constructor Detail

WOMessage

public WOMessage()
Construct and initialize a WOMessage with HTTP version 1.0 and string encoding ISO8859_1 (ISO Latin 1).

Method Detail

defaultEncoding

public static String defaultEncoding()
Returns the default character encoding used to construct a new WOMessage.

The default is UTF-8. Pre-5.4, ISO-8859-1 was the default encoding setting.

Returns:
the default character encoding
Since:
5.4
See Also:
WOMessage.contentEncoding(), WOMessage.setDefaultEncoding(java.lang.String), Sun documentation on encodings

setDefaultEncoding

public static void setDefaultEncoding(String aStringEncoding)
Lets you specify the default character encoding to be used when constructing a new WOMessage.

Parameters:
aStringEncoding - the default character encoding
See Also:
WOMessage.contentEncoding(), WOMessage.defaultEncoding(), Sun documentation on encodings

setDefaultURLEncoding

public static void setDefaultURLEncoding(String anEncoding)
Sets the default encoding to use when converting the parameter list that appears in a WebObjects generated URL from transcoded ASCII to Unicode and vice versa. The default is UTF-8, which will work for all languages. Unless you have good reasons for changing it, it is better to leave it alone. There might be one good reason for doing so:

Parameters:
anEncoding - String the default encoding to use
Since:
5.4
See Also:
Sun documentation on encodings

defaultURLEncoding

public static String defaultURLEncoding()
Gets the default encoding to use when converting the parameter list that appears in a WebObjects generated URL from transcoded ASCII to Unicode and vice versa. The default is UTF-8.

Returns:
the default URL encoding
Since:
5.4
See Also:
WOMessage.setDefaultURLEncoding(java.lang.String), Sun documentation on encodings

defaultHeaderEncoding

public static String defaultHeaderEncoding()
Encoding to be used when reading Http headers. Default is UTF-8

Returns:
encoding

setDefaultHeaderEncoding

public static void setDefaultHeaderEncoding(String headerEncoding)
Set the Encoding to be used when reading Http headers.

Parameters:
header - encoding

clone

public Object clone()
Overrides:
clone in class Object

setHTTPVersion

public void setHTTPVersion(String aVersion)
Sets the version of HTTP used for the message (for example, "HTTP/1.0").

Parameters:
aVersion - the version of HTTP
See Also:
WOMessage.httpVersion()

httpVersion

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

Returns:
the version of HTTP used for the message as a String
See Also:
WOMessage.setHTTPVersion(String aVersion)

setUserInfo

public void setUserInfo(Map aDictionary)
Sets a dictionary in the WOMessage object that can contain, as a convenience, any kind of information related to the current response. Objects further down the appendToResponse method chain can retrieve this information by invoking userInfo.

This method unconditionally makes an immutable copy of aDictionary. This can be a problem if changes made elsewhere to the dictionary's contents need to be reflected in the userInfo dictionary.

If you need to pass in a mutable dictionary that can be changed by other objects down the chain, wrap the mutable dictionary in a read-only (immutable) dictionary and pass the immutable dictionary as the argument to this method. Be extremely careful doing this if your application is multi-threaded and the userInfo data may be accessed by multiple threads.

Parameters:
aDictionary - a dictionary that can contain any kind of information related to the current response
See Also:
WOMessage.userInfo()

userInfo

public NSDictionary userInfo()
Return the userInfo dictionary. An object further upstream in the appendToResponse method chain can set this dictionary in the WOMessage object as a way to pass information to other objects.

Returns:
a dictionary that can contain any kind of information related to the current response
See Also:
WOMessage.setUserInfo(Map), WOApplication.appendToResponse(WOResponse aResponse, WOContext aContext)

userInfoForKey

public Object userInfoForKey(String key)
Return the value of the key in the user info dictionary

Parameters:
key - to search for
Returns:
value for key
Since:
5.4

setUserInfoForKey

public void setUserInfoForKey(Object value,
                              String key)
Sets the value for key in the user info dictionary

Parameters:
value - to set
key - to set
Since:
5.4

setHeaders

public void setHeaders(List someStrings,
                       String aKey)
Sets an HTTP header in the receiver with field-name aKey and values someStrings. If there are one or more existing headers with the field-name aKey, they are replaced.

See RFC 2616 for more than you could possibly want to know about HTTP headers.

Parameters:
someStrings - the HTTP header field-values
aKey - the HTTP header field-name
See Also:
WOMessage.setHeader(String aString, String aKey), WOMessage.appendHeader(String header, String key), #appendHeaders(NSArray headers, String key), WOMessage.headerForKey(Object aKey), WOMessage.removeHeadersForKey(Object aKey)

setHeader

public void setHeader(String aString,
                      String aKey)
Sets an HTTP header in the receiver with field-name aKey and value aString. If there are one or more existing headers with the field-name aKey, they are replaced. This method is commonly used to set the type of content in a response, for example:

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

See RFC 2616 for more than you could possibly want to know about HTTP headers.

Parameters:
aString - the HTTP header field-value
aKey - the HTTP header field-name
See Also:
WOMessage.setHeaders(List someStrings, String aKey), WOMessage.appendHeader(String header, String key), #appendHeaders(NSArray headers, String key), WOMessage.headerForKey(Object aKey), WOMessage.removeHeadersForKey(Object aKey)

appendHeader

public void appendHeader(String header,
                         String key)
Appends header to the list of header field-values in the receiver for the field-name key.

If there are no existing HTTP headers with field-name key, a new list is created, if there are one or more existing headers for key, the new value is appended to the existing list. See RFC 2616 for more than you could possibly want to know about HTTP headers.

Parameters:
header - the HTTP header field-value to be appended to the list of values
key - the HTTP header field-name of the header being appended
See Also:
WOMessage.headerKeys(), WOMessage.headersForKey(Object aKey), WOMessage.setHeaders(List someStrings, String aKey), #appendHeaders(NSArray headers, String key)

removeHeadersForKey

public void removeHeadersForKey(Object aKey)
Removes all HTTP headers with the field-name aKey from the receiver.

Parameters:
aKey - the HTTP header field-name of the headers being removed
See Also:
WOMessage.appendHeader(String header, String key), WOMessage.setHeader(String aString, String aKey)

headerKeys

public NSArray headerKeys()
Return the field-names for all headers that have been set, or null if none exist. You could easily test to see if a header is included by doing something similar to this:
 NSArray hKeys = aMessage.headerKeys();
 if (hKeys.containsObject("expires")) {
        // do something
 }
 

Returns:
NSArray containing the receiver's HTTP header field-names (keys are all lower cased)
See Also:
WOMessage.headers(), WOMessage.appendHeader(String header, String key), WOMessage.setHeader(String aString, String aKey), WOMessage.setHeaders(List headerList, String aKey)

headersForKey

public NSArray headersForKey(Object aKey)
Returns all HTTP header field-values corresponding to the field-name aKey.

Parameters:
aKey - the HTTP header field-name of the headers to return
Returns:
all HTTP headers with field-name aKey
See Also:
WOMessage.appendHeader(String header, String key), WOMessage.setHeader(String aHeader, String aKey), WOMessage.setHeaders(List headerList, String aKey)

headerForKey

public String headerForKey(Object aKey)
Returns the HTTP header field-value corresponding to the field-name aKey. If there are multiple headers with the same field-name, only the first one is returned. Returns null if there are no headers with field-name aKey

Parameters:
aKey - the HTTP header field-name of the header to return
Returns:
the HTTP header field-value for the header with field-name aKey
See Also:
WOMessage.appendHeader(String header, String key), WOMessage.setHeader(String aHeader, String aKey), WOMessage.setHeaders(List headerList, String aKey)

headerForKey

public String headerForKey(Object aKey,
                           String defaultValue)
Returns the HTTP header field-value corresponding to the field-name aKey. If there are multiple headers with the same field-name, only the first one is returned. Returns defaultValue if there are no headers with field-name aKey

Parameters:
aKey - the HTTP header field-name of the header to return
defaultValue - Value if the header is absent.
Returns:
the HTTP header field-value for the header with field-name aKey
Since:
5.4
See Also:
WOMessage.appendHeader(String header, String key), WOMessage.setHeader(String aHeader, String aKey), WOMessage.setHeaders(List headerList, String aKey)

hasHeaderForKey

public boolean hasHeaderForKey(Object aKey)
Check if a header has been defined in the headers set

Parameters:
aKey - the HTTP header field-name of the header to check
Returns:
true if header key exists
Since:
5.4
See Also:
WOMessage.appendHeader(String header, String key), WOMessage.setHeader(String aHeader, String aKey), WOMessage.setHeaders(List headerList, String aKey)

headers

public NSDictionary headers()
Returns an NSDictionary containing the WOMessage's HTTP headers.

Returns:
NSDictionary containing the WOMessage's HTTP headers.
See Also:
WOMessage.appendHeader(String header, String key), WOMessage.setHeader(String aHeader, String aKey)

setHeaders

public void setHeaders(Map headerDictionary)
Sets the HTTP headers in the receiver to the contents of the supplied NSDictionary object. This dictionary should be constructed such that its keys are the HTTP header field-names, and its values are NSMutableArrays containing the HTTP header field-values.

See RFC 2616 for more than you could possibly want to know about HTTP headers.

Parameters:
headerDictionary - an NSDictionary containing header field-names and field-values
See Also:
#appendHeaders(NSArray headerList, String aKey), WOMessage.headerKeys(), WOMessage.headersForKey(Object aKey), WOMessage.setHeaders(List headerList, String aKey)

appendHeaders

public void appendHeaders(List headers,
                          String key)
Appends headers to the list of header field-values in the receiver for the field-name key.

If there are no existing HTTP headers with field-name key, a new list is created, if there are one or more existing headers for key, the new values are appended to the existing list.

See RFC 2616 for more than you could possibly want to know about HTTP headers.

Parameters:
headers - the header values to be appended to the list of key
key - the header key
See Also:
WOMessage.headerKeys(), WOMessage.headersForKey(Object aKey), WOMessage.setHeaders(List headerList, String aKey)

setContent

public void setContent(byte[] values)
Sets the message content to the contents of the supplied byte array.

Parameters:
values - byte array containing the message content
See Also:
WOMessage.content(), WOMessage.setContent(NSData someContent), WOMessage.setContent(String someContent)

setContent

public void setContent(char[] someContent)
Sets the message content to the contents of the supplied character array.

Parameters:
someContent - character array containing the message content
See Also:
WOMessage.content(), WOMessage.setContent(NSData someContent), WOMessage.setContent(String someContent)

setContent

public void setContent(NSData someContent)
Sets the message content to someContent.

Parameters:
someContent - NSData containing the message content
See Also:
WOMessage.content(), WOMessage.setContent(char[] someContent), WOMessage.setContent(String someContent)

setContent

public void setContent(String someContent)
Sets the message content to the contents of the supplied String object.

Parameters:
someContent - String containing the message content
See Also:
WOMessage.content(), WOMessage.setContent(char[] someContent), WOMessage.setContent(NSData someContent)

contentString

public String contentString()
Returns the HTML content of the receiver as a String. If the content was set as an NSData, the String returned will be encoded using contentEncoding.

Returns:
the content of the receiver as a String
See Also:
WOMessage.content(), WOMessage.contentEncoding()

content

public NSData content()
Returns the HTML content of the receiver as an NSData object.If the content was set as a String, the NSData returned will contain the bytes of the String encoded using contentEncoding.

Returns:
the HTML content of the receiver as an NSData object
See Also:
WOMessage.contentString(), WOMessage.setContent(NSData someData), WOMessage.setContentEncoding(String anEncoding)

contentEncoding

public String contentEncoding()
Returns a String representing the encoding used for the message content. The current set of encodings supported is detailed at http://java.sun.com/j2se/1.3/docs/guide/intl/encoding.doc.html

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 ISO8859_1 (ISO Latin 1).

Returns:
a String representing the encoding used for the message's content
See Also:
WORequest.formValueEncoding(), WOMessage.setContent(NSData someData), WOMessage.setContentEncoding(String anEncoding)

setContentEncoding

public void setContentEncoding(String anEncoding)
Sets the encoding used for the message content. The current set of encodings supported is detailed at http://java.sun.com/j2se/1.3/docs/guide/intl/encoding.doc.html

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 ISO8859_1 (ISO Latin 1).

Parameters:
anEncoding - the encoding used for the message contents
See Also:
WOMessage.contentEncoding()

appendContentData

public void appendContentData(NSData someData)
Appends the content of NSData someData to the message's content.

Parameters:
someData - NSData to append to the message's content
See Also:
WOMessage.content(), WOMessage.setContent(NSData someData)

appendContentCharacter

public void appendContentCharacter(char aCharacter)
Appends the single ASCII character aCharacter to the message's content.

Should not be called if data has been added to the WOMessage's content using either setContent(NSData aData) or appendContent(NSData aData).

Parameters:
aCharacter - the single ASCII character to be appended
Since:
5.0

appendContentString

public void appendContentString(String aString)
Appends aString to the receiver's content. The special HTML characters "<", ">", "&", and double-quote are not escaped so a browser will interpret them as HTML.

Should not be called if data has been added to the WOMessage's content using either setContent(NSData aData) or appendContent(NSData aData).

Parameters:
aString - the string to be appended to the message's contents
Since:
5.0

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.

Parameters:
aString - the input string whose characters are to checked
charactersString - the input array of characters
Returns:
true if any of the characters in the character array are found in the String, false otherwise
Since:
5.0

appendContentHTMLString

public void appendContentHTMLString(String aString)
Appends aString to the receiver's content. Special HTML characters -- "<", ">", "&", and double quote -- are escaped so that the browser does not interpret them.

Should not be called if data has been added to the WOMessage's content using either setContent(NSData aData) or appendContent(NSData aData).

Parameters:
aString - an HTML string
Since:
5.0

appendContentHTMLAttributeValue

public void appendContentHTMLAttributeValue(String aString)
Appends the HTML attribute value passed in as aString to the HTTP content. Special HTML characters -- "<", ">", "&",\t,\n,\r, and double quote are escaped so that the browser does not interpret them.

Should not be called if data has been added to the WOMessage's content using either setContent(NSData aData) or appendContent(NSData aData).

Parameters:
aString - an HTML attribute value to be appended to the message content
Since:
5.0

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.

Overrides:
toString in class Object
Returns:
String representation of the receiver
Since:
5.0

addCookie

public void addCookie(WOCookie aCookie)
A convenience method that adds the specified WOCookie object to the WOMessage.

Parameters:
aCookie - the WOCookie object that is to be added
Since:
5.0
See Also:
WOMessage.cookies(), WOMessage.removeCookie(WOCookie aCookie), WOCookie

removeCookie

public void removeCookie(WOCookie aCookie)
A convenience method that removes the specified WOCookie object from the WOMessage.

Parameters:
aCookie - the WOCookie object to remove
See Also:
WOMessage.addCookie(WOCookie aCookie), WOMessage.cookies(), WOCookie

cookies

public NSArray cookies()
A convenience method that returns an array of WOCookie objects to be included in the message, usually a WOResponse.

Returns:
NSArray of WOCookie objects to be included in the message
Since:
5.0
See Also:
WOMessage.addCookie(WOCookie aCookie), WOMessage.removeCookie(WOCookie aCookie), WOCookie

stringByEscapingHTMLString

public static String stringByEscapingHTMLString(String aString)
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. This method is used 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.

Parameters:
aString - String on which conversion is to be performed
Returns:
a new String with certain characters escaped out or if escaping is not required, returns the original String
Since:
5.0

stringByEscapingHTMLAttributeValue

public static String stringByEscapingHTMLAttributeValue(String aString)
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. This method is used to escape strings which will appear as attribute values of a tag. The escaped characters are: "<", ">", "&",\t,\n,\r, and double quote.

Parameters:
aString - String on which conversion is to be performed
Returns:
a new String with certain characters escaped out or If escaping is not required, returns the original String
Since:
5.0

equals

public boolean equals(Object aMessage)
Returns true if the supplied Object is a WOMessage, or a subclass, whose headers and content equal those of the receiver.

Overrides:
equals in class Object
Parameters:
aMessage - the object to be compared
Returns:
true if the supplied Object is a WOMessage or subclass whose headers and content equal those of the receiver
Since:
5.0

contentAsDOMDocument

public Document contentAsDOMDocument()
                              throws WODOMParserException
Returns the content of the receiver as a DOM document object.

Returns:
the content of the receiver as a DOM document object
Throws:
WODOMParserException - when DOM parser throws an exception
Since:
5.0
See Also:
WOMessage.appendContentDOMDocumentFragment(org.w3c.dom.DocumentFragment aDocumentFragment), WOMessage.setContentDOMDocument(org.w3c.dom.Document aDocument)

appendContentDOMDocumentFragment

public void appendContentDOMDocumentFragment(DocumentFragment aDocumentFragment)
Converts the supplied DOM document fragment to an XML string and appends it to the message's contents.

Should not be called if data has been added to the WOMessage's content using either setContent(NSData aData) or appendContent(NSData aData).

Parameters:
aDocumentFragment - the DOM document fragment to be converted
Since:
5.0
See Also:
WOMessage.contentAsDOMDocument(), WOMessage.setContentDOMDocument(org.w3c.dom.Document aDocument), WOMessage

setContentDOMDocument

public void setContentDOMDocument(Document aDocument)
Sets the XML content of the response to the DOM document aDocument.

Parameters:
aDocument - a DOM document
Since:
5.0
See Also:
WOMessage.appendContentDOMDocumentFragment(org.w3c.dom.DocumentFragment aDocumentFragment), WOMessage.contentAsDOMDocument()

canAccessFieldsDirectly

public static boolean canAccessFieldsDirectly()
WOMessage's implementation of this static method returns true, indicating that key-value coding is allowed to access fields in this object if an appropriate method isn't present.

Returns:
true in all cases
Since:
5.0

storePageInBacktrackCache

public boolean storePageInBacktrackCache()
For WOAjaxHandlerRequests, this defaults to false.

Since:
5.4

setStorePageInBacktrackCache

public void setStorePageInBacktrackCache(boolean value)
For WOAjaxHandlerRequests, the default is false.

Since:
5.4

valueForKey

public Object valueForKey(String key)
Description copied from interface: NSKeyValueCoding
Retrieves the value of the property named by key.

The default implementation provided by NSKeyValueCoding.DefaultImplementation works as follows:

  1. Searches for a public accessor method based on key. For example, with a key of "lastName", the method looks for a method named getLastName, lastName, or isLastName.
  2. If a public accessor method is not found, searches for a private accessor method based on key (a method preceded by an underbar). For example, with a key of "lastName", the method looks for a method named _getLastName, _lastName, or _isLastName
  3. If an accessor method is not found and the static method canAccessFieldsDirectly returns true, the method searches for a field based on key and returns its value directly. For the key "lastName", this would be _lastName, _isLastName, lastName, or isLastName.
  4. If neither an accessor method nor a field is found, the method invokes handleQueryWithUnboundKey (defined in NSKeyValueCoding.ErrorHandling).

Note: The default implementations have significant performance optimizations. To benefit from them, implement NSKeyValueCoding on a custom class as shown above by using the methods in NSKeyValueCoding.DefaultImplementation, or if your class inherits from an WebObjects class that implements NSKeyValueCoding, do not override the inherited implementation. Using a custom implementation incurs significant performance penalties.

Specified by:
valueForKey in interface NSKeyValueCoding
Parameters:
key - identifies the property to retrieve
Returns:
the value of the property identified by key. Depending on the object you invoke this method upon, null may be replaced with NullValue
See Also:
NSKeyValueCoding.NullValue, NSKeyValueCoding.takeValueForKey(java.lang.Object, java.lang.String), NSKeyValueCoding.DefaultImplementation, NSKeyValueCoding.ErrorHandling, NSKeyValueCoding.ErrorHandling.handleQueryWithUnboundKey(java.lang.String)

takeValueForKey

public void takeValueForKey(Object value,
                            String key)
Description copied from interface: NSKeyValueCoding
Sets the value for the property identified by key to value.

The default implementation provided by NSKeyValueCoding.DefaultImplementation works as follows:

  1. Searches for a public accessor method of the form setKey, and invokes it if there is one.
  2. If a public accessor method is not found, searches for a private accessor method of the form _setKey, and invokes it if there is one.
  3. If an accessor method is not found and the static method canAccessFieldsDirectly returns true, searches for a field based on key and sets its value directly. For the key "lastName", this would be _lastName, _isLastName, lastName, or isLastName.
  4. If the type of the value argument is not compatible with the underlying field or method parameter, the default implementation will make an effort to convert between different Java numeric types (Integer, Double, BigDecimal, etc) as well as between Boolean and Number (true = 1, false = 0). If any other conversion would be necessary, an exception is thrown.
  5. If neither an accessor method nor a field is found, it is an error condition. It invokes handleTakeValueForUnboundKey if the object implements NSKeyValueCoding.ErrorHandling or throws NSKeyValueCoding.UnknownKeyException if the object does not.

Note: : The default implementations have significant performance optimizations. To benefit from them, implement NSKeyValueCoding on a custom class as shown above by using the methods in NSKeyValueCoding. DefaultImplementation, or if your class inherits from an WebObjects class that implements NSKeyValueCoding, do not override the inherited implementation. Using a custom implementation incurs significant performance penalties.

Specified by:
takeValueForKey in interface NSKeyValueCoding
Parameters:
value - the new value for the property named by key
key - identifies the property to change
See Also:
NSKeyValueCoding.NullValue, NSKeyValueCoding.valueForKey, NSKeyValueCoding.DefaultImplementation, NSKeyValueCoding.ErrorHandling, NSKeyValueCoding.ErrorHandling.handleTakeValueForUnboundKey(java.lang.Object, java.lang.String)

handleQueryWithUnboundKey

public Object handleQueryWithUnboundKey(String key)
Description copied from interface: NSKeyValueCoding.ErrorHandling
Invoked from valueForKey when it finds no property binding for key. The default implementation throws an NSKeyValueCoding.UnknownKeyException, with the target object(TargetObjectUserInfoKey) and key(UnknownUserInfokey) in the user info. An NSKeyValueCoding.ErrorHandling class can override this method to handle the query in some other way. The method can return a value, in which case that value is returned by the corresponding valueForKey invocation.

Specified by:
handleQueryWithUnboundKey in interface NSKeyValueCoding.ErrorHandling
Parameters:
key - the property name which generated this error
Returns:
any Object or null that the custom implementation desires. The default implementation throws an exception instead.
See Also:
NSKeyValueCoding.valueForKey, NSKeyValueCoding.UnknownKeyException, NSKeyValueCoding.DefaultImplementation

handleTakeValueForUnboundKey

public void handleTakeValueForUnboundKey(Object value,
                                         String key)
Description copied from interface: NSKeyValueCoding.ErrorHandling
Invoked from takeValueForKey when it finds no property binding for key. The default implementation throws an NSKeyValueCoding.UnknownKeyException, with the target object(TargetObjectUserInfoKey) and key(UnknownUserInfoKey) in the user info dictionary of the exception. An NSKeyValueCoding.ErrorHandling class can override this method to handle the error in some other way.

Specified by:
handleTakeValueForUnboundKey in interface NSKeyValueCoding.ErrorHandling
Parameters:
value - the new value which could not be set
key - the name of the property which generated this error
See Also:
NSKeyValueCoding.takeValueForKey, NSKeyValueCoding.UnknownKeyException, NSKeyValueCoding.DefaultImplementation

unableToSetNullForKey

public void unableToSetNullForKey(String key)
Description copied from interface: NSKeyValueCoding.ErrorHandling
Invoked from takeValueForKey when it is given a null value for a scalar property (such as an int or a float). The default implementation throws an IllegalArgumentException. You might want to implement the method (or override the inherited implementation) to handle the request in some other way, such as by substituting new Integer(0) or a sentinel value and invoking takeValueForKey again.

Specified by:
unableToSetNullForKey in interface NSKeyValueCoding.ErrorHandling
Parameters:
key - the name of the property which generated this error
See Also:
NSKeyValueCoding.takeValueForKey, NSKeyValueCoding.DefaultImplementation

valueForKeyPath

public Object valueForKeyPath(String keyPath)
Description copied from interface: NSKeyValueCodingAdditions
Retrieves the value of a property of the object at the end of the key path (a key path is a string of the form "key1.key2"). A key path has the form relationship.property (with one or more relationships); for example "movieRole.roleName" or "movieRole.talent.lastName". The default implementation of this method (provided by NSKeyValueCodingAdditions.DefaultImplementation) gets the destination object for each relationship using valueForKey, and returns the result of a valueForKey message to the final object.

Specified by:
valueForKeyPath in interface NSKeyValueCodingAdditions
Parameters:
keyPath - the keypath to evaluate
Returns:
the value for the derived property identified by keyPath
See Also:
NSKeyValueCoding.valueForKey(java.lang.String), NSKeyValueCodingAdditions.takeValueForKeyPath(java.lang.Object, java.lang.String), NSKeyValueCodingAdditions.DefaultImplementation

takeValueForKeyPath

public void takeValueForKeyPath(Object value,
                                String keyPath)
Description copied from interface: NSKeyValueCodingAdditions
Sets the value for the property identified by keyPath to value. A key path has the form relationship.property (with one or more relationships); for example "movieRole.roleName" or "movieRole.talent.lastName". The default implementation of this method (provided by NSKeyValueCodingAdditions.DefaultImplementation) gets the destination object for each relationship using valueForKey, and sends the final object a takeValueForKey message with value and property.

Specified by:
takeValueForKeyPath in interface NSKeyValueCodingAdditions
Parameters:
value - the property identified by keyPath is set to this
keyPath - identifies the property of an object
See Also:
NSKeyValueCoding.takeValueForKey(java.lang.Object, java.lang.String), NSKeyValueCodingAdditions.valueForKeyPath(java.lang.String), NSKeyValueCodingAdditions.DefaultImplementation

Last updated June 2008

Copyright © 2000-2008 Apple Inc.