Chameleon Service Instance Users Guide

Getting Started

Please refer to the Chameleon 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.

Basic Concepts

The Chameleon 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 Chameleon 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 Chameleon Service Instance. The Chameleon 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, Chameleon 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.

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 the Chameleon Service Instance, 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 Chameleon Service Instance supports two REQUESTs, described below.

GetCapabilities

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 / Optional	Description
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 / Optional	Description
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=,,,

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 Chameleon Service Instance will only work with data that is accessible via WMS

The Chameleon 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.