com.webobjects.appserver
Class WOMessage

java.lang.Object
  |
  +--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:

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

Inner classes inherited from class com.webobjects.foundation.NSKeyValueCoding

NSKeyValueCoding.DefaultImplementation, NSKeyValueCoding.ErrorHandling, NSKeyValueCoding.Null, NSKeyValueCoding.UnknownKeyException, NSKeyValueCoding.Utility, NSKeyValueCoding.ValueAccessor

Inner classes inherited from class 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 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 ISO8859_1 (ISO Latin 1).

Fields inherited from interface com.webobjects.foundation.NSKeyValueCoding

NullValue

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(org.w3c.dom.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(NSArray 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.
org.w3c.dom.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	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.
String	headerForKey(Object aKey) 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(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(org.w3c.dom.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	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(NSArray someStrings, String aKey) Sets an HTTP header in the receiver with field-name aKey and values someStrings.
void	setHeaders(NSDictionary 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	setUserInfo(NSDictionary aDictionary) Sets a dictionary in the WOMessage object that can contain, as a convenience, any kind of information related to the current response.
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	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

HTTP_STATUS_FORBIDDEN

public static final int HTTP_STATUS_FORBIDDEN

Integer value corresponding to the HTTP 1.1 status code for "Forbidden".

HTTP_STATUS_FOUND

public static final int HTTP_STATUS_FOUND

Integer value corresponding to the HTTP 1.1 status code for "Found".

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

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

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

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

HTTP_STATUS_OK

public static final int HTTP_STATUS_OK

Integer value corresponding to the HTTP 1.1 status code for "OK".

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

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

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

See Also:

cookies(), removeCookie(WOCookie aCookie), WOCookie

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

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.

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

See Also:

contentAsDOMDocument(), setContentDOMDocument(org.w3c.dom.Document aDocument), WOMessage

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:

content(), setContent(NSData someData)

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

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

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

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

String - the HTTP header field-name of the header being appended

See Also:

headerKeys(), headersForKey(Object aKey), setHeaders(NSArray headerList, String aKey), appendHeaders(NSArray headers, String key)

appendHeaders

public void appendHeaders(NSArray 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:

headerKeys(), headersForKey(Object aKey), setHeaders(NSArray headerList, String aKey)

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

clone

public Object clone()

Overrides:

clone in class Object

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:

contentString(), setContent(NSData someData), setContentEncoding(String anEncoding)

contentAsDOMDocument

public org.w3c.dom.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

See Also:

appendContentDOMDocumentFragment(org.w3c.dom.DocumentFragment aDocumentFragment), setContentDOMDocument(org.w3c.dom.Document aDocument)

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(), setContent(NSData someData), setContentEncoding(String anEncoding)

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:

content(), contentEncoding()

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

See Also:

addCookie(WOCookie aCookie), removeCookie(WOCookie aCookie), WOCookie

defaultEncoding

public static String defaultEncoding()

Returns the default character encoding used to construct a new WOMessage.

The default is ISO8859_1 (ISO Latin 1). The current set of encodings supported is detailed in http://java.sun.com/j2se/1.3/docs/guide/intl/encoding.doc.html

Returns:

the default character encoding

See Also:

contentEncoding(), setDefaultEncoding(java.lang.String)

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 ISO-8859-1.

Returns:

the default URL encoding

See Also:

setDefaultURLEncoding(java.lang.String)

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

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

Following copied from interface: com.webobjects.foundation.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.

Throws:

NSKeyValueCoding.UnknownKeyException - when it finds no property binding for key

See Also:

NSKeyValueCoding.valueForKey(java.lang.String), 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

Following copied from interface: com.webobjects.foundation.NSKeyValueCoding.ErrorHandling

Parameters:

value - the new value which could not be set

key - the name of the property which generated this error

Throws:

NSKeyValueCoding.UnknownKeyException - when it finds no property binding for key

See Also:

NSKeyValueCoding.takeValueForKey(java.lang.Object, java.lang.String), NSKeyValueCoding.UnknownKeyException, NSKeyValueCoding.DefaultImplementation

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:

appendHeader(String header, String key), setHeader(String aHeader, String aKey), setHeaders(NSArray headerList, 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

See Also:

headers(), appendHeader(String header, String key), setHeader(String aString, String aKey), setHeaders(NSArray 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:

appendHeader(String header, String key), setHeader(String aHeader, 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:

appendHeader(String header, String key), setHeader(String aHeader, String aKey), setHeaders(NSArray headerList, String aKey)

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:

setHTTPVersion(String aVersion)

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:

addCookie(WOCookie aCookie), cookies(), WOCookie

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:

appendHeader(String header, String key), setHeader(String aString, String aKey)

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

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:

content(), setContent(NSData someContent), setContent(String someContent)

setContent

public void setContent(NSData someContent)

Sets the message content to someContent.

Parameters:

someContent - NSData containing the message content

See Also:

content(), setContent(char[] someContent), 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:

content(), setContent(char[] someContent), setContent(NSData someContent)

setContentDOMDocument

public void setContentDOMDocument(org.w3c.dom.Document aDocument)

Sets the XML content of the response to the DOM document aDocument.

Parameters:

aDocument - a DOM document

See Also:

appendContentDOMDocumentFragment(org.w3c.dom.DocumentFragment aDocumentFragment), contentAsDOMDocument()

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:

contentEncoding()

setDefaultEncoding

public static void setDefaultEncoding(String aStringEncoding)

Lets you specify the default character encoding to be used when constructing a new WOMessage. The current set of encodings supported is detailed in http://java.sun.com/j2se/1.3/docs/guide/intl/encoding.doc.html

Parameters:

aStringEncoding - the default character encoding

See Also:

contentEncoding(), defaultEncoding()

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 ISO-8859-1. If you need the generated URL to work in a particular language, make sure you set the encoding using this method. A good choice would be "UTF-8", which works for all languages.

Parameters:

anEncoding - String the default encoding to use

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:

httpVersion()

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:

setHeaders(NSArray someStrings, String aKey), appendHeader(String header, String key), appendHeaders(NSArray headers, String key), headerForKey(Object aKey), removeHeadersForKey(Object aKey)

setHeaders

public void setHeaders(NSArray 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:

setHeader(String aString, String aKey), appendHeader(String header, String key), appendHeaders(NSArray headers, String key), headerForKey(Object aKey), removeHeadersForKey(Object aKey)

setHeaders

public void setHeaders(NSDictionary 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), headerKeys(), headersForKey(Object aKey), setHeaders(NSArray headerList, String aKey)

setUserInfo

public void setUserInfo(NSDictionary 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:

userInfo()

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

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

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

Following copied from interface: com.webobjects.foundation.NSKeyValueCoding

Parameters:

value - the new value for the property named by key

key - identifies the property to change

Throws:

NSKeyValueCoding.UnknownKeyException - if key cannot be found on the object this method was invoked upon.

See Also:

NSKeyValueCoding.NullValue, NSKeyValueCoding.valueForKey(java.lang.String), NSKeyValueCoding.DefaultImplementation, NSKeyValueCoding.ErrorHandling, NSKeyValueCoding.ErrorHandling.handleTakeValueForUnboundKey(java.lang.Object, java.lang.String)

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

Following copied from interface: com.webobjects.foundation.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

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

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

Following copied from interface: com.webobjects.foundation.NSKeyValueCoding.ErrorHandling

Parameters:

key - the name of the property which generated this error

Throws:

IllegalArgumentException - when it is given a null value for a scalar property

See Also:

NSKeyValueCoding.takeValueForKey(Object value, String key), NSKeyValueCoding.DefaultImplementation

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:

setUserInfo(NSDictionary aDictionary), WOApplication.appendToResponse(WOResponse aResponse, WOContext aContext)

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

Following copied from interface: com.webobjects.foundation.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

Throws:

NSKeyValueCoding.UnknownKeyException - if key cannot be found on the object this method was invoked upon.

See Also:

NSKeyValueCoding.NullValue, NSKeyValueCoding.takeValueForKey(java.lang.Object, java.lang.String), NSKeyValueCoding.DefaultImplementation, NSKeyValueCoding.ErrorHandling, NSKeyValueCoding.ErrorHandling.handleQueryWithUnboundKey(java.lang.String)

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

Following copied from interface: com.webobjects.foundation.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