---+ Package ==

%TOC%
---+!! package TWiki::Engine

The engine class is a singleton that implements details about TWiki's
execution mode. This is the base class and implements basic behavior.

Each engine should inherits from this and overload methods necessary
to achieve correct behavior.


---++ ClassMethod *statusText* <tt>($code) -> $text</tt>

Given an HTTP status code (three digit number), returns
default text associated with it.



---++ ObjectMethod *CRLF* <tt>() -> $crfl</tt>

Utility constant. Defined as sub thus can be used from
children objects.



---++ ClasstMethod new() -> $engine

Constructs an engine object.


---++ ObjectMethod *run* <tt>(@params)</tt>

Start point to TWiki Runtime Engines. Any params will be passed to 
TWiki::UI::handle_request().



---++ ObjectMethod *prepareRequest* <tt>($req,...)</tt>

Abstract method, must be defined by inherited classes.
   * =$req= - TWiki::Request object to populate
   * =...= - this method also receives any parameters passed to =run()= 
     by engine, and should perform specific initialization tasks.



---++ ObjectMethod *prepareConnection* <tt>($req)</tt>

Abstract method, must be defined by inherited classes.
   * =$req= - TWiki::Request object to populate

Should fill remoteAddr, remoteUser, method and secure fields
of =$req= object.



---++ ObjectMethod *prepareQueryParameters* <tt>($req,$query_string)</tt>

Should fill $req's query parameters field.

This method populates $req as it should if given $query_string parameter.
Subclasses may redefine this method and call SUPER with query string obtained.



---++ ObjectMethod *prepareHeaders* <tt>($req)</tt>

Abstract method, must be defined by inherited classes.
   * =$req= - TWiki::Request object to populate

Should fill $req's headers field.



---++ ObjectMethod *preparePath* <tt>($req)</tt>

Abstract method, must be defined by inherited classes.
   * =$req= - TWiki::Request object to populate

Should fill $req's uri and pathInfo fields.



---++ ObjectMethod *prepareCookies* <tt>($req)</tt>

   * =$req= - TWiki::Request object to populate

Should fill $req's cookie field. This method take cookie data from
previously populated headers field and initializes from it. Maybe 
doesn't need to overload in children classes.



---++ ObjectMethod *prepareBody* <tt>($req)</tt>

Abstract method, must be defined by inherited classes.
   * =$req= - TWiki::Request object to populate

Should perform any initialization tasks related to body processing.



---++ ObjectMethod *prepareBodyParameters* <tt>($req)</tt>

Abstract method, must be defined by inherited classes.
   * =$req= - TWiki::Request object to populate

Should fill $req's body parameters.



---++ ObjectMethod *prepareUploads* <tt>($req)</tt>

Abstract method, must be defined by inherited classes.
   * =$req= - TWiki::Request object to populate

Should fill $req's uploads field. Its a hashref whose keys are
parameter names and values TWiki::Request::Upload objects.



---++ ObjectMethod *prepareParameters* <tt>($req)</tt>
   
   * =$req= - TWiki::Request object to populate

Should fill $req's parameters field by merging query and body parameters.

Maybe doesn't need to be redefined in children.



---++ ObjectMethod *finalizeUploads* <tt>($res,$req)</tt>

Abstract method, must be defined by inherited classes.
   * =$res= - TWiki::Response object to get data from
   * =$req= - TWiki::Request object to get data from

Should delete any temp files created in preparation phase.



---++ ObjectMethod *finalizeError* <tt>($res)</tt>

Called if some engine especific error happens.

   * =$res= - TWiki::Response object to get data from



---++ ObjectMethod *finalizeHeaders* <tt>($res,$req)</tt>

Base method, must be redefined by inherited classes. For convenience
this method deals with HEAD requests related stuff. Children classes
should call SUPER.
   * =$res= - TWiki::Response object to get data from
   * =$req= - TWiki::Request object to get data from

Should call finalizeCookies and then send $res' headers to client.



---++ ObjectMethod *finalizeCookies* <tt>($res)</tt>

   * =$res= - TWiki::Response object to both get data from and populate

Should populate $res' headers field with cookies, if any.



---++ ObjectMethod *finalizeBody* <tt>($res)</tt>

   * =$res= - TWiki::Response object to get data from

Should send $res' body to client. This method calls =write()=
as needed, sou engines should redefine that method insted of this one.



---++ ObjectMethod *prepareWrite* <tt>($res)</tt>

Abstract method, must be defined by inherited classes.
   * =$res= - TWiki::Response object to get data from

Shold perform any task needed before writing.
That's ok if none needed ;-)



---++ ObjectMethod *write* <tt>($buffer)</tt>

Abstract method, must be defined by inherited classes.
   * =$buffer= - chunk of data to be sent

Should send $buffer to client.


