Passenger::Application::Session Class Reference

#include <Application.h>

Inherited by Passenger::Application::StandardSession, and Passenger::ApplicationPoolServer::RemoteSession.

List of all members.


Detailed Description

Represents the life time of a single request/response pair of a Ruby on Rails or Rack application.

Session is used to forward a single HTTP request to a Ruby on Rails/Rack application. A Session has two communication channels: one for reading data from the application, and one for writing data to the application.

In general, a session object is to be used in the following manner:

  1. Convert the HTTP request headers into a string, as expected by sendHeaders(). Then send that string by calling sendHeaders().
  2. In case of a POST of PUT request, send the HTTP request body by calling sendBodyBlock(), possibly multiple times.
  3. Shutdown the writer channel since you're now done sending data.
  4. The HTTP response can now be read through the reader channel (getStream()).
  5. When the HTTP response has been read, the session must be closed. This is done by destroying the Session object.

A usage example is shown in Application::connect().

Public Member Functions

virtual ~Session ()
 Implementing classes might throw arbitrary exceptions.
virtual void sendHeaders (const char *headers, unsigned int size)
 Send HTTP request headers to the application.
virtual void sendHeaders (const string &headers)
 Convenience shortcut for sendHeaders(const char *, unsigned int).
virtual void sendBodyBlock (const char *block, unsigned int size)
 Send a chunk of HTTP request body data to the application.
virtual int getStream () const =0
 Get the I/O stream's file descriptor.
virtual void shutdownReader ()=0
 Indicate that we don't want to read data anymore from the I/O stream.
virtual void shutdownWriter ()=0
 Indicate that we don't want to write data anymore to the I/O stream.
virtual void closeStream ()=0
 Close the I/O stream.
virtual void discardStream ()=0
 Discard the I/O stream's file descriptor, so that Session won't automatically closed it upon Session's destruction.
virtual pid_t getPid () const =0
 Get the process ID of the application instance that belongs to this session.


Member Function Documentation

virtual void Passenger::Application::Session::sendHeaders ( const char *  headers,
unsigned int  size 
) [inline, virtual]

Send HTTP request headers to the application.

The HTTP headers must be converted into CGI headers, and then encoded into a string that matches this grammar:

		   headers ::= header*
		   header ::= name NUL value NUL
		   name ::= notnull+
		   value ::= notnull+
		   notnull ::= "\x01" | "\x02" | "\x02" | ... | "\xFF"
		   NUL = "\x00"
		   

This method should be the first one to be called during the lifetime of a Session object. Otherwise strange things may happen.

Parameters:
headers The HTTP request headers, converted into CGI headers and encoded as a string, according to the description.
size The size, in bytes, of headers.
Precondition:
headers != NULL
Exceptions:
IOException The writer channel has already been closed.
SystemException Something went wrong during writing.
boost::thread_interrupted 

virtual void Passenger::Application::Session::sendHeaders ( const string &  headers  )  [inline, virtual]

Convenience shortcut for sendHeaders(const char *, unsigned int).

Parameters:
headers 
Exceptions:
IOException The writer channel has already been closed.
SystemException Something went wrong during writing.
boost::thread_interrupted 

virtual void Passenger::Application::Session::sendBodyBlock ( const char *  block,
unsigned int  size 
) [inline, virtual]

Send a chunk of HTTP request body data to the application.

You can call this method as many times as is required to transfer the entire HTTP request body.

This method should only be called after a sendHeaders(). Otherwise strange things may happen.

Parameters:
block A block of HTTP request body data to send.
size The size, in bytes, of block.
Exceptions:
IOException The writer channel has already been closed.
SystemException Something went wrong during writing.
boost::thread_interrupted 

virtual int Passenger::Application::Session::getStream (  )  const [pure virtual]

Get the I/O stream's file descriptor.

This steam is full-duplex, and will be automatically closed upon Session's destruction, unless discardStream() is called.

Precondition:
The stream has not been fully closed.

virtual void Passenger::Application::Session::shutdownReader (  )  [pure virtual]

Indicate that we don't want to read data anymore from the I/O stream.

Calling this method after closeStream() is called will have no effect.

Exceptions:
SystemException Something went wrong.
boost::thread_interrupted 

virtual void Passenger::Application::Session::shutdownWriter (  )  [pure virtual]

Indicate that we don't want to write data anymore to the I/O stream.

Calling this method after closeStream() is called will have no effect.

Exceptions:
SystemException Something went wrong.
boost::thread_interrupted 

virtual void Passenger::Application::Session::closeStream (  )  [pure virtual]

Close the I/O stream.

Exceptions:
SystemException Something went wrong.
boost::thread_interrupted 


The documentation for this class was generated from the following file:

Generated on Tue Jun 24 14:03:44 2008 for Passenger by  doxygen 1.5.5