QGIS API Documentation  3.26.3-Buenos Aires (65e4edfdad)
Public Member Functions | Static Public Member Functions | Protected Member Functions | List of all members
QgsServerOgcApiHandler Class Referenceabstract

The QgsServerOgcApiHandler abstract class represents a OGC API handler to be registered in QgsServerOgcApi class. More...

#include <qgsserverogcapihandler.h>

Inheritance diagram for QgsServerOgcApiHandler:
Inheritance graph
[legend]

Public Member Functions

virtual ~QgsServerOgcApiHandler ()
 
QString contentTypeForAccept (const QString &accept) const
 Looks for the first ContentType match in the accept header and returns its mime type, returns an empty string if there are not matches. More...
 
QgsServerOgcApi::ContentType contentTypeFromRequest (const QgsServerRequest *request) const
 Returns the content type from the request. More...
 
QList< QgsServerOgcApi::ContentTypecontentTypes () const
 Returns the list of content types this handler can serve, default to JSON and HTML. More...
 
virtual QgsServerOgcApi::ContentType defaultContentType () const
 Returns the default response content type in case the client did not specifically ask for any particular content type. More...
 
virtual std::string description () const =0
 Description. More...
 
virtual void handleRequest (const QgsServerApiContext &context) const SIP_THROW(QgsServerApiBadRequestException)
 Handles the request within its context. More...
 
std::string href (const QgsServerApiContext &context, const QString &extraPath=QString(), const QString &extension=QString()) const
 Returns an URL to self, to be used for links to the current resources and as a base for constructing links to sub-resources. More...
 
void htmlDump (const json &data, const QgsServerApiContext &context) const
 Writes data as HTML to the response stream in context using a template. More...
 
void jsonDump (json &data, const QgsServerApiContext &context, const QString &contentType=QStringLiteral("application/json")) const
 Writes data to the context response stream as JSON (indented if debug is active), an optional contentType can be specified. More...
 
json jsonTags () const
 Returns tags as JSON. More...
 
QgsVectorLayerlayerFromContext (const QgsServerApiContext &context) const
 Returns a vector layer instance from the "collectionId" parameter of the path in the given context, requires a valid project instance in the context. More...
 
json link (const QgsServerApiContext &context, const QgsServerOgcApi::Rel &linkType=QgsServerOgcApi::Rel::self, const QgsServerOgcApi::ContentType contentType=QgsServerOgcApi::ContentType::JSON, const std::string &title="") const
 Builds and returns a link to the resource. More...
 
json links (const QgsServerApiContext &context) const
 Returns all the links for the given request context. More...
 
virtual std::string linkTitle () const =0
 Title for the handler link. More...
 
virtual QgsServerOgcApi::Rel linkType () const =0
 Main role for the resource link. More...
 
virtual std::string operationId () const =0
 Returns the operation id for template file names and other internal references. More...
 
virtual QList< QgsServerQueryStringParameterparameters (const QgsServerApiContext &context) const
 Returns a list of query string parameters. More...
 
virtual QRegularExpression path () const =0
 URL pattern for this handler, named capture group are automatically extracted and returned by values() More...
 
virtual json schema (const QgsServerApiContext &context) const
 Returns handler information from the context for the OPENAPI description (id, description and other metadata) as JSON. More...
 
virtual const QString staticPath (const QgsServerApiContext &context) const
 Returns the absolute path to the base directory where static resources for this handler are stored in the given context. More...
 
virtual std::string summary () const =0
 Summary. More...
 
virtual QStringList tags () const
 Tags. More...
 
virtual const QString templatePath (const QgsServerApiContext &context) const
 Returns the HTML template path for the handler in the given context. More...
 
virtual QVariantMap values (const QgsServerApiContext &context) const SIP_THROW(QgsServerApiBadRequestException)
 Analyzes the incoming request context and returns the validated parameter map, throws QgsServerApiBadRequestError in case of errors. More...
 
void write (json &data, const QgsServerApiContext &context, const json &htmlMetadata=nullptr) const
 Writes data to the context response stream, content-type is calculated from the context request, optional htmlMetadata for the HTML templates can be specified and will be added as "metadata" to the HTML template variables. More...
 
void write (QVariant &data, const QgsServerApiContext &context, const QVariantMap &htmlMetadata=QVariantMap()) const SIP_THROW(QgsServerApiBadRequestException)
 Writes data to the context response stream, content-type is calculated from the context request, optional htmlMetadata for the HTML templates can be specified and will be added as "metadata" to the HTML template variables. More...
 

Static Public Member Functions

static json defaultResponse ()
 Returns the defaultResponse as JSON. More...
 
static QgsVectorLayerlayerFromCollectionId (const QgsServerApiContext &context, const QString &collectionId)
 Returns a vector layer from the collectionId in the given context. More...
 
static QString parentLink (const QUrl &url, int levels=1)
 Returns a link to the parent page up to levels in the HTML hierarchy from the given url, MAP query argument is preserved. More...
 

Protected Member Functions

void setContentTypes (const QList< QgsServerOgcApi::ContentType > &contentTypes)
 Set the content types to contentTypes. More...
 
void setContentTypesInt (const QList< int > &contentTypes)
 Set the content types to contentTypes. More...
 

Detailed Description

The QgsServerOgcApiHandler abstract class represents a OGC API handler to be registered in QgsServerOgcApi class.

Subclasses must override operational and informative methods and define the core functionality in handleRequest() method.

The following methods MUST be implemented:

Optionally, override:

class Handler1(QgsServerOgcApiHandler):
"""Example handler"""
def path(self):
return QtCore.QRegularExpression("/handlerone")
def operationId(self):
return "handlerOne"
def summary(self):
return "First of its name"
def description(self):
return "The first handler ever"
def linkTitle(self):
return "Handler One Link Title"
def linkType(self):
return QgsServerOgcApi.data
def handleRequest(self, context):
"""Simple mirror: returns the parameters"""
params = self.values(context)
self.write(params, context)
def parameters(self, context):
return [QgsServerQueryStringParameter("value1", True, QgsServerQueryStringParameter.Type.Double, "a double value")]
Since
QGIS 3.10

Definition at line 94 of file qgsserverogcapihandler.h.

Constructor & Destructor Documentation

◆ ~QgsServerOgcApiHandler()

QgsServerOgcApiHandler::~QgsServerOgcApiHandler ( )
virtual

Definition at line 64 of file qgsserverogcapihandler.cpp.

Member Function Documentation

◆ contentTypeForAccept()

QString QgsServerOgcApiHandler::contentTypeForAccept ( const QString &  accept) const

Looks for the first ContentType match in the accept header and returns its mime type, returns an empty string if there are not matches.

Definition at line 86 of file qgsserverogcapihandler.cpp.

◆ contentTypeFromRequest()

QgsServerOgcApi::ContentType QgsServerOgcApiHandler::contentTypeFromRequest ( const QgsServerRequest request) const

Returns the content type from the request.

The path file extension is examined first and checked for known mime types, the "Accept" HTTP header is examined next. Fallback to the default content type of the handler if none of the above matches.

Exceptions
QgsServerApiBadRequestErrorif the content type of the request is not compatible with the handler (
See also
contentTypes member)

Definition at line 429 of file qgsserverogcapihandler.cpp.

◆ contentTypes()

QList< QgsServerOgcApi::ContentType > QgsServerOgcApiHandler::contentTypes ( ) const

Returns the list of content types this handler can serve, default to JSON and HTML.

In case a specialized type (such as GEOJSON) is supported, the generic type (such as JSON) should not be listed.

Note
not available in Python bindings

Definition at line 75 of file qgsserverogcapihandler.cpp.

◆ defaultContentType()

QgsServerOgcApi::ContentType QgsServerOgcApiHandler::defaultContentType ( ) const
virtual

Returns the default response content type in case the client did not specifically ask for any particular content type.

The default implementation returns the first content type returned by contentTypes() or JSON if that list is empty.

Definition at line 69 of file qgsserverogcapihandler.cpp.

◆ defaultResponse()

json QgsServerOgcApiHandler::defaultResponse ( )
static

Returns the defaultResponse as JSON.

Note
not available in Python bindings

Definition at line 555 of file qgsserverogcapihandler.cpp.

◆ description()

virtual std::string QgsServerOgcApiHandler::description ( ) const
pure virtual

Description.

Implemented in QgsServerStaticHandler.

◆ handleRequest()

void QgsServerOgcApiHandler::handleRequest ( const QgsServerApiContext context) const
virtual

Handles the request within its context.

Subclasses must implement this methods, and call validate() to extract validated parameters from the request.

Exceptions
QgsServerApiBadRequestErrorif the method encounters any error

Reimplemented in QgsServerStaticHandler.

Definition at line 80 of file qgsserverogcapihandler.cpp.

◆ href()

std::string QgsServerOgcApiHandler::href ( const QgsServerApiContext context,
const QString &  extraPath = QString(),
const QString &  extension = QString() 
) const

Returns an URL to self, to be used for links to the current resources and as a base for constructing links to sub-resources.

Parameters
contextthe current request context
extraPathan optional extra path that will be appended to the calculated URL
extensionoptional file extension to add (the dot will be added automatically).

Definition at line 140 of file qgsserverogcapihandler.cpp.

◆ htmlDump()

void QgsServerOgcApiHandler::htmlDump ( const json &  data,
const QgsServerApiContext context 
) const

Writes data as HTML to the response stream in context using a template.

See also
templatePath()
Note
not available in Python bindings

Definition at line 272 of file qgsserverogcapihandler.cpp.

◆ jsonDump()

void QgsServerOgcApiHandler::jsonDump ( json &  data,
const QgsServerApiContext context,
const QString &  contentType = QStringLiteral( "application/json" ) 
) const

Writes data to the context response stream as JSON (indented if debug is active), an optional contentType can be specified.

Note
not available in Python bindings

Definition at line 182 of file qgsserverogcapihandler.cpp.

◆ jsonTags()

json QgsServerOgcApiHandler::jsonTags ( ) const

Returns tags as JSON.

See also
tags()
Note
not available in Python bindings

Definition at line 586 of file qgsserverogcapihandler.cpp.

◆ layerFromCollectionId()

QgsVectorLayer * QgsServerOgcApiHandler::layerFromCollectionId ( const QgsServerApiContext context,
const QString &  collectionId 
)
static

Returns a vector layer from the collectionId in the given context.

Exceptions
QgsServerApiNotFoundErrorif the layer could not be found.

Definition at line 545 of file qgsserverogcapihandler.cpp.

◆ layerFromContext()

QgsVectorLayer * QgsServerOgcApiHandler::layerFromContext ( const QgsServerApiContext context) const

Returns a vector layer instance from the "collectionId" parameter of the path in the given context, requires a valid project instance in the context.

Note
not available in Python bindings
Exceptions
QgsServerApiNotFoundErrorif the layer could not be found
QgsServerApiImproperlyConfiguredExceptionif project is not set

Definition at line 235 of file qgsserverogcapihandler.cpp.

◆ link()

json QgsServerOgcApiHandler::link ( const QgsServerApiContext context,
const QgsServerOgcApi::Rel linkType = QgsServerOgcApi::Rel::self,
const QgsServerOgcApi::ContentType  contentType = QgsServerOgcApi::ContentType::JSON,
const std::string &  title = "" 
) const

Builds and returns a link to the resource.

Parameters
contextrequest context
linkTypetype of the link (rel attribute), default to SELF
contentTypecontent type of the link (default to JSON)
titletitle of the link
Note
not available in Python bindings

Definition at line 206 of file qgsserverogcapihandler.cpp.

◆ links()

json QgsServerOgcApiHandler::links ( const QgsServerApiContext context) const

Returns all the links for the given request context.

The base implementation returns the alternate and self links, subclasses may add other links.

Note
not available in Python bindings

Definition at line 221 of file qgsserverogcapihandler.cpp.

◆ linkTitle()

virtual std::string QgsServerOgcApiHandler::linkTitle ( ) const
pure virtual

Title for the handler link.

Implemented in QgsServerStaticHandler.

◆ linkType()

virtual QgsServerOgcApi::Rel QgsServerOgcApiHandler::linkType ( ) const
pure virtual

Main role for the resource link.

Implemented in QgsServerStaticHandler.

◆ operationId()

virtual std::string QgsServerOgcApiHandler::operationId ( ) const
pure virtual

Returns the operation id for template file names and other internal references.

Implemented in QgsServerStaticHandler.

◆ parameters()

virtual QList<QgsServerQueryStringParameter> QgsServerOgcApiHandler::parameters ( const QgsServerApiContext context) const
inlinevirtual

Returns a list of query string parameters.

Depending on the handler, it may be dynamic (per-request) or static.

Parameters
contextthe request context

Definition at line 124 of file qgsserverogcapihandler.h.

◆ parentLink()

QString QgsServerOgcApiHandler::parentLink ( const QUrl &  url,
int  levels = 1 
)
static

Returns a link to the parent page up to levels in the HTML hierarchy from the given url, MAP query argument is preserved.

Definition at line 504 of file qgsserverogcapihandler.cpp.

◆ path()

virtual QRegularExpression QgsServerOgcApiHandler::path ( ) const
pure virtual

URL pattern for this handler, named capture group are automatically extracted and returned by values()

Example: "/handlername/(?P<code1>\d{2})/items" will capture "code1" as a named parameter.

See also
values()

Implemented in QgsServerStaticHandler.

◆ schema()

json QgsServerOgcApiHandler::schema ( const QgsServerApiContext context) const
virtual

Returns handler information from the context for the OPENAPI description (id, description and other metadata) as JSON.

It may return a NULL JSON object in case the handler does not need to be included in the API.

Note
requires a valid project to be present in the context
not available in Python bindings

Definition at line 200 of file qgsserverogcapihandler.cpp.

◆ setContentTypes()

void QgsServerOgcApiHandler::setContentTypes ( const QList< QgsServerOgcApi::ContentType > &  contentTypes)
protected

Set the content types to contentTypes.

Note
not available in Python bindings

Definition at line 600 of file qgsserverogcapihandler.cpp.

◆ setContentTypesInt()

void QgsServerOgcApiHandler::setContentTypesInt ( const QList< int > &  contentTypes)
protected

Set the content types to contentTypes.

Definition at line 591 of file qgsserverogcapihandler.cpp.

◆ staticPath()

const QString QgsServerOgcApiHandler::staticPath ( const QgsServerApiContext context) const
virtual

Returns the absolute path to the base directory where static resources for this handler are stored in the given context.

Definition at line 253 of file qgsserverogcapihandler.cpp.

◆ summary()

virtual std::string QgsServerOgcApiHandler::summary ( ) const
pure virtual

Summary.

Implemented in QgsServerStaticHandler.

◆ tags()

virtual QStringList QgsServerOgcApiHandler::tags ( ) const
inlinevirtual

Tags.

Definition at line 142 of file qgsserverogcapihandler.h.

◆ templatePath()

const QString QgsServerOgcApiHandler::templatePath ( const QgsServerApiContext context) const
virtual

Returns the HTML template path for the handler in the given context.

The template path is calculated from QgsServerSettings's apiResourcesDirectory() as follow: apiResourcesDirectory() + "/ogc/templates/" + context.apiRootPath + operationId + ".html" e.g. for an API with root path "/wfs3" and an handler with operationId "collectionItems", the path will be apiResourcesDirectory() + "/ogc/templates/wfs3/collectionItems.html"

Definition at line 259 of file qgsserverogcapihandler.cpp.

◆ values()

QVariantMap QgsServerOgcApiHandler::values ( const QgsServerApiContext context) const
virtual

Analyzes the incoming request context and returns the validated parameter map, throws QgsServerApiBadRequestError in case of errors.

Path fragments from the named groups in the path() regular expression are also added to the map.

Your handleRequest method should call this function to retrieve the parameters map.

Returns
the validated parameters map by extracting captured named parameters from the path (no validation is performed on the type because the regular expression can do it), and the query string parameters.
See also
path()
parameters()
Exceptions
QgsServerApiBadRequestErrorif validation fails

Definition at line 40 of file qgsserverogcapihandler.cpp.

◆ write() [1/2]

void QgsServerOgcApiHandler::write ( json &  data,
const QgsServerApiContext context,
const json &  htmlMetadata = nullptr 
) const

Writes data to the context response stream, content-type is calculated from the context request, optional htmlMetadata for the HTML templates can be specified and will be added as "metadata" to the HTML template variables.

HTML output uses a template engine.

Available template functions: See: https://github.com/pantor/inja#tutorial

Available custom template functions:

  • path_append( path ): appends a directory path to the current url
  • path_chomp( n ):removes the specified number "n" of directory components from the current url path
  • json_dump( ): prints current JSON data passed to the template
  • static( path ): returns the full URL to the specified static path, for example: static( "/style/black.css" ) will return something like "/wfs3/static/style/black.css".
  • links_filter( links, key, value ): Returns filtered links from a link list
  • content_type_name( content_type ): Returns a short name from a content type for example "text/html" will return "HTML"
  • nl2br( text ): Returns the input text with all newlines replaced by "<br>" tags
Note
not available in Python bindings

Definition at line 109 of file qgsserverogcapihandler.cpp.

◆ write() [2/2]

void QgsServerOgcApiHandler::write ( QVariant &  data,
const QgsServerApiContext context,
const QVariantMap &  htmlMetadata = QVariantMap() 
) const

Writes data to the context response stream, content-type is calculated from the context request, optional htmlMetadata for the HTML templates can be specified and will be added as "metadata" to the HTML template variables.

HTML output uses a template engine.

Available template functions: See: https://github.com/pantor/inja#tutorial

Available custom template functions:

  • path_append( path ): appends a directory path to the current url
  • path_chomp( n ): removes the specified number "n" of directory components from the current url path
  • json_dump(): prints current JSON data passed to the template
  • static( path): returns the full URL to the specified static path, for example: static("/style/black.css") will return something like "/wfs3/static/style/black.css".
  • links_filter( links, key, value ): returns filtered links from a link list
  • content_type_name( content_type ): returns a short name from a content type for example "text/html" will return "HTML"

Definition at line 133 of file qgsserverogcapihandler.cpp.


The documentation for this class was generated from the following files:
QgsServerOgcApiHandler
The QgsServerOgcApiHandler abstract class represents a OGC API handler to be registered in QgsServerO...
Definition: qgsserverogcapihandler.h:94
QgsServerQueryStringParameter
The QgsServerQueryStringParameter class holds the information regarding a query string input paramete...
Definition: qgsserverquerystringparameter.h:47