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

#include <qgsserverogcapihandler.h>

Inheritance diagram for QgsServerOgcApiHandler:

[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::ContentType >	contentTypes () 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
	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...

QgsVectorLayer *	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. 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< QgsServerQueryStringParameter >	parameters (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
	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
	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 QgsVectorLayer *	layerFromCollectionId (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:

path
operationId
summary (shorter text)
description (longer text)
linkTitle
linkType
schema

Optionally, override:

tags
parameters
contentTypes
defaultContentType

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

QgsServerApiBadRequestError if the content type of the request is not compatible with the handler (

See also: contentTypes member)

Definition at line 437 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 563 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

QgsServerApiBadRequestError if 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

context	the current request context
extraPath	an optional extra path that will be appended to the calculated URL
extension	optional 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 594 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

QgsServerApiNotFoundError if the layer could not be found.

Definition at line 553 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

QgsServerApiNotFoundError	if the layer could not be found
QgsServerApiImproperlyConfiguredException	if 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

context	request context
linkType	type of the link (rel attribute), default to SELF
contentType	content type of the link (default to JSON)
title	title 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

context the 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 512 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 608 of file qgsserverogcapihandler.cpp.

◆ setContentTypesInt()

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

protected

Set the content types to contentTypes.

Definition at line 599 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

QgsServerApiBadRequestError if 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
starts_with( string, prefix ): returns true if a string begins with the provided string prefix, false otherwise

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"
nl2br( text ): returns the input text with all newlines replaced by "<br>" tags
starts_with( string, prefix ): returns true if a string begins with the provided string prefix, false otherwise

Definition at line 133 of file qgsserverogcapihandler.cpp.

The documentation for this class was generated from the following files:

/build/qgis-3.37.0+git20240325+fdefdf9c27f+17bookworm/src/server/qgsserverogcapihandler.h
/build/qgis-3.37.0+git20240325+fdefdf9c27f+17bookworm/src/server/qgsserverogcapihandler.cpp

Public Member Functions

Static Public Member Functions

Protected Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ ~QgsServerOgcApiHandler()

Member Function Documentation

◆ contentTypeForAccept()

◆ contentTypeFromRequest()

◆ contentTypes()

◆ defaultContentType()

◆ defaultResponse()

◆ description()

◆ handleRequest()

◆ href()

◆ htmlDump()

◆ jsonDump()

◆ jsonTags()

◆ layerFromCollectionId()

◆ layerFromContext()

◆ link()

◆ links()

◆ linkTitle()

◆ linkType()

◆ operationId()

◆ parameters()

◆ parentLink()

◆ path()

◆ schema()

◆ setContentTypes()

◆ setContentTypesInt()

◆ staticPath()

◆ summary()

◆ tags()

◆ templatePath()

◆ values()

◆ write() [1/2]

◆ write() [2/2]