Wt: Wt::WResource Class Reference

Wt 4.10.4

Loading...
Searching...
No Matches
Public Member Functions | Protected Member Functions | List of all members
Wt::WResource Class Referenceabstract

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

`#include <Wt/WResource.h>`

Inheritance diagram for Wt::WResource:
[legend]

## Public Member Functions
| WResource ()
| Creates a new resource.
| ~WResource ()
| Destroys the resource.
void | suggestFileName (const Wt::WString &name, ContentDisposition disposition=ContentDisposition::Attachment)
| Suggests a filename to the user for the data streamed by this resource.
const Wt::WString & | suggestedFileName () const
| Returns the suggested file name.
void | setDispositionType (ContentDisposition cd)
| Configures the Content-Disposition header.
ContentDisposition | dispositionType () const
| Returns the currently configured content disposition.
void | setChanged ()
| Generates a new URL for this resource and emits the changed signal.
void | setInvalidAfterChanged (bool enabled)
| Return "page not found" for prior resource URLs after change.
bool | invalidAfterChanged () const
| Should "page not found" be returned for outdated resource URLs.
void | setInternalPath (const std::string &path)
| Sets an internal path for this resource.
std::string | internalPath () const
| Returns the internal path.
const std::string & | generateUrl ()
| Generates an URL for this resource.
const std::string & | url () const
| Returns the current URL for this resource.
Signal & | dataChanged ()
| Signal emitted when the data presented in this resource has changed.
void | setUploadProgress (bool enabled)
| Indicate interest in upload progress.
Signal< ::uint64_t, ::uint64_t > & | dataReceived ()
| Signal emitted when data has been received for this resource.
void | write (std::ostream &out, const Http::ParameterMap &parameters=Http::ParameterMap(), const Http::UploadedFileMap &files=Http::UploadedFileMap())
| Stream the resource to a stream.
virtual void | handleRequest (const Http::Request &request, Http::Response &response)=0
| Handles a request.
virtual void | handleAbort (const Http::Request &request)
| Handles a continued request being aborted.
void | haveMoreData ()
| Indicate that more data is available.
void | setTakesUpdateLock (bool enabled)
| Set whether this resource takes the WApplication's update lock.
bool | takesUpdateLock () const
| Returns whether this resources takes the WApplication's update lock.
Public Member Functions inherited from Wt::WObject
void | addChild (std::unique_ptr< WObject > child)
| Add a child WObject whose lifetime is determined by this WObject.
template<typename Child >
Child * | addChild (std::unique_ptr< Child > child)
| Add a child WObject, returning a raw pointer.
std::unique_ptr< WObject > | removeChild (WObject *child)
| Remove a child WObject, so its lifetime is no longer determined by this WObject.
template<typename Child >
std::unique_ptr< Child > | removeChild (Child *child)
| Remove a child WObject, so its lifetime is no longer determined by this WObject.
virtual const std::string | id () const
| Returns the (unique) identifier for this object.
virtual void | setObjectName (const std::string &name)
| Sets an object name.
virtual std::string | objectName () const
| Returns the object name.
void | resetLearnedSlots ()
| Resets learned stateless slot implementations.
template<class T >
void | resetLearnedSlot (void(T::*method)())
| Resets a learned stateless slot implementation.
template<class T >
WStatelessSlot * | implementStateless (void(T::*method)())
| Declares a slot to be stateless and learn client-side behaviour on first invocation.
template<class T >
WStatelessSlot * | implementStateless (void(T::*method)(), void(T::*undoMethod)())
| Declares a slot to be stateless and learn client-side behaviour in advance.
void | isNotStateless ()
| Marks the current function as not stateless.
template<class T >
WStatelessSlot * | implementJavaScript (void(T::*method)(), const std::string &jsCode)
| Provides a JavaScript implementation for a method.
Public Member Functions inherited from Wt::Core::observable
| observable () noexcept
| Default constructor.
virtual | ~observable ()
| Destructor.
template<typename... Args, typename C >
auto | bindSafe (void(C::*method)(Args...)) noexcept
| Protects a method call against object destruction.
template<typename... Args, typename C >
auto | bindSafe (void(C::*method)(Args...) const) const noexcept
| Protects a const method call against object destruction.
template<typename Function >
auto | bindSafe (const Function &function) noexcept
| Protects a function against object destruction.

## Protected Member Functions
void | beingDeleted ()
| Prepares the resource for deletion.
Protected Member Functions inherited from Wt::WObject
virtual WStatelessSlot * | getStateless (Method method)
| On-demand stateless slot implementation.

## Additional Inherited Members
Public Types inherited from Wt::WObject
typedef void(WObject::*) | Method()
| Typedef for a WObject method without arguments.
Static Public Member Functions inherited from Wt::WObject

## 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 should call the setChanged() method. setChanged() will make sure that the browser will use a new version of the resource by generating a new URL, and emits the dataChanged() signal to make those that refer to the resource aware that they should update their references to the new URL.

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 and implement handleRequest().

Example for a custom resource implementation:

class MyResource : public Wt::WResource
{
public:
MyResource()
{
suggestFileName("data.txt");
}
~MyResource() {
beingDeleted(); // see "Concurrency issues" below.
}
void handleRequest(const Wt::Http::Request& request,
Wt::Http::Response& response) {
response.setMimeType("plain/text");
response.out() << "I am a text file." << std::endl;
}
};
Wt::Http::Request
A resource request.
Definition Request.h:131
Wt::Http::Response
A resource response.
Definition Response.h:42
Wt::Http::Response::setMimeType
void setMimeType(const std::string &mimeType)
Set the content mime type.
Wt::Http::Response::out
std::ostream & out()
Returns the stream for getting the response output.
Wt::WResource
An object which can be rendered in the HTTP protocol.
Definition WResource.h:178
Wt::WResource::beingDeleted
void beingDeleted()
Prepares the resource for deletion.
Wt::WResource::handleRequest
virtual void handleRequest(const Http::Request &request, Http::Response &response)=0
Handles a request.
Wt::WResource::suggestFileName
void suggestFileName(const Wt::WString &name, ContentDisposition disposition=ContentDisposition::Attachment)
Suggests a filename to the user for the data streamed by this resource.

### 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. You can enable takesUpdateLock() to let WResource do that for you. 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)
: iterations_(iterations)
{
suggestFileName("data.txt");
}
~MyResource() {
beingDeleted();
}
void handleRequest(const Wt::Http::Request& request,
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 ? Wt::cpp17::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_;
};
Wt::Http::Request::continuation
ResponseContinuation * continuation() const
Returns a continuation object.
Definition Request.h:250
Wt::Http::ResponseContinuation
A resource response continuation object.
Definition ResponseContinuation.h:52
Wt::Http::ResponseContinuation::setData
void setData(const cpp17::any &data)
Set data associated with the continuation.
Wt::Http::ResponseContinuation::data
cpp17::any data()
Return data associated with the continuation.
Definition ResponseContinuation.h:67
Wt::Http::Response::createContinuation
ResponseContinuation * createContinuation()
Create a continuation object for this response.

### Global and private resources

By default, a resource is private to an application: access to it is protected by same secret session Id that protects any other access to the application.

You can also deploy static resources, which are global, using WServer::addResource().

### Monitoring upload progress

A resource may also handle the uploading of files (in fact, WFileUpload uses a WResource to do exactly that) or transmission of other large bodies of data being POST'ed or PUT to the resource URL. For these requests, it may be convenient to enable upload progress monitoring using setUploadProgress(), which allows you to be notified of data being received.

See also
  WAnchor, WImage

## Constructor & Destructor Documentation

## ◆ ~WResource()

Wt::WResource::~WResource | ( |  | ) |

Destroys 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, unless it is guaranteed that no requests will arrive for this resource when it is being deleted, e.g. if the server is already stopped.

## Member Function Documentation

## ◆ beingDeleted()

void Wt::WResource::beingDeleted | ( |  | ) |
| protected

Prepares 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.

## ◆ dataChanged()

Signal & Wt::WResource::dataChanged | ( |  | ) |

Signal emitted when 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.

It is better to call setChanged() than to emit this signal. setChanged generates a new URL for this resource to avoid caching problems and then emits this signal.

## ◆ dataReceived()

Signal< ::uint64_t, ::uint64_t > & Wt::WResource::dataReceived | ( |  | ) |

Signal emitted when data has been received for this resource.

When this signal is emitted, you have the update lock to modify the application. Because there is however no corresponding request from the browser, any update to the user interface is not immediately reflected in the client. To update the client interface, you need to use a WTimer or enable server-push.

The first argument is the number of bytes received so far, and the second argument is the total number of bytes.

See also
  setUploadProgress()

## ◆ dispositionType()

ContentDisposition Wt::WResource::dispositionType | ( |  | ) | const

Returns the currently configured content disposition.

See also
  setDispositionType()

## ◆ generateUrl()

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

Generates 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.

The old urls are not invalidated by calling this method, unless you enable setInvalidAfterChanged().

## ◆ handleAbort()

virtual void Wt::WResource::handleAbort | ( | const Http::Request & | request | ) |
| virtual

Handles a continued request being aborted.

This function is only applicable to a request for which a response continuation was created, and indicates that the client has been closed (or the resource is being deleted) before the response was completed. This function may be reimplemented so that you can close any resources associated with the response continuation.

The base implementation is empty.

Note that because this function could be called from within the destructor, you should not forget to call beingDeleted() from the specialized destructor of your resource.

## ◆ handleRequest()

virtual void Wt::WResource::handleRequest | ( | const Http::Request & | request,
|  | Http::Response & | response )
| pure virtual

Handles 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::Auth::OAuthTokenEndpoint, Wt::Auth::OidcUserInfoEndpoint, Wt::WFileResource, Wt::WMemoryResource, Wt::WPdfImage, Wt::WRasterImage, and Wt::WSvgImage.

## ◆ haveMoreData()

void Wt::WResource::haveMoreData | ( |  | ) |

Indicate that more data is available.

In some occasions, data may be requested for a resource which is currently not yet available. Then you can suspend the response using a continuation which you let wait for more data.

Using this method you can indicate that more data is available. This will resume all responses that are currently waiting for more data.

If no responses are currently waiting for data, then this method has no effect.

See also
  ResponseContinuation::waitForMoreData()

## ◆ internalPath()

std::string Wt::WResource::internalPath | ( |  | ) | const

Returns the internal path.

See also
  setInternalPath().

## ◆ invalidAfterChanged()

bool Wt::WResource::invalidAfterChanged | ( |  | ) | const

Should "page not found" be returned for outdated resource URLs.

See also
  setInvalidAfterChanged()

## ◆ setChanged()

void Wt::WResource::setChanged | ( |  | ) |

Generates a new URL for this resource and emits the changed signal.

This does not work when the resource is deployed at an internal path using setInternalPath().

See also
  setInvalidAfterChanged()

## ◆ setDispositionType()

void Wt::WResource::setDispositionType | ( | ContentDisposition | cd | ) |

Configures the Content-Disposition header.

The Content-Disposition header allows to instruct the browser that a resource should be shown inline or as attachment. This function enables you to set this property.

This is often used in combination with suggestFilename(). The Content-Disposition must not be None when a filename is given; if this case is encountered, None will be rendered as Attachment.

See also
  suggestFilename().

## ◆ setInternalPath()

void Wt::WResource::setInternalPath | ( | const std::string & | path | ) |

Sets an internal path for this resource.

Using this method you can deploy the resource at a fixed path. Unless you deploy using cookies for session tracking (not recommended), a session identifier will be appended to the path.

You should use internal paths that are different from internal paths handled by your application (WApplication::setInternalPath()), if you do not want a conflict between these two when the browser does not use AJAX (and thus url fragments for its internal paths).

The default value is empty. By default the URL for a resource is unspecified and a URL will be generated by the library.

For static resources the internal path is empty.

## ◆ setInvalidAfterChanged()

void Wt::WResource::setInvalidAfterChanged | ( | bool | enabled | ) |

Return "page not found" for prior resource URLs after change.

This option invalidates earlier versions of the resource url prior to the last call of setChanged() or generateUrl(). The default value is false.

This does not work when the resource is deployed at an internal path using setInternalPath().

See also
  setChanged(), generateUrl()

## ◆ setTakesUpdateLock()

void Wt::WResource::setTakesUpdateLock | ( | bool | enabled | ) |

Set whether this resource takes the WApplication's update lock.

By default, WResource does not keep the WApplication's update lock, so handleRequest() is done outside of the WApplication's event loop. This makes sure that resources don't block the event loop, and multiple requests to a WResource can be handled concurrently.

However, if necessary you can either manually grab the update lock, (see WApplication::UpdateLock) or enable this option.

Note
  This is not applicable to static resources, since static resources do not have a WApplication associated with them.

## ◆ setUploadProgress()

void Wt::WResource::setUploadProgress | ( | bool | enabled | ) |

Indicate interest in upload progress.

When supported, you can track upload progress using this signal. While data is being received, and before handleRequest() is called, progress information is indicated using dataReceived().

We envision that in the future support will depend on a combination of browser and connector. Currently only the wthttp connector provides support for this across all AJAX browsers. In the future, we are likely to implement this also using JavaScript File API features making it independent of connectors.

The default value is `false`.

## ◆ suggestedFileName()

const Wt::WString & Wt::WResource::suggestedFileName | ( |  | ) | const

Returns the suggested file name.

See also
  suggestFileName();

## ◆ suggestFileName()

void Wt::WResource::suggestFileName | ( | const Wt::WString & | name,
|  | ContentDisposition | disposition = ContentDisposition::Attachment )

Suggests 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.

The disposition type determines if the resource is intended to be opened by a plugin in the browser (Inline), or to be saved to disk (Attachment). NoDisposition is not a valid Content-Disposition when a filename is suggested; this will be rendered as Attachment.

See also
  setDispositionType().

## ◆ takesUpdateLock()

bool Wt::WResource::takesUpdateLock | ( |  | ) | const

Returns whether this resources takes the WApplication's update lock.

See also
  setTakesUpdateLock()

## ◆ url()

const std::string & Wt::WResource::url | ( |  | ) | const

Returns the current URL for this resource.

Returns the url that references this resource.

For static resources, this is the path that the resource was registered at using WServer::addResource(), including the deployment path. If the same resource is registered at multiple paths, url() will reflect the last path.

## ◆ write()

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).

Unlike when an actual request is being done, exceptions thrown from handleRequest() are not caught.