Poco::OSP::Web

class WebServerExtensionPoint

File Information

Library: OSP/Web
Package: Web
Header: Poco/OSP/Web/WebServerExtensionPoint.h

Description

WebServerExtension handles two extensions points. To register a directory in the Webserver:

<extension point="osp.web.server.directory"
           path="URI"
           resource="dir inside bundle"
           allowSpecialization="none|owner|all"
           index="index.html"/>

To register a RequestHandlerFactory for a given server uri/set of uris:

<extension point="osp.web.server.requesthandler"
           path="URI"
           class="MyRequestHandlerFactory"
           library="MyLib"/>

Note that the extension points are automatically removed if a bundle is stopped.

The following attributes can be specified for both extension points:

  • path: The URI on the server to which the resource or handler is mapped.
  • description: User-readable description of resource or handler.
  • secure: If "true", require a secure (HTTPS) connection to access the resource.
  • realm: Specify authentication realm (together with permission).
  • permission: Specify the necessary access permission for this resource. Unless a session name is specified, HTTP Basic Authentication is used to obtain the user's user name and password, which are then checked against the specified permission using the authorization service. If the permission string is an asterisk ("*"), only the validity of the credentials is verified. If the permission string is two asterisks ("**"), then credentials are optional, but, if present, must be valid.
  • authMethods: Specifies a comma-separated list of allowed authentication methods ("basic", "session", "bearer"). If not specified the globally enabled authentication methods will be used.
  • session: Specify the name of the session used for session-based authentication instead of HTTP Basic Authentication. If specified together with a permission, the session with the specified name is obtained from the WebSessionService, and the current users's name is obtained from the session's "username" attribute, which must be a std::string.
  • csrfProtection: If "true", enable CSRF/XSRF protection for session-based authentication. Requests must contain a header (default name "X-XSRF-TOKEN", but can be set with csrfToken attribute) containing the session's CSRF token.
  • csrfTokenHeader: For CSRF/XSRF protection, specify the name of the header containing the CSRF/XSRF token. Defaults to "X-XSRF-TOKEN".
  • hidden: If "true", path is not included by WebServerDispatcher::listVirtualPaths().
  • redirectOn401: If the request would result in a 401 (Unauthorized) response due to missing authentication (see authMethods, permission and session attributes), send a redirect (302) response instead to the specified location, but only if the request is a GET request. This can be used to redirect to the login page.

The following attributes can be specified for "osp.web.server.directory":

  • resource: Specify a directory within the bundle where the HTML, image and other files are located.
  • index: Specify the name of the default document (defaults to "index.html").
  • cache: If "true", files in this directory can be cached. Defaults to "true". Set to "false" to disable caching.
  • allowSpecialization: Using the allowSpecialization attribute, a bundle can specify whether other bundles can register themselves for subdirectories of the directory specified in path. The following values are supported: none: it is impossible to map resources or request handlers to subdirectories; owner: only this bundle can map resources or request handlers to subdirectories; all: any bundle can map resources or request handlers to subdirectories.

The following attributes can be specified for "osp.web.server.requesthandler":

  • pattern: A regular expression for matching requests to the handler. If specified, no path attribute should be specified. If both the pattern and path attributes are given, path is ignored. Paths containing a pattern are not included by WebServerDispatcher::listVirtualPaths().
  • methods: A comma-separated list of HTTP request methods ("GET", "POST", etc.") supported by the handler. If not specified, all methods are passed to the handler.
  • class: The class name of the request handler factory.
  • library: The name of the shared library containing the request handler factory.
  • cors: If "true", enable CORS (Cross-Origin Resource Sharing)
  • allowOrigin: Specify the allowed origin for CORS requests. Can be "*" or empty (default) to allow all domains. If empty, the response's "Access-Control-Allow-Origin" header will be set to the value of the request's "Origin" header. If "*" or a specific domain, the response's "Access-Control-Allow-Origin" header will be set to that value.
  • allowMethods: Allowed methods for CORS requests. Defaults to the value of the methods attribute, or "*" if methods is empty.
  • allowHeaders: A comma-separated list of header names. If not empty, a "Access-Control-Allow-Headers" header will be added with the given value.
  • allowCredentials: If "true", an "Access-Control-Allow-Credentials" header with value "true" will be added to the response. Defaults to "true".
  • exactMatch: If set to "true", the request URI path must exactly match the value specified in the "path" attribute. If set to "false" (default), will also match if the path specified in the "path" attribute is a parent of the request URI path.
  • errorResponseFormat: Format of error response. Can be "html" or "json". Defaults to "html", but can be overridden by client if the request contains an "Accept" header ("application/json" or "text/html").

Inheritance

Direct Base Classes: Poco::OSP::ExtensionPoint

All Base Classes: Poco::OSP::ExtensionPoint, Poco::RefCountedObject

Member Summary

Member Functions: handleCommon, handleDirectory, handleExtension, handleRequestHandler, onBundleStopped

Inherited Functions: duplicate, handleExtension, referenceCount, release, removeExtension

Constructors

WebServerExtensionPoint

WebServerExtensionPoint(
    BundleContext::Ptr pContext,
    WebServerDispatcher * pDispatcher
);

Creates the WebServerExtension. Expects a not null pointer to the Web which must be valid during the whole life-time of the extension object

Destructor

~WebServerExtensionPoint virtual

~WebServerExtensionPoint();

Destroys the WebServerExtension.

Member Functions

handleExtension virtual

void handleExtension(
    Bundle::ConstPtr pBundle,
    Poco::XML::Element * pExtensionElem
);

handleCommon protected

void handleCommon(
    Bundle::ConstPtr pBundle,
    Poco::XML::Element * pExtensionElem,
    WebServerDispatcher::VirtualPath & vPath
);

handleDirectory protected

void handleDirectory(
    Bundle::ConstPtr pBundle,
    Poco::XML::Element * pExtensionElem
);

handleRequestHandler protected

void handleRequestHandler(
    Bundle::ConstPtr pBundle,
    Poco::XML::Element * pExtensionElem
);

onBundleStopped protected

void onBundleStopped(
    const void * pSender,
    BundleEvent & ev
);

When a bundle is stopped, all of its request handlers and mappings are automatically disabled.

Variables

EXTPOINT_DIRECTORY static

static const std::string EXTPOINT_DIRECTORY;

EXTPOINT_HANDLER static

static const std::string EXTPOINT_HANDLER;

ATTR_ALLOWCREDENTIALS protected static

static const std::string ATTR_ALLOWCREDENTIALS;

ATTR_ALLOWHEADERS protected static

static const std::string ATTR_ALLOWHEADERS;

ATTR_ALLOWMETHODS protected static

static const std::string ATTR_ALLOWMETHODS;

ATTR_ALLOWORIGIN protected static

static const std::string ATTR_ALLOWORIGIN;

ATTR_ALLOWSPECIALIZATION protected static

static const std::string ATTR_ALLOWSPECIALIZATION;

ATTR_AUTHMETHODS protected static

static const std::string ATTR_AUTHMETHODS;

ATTR_CACHE protected static

static const std::string ATTR_CACHE;

ATTR_CLASS protected static

static const std::string ATTR_CLASS;

ATTR_CORS protected static

static const std::string ATTR_CORS;

ATTR_CSRFPROTECTION protected static

static const std::string ATTR_CSRFPROTECTION;

ATTR_CSRFTOKENHEADER protected static

static const std::string ATTR_CSRFTOKENHEADER;

ATTR_DESCRIPTION protected static

static const std::string ATTR_DESCRIPTION;

ATTR_EXACTMATCH protected static

static const std::string ATTR_EXACTMATCH;

ATTR_HIDDEN protected static

static const std::string ATTR_HIDDEN;

ATTR_INDEX protected static

static const std::string ATTR_INDEX;

ATTR_LIBRARY protected static

static const std::string ATTR_LIBRARY;

ATTR_METHODS protected static

static const std::string ATTR_METHODS;

ATTR_PATH protected static

static const std::string ATTR_PATH;

ATTR_PATTERN protected static

static const std::string ATTR_PATTERN;

ATTR_PERMISSION protected static

static const std::string ATTR_PERMISSION;

ATTR_REALM protected static

static const std::string ATTR_REALM;

ATTR_REDIRECTON401 protected static

static const std::string ATTR_REDIRECTON401;

ATTR_RESOURCE protected static

static const std::string ATTR_RESOURCE;

ATTR_RESPONSEFORMAT protected static

static const std::string ATTR_RESPONSEFORMAT;

ATTR_SECURE protected static

static const std::string ATTR_SECURE;

ATTR_SESSION protected static

static const std::string ATTR_SESSION;

MANIFEST_NAME protected static

static const std::string MANIFEST_NAME;