HTTPResponse

This class represents HTTP Response messages for the Modjs environment. It contains information on the status line to be sent back in the response (or that was sent back in the response), as well as the MIME entity that is the resultant response data and response headers, as a MimeEntity object. Primarily, this class represents a way for the Modjs script to return data to the requestor. To this end, there are many obStack related methods. These are only of use if this is _the_ response of the script. Otherwise, they don't really do much. They could, but they don't :) It can also be used to represent that data that is returned when manually requesting information from another HTTP server using a TCPConnection. In that case, the TCPConnection needs to be slurped up and passed to the HTTPResponse constructor. For the prime response, the default Content-type: is set to text/html. It can be changed easily though, of course.

To create an HTTPResponse object, the entire response text should be passed to the constructor, like so:

response = new HTTPResponse(response text blob)

Response objects will contain the following properties. They can be queried but usually should not be set directly, instead the obStack, print, setHeader, etc, methods should be used to ensure data consistency.

• statusCode: the status code of the response (such as 401, etc). For prime, this is initially set to 200 (OK) and the contents of this, when the script ends, will get sent back to the client as the status code.
• statusMsg: a brief message used to more easily describe the statusCode. In prime, this is initialized to OK, to go with the 200, but changing this has no real affect.
• prime: an indicator that this is the "prime" response, that is, the one used to respond back to the initial modjs apache request. If this is on, things like sendHeaders(), print() and obstacks are actually important.
• headersSent: an indicator that headers have been sent back for this prime request already. Therefore, new headers that are added, or old ones that get changed, will have no affect.
• obStack[]: stack of text blobs that can be written to, flushed, cleared, aborted, etc., to make handling responses that much easier. Use them! They are great! Also, refer to PHP's obstacks.
• entity: the actual MimeEntity. Don't manual write to this, please. Reading only!

The methods on the object are:

response.print(string|array of strings)

• prints the string or array of strings to the current obstack blob if there is one. Otherwise, appends it to the entity body and sends it straight out! If headers haven't been sent yet, they would be at that point! beware! Also the status line I guess? Not certain how that works...

response.addMimeData(MimeEntity|array of MimeEntitys)

• adds the given mime entities to the entity tree, as though printed (meaning, through obstacks). Content-type is not automatically changed, you have to do that beforehand! Including boundary generation (though that can be automatic, when setting to multipart content-type).

response.sendFile(File|array of Files)

• adds the contents of the given files to the body, as though printed (through obstacks, etc). Note adding a File as an attachment would need to be done through a MimeEntity containing the file, etc.

response.setHeader(name, value)
response.setHeader(MimeHeader)
response.setHeader(name, MimeValue)

• sets the given header in the top level mime entity to the given value. This is as smart as it can be. Hopefully you haven't sent headers yet! This will change the first header of the given name to the new value, or add a new header by that name. If one already exists and you don't want to overwrite it, you will need to set it in the entity itself. This is quasi-safe... but don't do anything else in there!

response.setCookie(name, value[, expiration [,domain, etc.]])

• sets the given cookie to the new value. If its a new cookie, you will need to specify the expiration and whatnot. This will generate a Set-Cookie: header in the response. Hopefully you haven't sent headers yet. If this is the prime response, this will also add the cookie/change the cookie of this name in the prime request. (maybe?)

response.sendHeaders()

• sends the current set of headers (and the status line, maybe?) out over the wire, if this is the prime response. Sets headersSent. This will mean that subsequent changes to the prime response top level entity will not ever be sent out.

response.obBegin()

• adds a new text blob to the obstack

response.obClear()

• clears the top text blob on the obstack, but leaves it there

response.obFlush()

• takes all the text of the top blob on the obstack and prints it to the lower one, or straight out. Leaves the top blob (now empty) on the stack.

response.obFinish()

• performs an obFlush() but also removes the top blob on the obstack

response.obAbort()

• performs an obClear() but also removes the top blob on the obstack