Wt::WResource Class Reference

An object which can be rendered in the HTTP protocol. More...

#include <Wt/WResource>

Inheritance diagram for Wt::WResource:

Inheritance graph
[legend]

List of all members.

Public Member Functions

 WResource (WObject *parent=0)
 Create a new resource.
 ~WResource ()
 Destroy the resource.
void suggestFileName (const std::string &name)
 Suggest a filename to the user for the data streamed by this resource.
const std::string generateUrl () const
 Generate an URL for this resource.
Signal< void > & dataChanged ()
 Emit this signal if the data presented in this resource has changed.
const std::string & suggestedFileName () const
 Returns the suggested file name.
void write (std::ostream &out, const Http::ParameterMap &parameters=Http::ParameterMap(), const Http::UploadedFileMap &files=Http::UploadedFileMap())
 Stream the resource to a stream.

Protected Member Functions

void beingDeleted ()
 Prepare the resource for deletion.
virtual void handleRequest (const Http::Request &request, Http::Response &response)=0
 Handle a request.


Detailed Description

An object which can be rendered in the HTTP protocol.

Usage

Besides the main page, other objects may be rendered as additional resources, for example documents or images. Classes such as WAnchor or WImage can use a resource instead of a URL to provide their contents. Whenever the resource has changed, you can emit the dataChanged() signal to make those that refer to the resource aware that they should be updated.

You can help the browser to start a suitable helper application to handle the downloaded resource, or suggest to the user a suitable filename for saving the resource, by setting an appropriate file name using suggestFileName().

To serve resources that you create on the fly, you need to specialize this class an implement handleRequest().

Example for a custom resource implementation:

 class MyResource : public Wt::WResource
 {
 public:
   MyResource(Wt::WObject *parent = 0)
     : Wt::WResource(parent)
   {
     suggestFileName("data.txt");
   }

   ~MyResource() {
     beingDeleted(); // see "Concurrency issues" below.
   }

 protected:
   void handleRequest(const Wt::Http::Request& request,
                      const Wt::Http::Response& response) {
     response.setMimeType("plain/text");
     response.out() << "I am a text file." << std::endl;
   }
 };

Concurrency issues

Because of the nature of the web, a resource may be requested one time or multiple times at the discretion of the browser, and therefore your resource should in general not have any side-effects except for what is needed to render its own contents. Unlike event notifications to a Wt application, resource requests are not serialized, but are handled concurrently. You need to grab the application lock if you want to access or modify other widget state from within the resource. When deleting a resource, any pending request is cancelled first. For this mechanism to work you need to specialize the destructor and call beingDeleted(). This method may safely be called multiple times (i.e. from within each destructor in the hierachy).

Continuations for asynchronous I/O

With respect to I/O, the current strategy is to cache the whole response first in a buffer and use async I/O to push the data to the client, in order to free the thread while waiting for I/O on a possibly slow link. You do not necessarily have to provide all output at once, instead you can obtain a Http::ResponseContinuation object for a response, construct the response piecewise. A new request() will be made to continue the response.

Example for a custom resource implementation using continuations:

 class MyResource : public Wt::WResource
 {
 public:
   MyResource(int iterations, Wt::WObject *parent = 0)
     : Wt::WResource(parent)
     : iterations_(iterations)
   {
     suggestFileName("data.txt");
   }

   ~MyResource() {
     beingDeleted();
   }

 protected:
   void handleRequest(const Wt::Http::Request& request,
                      const Wt::Http::Response& response) {
     // see if this request is for a continuation:
     Wt::Http::ResponseContinuation *continuation = request.continuation();

     // calculate the current start
     int iteration = continuation ? boost::any_cast<int>(continuation->data()) : 0;
     if (iteration == 0)
       response.setMimeType("plain/text");

     int last = std::min(iterations_, iteration + 100);
     for (int i = iteration; i < last; ++i)
       response.out() << "Data item " << i << std::endl;

     // if we have not yet finished, create a continuation to serve more
     if (last < iterations_)
       continuation = response.createContinuation();
       // remember what to do next
       continuation->setData(last);
     }
   }

 private:
   int iterations_;
 };

See also:
WAnchor, WImage

Constructor & Destructor Documentation

Wt::WResource::~WResource (  ) 

Destroy the resource.

When specializing a resource, you MUST call beingDeleted() from within the specialized destructor, in order to stop any further requests to the resource.


Member Function Documentation

void Wt::WResource::suggestFileName ( const std::string &  name  ) 

Suggest a filename to the user for the data streamed by this resource.

For resources, intended to be downloaded by the user, suggest a name used for saving. The filename extension may also help the browser to identify the correct program for opening the resource.

const std::string Wt::WResource::generateUrl (  )  const

Generate an URL for this resource.

Generates a new url that refers to this resource. The url is unique to assure that it is not cached by the web browser, and can thus be used to refer to a new "version" of the resource, which can be indicated by emitting the dataChanged() signal.

Signal<void>& Wt::WResource::dataChanged (  )  [inline]

Emit this signal if the data presented in this resource has changed.

Widgets that reference the resource (such as anchors and images) will make sure the new data is rendered.

const std::string& Wt::WResource::suggestedFileName (  )  const [inline]

Returns the suggested file name.

See also:
suggestFileName();

void Wt::WResource::write ( std::ostream &  out,
const Http::ParameterMap parameters = Http::ParameterMap(),
const Http::UploadedFileMap files = Http::UploadedFileMap() 
)

Stream the resource to a stream.

This is a convenience method to serialize to a stream (for example a file stream).

void Wt::WResource::beingDeleted (  )  [protected]

Prepare the resource for deletion.

When specializing a resource, you MUST call beingDeleted() from within the specialized destructor, in order to stop any further requests to the resource.

virtual void Wt::WResource::handleRequest ( const Http::Request request,
Http::Response response 
) [protected, pure virtual]

Handle a request.

Reimplement this method so that a proper response is generated for the given request. From the request object you can access request parameters and whether the request is a continuation request. In the response object, you should set the mime type and stream the output data.

A request may also concern a continuation, indicated in Http::Request::continuation(), in which case the next part for a previously created continuation should be served.

While handling a request, which may happen at any time together with event handling, the library makes sure that the resource is not being concurrently deleted, but multiple requests may happend simultaneously for a single resource.

Implemented in Wt::Ext::DataStore, Wt::WFileResource, Wt::WMemoryResource, and Wt::WSvgImage.


Generated on Mon Mar 9 08:27:51 2009 for Wt by doxygen 1.5.6