/ 
Geo-OGC-Service-0.01
River stage one • 2 direct dependents • 2 total dependents
/ Geo::OGC::Service

NAME

Geo::OGC::Service - Perl extension for geospatial web services

SYNOPSIS

In a service.psgi file write something like this

use strict;
use warnings;
use Geo::OGC::Service;
use Geo::OGC::Service::WFS;
my $app = Geo::OGC::Service->psgi_app(
  '/var/www/etc/dispatch', 
  'TestApp',
  {
      'WFS' => 'Geo::OGC::Service::WFS',
  }
  );
$app;

DESCRIPTION

This module provides psgi_app and respond methods for booting a web service.

SERVICE CONFIGURATION

Setting up a PSGI service consists typically of three things:

1) write a service.psgi file (see above) and put it somewhere like

/var/www/service/service.psgi

2) Set up starman service and add to its init-file line something like

exec starman --daemonize --error-log /var/log/starman/log --l localhost:5000 /var/www/service/service.psgi

3) Add a proxy service to your apache configuration

<Location /TestApp>
  ProxyPass http://localhost:5000/ 
  ProxyPassReverse http://localhost:5000/
</Location>

Setting up a geospatial web service configuration requires a configuration table file, for example

/var/www/etc/dispatch

(make sure this file is not served by apache)

The dispatch file should consist of lines with two items separated by a tab. The first item should be the string that is the parameter to psgi_app above (MyService in this case). The second item should be a path to a file which contains the configuration for the service. The configuration must be in JSON format. I.e., something like

{
  "CORS": "*",
  "MIME": "text/xml",
  "version": "1.1.0",
  "TARGET_NAMESPACE": "http://ogr.maptools.org/"
}

The keys and structure of this file depend on the type of the service you are setting up. "CORS" and "debug" are the only ones that are recognized by this module. "CORS" is either a string denoting the allowed origin or a hash of "Allow-Origin", "Allow-Methods", "Allow-Headers", and "Max-Age".

EXPORT

None by default.

METHODS

psgi_app

This is the psgi app boot method. You need to call it in the psgi file as a class method. The parameters are

configuration_table, service_name, services

configuration_table is a path to a file of pairs of service names and service configuration.

service_name is the name of this service and a key in the configuration_table.

services is a reference to a hash of OGC service names associated with names of classes, which should process those service requests.

respond

This subroutine is called for each request from the Internet. The call is responded during the execution of the subroutine. First, the configuration file is read and decoded. If the request is "OPTIONS" the call is responded with the following headers

Content-Type = text/plain
Access-Control-Allow-Origin = ""
Access-Control-Allow-Methods = "GET,POST"
Access-Control-Allow-Headers = "origin,x-requested-with,content-type"
Access-Control-Max-Age = 60*60*24

The values of Access-Control-* keys can be set in the configuration file. The above values are the default ones.

In the default case this method constructs a new service object and calls its process_request method with PSGI style $responder object as a parameter.

This subroutine may fail due to an error in the configuration file, while interpreting the request, and while processing the request.

service

This subroutine does a preliminary interpretation of the request and converts it into a service object. The contents of the configuration is merged into the object.

The returned service object may contain the following information

config => a clone of the configuration for this service
posted => XML::LibXML DOM document element of the posted data
filter => XML::LibXML DOM document element of the filter
parameters => hash of rquest parameters obtained from Plack::Request

This subroutine may fail due to a request for an unknown service.

XMLWriter

A helper class for writing XML.

SYNOPSIS

my $writer = Geo::OGC::Service::XMLWriter::Caching->new();
$writer->open_element(
      'wfs:WFS_Capabilities', 
      { 'xmlns:gml' => "http://www.opengis.net/gml" });
$writer->element('ows:ServiceProvider',
                   [['ows:ProviderName'],
                    ['ows:ProviderSite', {'xlink:type'=>"simple", 'xlink:href'=>""}],
                    ['ows:ServiceContact']]);
$writer->close_element;
$writer->stream($responder);

or

use Capture::Tiny ':all';
my $writer = Geo::OGC::Service::XMLWriter::Streaming->new($responder);
for (@a_very_very_long_list) {
  my $stdout = capture_stdout {
    say something;
  };
  $writer->write($stdout);
}

DESCRIPTION

The classes Geo::OGC::Service::XMLWriter (abstract), Geo::OGC::Service::XMLWriter::Streaming (concrete), and Geo::OGC::Service::XMLWriter::Caching (concrete) are provided as a convenience for writing XML to the client.

The element method has the syntax

$writer->xml_element($tag[, $attributes][, $content])

$attributes is a reference to a hash

$content is a reference to a list of xml elements (tag...)

SEE ALSO

Discuss this module on the Geo-perl email list.

https://list.hut.fi/mailman/listinfo/geo-perl

For PSGI/Plack see

http://plackperl.org/

AUTHOR

Ari Jolma, <ari.jolma at gmail.com>

COPYRIGHT AND LICENSE

Copyright (C) 2015 by Ari Jolma

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.22.0 or, at your option, any later version of Perl 5 you may have available.