Foswiki::Engine

internal package Foswiki::Engine

The engine class is a singleton that implements details about Foswiki'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 new() → $engine

Constructs an engine object.

ObjectMethod run()

Start point to Runtime Engines.

ObjectMethod prepare() → $req

Initialize a Foswiki::Request object by calling many preparation methods and returns it, or a status code in case of error.

ObjectMethod prepareConnection( $req )

Abstract method, must be defined by inherited classes.

• $req - Foswiki::Request object to populate

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

ObjectMethod prepareQueryParameters( $req, $queryString )

Should fill $req's query parameters field.

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

ObjectMethod prepareHeaders( $req )

Abstract method, must be defined by inherited classes.

• $req - Foswiki::Request object to populate

Should fill $req's headers and remoteUser fields.

ObjectMethod preparePath( $req )

Abstract method, must be defined by inherited classes.

• $req - Foswiki::Request object to populate

Should fill $req's uri and pathInfo fields.

ObjectMethod prepareCookies( $req )

• $req - Foswiki::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( $req )

Abstract method, must be defined by inherited classes.

• $req - Foswiki::Request object to populate

Should perform any initialization tasks related to body processing.

ObjectMethod prepareBodyParameters( $req )

Abstract method, must be defined by inherited classes.

• $req - Foswiki::Request object to populate

Should fill $req's body parameters.

ObjectMethod prepareUploads( $req )

Abstract method, must be defined by inherited classes.

• $req - Foswiki::Request object to populate

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

ObjectMethod finalize($res, $req)

Finalizes the request by calling many methods to send response to client and take any appropriate finalize actions, such as delete temporary files.

• $res is the Foswiki::Response object
• $req it the Foswiki::Request object.

ObjectMethod finalizeUploads( $res, $req )

Abstract method, must be defined by inherited classes.

• $res - Foswiki::Response object to get data from
• $req - Foswiki::Request object to get data from

Should delete any temp files created in preparation phase.

ObjectMethod finalizeError( $res, $req )

Called if some engine especific error happens.

• $res - Foswiki::Response object to get data from
• $req - Foswiki::Request object to get data from

ObjectMethod finalizeHeaders( $res, $req )

Base method, must be redefined by inherited classes. For convenience this method deals with HEAD requests related stuff. Children classes should call SUPER.

• $res - Foswiki::Response object to get data from
• $req - Foswiki::Request object to get data from

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

ObjectMethod finalizeCookies( $res )

• $res - Foswiki::Response object to both get data from and populate

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

ObjectMethod finalizeBody( $res, $req )

• $res - Foswiki::Response object to get data from
• $req - Foswiki::Request 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.

flush($res, $req)

Forces the response headers to be emitted if they haven't already been sent (note that this may in some circumstances result in cookies being missed) before flushing what is in the body so far.

Before headers are sent, any Content-length is removed, as a call to flush is a statement that there's more to follow, but we don't know how much at this point.

This function should be used with great care! It requires that the output headers are fully complete before it is first called. Once it has been called, the response object will refuse any modifications that would alter the header.

ObjectMethod prepareWrite( $res )

Abstract method, may be defined by inherited classes.

• $res - Foswiki::Response object to get data from

Should perform any task needed before writing. That's ok if none needed

ObjectMethod write( $buffer )

Abstract method, must be defined by inherited classes.

• $buffer - chunk of data to be sent

Should send $buffer to client.