Restlet-based domain resource extension

SuperMap iServer supports publishing REST services using Restlet and JAX-RS. For details on Restlet mechanism, please refer to REST Service Publishing Mechanism.

• Defining REST Service
  • 1 Resource base class
  • 2 Getting service components
  • 3 Defining HTML representation
  • 4 Resource configuration
  • 5 Example
• Extending Encoder
• Extending Decoder

Defining REST Service

1 Resource base class

In the REST implementation framework of SuperMap iServer Restlet mechanism, the highest level of resource class is ResourceBase, from which all resource implementation classes, like all the implementation classes of resources already provided by SuperMap iServer, are inherited.

When extending REST resource, the resource must inherit from ResourceBase or its child classes. SuperMap iServer abstracts a lot of abstract classes from the ResourceBase class and the final implementation classes, indicating different types of resources. To extend REST resources in a more efficient way, users can extend based on the abstract class, which has the most common functions with the target resource.

For abstract classes of REST resources in SuperMap iServer, please refer to JavaDoc: package com.supermap.services.rest.resources.

Here we take the SimpleAlgorithmResultResourceBase abstract class as an example. To implement a resource through inheriting from this class, the abstract methods in the table below need to be implemented.

Note: Please add @Component for the implementation class of the resource to indicate the service component associated with the resource.

2 Getting service components

SuperMap iServer publishes the service components as Web services through the corresponding service interfaces. In the implementation class of the resource, GIS capabilities of the service components obtained from the service interface context.

ResourceBase provides the getInterfaceContext() interface, which can be directly used by the implementation class of the resource to get service component context, therefore getting service components. The code segment is as follows:

                InterfaceContext interfacecontext=super.getInterfaceContext();
                List<FirstComponent> firstComponents=interfacecontext.getComponents(FirstComponent.class);
                FirstComponent firstComponent=firstComponents.get(0);

3 Defining HTML representation

The default formats supported by custom REST resources are xml, json, and rjson. If the FreeMarker template is defined, HTML format will be supported.

FreeMarker is a tool for generating text output based on templates. In the REST framework of SuperMap iServer, ${resource.content.*} in the *.ftl template file represents the representation result. In Restlet mechanism, the file name must be identical to the ID of the configuration item of the resource. The *.ftl file needs to be placed in :///templates of the Jar package.

SuperMap iServer provides some variables for users to create *.ftl templates, therefore obtaining resource information. For more details, please refer to FreeMarker Variables Provided by iServer.

4 Resource configuration

Firstly, understand module configuration file and resource configuration file through Configuration File Instruction. When publishing domain component as REST resource, the two configuration files need to be created. The two files are packaged into the Jar package, enabling the efficient usage of the extended module and the management of the administrator.

The module configuration file is located in Jar:///META-INF/extensions/services/rest.

The location of the resource configuration file is specified by resourceFiles in the module configuration file.

Package the resource configuration with the resource implementationo class and FreeMarker template into a Jar package and place the Jar package in %SuperMap iServer_HOME%/webapps/iserver/WEB-INF/lib. Then start SuperMap iServer service.

5 Example

See %SuperMap iServer_HOME%/samples/code/Temprature_Restlet . This sample realizes the weather query based on Restlet. For how to use it, please see readme.txt in the project folder.

Extending Encoder

The default output formats supported by the custom REST service include xml, json, and rjson. If the FreeMarker template is defined, HTML format will be supported. More output formats will be supported by domain resources through extension.

In the REST implementation framework of SuperMap iServer, the com.supermap.services.rest.encoders.Encoder abstract class is provided for encoders. All encoders, like ImageEncoder, JsonEncoder, SceneEncoder, StreamEncoder, TemplateEncoder, XMLEncoder, etc. provided in SuperMap iServer, are inherited from this class.

When extending encoder, users can inherit from the Encoder abstract class and implement its abstract classes, or inherit from an existing encoder and override its methods. Certain methods are listed in the table below. For more details, please refer to JavaDoc.

Users can implement a custom encoder by inheriting from the Encoder abstract class or its child classes and implement or override the methods in the table above.

The extension process is similar to Extending an Encoder for extending an existing REST resource.

Note: The response media type is decided by the suffix of the HTTP request URI. Please refer to Relationship between URI Suffix and Media Types.

Extending Decoder

The default parameter passing format of SuperMap iServer is json. Also, xml format is supported for parameter passing.

X-RequestEntity-ContentType and X-UrlEntity-ContentType message headers in the HTTP request respectively indicate the types of request parameters and URI query parameters. When specified as application/xml, SuperMap iServer will decode the parameters in the HTTP request as they are in xml format. If not specified, json format will be regarded as the default format.

In the REST implementation framework of SuperMap iServer, the com.supermap.services.rest.decoders.Decoder abstract class is provided for decoders. All decoders, like JsonDecoder, XMLDecoder provided in SuperMap iServer, are inherited from this class.

When extending decoder, users can inherit from the Decoder abstract class and implement its abstract classes, or inherit from an existing decoder and override its methods. Certain methods are listed in the table below. For more details, please refer to JavaDoc.

Users can implement a custom decoder by inheriting from the Decoder abstract class or its child classes and implement or override the methods in the table above.

The extension process is similar to Extending a Decoder for extending an existing REST resource.