source: TI05-delivery/ows_framework/trunk/ows_protocol.wiki @ 2594

Subversion URL: http://proj.badc.rl.ac.uk/svn/ndg/TI05-delivery/ows_framework/trunk/ows_protocol.wiki@3421
Revision 2594, 5.1 KB checked in by spascoe, 13 years ago (diff)

Various changes. Some test data is generated with make_data.py and this
is used to test the csml_wms controller. These tests pass.

Also there are some subsetToGridSeries tests. These fail at the moment. They need refining to check they are valid tests.

Line 
1'''NOTE''': This document is work in progress and, in it's present form, is best understood in conjuction with [source:/TI05-delivery/ows_framework/trunk the source].
2
3== A note about Pylons terminology ==
4
5In Pylons
6
7 - ''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.
8 - ''actions'' are methods of a ''controller''.  They are also selected using ''Routes''.
9
10== OGC Web Services ==
11
12Support for implementing OGC Web Services using Pylons is provided via:
13
14 1. The {{{ows_common}}} package.
15 1. The !OwsController class
16 1. The OWS Controller protocol defining standard attributes on Pylons controllers and actions
17 1. Decorators on controller actions
18
19=== The {{{ows_common}}} package ===
20
21The {{{ows_common}}} package provides a library of objects modelling
22the OWS Common specification v1.1.0.  Metadata required for a OWS
23should be represented using {{{ows_common}}} where ever possible to
24maximise code reuse.  For instance, templates are provided to render
25{{{ows_common}}} objects into OWS 1.1.0 or WMS 1.3.0 compliant
26GetCapabilities documents
27({{{ows_server.templates.ows.get_capabilities}}} and
28{{{ows_server.templates.ows.wms_capabilities}}}.  Implementations of
29other services can reuse parts of the core template.
30
31Also {{{ows_common.exceptions}}} provides a set of exception classes
32that are caught by the framework and rendered as a standard OWS
33exception response.
34
35=== The !OwsController class ===
36
37All OWS implementations should be implemented as a Pylons controller
38inheriting from {{{ows_server.base.OwsController}}}.  The method
39{{{OwsController._renderCapabilities()}}} returns a response object
40containing a standard OWS common 1.1.0 Capabilities document.
41Populating this document with service-specific metadata can be done by
42overriding the {{{OwsController._loadCapabilities() method.
43
44OWS operations are created by defining a {{{OwsController}}} method of
45the same name wrapped in the {{{@operation}}} decorator.  See below
46about decorators.
47
48=== Decorators ===
49
50The {{{ows_server.lib.decorators}}} module provides a set of
51decorators for setting attributes of the OWS controller protocol.
52These are added to the beginning of operation definitions e.g.:
53
54{{{
55#!python
56class WmsController(OwsController):
57
58    # ...
59
60    @operation
61    @parameter('Format', possibleValues=['text/xml'])
62    @parameter('Service', possibleValues=['WMS'], required=True)
63    @parameter('Version', possibleValues=['1.3.0'])
64    def GetCapabilities(self, file, service=None, version=None):
65        # ...
66}}}
67
68 {{{@operation}}}::
69  Should be the top-most decorator.  It wraps the method in a function that
70  performs request handling and type checking on the operation's arguments.
71 {{{@parameter}}}::
72  Add one of these for each operation parameter.  This instructs the framework
73  to perform several tasks.
74   1. Add the parameter (from request.params) to the list of arguments send to
75      the operation method.
76   1. Populate {{{ows_common}}} objects to describe this parameter in the
77      GetCapabilities document.
78   1. Do type-checking on the parameter's value during invocation.
79      The {{{possibleValues}}} argument allows you to define a set of
80      possible values, the {{{require}}} argument can declare an argument
81      required and the {{{validator}}} argument allows you to provide a
82      validation function.
83 {{{@constraint}}}::
84  OWS common 1.3.0 allows you to define constraints on operations.  This
85  decorator will populate the necessary {{{ows_common}}} objects for describing
86  the constraint in the GetCapabilities document.
87
88=== The OWS controller Protocol ===
89
90The {{{OwsController}}} class and decorators rely on as series of
91standard attributes being attached to the {{{OwsController}}} subclass
92implementing a OWS.  All attribute names begin with {{{_ows_}}}
93
94 {{{_ows_name}}}::
95  Defined in a method.  The CamelCased name of the operation.  This is
96  automatically set with the {{{@operation}}} decorator.
97 {{{_ows_parameters}}}::
98  Definied in a controller or method.  A dictionary mapping parameter
99  names to {{{ows_common.domain.Domain}}} objects.  Parameters are
100  used to define operation arguments and
101  operation-level parameters such as request format.  As well as
102  populating the Capabilities document, type checking is done on the
103  request parameter based on the parameter's domain.  See Decorators for
104  details.
105 {{{_ows_constraints}}}::
106  The same as {{{_ows_parameters}}} except for constraints.  Constraints are
107  defined in OWS Common 1.1.0.  An example of use would be the
108  MaximumLayerLevels element in WMS 1.3.0.
109 {{{_ows_versions}}}::
110  Definied in a controller.  Used to describe what version(s) of the OWS a controller supports.
111 {{{_ows_required_parameters}}}::
112  Defined in a method.  Describes which keys of {{{_ows_parameters}}} are required.  The
113  framework will automatically raise an OWS exception if a request doesn't contain this
114  parameter.
115 {{{_ows_validators}}}::
116  Defined in a method.  Provides a mechanism for adding custom type
117  checking to an operation parameter.  See Decorators.
118
Note: See TracBrowser for help on using the repository browser.