CWC2 Service Instance - version 2.0

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 - they do not necessarily have to have any of the Chameleon engine running on their local machine (so long as it is running on the machine providing the service). The Service Instance is invoked through a specially-constructed URL which contains pointers (parameters) to an Application Template and a context. (There are examples of these URLs throughout this document.)

A service exception describes 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 generates and returns a service exception instead of the requested 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.

For an example of a service exception, see the Testing the Service Instance section.

This section describes parameters that are common to, and mandatory in, every invocation of the Service Instance. Valid values for these parameters depend on how the service instance is being invoked and are described in the Supported REQUESTs section below.

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.

VERSION

The VERSION parameter indicates the protocol version number to be used.

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.

Example URL

The following is the most basic valid URL to invoke a Service Instance, using all three of the above required parameters:

http://localhost/chameleon/cwc2/cwc2.php?service=VCG&version=0.1.0&request=GetApplication
        

Note: the GetCapabilities REQUEST is not implemented for Chameleon 2.0.

The purpose of the GetCapabilities operation is to describe the operating parameters of a particular Service Instance so that clients can use the service in an effective manner.

Request Parameters

The GetCapabilities operation has three mandatory parameters: SERVICE, REQUEST, and VERSION, described in the following table:

Please see the Common Invocation Parameters section above for details on the above parameters.

Response

The response to the GetCapabilities request is an XML document. This feature is not yet implemented, but will be in a future version.

Example URL

Once the GetCapabilities request is operational, the following URL would retrieve the capabilities information:

http://localhost/chameleon/cwc2/cwc2.php?service=VCG&version=0.1.0&request=GetCapabilities
        

The purpose of the GetApplication operation is to generate a client application based on the parameters provided when invoking the service.

Request Parameters

The GetApplication operation has three mandatory parameters and six optional parameters, which are described in the following table:

Please see the Common Invocation Parameters section above for details on the required parameters.

LANGUAGES

A list of language specifiers separated by commas. Languages are specified in the form of a two-character (lowercase) language code followed by a dash and then a two-character (uppercase) country code (e.g., en-CA). Service Instances list supported languages in the capabilities document. Unsupported languages may be requested, but the Service Instance uses the default language in these case. In addition, if the LANGUAGE parameter is not set, the default language (set in the Service Instance configuration file) is used.

This parameter is optional unless TEMPLATES parameter is set, in which case it becomes mandatory.

TEMPLATES

A list of application template paths or URLs separated by commas. A template is identified either by a relative (to the template root directory specified in the Service Instance configuration) path on the server or by a URL to a Web-accessible template. The templates are listed in the same order as their related language specifiers in the LANGUAGES parameter, 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.

Example URL

The following URL could be used to support a bilingual application using remote context files:

http://localhost/chameleon/cwc2/cwc2.php?
    service=VCG
    &version=0.1.0
    &request=GetApplication
    &LANGUAGES=en-CA,fr-CA
    &TEMPLATES=http://localhost/chameleon/cwc2/templates/sample_cwc2_en.html,
          http://localhost/chameleon/cwc2/templates/sample_cwc2_fr.html
        

This parameter is optional unless LANGUAGES is set, in which case it becomes 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 either by a relative (to a directory specified in the Service Instance configuration) path on the server or a URL to a Web-accessible context. The contexts are loaded in the order in which they appear in this list, and the projection and spatial extents are taken from the last context loaded (see Common Problems below). The order of these 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.

Example URL

The following URL could be used to get multiple remote contexts while using the default template and language:

http://localhost/chameleon/cwc2/cwc2.php?
    service=VCG
    &version=0.1.0
    &request=GetApplication
    &LANGUAGES=en-CA,fr-CA
    &TEMPLATES=http://localhost/chameleon/cwc2/templates/sample_cwc2_en.html,
          http://localhost/chameleon/cwc2/templates/sample_cwc2_fr.html
        

This parameter is optional. The Service Instance defines a default value context in its configuration file.

LANGUAGE

The language to use to display the application. This causes one of the templates to be selected from those specified as available in the TEMPLATES parameter. Typically, this parameter only needs to be used when a non-default language is being requested.

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 than the default. By default, the Service Instance uses 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 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 than the default. By default, the Service Instance uses 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
        

Example URL

The following URL could be used to get a fully remote, bilingual application using multiple contexts, and defining an SRS and BBOX:

http://localhost/chameleon/cwc2/cwc2.php?
    service=VCG
    &version=0.1.0
    &request=GetApplication
    &LANGUAGES=en-CA,fr-CA
    &TEMPLATES=http://localhost/chameleon/cwc2/templates/sample_cwc2_en.html,
          http://localhost/chameleon/cwc2/templates/sample_cwc2_fr.html
    &SRS=epsg:4326
    &BBOX=-180,-90,180,90
    &CONTEXTS=http://localhost/chameleon/cwc2/contexts/world_context.xml,
          http://localhost/chameleon/cwc2/contexts/gmap_context.xml
      

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 directories). 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
        

most likely will 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.

When specifying multiple CONTEXTS, the Service Instance loads them sequentially and uses 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 example, if you try to load the world_context.xml and the gmap_context.xml contexts (in that order) that come with the Service Instance, the world data is displayed in LCC projection and does not appear to 'line up' with the gmap data. The problem is that the LCC 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.