CHAMELEON 1.99: CWC2 SERVICE INSTANCE
======================================
***************************************************************************
* WARNING: THIS DOCUMENTENT IS A VERY VERY EARLY DRAFT. THIS INFORMATION *
* WAS IDENTIFIED AS IMPORTANT FOR USERS OF CHAMELEON THIS IS WHY IT IS ON *
* THE MAPTOOLS. *
* *
* This Document outlines: *
* * How to configure CWC2 Service Instance *
* * What has been currently implemented for the Service Instance. *
* * How to use the Service Instance (User Guide). *
* * Example Service Instance URLs. *
* *
***************************************************************************
CONFIGURATION FILE CHANGES - VERY IMPORTANT
==============================================
With the addition of the service instance (called cwc2), I have finally fixed up
the configuration files. The configuration file in beta1 was called cwc2.xml
for historical reasons (since chameleon was originally called CWC2). It
contained several parameters that were only really needed by the service
instance but I left them in because I knew that this service instance was coming
back at some point. So now that it is back, I have split the configuration file
into two separate files, chameleon.xml and cwc2.xml. It is NOT sufficient to
rename your cwc2.xml to chameleon.xml. The splitting process resulted in the
removal of some completely unnecessary elements, the adding of new parameters,
and changing the names of some elements.
You MUST start from the xml-dist versions of these files. You will find that
you can copy some settings from the existing cwc2.xml into the appropriate place
in either chameleon.xml or the new cwc2.xml.
For ms4w users, the package comes pre-configured so you don't have to worry
about this at all.
For non-ms4w users, you may want to check out the ms4w version's configuration
files if you are having difficulty.
CWC2 Service Instance Notes
---------------------------
In lieu of real documentation, I'm providing some working notes at this time.
This will eventually show up in one of the chameleon documents :)
Installing the CWC2 Service Instance
====================================
The CWC2 Service Instance is installed with the Chameleon package by default.
To access the Service Instance, you will need to adjust your system
configuration and edit the Service Instance configuration file to reflect your
system's configuration.
Note that the Service Instance requires a properly installed and configured
Chameleon package, please follow the Chameleon installation instructions and
ensure that Chameleon is fully functional before attempting to configure the
Service Instance.
System Configuration
====================
You will need to configure your Web Server to grant access to at least one
directory in the service instance. Two other directories are optional. The
following table is a suggested configuration:
URL Required? Path
--------------------------- --------- -------------------------------
http://{myserver}/cwc2 YES {install-path}/chameleon/cwc2/htdocs/
http://{myserver}/templates NO {install-path}/chameleon/cwc2/templates/
http://{myserver}/contexts NO {install-path}/chameleon/cwc2/contexts/
Service Instance Configuration
==============================
You will need to make a copy of the cwc2.xml-dist file found in the
{install-path}/chameleon/config folder and name it cwc2.xml. You will need
to edit at least some of the settings found in this file. Each configuration
item is described in the xml document, but as a minimum you should review the
following items:
Config Item Set to ...
--------------------- -----------------------------------------------
service_instance_path URL to service instance htdocs folder (from above)
server_data_path {install-path}/chameleon/cwc2/data
default_context {install-path}/chameleon/cwc2/contexts/world_context.xml
default_template {install-path}/chameleon/cwc2/templates/sample_cwc2.html
context_root {install-path}/chameleon/cwc2/contexts/
template_root {install-path}/chameleon/cwc2/templates
fontlist_file {install-path}/chameleon/cwc2/etc/fonts.txt
symbol_file {install-path}/chameleon/cwc2/etc/symbols.sym
Testing the Service Instance
============================
Assuming that the above configuration is implemented correctly, the Service
Instance should now be fully functional. You can test your Service Instance by
connecting to the following URL:
http://{myserver}/cwc2/cwc2.php
You should receive the following message:
request URI was http://{myserver}/cwc2/cwc2.php
query string was
Missing mandatory SERVICE parameter
This error message means that the Web Server is correctly providing access to
the Service Instance.
Normally, the Service Instance is configured to provide a default application
and context. If you followed the instructions above, you can access the default
application and context by connecting to the following URL:
http://{myserver}/cwc2/cwc2.php?service=VCG
&request=GetApplication&version=0.1.0
Please read the CWC2 Service Instance Users Guide to find out more about
communicating with and using the features of the Service Instance
Getting Help
============
The CWC2 Service Instance is part of the Chameleon package available from
http://www.maptools.org. Please visit the Chameleon web site at
http://www.maptools.org/chameleon to access information about using Bugzilla
and the Chameleon users mailing list.
**** CWC2 USERS GUIDE ****
CWC2 Service Instance Users Guide
=================================
Getting Started
===============
Please refer to the CWC2 Service Instance Installation Guide for instructions on
getting your Service Instance installed and tested. This document assumes that
you have a fully functional and correctly configured Service Instance.
Terms and Definitions
=====================
CWC2 - TBD
Service Instance - TBD
Chameleon - TBD
CWC2 Service Instance Server - TBD
Application - TBD
...
Basic Concepts
==============
The CWC2 Service Instance is an application built on top of the Chameleon engine
that allows application developers to create web mapping applications by
creating an Application Template and a Web Map Context document. It will only
work with WMS layers.
The CWC2 Service Instance is a web service that can be invoked by clients using
only a web browser.
Service Exceptions
==================
A Service Exception is the term used to describe the result of an error that
happens in the CWC2 Service Instance. The CWC2 Service Instance is designed to
capture internal errors and report them in a standard, machine-parsable way
using structured XML documents. Whenever an error is trapped internally, CWC2
will generate and return a Service Exception instead of the application. The
intention is to provide sufficient information to the user to allow for
troubleshooting of the problem that caused the Service Exception to be
triggered. Service Exceptions can happen at any time and for a wide variety of
reasons.
{NOTE: service exceptions are currently just plain text}
Common Request Parameters
=========================
This section describes parameters that are common to every invocation of the
Service Instance.
REQUEST
-------
The REQUEST parameter indicates which operation is being invoked and its value
is one of the names of the operations supported by the service instance. The
REQUEST parameter is mandatory in every invocation of the service instance.
VERSION
-------
The VERSION parameter indicates the protocol version number and is mandatory in
every invocation of the service instance.
SERVICE
-------
The SERVICE parameter indicates the service that is being requested. Some web
services can be configured to provide multiple services through the same base
URL. In the case of CWC2, this is not yet possible, however, this parameter is
provided for compatibility with existing services and for possible future
requirements. The SERVICE parameter is mandatory in every invocation of the
service instance.
Supported REQUESTs
==================
The CWC2 Service Instance supports two REQUESTs, described below.
GetCapabilities
===============
{NOTE: not yet implemented}
The purpose of the GetCapabilities operation is to describe the operating
parameters of a particular Service Instance to enable clients to use the service
in an effective manner.
GetCapabilites Request Parameters
---------------------------------
The GetCapabilities operation has three mandatory paramters, SERVICE, REQUEST
and VERSION, described in the following table:
Parameter Required/ Description
Optional
SERVICE=VCG R Service name, must be VCG.
REQUEST=GetCapabilities R request name, must be GetCapabilities
VERSION={version} R supported protocol version number
GetCapabilities Reponse
-----------------------
The response to the GetCapabilities request is an XML document. This feature is
not yet implemented.
GetApplication
==============
The purpose of the GetApplication operation is to generate a client application
based on the parameters provided when invoking the service.
GetCapabilites Request Parameters
---------------------------------
The GetApplication operation has three mandatory paramters and six optional
parameters described in the following table:
Parameter Required/ Description
Optional
SERVICE=VCG R Service name, must be VCG.
REQUEST=GetApplication R request name, must be GetApplication
VERSION={version} R supported protocol version number
LANGUAGES={list} O a list of languages
TEMPLATES={list} O a list of application template paths or
URLs
CONTEXTS={list} O a list of context paths or URLs
LANGUAGE={lang} O the language to display
BBOX={list} O a comma separated list of coordinates
that describe the initial spatial extents
to be displayed to the user
SRS={srs} O a spatial reference system, must be a valid
EPSG code, to be used for the initial map
view.
LANGUAGES
---------
A list of language specifiers separated by commas. Languages are specified in
the form of a two-character language code followed by a dash and a two character
country code. Service instances will list supported languages in the
capabilities document. Unsupported languages may be requested, but the service
instance will use the default language for unsupported languages.
This parameter is optional unless TEMPLATES is set, in which case it is
mandatory.
TEMPLATES
---------
A list of application template paths or URLs separated by commas. A template is
identified by either a relative path on the server (relative to the template
root directory specified in the service instance configuration) or a URL to a
web-accessible template. The templates are listed in the same order as the
LANGUAGES, with one template required for each supported language (even if the
same template supports every language). URLs must be in the standard
http://{server}/path/template.html format and must be URL-encoded.
This parameter is optional unless LANGUAGES is set, in which case it is
mandatory. The service instance defines a default template in its configuration
file.
CONTEXTS
--------
A list of web map context paths or URLs separated by commas. A context is
identified by either a relative path on the server (relative to a directory
specified in the service instance configuration) or a URL to a web-accessible
context. The contexts are loaded in the order in which they appear in this
value, and the projection and spatial extents are taken from the last context
loaded (see Common Problems below). The order of the contexts determines the
order in which the layers of each context are drawn. Layers from the first
context in the list are drawn first, layers from later contexts are drawn 'on
top' of earlier ones. URLs must be in the standard http://{server}
/path/template.html format and must be URL-encoded.
This parameter is optional. The service instance defines a default value in its
configuration file.
LANGUAGE
--------
The lanuage to use to display the application. This will cause one of the
templates to be selected from the available TEMPLATES.
This parameter is optional. The service instance defines a default value in its
configuration file.
BBOX
----
The BBOX provides a mechanism to define a different set of initial spatial
extents that the default. By default, the Service Instance will use the extents
defined in the last context opened. This may not be appropriate in all cases,
especially when providing multiple contexts. The format for this parameter is to
provide a comma-separated list of values in the following order:
BBOX={MINX},{MINY},{MAXX},{MAXY}
The values are specified in georeferenced coordinates and depend on the spatial
reference system of the initial view.
SRS
---
The SRS provides a mechanism to define a different spatial reference system that
the default. By default, the Service Instance will use the SRS defined in the
last context opened. This may not be appropriate in all cases, especially when
providing multiple contexts. This parameter must use EPSG codes in the
following format:
SRS=EPSG:XXXXX
Common Problems
===============
Paths to TEMPLATES and CONTEXTS
-------------------------------
When specifying a template or a context, you must do so in relation to the
Service Instance server. This means that if the context or template that you
wish to access is on the Service Instance server, then it must reside in the
Service Instances defined template directory or context directory (or a
subdirectory of these). If the context or template is not on the Service
Instance server, then you must refer to it using a valid URL. It is very
important to note that the URL will be opened from the Service Instance server,
so a URL that refers to localhost:
http://localhost/mytemplates/app1.html
will most likely NOT work. This is because the Service Instance, when it tries
to open this URL, will be pointing to itself, most likely not the situation you
intended.
Multiple CONTEXTS appear wrong
------------------------------
When specifying multiple CONTEXTS, the Service Instance will load them
sequentially and use the BBOX and SRS defined in the last context it loads. It
is quite possible that the BBOX and SRS in the last context you want to load are
not valid for all the contexts that you are trying to load. For instance, if
you try to load the world_context.xml and the gmap_context.xml (in that order)
that come with the service instance, the world data will be displayed in LCC
projection and will not appear to 'line up' with the gmap data. The problem is
that the projection is invalid for extents beyond Canada. To fix this problem,
you can manually provide a BBOX and SRS as part of the request. In this case,
changing the SRS to EPSG:4326 displays everything correctly.
Limitations
===========
The CWC2 Service Instance will only work with data that is accessible via WMS
The CWC2 Service Instance does not allow applications to define and access
custom widgets unless they are installed in the Chameleon instance that the CWC2
Service Instance is configured to use.
******************************************************
EXAMPLE Service Instance URLS:
=============================
Some example invocations:
* The base URL to the service instance is (note this is an invalid request):
http://localhost/chameleon/cwc2/cwc2.php
* The URL to get the Service Instance capabilities is (note this doesn't do
anything yet):
http://localhost/chameleon/cwc2/cwc2.php?service=VCG&request=
GetCapabilities&version=0.1.0
* The URL to get the default template, context and language is (note this is the
most basic valid request):
http://localhost/chameleon/cwc2/cwc2.php?service=VCG&request=
GetApplication&version=0.1.0
* The URL to get a single local template for a given language is:
http://localhost/chameleon/cwc2/cwc2.php?request=GetApplication&version=
0.1.0&LANGUAGES=en-CA&TEMPLATES=sample_cwc2.html
* The URL to get a single remote template for a given language is:
http://localhost/chameleon/cwc2/cwc2.php?request=GetApplication&version=
0.1.0&LANGUAGES=en-CA&TEMPLATES=
http://localhost/chameleon/cwc2/templates/sample_cwc2.html
* The URL to get a bilingual application using local templates is:
http://localhost/chameleon/cwc2/cwc2.php?request=GetApplication&version=
0.1.0&LANGUAGES=en-CA,fr-CA&TEMPLATES=sample_cwc2_en.html,sample_cwc2_fr.html
* The URL to get a bilingual application using remote templates is:
http://localhost/chameleon/cwc2/cwc2.php?request=GetApplication&version=
0.1.0&LANGUAGES=en-CA,fr-CA&TEMPLATES=
http://localhost/chameleon/cwc2/templates/sample_cwc2_en.html,http://localhost/c
hameleon/cwc2/templates/sample_cwc2_fr.html
* The URL to get a single local context using default template and language is:
http://localhost/chameleon/cwc2/cwc2.php?service=VCG&request=
GetApplication&version=0.1.0&CONTEXTS=gmap_context.xml
* The URL to get a single remote context using default template and language is:
http://localhost/chameleon/cwc2/cwc2.php?service=VCG&request=
GetApplication&version=0.1.0&CONTEXTS=
http://localhost/chameleon/cwc2/contexts/gmap_context.xml
* The URL to get multiple local contexts using default template and language is:
http://localhost/chameleon/cwc2/cwc2.php?service=VCG&request=
GetApplication&version=0.1.0&CONTEXTS=world_context.xml,gmap_context.xml
* The URL to get multiple remote context using default template and language is:
http://localhost/chameleon/cwc2/cwc2.php?service=VCG&request=
GetApplication&version=0.1.0&CONTEXTS=
http://localhost/chameleon/cwc2/contexts/world_context.xml,http://localhost/cham
eleon/cwc2/contexts/gmap_context.xml
* The URL to get a fully remote, bilingual application using multiple contexts
is:
http://localhost/chameleon/cwc2/cwc2.php?service=VCG&request=
GetApplication&version=0.1.0&LANGUAGES=en-CA,fr-CA&TEMPLATES=
http://localhost/chameleon/cwc2/templates/sample_cwc2_en.html,http://localhost/
chameleon/cwc2/templates/sample_cwc2_fr.html&CONTEXTS=
http://localhost/chameleon/cwc2/contexts/world_context.xml,http://localhost/cham
eleon/cwc2/contexts/gmap_context.xml
* The URL to get a fully remote, bilingual application using multiple contexts,
and defining an SRS and BBOX:
http://localhost/chameleon/cwc2/cwc2.php?service=VCG&request=
GetApplication&version=0.1.0&LANGUAGES=en-CA,fr-CA&TEMPLATES=
http://localhost/chameleon/cwc2/templates/sample_cwc2_en.html,http://localhost/c
hameleon/cwc2/templates/sample_cwc2_fr.html&CONTEXTS=
http://localhost/chameleon/cwc2/contexts/world_context.xml,http://localhost/cham
eleon/cwc2/contexts/gmap_context.xml&srs=epsg:4326&BBOX=-180,-90,180,90
|
