Package eu.webtoolkit.jwt

Class WResource

  • Direct Known Subclasses:
    OAuthTokenEndpoint, OidcUserInfoEndpoint, WFileResource, WMemoryResource, WPdfImage, WRasterPaintDevice, WSvgImage
    public abstract class WResource
extends WObject
    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 resource, or suggest to the user a suitable filename for saving the resource, by setting an appropriate file name using suggestFileName(String).

    To serve resources that you create on the fly, you need to specialize this class and reimplement handleRequest(WebRequest, WebResponse).

    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 JWt application, resource requests are not serialized, but are handled concurrently. Therefore you are not allowed to access or modify widget state from within the resource, unless you provide your own locking mechanism for it.
    See Also:
    WAnchor, WImage

    • Constructor Detail

      • WResource

        public WResource()
        Constructor.

    • Method Detail

      • generateUrl

        public java.lang.String generateUrl()
        Generates a URL for 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 triggering the dataChanged() signal. The old urls are not invalidated by calling this method, unless you enable setInvalidAfterChanged().

        Returns:
        the url.

      • handleRequest

        protected abstract void handleRequest​(WebRequest request,
                                      WebResponse response)
                               throws java.io.IOException
        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.

        Parameters:
        request - The request information
        response - The response object
        Throws:
        java.io.IOException

      • dataChanged

        public Signal dataChanged()
        Signal triggered 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 trigger this signal since that method generates a new URL for this resource to avoid caching problems before emitting the signal.

      • write

        public void write​(java.io.OutputStream out,
                  java.util.Map<java.lang.String,​java.lang.String[]> parameterMap,
                  java.util.Map<java.lang.String,​java.util.List<eu.webtoolkit.jwt.servlet.UploadedFile>> uploadedFiles)
           throws java.io.IOException
        Writes the resource to an output stream.

        This is a utility method that allows you to write the resource to an output stream, by using handleRequest(WebRequest, WebResponse).

        Parameters:
        out - The output stream.
        parameterMap - A map with parameters that are made available in the WebRequest.
        uploadedFiles - A list of uploaded files that are made available in the WebRequest.
        Throws:
        java.io.IOException

      • write

        public void write​(java.io.OutputStream out)
           throws java.io.IOException
        Writes the resource to an output stream.

        This is a utility method that allows you to write the resource to an output stream, by using handleRequest(WebRequest, WebResponse).

        Parameters:
        out - The output stream.
        Throws:
        java.io.IOException

      • writeToMemory

        public byte[] writeToMemory()
                     throws java.io.IOException
        Writes the resource into a byte array. This is a convenience method to write the resource into a byte array. This is especially useful if you want to convert the resource into a WMemoryResource (when overriding botResource() for instance).
        Returns:
        The byte array containing the resource data.
        Throws:
        java.io.IOException

      • suggestFileName

        public void suggestFileName​(java.lang.String name,
                            WResource.DispositionType dispositionType)
        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 (DispositionType#Inline), or to be saved to disk (DispositionType#Attachment). DispositionType#NoDisposition is not a valid Content-Disposition when a filename is suggested; this will be rendered as DispositionType#Attachment.

        See Also:
        setDispositionType(DispositionType dispositionType)

      • suggestFileName

        public void suggestFileName​(java.lang.String name)
        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 (DispositionType#Inline), or to be saved to disk (DispositionType#Attachment). DispositionType#NoDisposition is not a valid Content-Disposition when a filename is suggested; this will be rendered as DispositionType#Attachment.

        See Also:
        Calls

      • getSuggestedFileName

        public java.lang.String getSuggestedFileName()
        Returns the suggested file name.
        See Also:
        suggestFileName(String)

      • setInvalidAfterChanged

        public void setInvalidAfterChanged​(boolean 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()

      • isInvalidAfterChanged

        public boolean isInvalidAfterChanged()
        Should "page not found" be returned for outdated resource URLs
        See Also:
        #setInvalidAfterChanged()

      • setDispositionType

        public void setDispositionType​(WResource.DispositionType dispositionType)
        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(String, DispositionType). The Content-Disposition must not be DispositionType#NoDisposition when a filename is given; if this case is encountered, None will be rendered as DispositionType#Attachment.
        See Also:
        suggestFileName(String, DispositionType)

      • getUrl

        public java.lang.String getUrl()
        Returns the current URL for this resource. Returns the url that refers to this resource.

      • getInternalPath

        public java.lang.String getInternalPath()
        Returns the internal path.
        See Also:
        setInternalPath(String)

      • setInternalPath

        public void setInternalPath​(java.lang.String internalPath)
        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(String)), 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.

      • setAlternativeBotUrl

        public void setAlternativeBotUrl​(java.lang.String url)
        Sets an alternative URL, given to bots, for this resource. If url is not empty, this URL will be used instead of the regular URL when the request comes from a bot (e.g., a web crawler). As bots have their session terminated after sending a reply, the WApplication linked to it, and thus also its resources are removed. This means functionality such as continuations, handling resource or application changes are not available. Only public resources can be accessed by bots (see WServer#addResource()). Private resources (linked to the WApplication) cannot be accessed by bots. By default, this is empty.

        Note: If this is not empty, the resource will not be accessible to bots.

      • getAlternativeBotUrl

        public java.lang.String getAlternativeBotUrl()

      • setUploadProgress

        public void setUploadProgress​(boolean enabled)
        Indicate interest in upload progress. When supported, you can track upload progress using this signal. While data is being received, and before handleRequest(WebRequest request, WebResponse response) is called, progress information is indicated using dataReceived(). The default value is false.

      • setTakesUpdateLock

        public void setTakesUpdateLock​(boolean enabled)
        Set whether this resource takes the WApplication's update lock.

        By default, WResource takes the WApplication's update lock, so handleRequest() is performed in the WApplication's event loop.

        If necessary this can be disabled by setting this option to false. This will make it so that handleRequest() does not block the WApplication, and multiple handleRequest() calls can be performed concurrently.

        This option has no effect on static resources, since there is no WApplication in that case.

      • takesUpdateLock

        public boolean takesUpdateLock()
        Get whether this resource takes the WApplication's update lock
        See Also:
        setTakesUpdateLock(boolean)

      • setAllowAutoRemoval

        public void setAllowAutoRemoval​(boolean allow)
        Sets whether this resource can be automatically removed. If enabled on a public resource, the resource will be counted as an auto-removable resource. The total number of auto-removable resources is limited by the configuration option Configuration.setMaxAutoRemovablePublicResources(int). If the number of auto-removable resources exceeds this limit, the oldest auto-removable resource will be removed from the public resources. By default, this is set to false. Except for WSelfDeletingResource for which it is true.
        See Also:
        getBotResource()

      • getVersion

        public int getVersion()

      • incrementVersion

        public void incrementVersion()

      • setBotResourceId

        public void setBotResourceId​(java.lang.String id)
        Sets the bot resource ID. This id will be appended to the resource path of the bot resource. This is useful to avoid storing the same resources multiple times in memory since only one resource can be served at any given path. By default, returns #id().
        See Also:
        getBotResource(), WSelfDeletingResource

      • getBotResource

        public WResource getBotResource()
        Returns a WResource that will be made public for bot sessions. When the serve-private-resources-to-bots configuration option is set to true, this method is called before the destruction of the WApplication if this resource was exposed as a private resource for a bot session. The returned resource will then be added to the server's public resources, unless the returned value is a null. The path at which the resource will be made available will be the value of the bot-resources-path option (specified in the configuration), followed by getBotResourceId()) (separated from the path by a slash). By default, this returns null.
        See Also:
        setBotResourceId(String id), useCustomBotResourceId(), WSelfDeletingResource

      • dataReceived

        public Signal2<java.lang.Long,​java.lang.Long> 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.
        See Also:
        setUploadProgress(boolean enabled)

      • dataExceeded

        public Signal1<java.lang.Long> dataExceeded()