wiki:OwsFramework/OwsProtocol

Version 2 (modified by spascoe, 12 years ago) (diff)

--

NOTE: This document is work in progress. It reflects the state of the codebase at TI05-delivery/ows_framework/branches/ows_framework-refactor. This is evolving away from the code used in the deployed NDG Discovery Portal.

A note about Pylons terminology

In Pylons

  • controllers are classes inherited from pylons.controllers.WSGIController that reside in the controllers package of your application. Requests are routed to particular controllers via the Routes configuration.
  • actions are methods of a controller. They are also selected using Routes.

OGC Web Services

Support for implementing OGC Web Services using Pylons is provided via:

  1. The ows_common package.
  2. The OwsController class
  3. The OWS Controller protocol defining standard attributes on Pylons controllers and actions
  4. Decorators on controller actions

The ows_common package

The ows_common package provides a library of objects modelling the OWS Common specification v1.1.0. Metadata required for a OWS should be represented using ows_common where ever possible to maximise code reuse. For instance, templates are provided to render ows_common objects into OWS 1.1.0 or WMS 1.3.0 compliant GetCapabilities? documents (ows_server.templates.ows.get_capabilities and ows_server.templates.ows.wms_capabilities. Implementations of other services can reuse parts of the core template.

ows_common.exceptions provides a set of exception classes that are caught by the framework and rendered as a standard OWS exception response.

ows_common.pylons provides a framework for creating OGC WebServices? with the pylons web-application framework.

The OwsController class

All OWS implementations should be implemented as a Pylons controller inheriting from ows_common.pylons.ows_controller.OwsController. The method OwsController._renderCapabilities() returns a response object containing a standard OWS common 1.1.0 Capabilities document. Populating this document with service-specific metadata can be done by overriding the {{{OwsController?._loadCapabilities() method.

OWS operations are created by defining a OwsController method of the same name wrapped in the @operation decorator. See below about decorators.

Decorators

The ows_server.lib.decorators module provides a set of decorators for setting attributes of the OWS controller protocol. These are added to the beginning of operation definitions e.g.:

class WmsController(OwsController):

    # ...

    @operation
    @parameter('Format', possibleValues=['text/xml'])
    @parameter('Service', possibleValues=['WMS'], required=True)
    @parameter('Version', possibleValues=['1.3.0'])
    def GetCapabilities(self, file, service=None, version=None):
        # ...
@operation
Should be the top-most decorator. It wraps the method in a function that performs request handling and type checking on the operation's arguments.
@parameter
Add one of these for each operation parameter. This instructs the framework to perform several tasks.
  1. Add the parameter (from request.params) to the list of arguments send to the operation method.
  2. Populate ows_common objects to describe this parameter in the GetCapabilities? document.
  3. Do type-checking on the parameter's value during invocation. The possibleValues argument allows you to define a set of possible values, the require argument can declare an argument required and the validator argument allows you to provide a validation function.
@constraint
OWS common 1.3.0 allows you to define constraints on operations. This decorator will populate the necessary ows_common objects for describing the constraint in the GetCapabilities? document.

The OWS controller Protocol

The OwsController class and decorators rely on as series of standard attributes being attached to the OwsController subclass implementing a OWS. All attribute names begin with _ows_

_ows_name
Defined in a method. The CamelCased? name of the operation. This is automatically set with the @operation decorator.
_ows_parameters
Definied in a controller or method. A dictionary mapping parameter names to ows_common.domain.Domain objects. Parameters are used to define operation arguments and operation-level parameters such as request format. As well as populating the Capabilities document, type checking is done on the request parameter based on the parameter's domain. See Decorators for details.
_ows_constraints
The same as _ows_parameters except for constraints. Constraints are defined in OWS Common 1.1.0. An example of use would be the MaximumLayerLevels? element in WMS 1.3.0.
_ows_versions
Definied in a controller. Used to describe what version(s) of the OWS a controller supports.
_ows_required_parameters
Defined in a method. Describes which keys of _ows_parameters are required. The framework will automatically raise an OWS exception if a request doesn't contain this parameter.
_ows_validators
Defined in a method. Provides a mechanism for adding custom type checking to an operation parameter. See Decorators.