JAX-RS-based domain resource extension |
SuperMap iServer supports publishing REST services using Restlet and JAX-RS. For details on Restlet mechanism, please refer to: JAX-RS Introduction.
In the REST implementation framework of SuperMap iServer JAX-RS mechanism, the highest level of resource class is com.supermap.services.rest.resources.JaxrsResourceBase, from which all resource implementation classes are directly or indirectly inherited.
As the further implementation of JaxrsResourceBase, com.supermap.services.rest.resources.JaxAlgorithResultSetResource<T> makes the implementation of resources that need to support the POST request easy.
Inherit from JaxrsResourceBase or .JaxAlgorithResultSetResource<T> and follow the JAX-RS standard to define the resource.
Note: 1 Please add @Component for the implementation class of the resource to indicate the service component associated with the resource, as shown below:
@Path("/addressmatch")
// Declare the business compnents that need to be used by the resource
@Component(interfaceClass = com.supermap.services.components.AddressMatch.class)
public class AddressMatchResource extends JaxrsResourceBase {
...
}
2 @produce and @Consumes can be omitted. The JAX-RS resources implemented based on iServer resource base class supports the xml, json, and rjson output formats, and the json parameter format by default.
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.
JaxrsResourceBase 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<Temperature> tempratureComponents=interfaceContext.getComponents(Temperature.class);
Temperature tempratureComponent=tempratureComponents.get(0);
In the REST resource implementation class in JAX-RS mechanism, SuperMap iServer provides the FreeMarker template, which is specified by the @Template annotation. The code segment is shown as below.
@GET
@Path("{cityname}")
@Template(name = "temperature.ftl")
public String getMapImageURI(
@PathParam("cityname") String cityname,
@Context HttpServletRequest request) {
...
}
FreeMarker is a tool for generating text output based on templates. The *.ftl file needs to be placed in :///templates of the Jar package. In the @Template annotation, name indicates the name of the *.ftl file.
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.
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, which is in the Jar package, 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.
The sample project can be found in %SuperMap iServer_HOME%\samples\code\DSSE_JSR.
For sample direction, please refer to Defining REST Resource based on JAX-RS.
Users need to import the whole project file and compile it as a JAR package (please refer to dsse_jsr.jar), and then place the JAR package in %SuperMap iServer_HOME%\webapps\iserver\WEB-INF\lib. After that, configure service configuration file (refer to service configuration file structure) and start iServer service.
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 JAX-RS mechanism, the extension of REST resource decoder should follow the JAX-RS standard. In the implementation of javax.ws.rs.ext.MessageBodyWriter, @Provider indicates the custom MessageBodyProvider used, and @Produces indicates the specified media type.
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.
The parameter format supported by the custom REST resource is json.
In the JAX-RS mechanism, the extension of REST resource decoder should follow the JAX-RS standard. In the implementation of javax.ws.rs.ext.MessageBodyReader, @Provider indicates the custom MessageBodyProvider used, and @Consumes indicates the specified media type.
The extension process is similar to Extending a Decoder 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.