PATH  WebObjects 4.0 Documentation > WebObjects Framework Reference



WOResponse

Inherits From:
NSObject

Conforms To: NSObject (NSObject)

Declared in: WebObjects/WOResponse.h


Class Description

A WOResponse object represents an HTTP response that an application returns to a Web server to complete a cycle of the request-response loop. The composition of a response occurs during the third and final phase of this loop, a phase marked by the propagation of the appendToResponse:inContext: message through the objects of the application. The WOApplication object first sends this message, passing in a newly-created WOResponse object as an argument. WOElement objects, which represent the dynamic and static HTML elements on a page, respond to the message by appending their HTML representation to the content of the WOResponse object. WOApplication, WOSession, and WOComponent objects can also respond to the message by adding information to the WOResponse object.

A WOResponse has two major parts: HTML content and HTTP information. The content is what is displayed in a Web browser; it can include escaped HTML, which is HTML code shown "as is," uninterpreted. The other information encapsulated by a WOResponse object is in the handling the response. This HTTP data includes headers, status codes, and version string. See the HTTP specification or HTTP documentation for descriptions of these items.

As you might expect, the methods of the WOResponse class can be divided into two groups, those that add to a response's HTML content and those that read and set HTTP information. The former group consists of methods that escape HTML (appendContentHTMLAttributeValue: and appendContentHTMLString: ) and those that don't. For images and other binary data, you can use the appendContentData: . You can obtain and set the entire content of the response with content and setContent: . The following example shows a sequence of "appendContent" messages that compose an HTTP "POST" message:

[aResponse appendContentString:@"&ltform method=\"POST\" action=\""];

[aResponse appendContentHTMLAttributeValue:[aContext url]];

[aResponse appendContentCharacter:'"'];

[aResponse.appendContentString:@"&gt"];

Most of the remaining WOResponse methods set and read the response's HTTP headers, the HTTP status code, and the HTTP 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 OPENSTEP string-constant names.

int Value OPENSTEP 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


Adopted Protocols

NSCopying
- copy
- copyWithZone:
WOActionResults
- generateResponse

Method Types

Creation
- init
Obtaining attributes
+ defaultEncoding
- content
- headerForKey:
- headerKeys
- headersForKey:
- httpVersion
- status
- userInfo
Setting attributes
+ setDefaultEncoding:
- setContent:
- setHeader:forKey:
- setHeaders:forKey:
- setHTTPVersion:
- setStatus:
- setUserInfo:
Appending response content
- appendContentBytes:length:
- appendContentCharacter:
- appendContentData:
- appendContentString:
- setContentEncoding:
- contentEncoding
Working with HTML content
- appendContentHTMLAttributeValue:
- appendContentHTMLString:
+ stringByEscapingHTMLString:
+ stringByEscapingHTMLAttributeValue:
Working with cookies
- addCookie:
- cookies
- removeCookie:

Class Methods


defaultEncoding

+ (NSStringEncoding)defaultEncoding

Returns the default character encoding used to construct a new WOResponse. By default, this encoding is NSISOLatin1. For more information, see "Content Encodings".


setDefaultEncoding:

+ (void)setDefaultEncoding: (NSStringEncoding)aStringEncoding

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


stringByEscapingHTMLString:

+ (NSString *)stringByEscapingHTMLString: (NSString *)aString

This method 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 aString is returned. Use this method to escape strings which will appear in the visible part of an HTML file (that is, not inside a tag). The escaped characters are:

& &
" "
< &lt;
> &gt;


stringByEscapingHTMLAttributeValue:

+ (NSString *)stringByEscapingHTMLAttributeValue: (NSString *)aString

This method takes astring and, if escaping is required, returns a new string with certain characters escaped out. If escaping is not required, no conversion is performed and aString is returned. Use this method to escape strings which will appear as attribute values of a tag. The escaped characters are:

& &amp;
" &quot;
\t &#9;
\n &#10;
\r &#13;
< &lt;
> &gt;


Instance Methods


addCookie:

- (void)addCookie: (WOCookie *)aCookie

Adds the specified WOCookie object to the response.

See also: - cookies , - removeCookie: , WOCookie class specification


appendContentBytes:length:

- (void)appendContentBytes: (const void *)someBytes length: (unsigned)length

Appends length number of bytes pointed to by someBytes to the HTTP response.


appendContentCharacter:

- (void)appendContentCharacter: (char)aChar

Appends a single ASCII character (aChar) to the HTTP response.

Example:

// ...

if (aFlag)

	[aResponse appendContentCharacter:'Y'];

else

	[aResponse appendContentCharacter:'N'];


appendContentData:

- (void)appendContentData: (NSData *)dataObject

Appends a data-encapsulating object (dataObject) to the HTTP response.


appendContentHTMLAttributeValue:

- (void)appendContentHTMLAttributeValue: (NSString *)aValue

Appends an HTML attribute value to the HTTP content after transforming the string aValue into an NSData object using the receiver's content encoding. Special HTML characters ("<", ">", "&", and double quote) are escaped so that the browser does not interpret them. In other words, the message

[aResponse appendContentHTMLAttributeValue:@"<B>"];

would transform the argument to "&lt;B&gt;".

See also: - setContentEncoding:


appendContentHTMLString:

- (void)appendContentHTMLString: (NSString *)aString

Appends an HTML string to the HTTP response after transforming the string aString into an NSData object using the receiver's content encoding. Special HTML characters ("<", ">", "&", and double quote) are escaped so that the browser does not interpret them. For example, "<P>" becomes "&ltP&gt".

See also: - setContentEncoding:


appendContentString:

- (void)appendContentString: (NSString *)aString

Appends a string to the content of the HTTP response. The string is transformed into an NSData object using the receiver's content encoding. The special HTML characters "<", ">", "&", and double-quote are not escaped so the browser can interpret them as HTML.


content

- (NSData *)content

Returns the HTML content of the receiver as an NSData object.

An exception is raised if you attempt to get the content when all elements of the page have not had their chance to append HTML to the response. Thus, you should invoke this method in the application object's handleRequest: method, after super's handleRequest: has been invoked. (For scripted applications, handleRequest: is implemented in Application.wos). Note that at this point in the request-handling process, the components, pages, and session have already been put to sleep, so you won't have access to any context, session, or page information. If you need such information for your response, store it somewhere--such as in WOResponse'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:inContext: method, for example.

See also: - setContent: , - setContentEncoding:


contentEncoding

- (NSStringEncoding)contentEncoding

Returns an integer representing the encoding used for the response content. See "Content Encodings" in the class description for a mapped list of supported encodings and their Objective-C names. Usually, 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 .

NSStringEncoding theEncoding = [[aContext request] formValueEncoding];

The default string encoding is ISO Latin1.

See also: - setContent: , - setContentEncoding:


cookies

- (NSArray *)cookies

Returns an array of WOCookie objects to be included in the response.

See also: - addCookie: , - removeCookie: , WOCookie class specification


generateResponse

- (WOResponse *)generateResponse

Returns a WOResponse object. WOResponse's implementation simply returns itself.

See also: - generateResponse (WOComponent)


headerForKey:

- (NSString *)headerForKey: (NSString *)aKey

Returns the HTTP header information identified by aKey. If there are multiple headers associated with the one key, only the first one is returned. Returns nil if there are no headers for the key.

See also: - setHeader:forKey:


headerKeys

- (NSArray *)headerKeys

Returns an array of string keys associated with the receiver's HTTP headers. Returns nil if there are no headers. You could easily test to see if a header is included by doing something similar to this:

NSArray *hKeys =  [aResponse headerKeys];

if ([hKeys containsObject:@"expires"]) {

	// do something

}

See also: - setHeaders:forKey:


headersForKey:

- (NSArray *)headersForKey: (NSString *)aKey

Returns all HTTP headers identified by aKey.

See also: - setHeaders:forKey:


httpVersion

- (NSString *)httpVersion

Returns the version of HTTP used for the response (for example, "HTTP/1.0").

See also: - setHTTPVersion:


init

- (id)init

Initializes a WOResponse instance. HTTP status is set to 200 (OK), client caching is enabled, and the default string encoding is made ISO Latin 1.


removeCookie:

- (void)removeCookie: (WOCookie *)aCookie

Removes the specified WOCookie object from the response.

See also: - cookies , - removeCookie: , WOCookie class specification


setContent:

- (void)setContent: (NSData *)someData

Sets the HTML content of the HTTP response to someData.

See also: - content


setContentEncoding:

- (void)setContentEncoding: (NSStringEncoding)anEncoding

Sets the encoding used for the content of the HTTP response. See "Content Encodings" in the class description for a mapped list of supported encodings and their Objective-C names. The default string encoding is ISO Latin1.

See also: - contentEncoding


setHTTPVersion:

- (void)setHTTPVersion: (NSString *)aVersion

Sets the version of HTTP used for the response (for example, "HTTP/1.0").

See also: - httpVersion


setHeader:forKey:

- (void)setHeader: (NSString *)aHeader forKey: (NSString *)aKey

Sets the HTTP header aHeader in the receiver and associates, for retrieval, the HTTP key aKey with the header. This method is commonly used to set the type of content in a response, for example:

[aResponse setHeader:@"text/html" forKey:@"content-type"];

See also: - headerForKey:


setHeaders:forKey:

- (void)setHeaders: (NSArray *)headerList forKey: (NSString *)aKey

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

See also: - headerKeys , - headersForKey:


setStatus:

- (void)setStatus: (unsigned int)anInt

Sets the HTTP status to anInt. Consult the HTTP specification or HTTP documentation for the significance of status integers.

See also: - status


setUserInfo:

- (void)setUserInfo: (NSDictionary *)aDictionary

Sets a dictionary in the WOResponse object that, as a convenience, can contain any kind of information related to the current response. Objects further down the appendToResponse:inContext: message "chain" can retrieve this information using userInfo .


status

- (unsigned int)status

Returns an integer code representing the HTTP status. Consult the HTTP specification or HTTP documentation for the significance of these status codes.

By default, the status is 200 ("OK" status).

See also: - setStatus:


userInfo

- (NSDictionary *)userInfo

Returns a dictionary that, as a convenience, can contain any kind of information related to the current response. An object further "upstream" in the appendToResponse:inContext: message "chain" can set this dictionary in the WOResponse object as a way to pass information to other objects.

See also: - setUserInfo:





Copyright © 1998, Apple Computer, Inc. All rights reserved.