Extensions are modular and usually offer functions suited for specific tasks. On its own, JMap Web provides a basic set of features. JMap Web extensions allow the customization and the inclusion of new features to deployments based on the JMap Web application template.

Just like JMap Pro extensions, JMap administrators may choose which extensions they want to include during the application deployment assistant. The selected extensions will be loaded as part of JMap Web’s initialization process.

Similar to a JMap Javascript library, a JMap Web extension consists of a collection of Javascript files, style sheets (CSS) and resources (images, sounds, etc.).

You can use the JMap Web extension builder tool to rapidly scaffold a Web extension’s files. Open a command line/terminal window or use a file browser and navigate to the tools / web extension builder directory of the JMap 7 SDK installed on your computer.

Using the JMap Web extension builder

You will find a webextensionbuilder.xml file. Open it in a text editor. Edit it in order to specify a list of arguments that will allow you to create your own extension. The following arguments are required:

Example of a modified webextensionbuilder.xml file used to create your extension:

<project name="JMap 7 SDK - Web Extension Builder" basedir="." default="run">

<!-- set global properties for this build -->

<property file="../../sdk.properties"/>

<target name="run">

<java fork="true" classname="jmap.sdk.tools.webextensionbuilder.WebExtensionBuilder"

classpath="webextensionbuilder.jar;${sdk_classpath}">

<!-- Use default parameter values. Uncomment following line to use other parameters -->

<arg line="-fullname 'Web SDK Documentation Example' -namespace Example -version 1.0 -dest output"/>

</java>

</target>

</project>

Creating the extension using ant on the command line

From the terminal, invoke the ant script:

ant -f webextensionbuilder.xml

Creating the extension using ant through Eclipse

To create a JMap Web extension using Eclipse, the following should be installed on your system, make sure a Java Developer Kit is installed and configured as the default JRE in Eclipse:

You should also make sure that your JDK’s tools.jar file is added to Eclipse’s Ant Runtime Configuration:

Execute the build task by opening the webextensionbuilder.xml file in Eclipse. Execute the run target.

Understanding the extension’s files

After the ant script’s execution, you will have an extension’s boiler plate code at the specified location.

output

└── web_sdk_documentation_example

├── actions

── build.xml

├── readme.markdown

└── src

└── Example

└── SampleAction.java

├── assets

├── css

└── web_sdk_documentation_example.css

└── js

└── web_sdk_documentation_example.js

└── extension.json

7 directories, 6 files

By default and for demonstration purposes, an AJAX Dispatcher action called web_sdk_documentation_example_sample_action is included. For more details on AJAX Dispatcher actions, refer yourself to the Sending Server Requests and Custom Actions example.

Your extension’s generated CSS and Javascript assets will be loaded during the JMap initialization process.

All other CSS or Javascript resources will need to be loaded programmatically in the generated Javascript file (in this case the web_sdk_documentation_example.js file).

Since extension files are loaded at runtime, it is important that you do not rename or move the generated CSS and Javascript files. The name of those files should always be the extension’s short name as defined in the extension.json file.

The source code of the generated Javascript file includes comments that describe the required properties and functions that make up your JMap Web extension. It is recommend that you read the contents of this file so that you can familiarize yourself with its content.

Among the generated files is extension.json. This file will serve as a manifest for JMap Server. It must contain valid JSON. This file must not be removed or renamed.

Interacting With OpenLayers

As previously mentioned, a JMap.app global variable is defined during initialization. One of that object’s responsibility is to capture a reference to your application’s Map.

JMap.app.map is your application’s instance of the ol.Map class. JMap’s Javascript libraries use the OpenLayers API in order to accomplish many tasks. Tasks such as layer manipulation, operations on coordinates/bounds as well as managing the map’s controls and popups.

OpenLayers offers a large gallery of development examples. It is recommended that you use this resource throughout your development as a way to familiarize yourself with their API. The gallery and the API documentation are indispensable resources that you should consult frequently.

Examples

This portion of the documentation offers examples of several tasks that can be accomplished in JMap Web extensions.

Managing Tools

Note: Knowledge of OpenLayer’s Class base type is strongly recommended before continuing with this documentation.

Several classes were developed in order to support various types of map interactions when touch/mouse events are performed. They are the following:

JMap.Html5Core.Tool.ToolManager: During the initialization process, a single instance of this class is produced and is made accessible via the JMap.app.clickToolManager variable. This object keeps track of all registered tools as well as the single currently activated tool. That object’s currentTool will be the recipient of the click and touch events.

JMap.Html5Core.Tool.Tool: Superclass from which all tools must inherit.

The following code creates a tool:

JMap.Html5Core.Tool.SampleTool = function(options){

var _this = this;

this.hasInterraction = true; this.name = 'SampleTool';

this.buttonDiv = document.createElement('div');

$(this.buttonDiv)

.attr({

'id' : 'SampleTool',

'class' : 'SampleToolClass'

})

.click( function(event){

JMap.app.clickToolManager.toggleUiTool(_this);

event.stopImmediatePropagation(); });

$('#JMapStandardToolBar').append(this.buttonDiv);

goog.base(this, options);

);

goog.inherits(JMap.Html5Core.Tool.SampleTool, JMap.Html5Core.Tool.Tool);

JMap.Html5Core.Tool.SampleTool.prototype.initializeInteraction = function() { this.interaction = new ol.interaction.Interaction({})

};

JMap.Html5Core.Tool.SampleTool.prototype.off = function()

{

goog.base(this, 'off');

};

JMap.Html5Core.Tool.SampleTool.prototype.on = function()

{

goog.base(this, 'on');

};

var sampleTool = new JMap.Html5Core.Tool.SampleTool({});

JMap.app.clickToolManager.addTool(sampleTool);

After it has been instantiated, you need to register it against the JMap.app.clickToolManager and activate it.

JMap.app.clickToolManager.addTool(sampleTool);

JMap.app.clickToolManager.setCurrentTool(sampleTool);

If a tool was already activated at the time that toggleUiTool() was called, that tool will be deactivated.

Working With Vector Layers

OpenLayers offers multiple classes allowing the visualization of various data sources. The ol.layer.Vector and ol.source.Vector classes are particularly useful to display vector data features created programmatically.

The following code excerpt creates and adds a vector layer to an initialized application. Using your own custom tool, you will be able to create Point geometries wherever click events are performed.

JMap.Html5Core.Tool.SampleTool = function(options){

var _this = this;

this.hasInterraction = true;

this.name = 'SampleTool';

this.vectorLayer = null;

this.layerSource = null;

this.buttonDiv = document.createElement('div');

$(this.buttonDiv)

.attr({

'id' : 'SampleTool',

'class' : 'SampleToolClass'

})

.click( function(event){

JMap.app.clickToolManager.toggleUiTool(_this);

event.stopImmediatePropagation();

});

$('#JMapStandardToolBar').append(this.buttonDiv);

goog.base(this, options);

);

goog.inherits(JMap.Html5Core.Tool.SampleTool, JMap.Html5Core.Tool.Tool);

JMap.Html5Core.Tool.SampleTool.prototype.initializeInteraction = function() {

this.layerSource = new ol.source.Vector({

wrapX: false

});

this.vectorLayer = new ol.layer.Vector({ source: layerSource, });

this.interaction = new ol.interaction.Draw({

id: 'SampleToolInterraction',

source: this.source,

type: 'Point',

style: new ol.style.Style({})

});

};

JMap.Html5Core.Tool.SampleTool.prototype.off = function(){

JMap.app.map.removeLayer(this.vectorLayer);

goog.base(this, 'off');

};

JMap.Html5Core.Tool.SampleTool.prototype.on = function()

{

JMap.app.map.addLayer(this.vectorLayer);

goog.base(this, 'on');

};

var vectorLayerTool = new JMap.Html5Core.Tool.SampleTool({});

JMap.app.clickToolManager.addTool(vectorLayerTool);

Similarly, as described in the previous example, the following code will register your newly created tool against the JMap.app.clickToolManager and activate it.

JMap.app.clickToolManager.addTool(vectorLayerTool);

JMap.app.clickToolManager.setCurrentTool(vectorLayerTool);

Editing Vector Data

Although vector data editing in JMap Web is now offered as part of JMap 7, the JMap Web public API does not offer methods to do so programmatically. However, you can use OpenLayers’s API to create, edit and delete your own features associated to your own vector layers that were created programmatically.

Here are a few links detailing OpenLayers’s vector data editing functions:

• Draw Features

• Custom Interactions

• Box Selection

• Draw and Modify Features

Working With Vector Styles

It is possible to define the appearance of your vector layer features. This is generally accomplished by associating a ol.style to your layer.

A Style may contain any of the properties described here in order to modify the appearance of layer features.

• Custom Polygon Styles

Recommendations

When in a production environment, it is recomended that your extension’s assets be minified in order to limit the number of HTTP requests on load. It also allows you to obfuscate your code up to a certain extent. We use Google’s Closure Compiler and recommend it.

As previously mentioned, if your extension has dependencies, they will need to be loaded programmatically in your extension’s generated javascript file.

OpenLayers’s API documentation is generated by parsing the source code’s comments. This means that methods and properties may not appear in the docs if they are not properly commented. Directly browsing OpenLayer’s source code may help you if something in their documentation is not clear.

Extension Development Workflow

Developers may want to operate differently when developing JMap Web extensions. The two following workflows tend to be preferred.

1. The developer works in the generated extension’s folder. They usualy modify the extension’s assets, copy the extension files to the $JMAP_HOME$/extensions/web directory, update their applications and test their changes in the updated application.

2. The developer works directly in the deployed application’s files.

Both approaches have their own pros and cons.

The first technique, while slower, allows for a safer and more incremental process. Keeping track of code changes is easier.

The second technique is faster, however you will need to consistently merge your changes to your version controlled checkout. This approach may also lead to data loss if you ever update your application and your changes were not included in your $JMAP_HOME$/extensions/web directory.

In addition to executing code in the user’s browser, a JMap Web extension may define actions that can leverage JMap Server’s API. These actions will be registered against your deployment’s AJAX Dispatcher service and may be triggered via HTTP requests.

A JMap Web extension can contain several actions. You also may create additional non-action classes that will be referenced within your actions.

Creating an Action

Create a class that inherits from AbstractHttpRequestAction. To follow along this example, the name of your class should be MyFirstAction.

package myextension;

import java.io.IOException;

import java.io.PrintWriter;

import javax.servlet.http.HttpServletRequest;

import javax.servlet.http.HttpServletResponse;

import jmap.http.ajax.servlets.AbstractHttpRequestAction;

public class MyFirstAction

extends AbstractHttpRequestAction

{

@Override

public void execute(HttpServletRequest request, HttpServletResponse response) throws IOException

{

}

}

As you may have noticed, the action requires the HttpServletRequest and HttpServletResponse classes in order to compile. Add Tomcat server’s servlet-api JAR to your build path. That particular JAR file may be found within the $JMAP_HOME$/tomcat/lib directory.

An action requires an execute method. That method will be called whenever an HTTP request specifically requesting your action is received by the AJAX Dispatcher.

For the purposes of this example, the following is a typical Hello World! action.

package myextension;

import java.io.IOException;

import java.io.PrintWriter;

import javax.servlet.http.HttpServletRequest;

import javax.servlet.http.HttpServletResponse;

import jmap.http.ajax.servlets.AbstractHttpRequestAction;

public class MyFirstAction extends AbstractHttpRequestAction

{

@Override

public void execute(HttpServletRequest request, HttpServletResponse response)

throws IOException

{

final PrintWriter writer = response.getWriter();

String name = request.getParameter("name");

if (name != null && name.trim() != "")

writer.print("Hello, " + name);

else

throw new IllegalArgumentException("Invalid argument. Must specify anameparameter.");

}

}

Producing a JAR File for Your Action

In order to be included as part of a JMap Web extension, your server-side Java code must be compiled and packaged as a single JAR file.

Using Ant

When using JMap 6.0 SDK’s webextensionbuilder tool (described in the Programming JMap Web Extensions section) to produce an extension’s boilerplate code, a SampleAction is provided as a starting point. A build.xml file is also provided. You can use that file with Ant to compile and produce your extension’s JAR file.

Copy your MyFirstAction.java file to your extension’s actions/src directory. Since the MyFirstAction class is defined within the myextension package, create a myextension directory under actions/src and put your MyFirstAction.java file in it. At this point, you should have the following items in your actions directory:

actions/

├── build.xml

├── readme.markdown

└── src

├── Example

└── SampleAction.java

└── myextension

└── MyFirstAction.java

3 directories, 4 files

Using the command line/terminal navigate to your extension’s actions directory and execute the following command.

ant -f build.xml

Once you have your JAR file, make sure it’s in your web extension’s actions directory.

Using Ant through Eclipse

As was the case when using the web extension builder tool, you may use Ant through Eclipse to produce your extension’s server jar file. This requires that a JDK is set as Eclipse’s default JRE and that the JDK’s tools.jar file is added to the Ant runtime configuration’s classpath. These steps were previously detailed here.

1. Open the your extension’s actions/build.xml file in Eclipse.

2. Execute the “package” ant target.

Once you have your JAR file, make sure it’s in your web extension’s actions directory.

Identifying Your Extension’s Actions

As part of your extension, the extension.json file informs JMap Server about itself. You must now indicate that the extension contains actions. Open that file in a text editor.

The actions property is an array that can contain several object literals each describing individual actions.

The actions array’s object literals must have the following property keys:

This snippet is how you would represent the MyFirstAction action as part of the web_sdk_documentation_example extension that was created earlier:

{

"actions": [

{

"name": "hello",

"className": "myextension.MyFirstAction",

"version": "1.0.0"

}

],

"fullname": "Web SDK Documentation Example",

"namespace": "Example",

"shortname": "web_sdk_documentation_example",

"version": "1.0"

}

Your extension may include as many actions as you want. Just be sure to include them within your extension’s extension.json file.

After editing the extension.json file, be sure that it contains valid JSON. JSONLint is an online JSON validator that can be used for that purpose.

Calling your action from your JMap Web Extension

As previously mentioned, your action’s execute method will be called once the AJAX Dispatcher receives an HTTP request that specifies your action’s name as a parameter.

The following example demonstrates how you can submit an HTTP Request to your action using jQuery.ajax(). To test this, you can either include this snippet in your extension’s init function or copy and paste it in a browser’s Javascript console currently logging your deployed application.

$.ajax(JMap.app.ajaxDispatcher,{

data: {

"action": "hello", // The action name as defined in the extension.json file.

"name": "Developer" // The name parameter as expected by the action.

}

}).error(function(jqXHR, textStatus, errorThrown) {

alert(textStatus);

}).success(function(data, textStatus, jqXHR) {

alert(data);

});

In order to deploy an extension with your JMap Web deployment, you must first install the extension on your JMap Server. You install a JMap Web extension by copying its parent directory (named after the extension’s shortname) to the $JMAP_HOME$/extensions/web directory.

As part of the JMap Web application deployment process, you should now see a list of Web extensions you may wish to include. Choose your newly created “Web SDK Documentation Example” and complete the wizard.

The JMap Web application template offers many actions to facilitate JMap Server interactions. This section will present some of them and how you can use them.

Note: The majority of actions require map state information as parameters. For the most part, these can be obtained using OpenLayers’s API.

All examples in this section refer to a deployment based on the The World project. The deployment covers the project’s complete extent and includes the following layers: “Base” and “Cities”. Refer yourself to the following screen shots in order to create a similar deployment.

'extractelements' Action

The extractelements action provides a list of a JMap layer’s elements.

The ‘geometry’ request type

The geometry request will extract elements that intersect or are contained within a supplied geometry.

Parameters

The following is the list of parameters that can be provided to the extractelements action.

Example

Performs an element extraction request for the “Cities” layer around the Scotland area.

$.ajax(JMap.app.ajaxDispatcher, {data: {

'action': 'extractelements',

'request': 'geometry',

'geometry': 'POLYGON((-6.378882 54.903806,-1.336158 54.903806,-1.336158 59.540037,-6.378882 59.540037,-6.378882 54.903806))',

'res': JMap.app.map.getResolution(),

'bbox': JMap.app.map.getExtent().toBBOX(),

'layers': 'Cities'

}}).success(function(data, textStatus, jqXHR) {

console.log(data);

});

Response

Each element’s ID, geometry (supplied as a WKT formatted string), attribute values, bounds and centered point are returned. The layer’s bound attributes are also included as well as their SQL type. An element’s attributes’s index corresponds to the layer’s attributes as configured in JMap Admin. If elements from many layers match the request parameters, an array of these object literals will be returned.

{

"layerId": 7,

"elementAttributes": [

{

"sqlType": 12,

"name": "CITY"

},

{

"sqlType": 12,

"name": "COUNTRY"

},

{

"sqlType": 12,

"name": "CAP"

},

{

"sqlType": 4,

"name": "POP2000"

}

],

"elements": [

{ "centeredPoint": {

"x": -1.3899999735879476,

"y": 54.910001831054686

},

"bounds": {

"x": -1.3899999735879476,

"width": 0,

"y": 54.910001831054686,

"height": 0

},

"attributeValues": [

"Sunderland",

"UK - England and Wales",

"0",

181100

],

"geometry": "POINT(-1.3899999735879476 54.910001831054686)",

"id": 622

},

{

"centeredPoint": {

"x": -4.2699998496102864,

"y": 55.87000091552734

},

"bounds": {

"x": -4.2699998496102864,

"width": 0,

"y": 55.87000091552734,

"height": 0

},

"attributeValues": [

"Glasgow",

"Scotland",

"0",

610700

],

"geometry": "POINT(-4.2699998496102864 55.87000091552734)",

"id": 624

},

{

"centeredPoint": {

"x": -3.2200001357125814,

"y": 55.949998931884764

},

"bounds": {

"x": -3.2200001357125814,

"width": 0,

"y": 55.949998931884764,

"height": 0

},

"attributeValues": [

"Edinburgh",

"UK - England and Wales",

"0",

382600

],

"geometry": "POINT(-3.2200001357125814 55.949998931884764)",

"id": 625

},

{

"centeredPoint": {

"x": -2.9999998686837728,

"y": 56.469999389648436

},

"bounds": {

"x": -2.9999998686837728,

"width": 0,

"y": 56.469999389648436,

"height": 0

},

"attributeValues": [

"Dundee",

"Scotland",

"0",

148900

],

"geometry": "POINT(-2.9999998686837728 56.469999389648436)",

"id": 627

},

{

"centeredPoint": {

"x": -2.1000000117349202,

"y": 57.14999969482422

},

"bounds": {

"x": -2.1000000117349202,

"width": 0,

"y": 57.14999969482422,

"height": 0

},

"attributeValues": [

"Aberdeen",

"Scotland",

"0",

188500

],

"geometry": "POINT(-2.1000000117349202 57.14999969482422)",

"id": 628

},

{

"centeredPoint": {

"x": -1.6000000117349202,

"y": 54.99999816894531

},

"bounds": {

"x": -1.6000000117349202,

"width": 0,

"y": 54.99999816894531,

"height": 0

},

"attributeValues": [

"Newcastle upon Tyne",

"UK - England and Wales",

"0",

980000

],

"geometry": "POINT(-1.6000000117349202 54.99999816894531)",

"id": 1899

}

]

}

‘layerinfo’ Action

The layerinfo action provides details regarding layers of the deployment’s associated project.

The ‘geteditablelayers’ request type

The geteditablelayers request will return layer various layer details on which the currently authenticated user may perform data editing tasks.

Parameters

This action does not require any parameters. Instead, it uses the current session information to perform this operation.

Example

$.ajax(JMap.app.ajaxDispatcher, {

data: {

'action': 'layerinfo',

'request': 'geteditablelayers'

}

}).success(function(data, textStatus, jqXHR) {

console.log(data);

});

Response

The server response exposes an array of editableLayers object literals. Each of the array’s objects contains the following keys:

forms are returned as an array of object literals. They have the following structure:

Example

This is an example of a geteditablelayers response. You may have different results. In any case, they should reflect the state of your configured permissions and forms.

{

"editableLayers": [

{

"offset": {

"x": 9.5367431640625e-7,

"y": -3.186320304870577 },

"permissions": 0,

"id": 4,

"fields": [

{

"name": "COUNTRY",

"serverDataType": 12

},

{

"name": "CONTINENT",

"serverDataType": 12

},

{

"name": "POP_1994",

"serverDataType": 8

},

{

"name": "POP_GRW_RT",

"serverDataType": 8

},

{

"name": "POP_0_14",

"serverDataType": 8

},

{

"name": "POP_15_64",

"serverDataType": 8

},

{

"name": "POP_65PLUS",

"serverDataType": 8

},

{

"name": "POP_AREA",

"serverDataType": 8

}

],

"idFieldName": "JMAP_ID",

"forms": []

},

{

"offset": {

"x": 0.56195068359375,

"y": 13.687942504882812

},

"permissions": 0,

"id": 6,

"fields": [

{

"name": "LAKE_NAME",

"serverDataType": 12

},

{

"name": "VOLUME_CKM",

"serverDataType": 8

},

{

"name": "AREA_SKM",

"serverDataType": 8

}

],

"idFieldName": "JMAP_ID",

"forms": []

},

{

"offset": {

"x": 20.934576233500025,

"y": 10.050437668683657

},

"permissions": 0,

"id": 5,

"fields": [],

"idFieldName": "JMAP_ID",

"forms": []

},

{

"offset": {

"x": 16.215000694478334,

"y": 16.463705277985326

},

"permissions": 0,

"id": 3,

"fields": [

{

"name": "HYD_NAME", "

serverDataType": 12

},

{

"name": "LENGTH_KM",

"serverDataType": 4

}

],

"idFieldName": "JMAP_ID",

"forms": []

},

{

"offset": {

"x": 31.452202349999993,

"y": -14.421794805000005

},

"permissions": 0,

"id": 2,

"fields": [

{

"name": "CONTINENTNAME",

"serverDataType": 12

}

],

"idFieldName": "JMAP_ID",

"forms": []

},

{

"offset": {

"x": 1.6169597031546061,

"y": 8.079999999999998

},

"permissions": 15,

"id": 7,

"fields": [

{

"name": "CITY",

"serverDataType": 12

},

{

"name": "COUNTRY",

"serverDataType": 12

},

{

"name": "CAP",

"serverDataType": 12

},

{

"name": "POP2000",

"serverDataType": 4

}

],

"idFieldName": "JMAP_ID",

"forms": [

{

"permissions": 0,

"name": "Form",

"json": "{\"formSections\":[{\"name\":\"Section 1\",\"nbRows\":3,\"fields\":[{\"$ATTRIBUTE_NAME\":\"CITY\",\"$ROW\":0,\"$MASKFORMATTER\":\"\",\"$COL\":0,\"$INPUT_TYPE\":\"$INPUT\",\"$MULTILINE\":false,\"$PREFIX\":\"CITY\",\"$ALIGNMENT\":\"LEFT\",\"$REQUIRED\":true,\"$MAX_NUMBER_CHARACTERS\":255,\"$COLSPAN\":1,\"$WIDTH\":100,\"$TOOLTIP\":\"\",\"$ATTRIBUTE_SQL_TYPE\":12,\"$READ_ONLY\":false}]}",

"id": 1,

"type": "LAYER_ATTRIBUTES_FORM",

"uidAttributeName": null

}

]

}

]}

‘loadformdata’ Action

The loadformdata action provides external form data for a requested layer element.

Parameters

loadformdata expects the following parameter:

Example

This example refers to another project for which external forms were configured.

var data = { elementId: 6, formId: 2, layerId: 1,

listFields: [],

"mapValues": {

"MOBILE_JMAP_ID": 6,

"MOBILE_JMAP_GEOMETRY": "POINT(-8189010.0 5701129.5)",

"AUTHOR": "jrhaddad",

"CREATION_TIME": 1415767972000,

"MODIFICATION_TIME": 1418400517000,

"ABR_CODE": "342",

"ABR_NAME": "ES34F",

"ABR_LOC_TYPE": "Arrêt bus",

"ABR_WHEEL_CHAIR": "Non accessible",

"ABR_DATE_INSP": null,

"ABR_STATUS": null

}

};

$.ajax(JMap.app.ajaxDispatcher, {data: {

'action': 'loadformdata',

'data': JSON.stringify(data)

}}).success(function(data, textStatus, jqXHR) {

console.log(data);

});

Response

The server responds by providing a two dimensional rows array of Javascript object literals representing field values. Each item in the rows array represents a row of data. Multiple rows are returned when obtaining data that was entered using a EXTERNAL_ATTRIBUTES_SUB_FORM type form.

The name of the form field, its value and the data’s SQL type are returned.

{

"rows": [

[

{

"name": "insp_abribus.id_inspection",

"value": 5,

"type": 4

},

{

"name": "insp_abribus.id_abribus",

"value": 6,

"type": 4

},

{

"name": "insp_abribus.date_inspection",

"value": 1415854800000,

"type": 93

},

{

"name": "insp_abribus.etat",

"value": "Bon état",

"type": 12

},

{

"name": "insp_abribus.observations",

"value": "Tout est ok",

"type": 12

}

]

]

}

The following class diagram shows a simplified version of JMap Pro’s architecture.

The JMap Server SDK (JMap 7 SDK) is comprised of documents, source code examples and tools to help developers customize JMap applications and extend their functionality.

JMap is made up of several different parts. Its main parts are: JMap Server, JMap Admin, JMap Pro, JMap NG, JMap Web, and JMap Survey. Each part is based on its own technological environment, which determines how programming is carried out.

The following table describes the technological environment of each JMap component.

Two coordinate systems are used in JMap Pro programming: the WC or World Coordinates system and the DC or Device Coordinates system. The WC system is the system used for the original data and the DC system is used for the screen that will display the map.

WC

All the geometry coordinates in JMap are in WC. For example, if your data uses the MTM zone 8 projection, the values of the coordinates will be similar to (300 000, 5 000 000). If your data is not projected, it will be in longitude and latitude and its range will be from -180 to 180 degrees east-west and from -90 to 90 degrees north-south

DC

The computer screen used to display the map is divided into pixels with the coordinates (0,0) showing on the top left part of the screen. This is the DC system. When you are working with mouse-clicked events (i.e., MouseClicked) in a JMap application, you are working with DC coordinates contained in the event and expressed in pixels.

Transforming coordinates between WC and DC

In JMap programming, WC coordinates must frequently be transformed into DC and vice-versa. When the map elements of a layer are drawn on the screen, their coordinates are converted from WC to DC on the fly in order to light up the appropriate pixels on the screen. However, when a mouse click occurs on the map, the DC coordinates of the mouse cursor are transformed into WC coordinates in order to select the appropriate element on the map.

The K2DTransform class contains an affine transformation matrix used to convert data between the DC and WC systems. It provides methods to transform the coordinates in both directions. Each map in JMap (View class) has its own transformation instance.

The following source code example demonstrates how to transform WC coordinates into DC.

K2DTransform transform = ...

Point pointWC;

Point pointDC;

// Transform a point from WC to DC

pointWC = new Point.Double(100., 100.);

pointDC = transform.transform(pointWC);

// Transform a point from DC to WC

pointDC = new Point.Double(100., 100.);

pointWC = transform.transformInv(pointDC);

The following source code example demonstrates how to transform DC coordinates resulting from a mouse click event to WC. The transformation is obtained from the view.

View view = ...

K2DTransform transform = view.getTransform();

MouseEvent e = ...

Point pointWC = transform.transformInv(new Point.Double(e.getX(), e.getY()));

The following source code example demonstrates how to transform DC coordinates using a mouse click event. This simple method is only available from a tool class derived from the Tool class.

Point pointWC = Tool.toWCPoint(e);

Rectangle transformations (normal or inverted) must be performed with caution: if a rotation is applied to a view, the rectangle that is returned could be overwritten. To prevent this problem, it is preferable to make calculations on an oriented rectangle initialized from the rectangle to be transformed.

View view = ...

final ViewState viewState = view.getViewState();

// Computes the display bounding box of the selection

final Rectangle displaySelectBounds = view.getLayerManager().getDisplaySelectedBounds(viewState, true);

if (displaySelectBounds != null)

{

// Transforms the display bounding box into a WC extent.

final OrientedRectangle selectBounds = viewState.getTransform().transformInv(

new OrientedRectangle.Double(displaySelectBounds)

);

view.zoom(selectBounds);

view.refresh()

}

The purpose of this section is to guide Java developers in developing mapping applications based on JMap Pro and JMap Server 7 using JMap’s Java API.

Although the JMap Pro application can be customized, it is strongly recommended to implement all new features and customizations by developing extensions with JMap’s Java API.

JMap Pro is a Java-based client application. It can run as a Java applet in a browser, as a standalone JavaWebStart (JNLP) application or as a standalone application launched at the command line (which is especially useful for development). In all cases, the application is the same, and all extensions developed are compatible.

JMap Server is a server application developed in Java. You can develop extensions for JMap Server using JMap’s Java API.

Setting up the Environment

Ant

For programming, the JMap 7 SDK uses Ant to perform various tasks using scripts. Ant can be downloaded from http://ant.apache.org.

When used from Eclipse, Ant may be unable to find the Java compiler in order to compile classes. In such a case, you must add a reference to the tools.jar library provided with the Java JDK in the Ant configuration. For more information, refer to this article: http://wiki.eclipse.org/FAQ_Why_can’t_my_Ant_build_find_javac%3F.

Eclipse

Eclipse is the preferred Java development environment for JMap. It can be downloaded from this address: http://www.eclipse.org. However, it is quite possible to develop JMap applications using the environment and tools of your choice. The following information applies to the Eclipse Luna (version 4.4) environment.

Integrate JMap 7 SDK as an Eclipse project

To simplify development, it is recommended to integrate the JMap 7 SDK as an Eclipse project. Your development should be in projects that are separate from the SDK to keep it intact as a source of reference.

1. In an Eclipse worskpace (existing or new), create a Java project for the JMap 7 SDK.

   File -> New -> Java Project

2. Select the path of the JMap 7 SDK that was specified when it was installed. To do this, you must disable the Use default location option to let Eclipse browse a folder outside of the current workspace. The project name is set automatically when the folder is selected.

3. Press Finish.

Create a new project

To start new development work using the JMap 7 SDK (such as creating a new JMap extension), it is recommended to create separate projects. Each new project should point to the libraries distributed with the SDK to allow for compilation. The example below shows how to create a new JMap project.

1. In the same Eclipse workspace containing the project for the JMap 7 SDK, create a new Java project.

   File -> New -> Java Project

2. Give your project a name then press Next.
3. Select the Projects tab and press Add.
4. Select the JMap SDK project. All of the SDK’s libraries will become available for your project. Press OK.
5. Press Finish.

Examples

The JMap 7 SDK comes with many examples located in the JDK_HOME/examples folder.

The Ant script build_examples.xml is used to compile and run the examples.

Many simple examples can be run in JMap Pro from a unique GUI using the Showcase extension.

The Hello World extension demonstrates a basic JMap Pro client extension that communicates with a JMap Server extension.

The Webextensions extension shows how to develop an action that can respond to JMap Web queries (refer to JMap Web Development).

In JMap, map elements are objects (points, lines, polygons, text, etc.) that make up the map. The classes of these elements are all derived from the abstract class K2DElement. Map elements are organized into layers that are displayed in a JMap application within a view (View class). Each map element is associated with a geometry (Geometry interface) and has a digital identifier as well as a certain number of attributes. The map element does not directly contain any geometry information. Instead, it is the associated geometry that contains all of the geometry coordinates. Element identifiers found within the same layer must be unique. The GeneratedUniqueId() utility method of the K2DElement abstract class allows you to generate a sequence of unique identifiers for the elements.

Creating map elements

The following example demonstrates how to create map elements:

// Create a point geometry Point

pointGeometry = new Point.Double(100., 100.);

// Create the element using the geometry, null attributes and auto generated id

K2DPoint point = new K2DPoint(pointGeometry, null, K2DElement.generateUniqueId());

// Create a line geometry Point

pointGeometry1 = new Point.Double(100., 100.);

Point pointGeometry2 = new Point.Double(200., 200.);

Line lineGeometry = new Line(pointGeometry1, pointGeometry2);

// Create some attributes

String attrib1 = "some value";

Integer attrib2 = new Integer(999);

// Create the element using the geometry, 2 attributes and auto generated id

K2DPolyline line = new K2DPolyline(lineGeometry, new Object[] {attrib1, attrib2}, K2DElement.generateUniqueId());

Element attributes

Map elements normally have values for their attributes. These values are the descriptive data of the map elements. All elements within the same layer possess the same list of attributes (same names, same types). Note that the elements contain only the values of the attributes (table or chart of objects) and not their definition. The definition of these attributes is managed at the layer level, using the Attribute class.

The list of attributes for the elements of a layer is determined by the JMap administrator when the layer (linked attributes) is created. The types of attributes are defined using Java constants for the SQL types (java.sql.Types class).

Element attributes are used for many functions such as tooltips, labels, thematics, and filtering.

The following example demonstrates how to access the values of element attributes:

K2DElement element = ... Object[] attributeValues = element.getAttributes();

for (int i = 0; i < attributeValues.lenght; i++)

{

System.out.println(i + " : " + attributeValues[i]);

}

The following example demonstrates how to access the definition of a layer’s attributes.

VectorLayer layer= ...

Attribute[] attributes = layer.getAttributeMetaData();

for (int i = 0; i < attributes .lenght; i++)

{

System.out.println(i + " name : " + attributes[i].getName());

System.out.println(i + " title : " + attributes[i].getTitle());

System.out.println(i + " type: " + attributes[i].getType());

}

Element style

When elements are drawn on the map, a style object is used to determine the visual aspects of the elements. Instances of the Style class have properties such as line color, fill color, letter font, transparency, etc. Each layer will have one or more styles. The style used for displaying the elements is based on the scale of the map and whether or not it contains thematics. Thematics dictate the style of the displayed elements based on the attribute values of these elements.

The following example demonstrates how to obtain the style used for a layer according to a particular scale. Here the presence of thematics on the layer is not taken into account.

K2DElement element = ...

VectorLayer layer = ...

Style style = layer.getStyle(view.getScaleFactor());

The following example demonstrates how to obtain the style used to display a specific element at a given scale. The resulting style does not take into account the presence of thematics on the layer.

K2DElement element = ...

VectorLayer layer = ...

Style style = layer.getStyle(element, view.getScaleFactor());

Style properties can be modified by calling the methods of the Style class. The following example demonstrates how to modify the style parameters of a layer of polygons at the current map scale.

VectorLayer layerOfPolygons = ...

Style style = layerOfPolygons.getStyle(view.getScaleFactor());

style.setBorderColor(Color.BLACK);

style.setFillColor(Color.BLUE);

style.setTransparency(.5f); // 50% transparent

Bounding rectangle on display

The bounding rectangle of a displayed map element is the smallest rectangle in device coordinates (DC) that completely contains the element, taking its style into account. The style of an element influences the bounding rectangle displayed. For example, a thick polygon border will increase the size of the bounding rectangle, and the size of a point symbol will determine the size of the bounding rectangle on display, and so forth.

The following code example shows how to obtain the bounding rectangle of a displayed map element:

K2DElement element = ...

View view = ...

VectorLayer layer = ...

Rectangle displayBounds = element.getDisplayBounds(view.getTransform(), layer.getStyle(element, view.getScaleFactor()));

Note that the getDisplayBounds method takes the transformation of the view (refer to Coordinate Systems) and element style as parameters.

Selection

The map elements of vector layers can be selected. A variety of tools allow the user to select elements in the vector layers of a JMap project.

The K2DElement class has a property called selected that indicates whether or not an element is selected. Selected elements are displayed using a different style, which is the selection style of the vector layer.

Vector layers manage the list of their selected elements. The API of the VectorLayer class offers several methods related to selecting elements. See Layers and Layer Manager for more information on this topic.

The following source code example shows how to select and unselect elements.

K2DElement element = ...

VectorLayer layer = ...

// add the element to the current selection

layer.addToSelection(element);

// test if element is selected, useless, just to demonstrate boolean

isSelected = element.isSelected();

// cycle through selection

Collection selection = layer.getSelection();

for (K2DElement element : selection)

System.out.println(element));

// unselect element

layer.unselectElement(element);

// clear layer selection

layer.clearSelection();

Styled elements

Styled elements (K2DStyledElement class) are special map elements. They have their own style and they ignore the style of the layer that contains them when they are displayed. They are useful when programmatically adding elements to the map that have their own style. Aside from this difference, styled elements behave exactly like any other map elements.

The following coding example shows how to create styled elements.

K2DElement element = ...

Style style = ...

K2DStyledElement styledElem = new K2DStyledElement(element, style);

// element will use this style to draw itself

Geometries

The API of JMap geometries is used for development purposes in JMap Pro and JMap Server.

In JMap, all vector data elements that appear on the map are based on geometries. They are simple classifications of basic geometric elements such as points, lines, and surfaces. In JMap, the classification scheme of geometries has been largely inspired by the model of geometries published by the Open Geospatial Consortium. Geometries do not contain attributes, identifiers, or display properties, but only two-dimensional x and y coordinates.

In JMap, the geometry classes can be found in the com.kheops.jmap.spatial package. The interface implemented by all geometries is Geometry.

The Point is a type of basic geometry used to compose all geometries. This type of geometry only contains a set of coordinates (x,y). This class is abstract and, therefore, its derivatives - Point.Float (simple precision) and Point.Double (double precision) - must be used.

// Creating a new point specifying coordinates Point pt1 = new Point.Double(-73., 45.);

// Creating a new point by cloning an existing point Point pt2 = (Point) pt1.clone();

// Changing the location of an existing point pt1.setLocation(-74., 45);

The main geometry classes are the following:

Composite versions of geometries exist to support collections of geometries of the same type. These classes are: MultiPoint, MultiCurve, MultiLineString, MultiSurface and MultiPolygon. In addition, the Complex class is a special type of collection comprising various types of geometries.

To simplify the management of all these types of geometries, 5 interfaces are available: PointTypeGeometry, LineTypeGeometry, PolygonTypeGeometry, AnnotationTypeGeometry and EllipseTypeGeometry. These interfaces combine all types of geometries, including collections.

Geometry precision

JMap allows you to create single precision or double precision geometries. Combined with other strategies, simple precision is mainly used to compress data in order to optimize system performance. As a programmer, you should only use double precision.

// Creating a new point with single precision Point pt1 = new Point.Float(-73., 45.);

// Creating a new point with double precision Point pt2 = new Point.Double(-73., 45.);

Operations on geometries

Spatial operators

Spatial operators are used to make geometric calculations on the geometries. These calculations can generate 3 types of results:

• Numeric results (e.g. calculate the distance between 2 geometries)

• Boolean results (e.g. test to see if 2 geometries intersect)

• Geometric results (calculate the union of 2 geometries)

The GeometryUtil class provides simple methods to perform calculations on geometries. The methods most often used are presented in the following table:

Precision models

The PrecisionModel class allows you to define the tolerance being considered in performing calculations using the geometries. Using a precision model that is well adapted to the geometries can give more precise results when making calculations.

The precision model generally varies according to the measurement unit of the data (meters, degrees, etc.). The PrecisionModelFactory class allows you to obtain an instance of PrecisionModel for a given unit. Each instance of the Layer class has its own instance of PrecisionModel that can be used. It is also possible to ask JMap to determine the optimal precision model for a specific geometry.

The following example shows different ways of generating an appropriate precision model.

// Obtain the optimal precision model for data of the current projectProject project = ... PrecisionModel precisionModel1 = PrecisionModelFactory.getInstance(project.getMapUnit());

// Obtain the optimal precision model for unit Meter PrecisionModel precisionModel2 = PrecisionModelFactory.METER;

// Obtain the optimal precision model of a layerLayer layer = ... PrecisionModel precisionModel3 = layer.getPrecisionModel();

// Obtain the optimal precision model for the specified geometry Geometry geometry = ... PrecisionModel precisionModel4 = PrecisionModelFactory.getInstance(geometry);

Transformations

You can perform transformations of all sorts on geometries. The Geometry interface contains the method transform(Transformation), which receives an instance of Transformation. This method creates a clone of the geometry, applies the specified transformation on it and returns the newly transformed geometry. Transformations can change the coordinates of the geometry and even modify the nature of the geometry itself. They can be used to apply a map projection or a generalization to geometries, for instance.

It is also possible to apply transformations using the transform() method of the Transformation class. In this case, the geometry may not always be cloned, depending on the type of transformation. Refer to the documentation of each transformation for more information.

The UnaryTransformation class is the base class of the transformations that only modify the coordinates composing the geometry. If you must implement your own transformation class, you will probably derive it from this class.

The following table shows the transformations that are available with the JMap API.

The following code example shows how to use the precision change transformation.

Point[] points = new Point[]

{

new Point.Double(10., 10.),

new Point.Double(20., 20.),

new Point.Double(30., 30.)

};

LineString doubleLineString = new LineString( points );

// The transformation can be done by the geometry. After the execution, doubleLineString will still contain single precision coordinates.

LineString singleLineString1 = (LineString)doubleLineString.transform(PrecisionTransformation.TO_FLOAT);

// The transformation is made directly on the geometry. After the execution, doubleLineString will contain single precision coordinates. Moreover, singleLineString2 refers to the same instance as doubleLineString.

LineString singleLineString2 = (LineString)PrecisionTransformation.TO_FLOAT.transform(doubleLineString);

The following code example shows how to use the map projection change transformation.

Point[] points = new Point[] { new Point.Double(-73.12345, 45.12345), new Point.Double(-73.54321, 45.54321) }; LineString lineString = new LineString( points );

// Define the source and the destination projections Projection fromProjection = new LongitudeLatitude(); Projection toProjection = new Mtm(); toProjection.setParams("8"); // zone 8 // Create a combined projection object that converts points from one projection to the other final CombinedProjection combinedProj = new CombinedProjection(fromProjection, toProjection); // Apply the projection transformation lineString = (LineString)lineString.transform(new ProjectionTransformation(combinedProj));

The following example shows how to create an anonymous transformation class using the adapter TransformationAdapter. The transformation converts the points into ellipses.

Point[] points = new Point[]

{

new Point.Double(10., 10.),

new Point.Double(20., 20.),

new Point.Double(30., 30.)

};

// Create a new transformation which creates a new ellipse at the specified location. Transformation tr = new TransformationAdapter()

{

public Geometry transform(Point point)

{

return new Ellipse(

(Point)point.clone(),

new Dimension.Double(5, 3), 0

);

}

};

// Apply the transformation on all points

Ellipse[] ellipses = new Ellipse[points.length];

for (int i = 0; i < ellipses.length; i++)

ellipses[i] = (Ellipse)tr.transform(points[i]);

Bounding rectangle

The bounding rectangle (MBR for Minimum Bounding Rectangle) of a geometry is the smallest orthogonal rectangle that totally encompasses the geometry. The MBR is used in JMap to do quick spatial analyses of a large number of geometries before using more precise (yet slower) algorithms on a smaller number of geometries. As prescribed by the Geometry interface of JMap, all types of geometries implement the getBounds() method that generates the MBR of the geometry.

The MBR of a point is a rectangle with a width of 0 and a height of 0. The MBR of a vertical line is a rectangle with a width of 0 and the MBR of a horizontal line is a rectangle with a height of 0.

The following tables present the keys of JMap Pro’s GUI components. These keys are used to control these components through programming, notably in the methods of the JMapGuiService class.

When JMap Pro opens, a connection to the associated JMap Server is established. This connection is used to direct the various system requests, including requests to load the project configuration and data as well as .

Communication between a JMap Pro (desktop) application and JMap Server is done by exchanging requests and responses. The requests and the responses are in fact serialized objects that must normally be programmed, and these objects will contain the properties required to execute the request and return the information to the client. For example, an application managing citizen requests might have a request and response with the following properties:

Response status

Your extension should always check the status of a response before using it. If the status is not equal to JMapSRV_STS_SUCCESS, a special treatment should be done in order to manage the error situation. In this case, the getMessage() method allows you to generate a message explaining the cause of the error.

Sending requests to JMap Server

JMapSrvConnection jmapConn = JMapApplicationContext.getInstance().getConnection();

The following code example shows how to use the executeRequest method.

MyRequest request = new MyRequest("This is a test", 555);

JMapSrvConnection jmapConn = JMapApplicationContext.getInstance().getConnection();

MyResponse response = (MyResponse)jmapConn.executeRequest(request); // Execution WILL block here

if (response.getStatus() == MyResponse.JMAPSRV_STS_SUCCESS)

{

// Do something useful with the response

}

else

{

// Handle error here

}

The following code example shows how to use the pushRequest method.

MyRequest request = new MyRequest("This is a test", 555);

request.setClient(new JMapRequestClient()

{

// Will be called when the response is received from JMapServer

@Override

public void callback(JMapRequest request, JMapResponse response)

{

if (response.getStatus() == MyResponse.JMAPSRV_STS_SUCCESS)

{

// Do something useful with the response

}

else

{

// Handle error here

}

}

});

JMapSrvConnection jmapConn = JMapApplicationContext.getInstance().getConnection(); jmapConn.pushRequest(request); // Execution WILL NOT block here

Concepts

JMap Pro applications are developed on a modular basis to simplify the addition of new features. Applications can be broken down into three levels, two of which are scalable to allow for programming additional features.

The first level is the entry point of the application ( class), which covers the type of application (applet, Java Web Start or standalone Java) and instantiates the application class (instance of the class) to be used. The second level is the JMap Pro application; it is driven by its abstract class, , which provides all the services required to ensure its proper operation. Since the class does not provide the application’s graphical interface, it is necessary to instantiate a class that inherits the JMapApplication class and that will instantiate the application’s graphical components, including the layer hierarchy and button toolbars. The DockingClient class, included in this SDK, is a good example of a JMap Pro application. The third level is for JMap extensions. JMap Pro applications allow you to develop and use extension classes ( class) to add new features to applications. JMap Pro extension development is explained in the following .

Communication with JMap Server

When the application is initialized, a connection with JMap Server is established based on the application parameters that have been specified. Communication with the server is unidirectional and allows for exchanging messages using requests and responses. The details of this communication are explained in this .

Application services

Application context

A JMap tool provides interaction between the user and the map using the mouse. For example, when the user activates the selection tool and clicks on the map to select an item, it is the selection tool class that performs the work. This tool is programmed to make a selection at the location that is clicked on the map. Similarly, when the distance measurement tool is used, the tool class calculates and displays the distance between the 2 points clicked by the user. Thus, developing a JMap tool allows you to implement custom actions.

In general, only one tool at a time can be enabled. In order to be enabled, a tool must be the active tool in a JMap view. To do so, you must use the method of the or class. Note that the method used to activate the tool, such as a button or a menu item, has no connection with the operation of the tool itself.

When the user changes the active the tool (e.g. by pressing a button), the code will essentially be as follows:

JMapApplicationContext.getInstance().getViewManager().setCurrentTool(new MyTool());

When a tool is active, it receives all the mouse events that are generated by the active view. The Tool class is responsible for processing these events and taking the appropriate actions.

To develop a new tool, you must program a class derived from the abstract class and implement only the methods needed to perform the tool’s function. For example, if the tool must perform an action when the user clicks the mouse, you must implement the method.

Tool class methods:

The following code example shows a simple tool that displays the properties of the first element found at the coordinates of the mouse cursor when the user presses and releases the left mouse button on the map. Only vector layers are considered and the search is performed from the highest layer to the lowest layer, in the layer display order. Other methods of the Tool class are not implemented because they are not required for the operation of this tool.

public class ElementInfoTool extends Tool

{

public void onToolReleased(MouseEvent e)

{

super.onToolReleased(e);

System.out.println("ElementInfoTool.onToolReleased");

// Obtain array of layers to cycle them in reverse order

final Layer aLayers[] = this.view.getLayerManager().getAllLayers();

// Get the layer visibility status from the layer manager (also includes the hierarchy visibility)

final LayerVisibilitySet layersVisibility = this.view.getLayerManager().getLayerTreeVisibility();

// Transform mouse x,y coordinate to WC coordinate

// Point wcCoord = view.getTransform().transformInv(new Point.Double(e.getX(), e.getY())); final Point wcCoord = toWCPoint(e); // method inherited from class Tool

final ViewState viewState = this.view.getViewState();

// Cycle through every layer in reverse order (from top position to bottom position) looking for an element under the x,y position.

for (int i = aLayers.length - 1; i >= 0; i--)

{

// Consider only vector layers

if (!(aLayers[i] instanceof VectorLayer))

continue;

final VectorLayer vectorLayer = (VectorLayer) aLayers[i];

// Layer must be visible, selectable and displayed at the current scale

if (layersVisibility.isVisible(vectorLayer.getId()) && vectorLayer.isSelectable() && vectorLayer.isDrawable(viewState.getScale()))

{

final K2DElement elem = vectorLayer.getElementAtPoint(wcCoord, viewState, true);

if (elem != null)

{

String message = "Selected element on layer " + vectorLayer.getName() + ":\n\n"

+ "Class:" + elem.getClass().getName() + '\n'

+ "Id: " + elem.getId() + '\n'

+ "Geometry: " + elem.getGeometry().getClass() + '\n'

+ "Display bounds: " + elem.getDisplayBounds(viewState, vectorLayer.getStyle(elem, viewState.getScale())) + '\n'

+ "Attributes:\n";

final Object[] attribs = elem.getAttributes();

final Attribute[] attribDefinitions = vectorLayer.getAttributeMetaData();

for (int j = 0; j < attribs.length; j++)

{

message += " " + attribDefinitions[j].getName() + " : " + attribs[j] + '\n';

}

JOptionPane.showMessageDialog(this.view, message);

break;

}

}

}

}

}

Drawing tools

You can implement tools to draw on the map simply by deriving them from existing JMap classes for drawing tools.

By deriving from these classes, all the basic operations are inherited. The following options are available:

• Persistent and volatile modes (determines whether items are created);

• Select the layer that will receive the items drawn;

• Style parameters of drawn elements (colors, line types, etc.);

• Display dimensions on the map while drawing.

public class CreatePolygonTool extends ToolDrawPolygon

{ private final static String LAYER_NAME = "Zones";

private VectorLayer targetLayer; // The layer that will hold the polygons

public void init(View view)

{

super.init(view);

// Make sure the layer exists. If not create it and register it in the layer manager of the view.

final LayerManager layerMgr = view.getLayerManager();

this.targetLayer = (VectorLayer)layerMgr.getLayer(LAYER_NAME);

if (this.targetLayer == null)

{

// The layer does not exist, create it

this.targetLayer = new VectorLayer(Layer.getNextUserLayerId(), // avoid id conflict with other layers

LAYER_NAME,

ElementTypes.TYPE_POLYGON);

// Tell JMap that information on this layer does not come from the server

this.targetLayer.setLocal(true);

// Set the mouse-over text for the layer. It will be displayed when the user stops the mouse pointer over an element.

this.targetLayer.setMouseOverConfiguration(new MouseOverConfiguration("This is a zone."));

// Add the layer to the layer manager list. All layers need to be registered in the layer manager in order to be displayed in the view. The layer is added to the top.

layerMgr.addLayer(this.targetLayer);

}

// Tell the superclass that the resulting elements should be persisted when completed. That means that they will be placed on a layer. Otherwise, they would be deleted as soon as they are completed.

setPersistent(true);

// Tell the superclass to place the resulting elements on the target layer. Otherwise, they would be placed on the default drawing layer

// (id = LayerManager.LAYER_ID_USER_DRAWINGS).

setDrawLayer(this.targetLayer);

// Modify the style of the surface elements (polygons).

final Style surfaceStyle = getStyleContainer().getSurfaceStyle();

surfaceStyle.setFillColor(Color.GREEN);

surfaceStyle.setTransparency(.50f);

// To have the valid drawing style displayed in the layer bar, make the layer default style identical to the drawing style.

this.targetLayer.setStyle(surfaceStyle, 0.);

}

}

View class

In JMap, the class is the main GUI component responsible for displaying the map. The methods of this class allow you to control the map (zoom, pan, etc.), to refresh it, to get information on the scale, etc.

The table below shows the main methods of the class.

Events of the View class

In JMap, a view generates events in several situations. To get these events, you must register a listener to the view. To get events generated by all open views, it is recommended to register a listener on the View Manager. Read below for more information on this subject.

View view = ...

view.addViewEventListener(new ViewEventListener()

{

@Override

public void viewToolChangedOccurred(ViewToolChangedEvent e)

{

}

...

});

ViewState class

ViewManager class

Events of the ViewManager class

View view = ...

ViewManager viewManager = view.getLayerManager();

viewManager.addViewManagerEventListener(new ViewManagerEventListener()

{

@Override

public void viewAdded(ViewAddedEvent e)

{

}

...

});

ViewUtil class

Concepts

Layers ( class and its related classes) are highly important in JMap programming. They contain and manage the map data displayed on the map ( class). There are two main types of layers: vector layers ( class), which contain vector data, and raster layers ( class), which contain raster data (images).

When a project is loaded, the client application gets the layer configuration from the server and creates the related instances in the . Initially, a layer does not contain any data. Its data will only be loaded, in full or in part, after the view has been refreshed, based on the loading mode and display restrictions (visibility state and display thresholds).

In JMap, there are two different modes to load layers: by tile and by region. Vector layers support both modes, but raster layers can only be loaded by region.

Tiled layers divide the region of the layer into rows and columns; each cell is a data tile ( and classes). Since the layers are initially empty at application startup, data tiles will be loaded by the application when they are initially displayed in a view. Once it is loaded in a layer, a tile will be kept in memory for the duration of the session, unless the session expires prematurely or the memory manager decides to delete the tile.

When a data tile request is sent to JMap Server, all geometries ( interface) intersecting the region of the tile will be transferred to the client. Once the tile is received, the geometries will be transformed into elements ( class), which will then be loaded in the of the layer. To avoid duplicating an element in several data tiles, elements that are not completely included in a tile will eventually be moved to the layer’s universe tile.

Layers loaded by region are based on the same structure ( and classes), but they only have a single tile with a variable region. When a change is applied to the transformation matrix of the view and the view is refreshed, layers loaded by region will reload their single tile with the data intersecting the extent of the view.

The Layer class and its derived classes

Layer class

The Layer class is abstract and therefore cannot be instantiated. However, it provides the basic methods for all layers.

VectorLayer class

Vector layers have a set of attributes that are common to all elements of the layer. These attributes provide the descriptive data of the layer’s elements.

RasterLayer class

Layer class events

The layers in JMap generate events in several situations. To get the events generated by a layer, you must register a listener on the layer. To get the events generated by all the layers of the project, it is recommended to register a listener on the layer manager. See below for more information on this subject.

Layer layer = ...

layer.addLayerEventListener(new LayerEventListener()

{

@Override

public void layerSelChangedEventOccurred(LayerSelChangedEvent e)

{

// TODO

}

...

});

LayerManager class

LayerManager class events

The layer manager in JMap generates events. To receive the events generated by a layer manager, you must register a listener on the appropriate layer manager. Note that a listener registered on the layer manager will get the events generated by all the layers handled by the layer manager.

The Java API documentation for JMap 7 is available online at https://dev.k2geospatial.com/jmap/javadoc/Kathmandu.

Integration With Client Applications

There are several ways to allow communication between a JMap Pro application and another client application, also called an external application.The external application is an application running locally on the same computer as JMap Pro. We are not talking here of web applications (HTML, javascript), but rather client applications. The JMap Socket extension provides this communication in a simple and effective way.

JMap Socket extension

The Socket extension is a generic extension that allows a bidirectional socket communication between external applications and JMap Pro extensions. This extension does not directly process the messages. Its role is limited to providing communication. Here is a typical scenario describing the use of this extension:

An external application sends the identifier of an element to JMap and it is automatically located and selected on the map. Conversely, the user clicks on a map element, and JMap sends the ID of the element to the external application, which displays a form with the properties of the element.

General operation

The Socket extension provides a standard means of communication allowing JMap extensions to communicate with external applications. External applications are applications running locally on the same computer as JMap Pro. These applications can be written in any programming language (Java, C + +, Windev, C #, VB.NET, etc.). Note that web applications (HTML, javascript, etc.) are not supported by this integration method. Other methods are better suited to web applications (see Java Communication - Javascript).

To communicate, external applications and JMap extensions send messages that are in fact byte arrays. The contents of these byte arrays is interpreted on either side. The Socket extension does not interpret their content.

The external application always connects to JMap first. It does so by opening a socket to the port configured in the Socket extension. Thereafter, the external application will once again initiate communication. This first contact is a special communication called a handshake. During the handshake, the external application indicates its unique identifier (a character string identifying the application).

As for the JMap extension that wants to communicate with the external application, it must register with the Socket extension. It must provide the same identifier as the external application. This is the identifier that links the two.

Subsequently, the external application and JMap extension can send each other messages in any direction. Each party (the external application or extension) is responsible for interpreting the messages and taking the appropriate actions.

Optionally, the Socket extension can launch the external application if it does not respond. Once it is launched, the external application may initiate communication as described above.

Programming on the external application side

The code examples that follow are written in Java . An external application programmed in another language should implement the same logic, in that application’s language.

1. Opening a socket using IP address 127.0.0.1 and port 12351):

   Socket socket = new Socket(“127.0.0.1”, 12351);

2. Sending a handshake message

   The handshake message is received and interpreted by the Socket extension only. Note that the number of bytes of the message must precede the contents of the message. The message is sent as a byte array. The character encoding (charset) of this message is defined in the configuration of the Socket (socket.properties file) extension.

   DataOutputStream dos = new DataOutputStream(socket.getOutputStream());

   String handshake = "handshake:MyIdentifier";

   dos.writeInt(handshake.getBytes().length);

   dos.write(handshake.getBytes());

   dos.flush();

3. Sending other messages

   Subsequent messages are sent the same way as the handshake message, however, they will be received and interpreted by the extensions registered with the same identifier. Extensions that receive messages must therefore be able to understand the content of messages and perform the corresponding actions. The character encoding of the message is free and must be agreed to by the extension and the external application.

   DataOutputStream dos = new DataOutputStream(socket.getOutputStream());

   String message = "locate :id=333";

   dos.writeInt(message.getBytes().length);

   dos.write(message.getBytes());

   dos.flush();

4. Receiving messages from JMap

   Receiving messages is done using the same socket as for sending. The length of the message is read first, followed by the byte array of the message. Message reception should be done asynchronously, in a separate thread.

   DataInputStream dis = new DataInputStream(socket.getInputStream());

   int length = dis.readInt();

   if (length > 0)

   {

   byte[] messageBytes = new byte[length];

   dis.readFully(messageBytes);

   }

Programming on the JMap extension side

The following example shows how to register a JMap extension with the socket extension to be notified when a connection or disconnection occurs and when messages from the external application are received. This code could be placed in the init() method of the JMap extension.

SocketClientExtension.register(new SocketClient()

{

@Override

public void socketMessageReceived(byte[] bytes)

{

String data = new String(bytes /*, Charset.forName("ISO-8859-5")*/);

// Interpret content of data…

}

@Override

public void socketConnectionOpened()

{

}

@Override

public void socketConnectionClosed()

{

}

@Override

public String getIdentifier()

{

return "MyIdentifier";

}

@Override

public String getExecutable()

{

// Optional - return null if not needed return "c:/external_app.exe";

}

});

The following example shows how to send a message to the external application from the JMap extension.

String message = "openform: id =99";

byte[] bytes = message.getBytes();

SocketClientManager.getInstance().sendMessage("MyIdentifier" , bytes);

Integration With Web Applications

Java applets are executed in the environment of a web browser. Therefore, they can interact, in both directions, with the javascript code in the web page that contains the applet. This communication allows you to create HTML interfaces to control the map and perform simple integrations with other applications running in the environment of the web browser. This does not apply to JMap Pro applications deployed with the JavaWebStart method (not in a web browser) because no web page is involved in these cases.

Javascript to Java

The following sample web page is a normal startup page for a JMap Pro applet to which javascript functions have been added (pan and zoom). Hyperlinks are also used to call these functions. When triggered, the functions call the JMap API to control the map.

The JMap Pro application has a getApplicationContext() method that is used to access all the components of the application.

<%@page contentType="text/html;charset=ISO-8859-1"%>

<%

String username = request.getParameter("username");

String password = request.getParameter("password");

String parameters = null;

if (username != null && username.length() != 0)

{

parameters = "?username=" + username;

if (password != null)

parameters += "&password=" + password;

}

%>

<html>

<head>

<title>

aa

</title>

<script src="library/deployJava.js"></script>

<script src="library/jmap.js"></script>

</head>

<BODY BGCOLOR="#ffffff" topmargin="0" leftmargin="0" rightmargin="0" bottommargin="0">

<script>

function zoom(factor)

{

document.jmap.getApplicationContext().getViewManager().getActiveView().zoom(factor);

document.jmap.getApplicationContext().getViewManager().getActiveView().refresh();

}

function pan(x, y)

{

document.jmap.getApplicationContext().getViewManager().getActiveView().pan(x, y);

document.jmap.getApplicationContext().getViewManager().getActiveView().refresh();

}

</script>

<a href="javascript:zoom(2.);">Zoom in</a>

<a href="javascript:zoom(0.5);">Zoom out</a>

<a href="javascript:pan(0, 200);">Pan north</a>

<a href="javascript:pan(0, -200);">Pan south</a>

<a href="javascript:pan(200, 0);">Pan west</a>

<a href="javascript:pan(-200, 0);">Pan east</a>

<script>

var attributes =

{

name: "jmap",

codebase: "http://127.0.0.1:8080/aa",

code: "com.kheops.jmap.client.application.JMapApplicationLauncher",

archive: "dockingClient.jar,jmap_application.jar,jmap_client.jar,jmap_client_images.jar,jmap_projections.jar,jmap_symbols.jar,custom_symbols.jar,jmap_metadata.jar,jmap_net.jar,jmap_spatial.jar,kheops_ui.jar,kheops_util.jar,gif4j_pro_2.0.jar,jide-action.jar,jide-common.jar,jide-components.jar,jide-dock.jar,jide-grids.jar",

width: "100%",

height: "100%",

mayscript: true,

separate_jvm: true,

parameters: "-appclassname jmap.viewers.docking.AppDocking -project &quot;The World&quot; -directport 7003 -httpport 8080 <%= username != null ? username : "" %> <%= password != null ? password : "" %> -proxypath /aa/servlet/jmapproxy -serverid &quot;aa&quot; -maxmemory 33554432 -connection direct -donotlistusers false -showconnectionmoredetails false true "

};

var parameters = {fontSize:16, jnlp_href:'dockingClient.jnlp'} ;

deployJava.runApplet(attributes, parameters, '1.6.0_10');

</script>

</body>

</html>

Java to Javascript

From a JMap Pro applet, it is possible to call javascript functions that are in the web page containing the applet. This allows for interaction between the JMap Pro application and its HTML environment. For example, it would be possible to select an item on the map and display its information in an HTML page.

To enable this java-javascript communication, the mayscript: true parameter must be specified in the attributes used to start the applet, as shown in the following example.

<script>

var attributes =

{

name: "jmap",

codebase: "http://127.0.0.1:8080/aa",

code: "com.kheops.jmap.client.application.JMapApplicationLauncher",

archive: "dockingClient.jar,jmap_application.jar,jmap_client.jar,jmap_client_images.jar,jmap_projections.jar,jmap_symbols.jar,custom_symbols.jar,jmap_metadata.jar,jmap_net.jar,jmap_spatial.jar,kheops_ui.jar,kheops_util.jar,gif4j_pro_2.0.jar,jide-action.jar,jide-common.jar,jide-components.jar,jide-dock.jar,jide-grids.jar",

width: "100%",

height: "100%",

mayscript: true,

separate_jvm: true,

parameters: "-appclassname jmap.viewers.docking.AppDocking -project &quot;The World&quot; -directport 7003 -httpport 8080 <%= username != null ? username : "" %> <%= password != null ? password : "" %> -proxypath /aa/servlet/jmapproxy -serverid &quot;aa&quot; -maxmemory 33554432 -connection direct -donotlistusers false -showconnectionmoredetails false true "

};

var parameters = {fontSize:16, jnlp_href:'dockingClient.jnlp'} ;

deployJava.runApplet(attributes, parameters, '1.6.0_10');

</script>

To call a javascript function from your Java code (possibly your JMap extension), you must use the JSObject API, as shown in the following example.

JSObject w = JSObject.getWindow((Applet)appContext.getRootPaneContainer());

w.eval("show_form(" + id + ");");

In this example, the getWindow method receives the instance of the applet as a parameter. The getRootPaneContainer method of the JMapApplicationContext class returns the top level container of the application, the latter being the instance of the Applet when the application is running inside the web browser.

The javascript function to be called and its parameters are taken as parameters by the eval method. In this example, an ID is passed to the javascript function.

JMap Server extensions are modules developed in Java that are added to JMap Server to respond to new types of queries and perform tasks on the server side. Server extensions can contain configuration interfaces that are integrated to the Extensions section of JMap Admin. Often, a server extension works with a client extension.

To develop a server extension and make it available, you must perform the two following steps:

1. Develop an extension by creating a Java class that implements the JMapServerExtension interface.

2. (Optional) Develop a JMap Admin configuration interface for your extension.

3. Deploy your extension in JMap Server.

See the following sections for more information.

Programming Server Extensions

The JMapServerExtension Interface

The first step towards developing a JMap Server extension is to write a class that implements the JMapServerExtension interface. This interface includes the following 3 methods, which are called at different moments in the life cycle of the extension:

To do its job, your extension can use the services offered by JMap Server. This includes spatial data extraction, access to relational databases connected to JMap Server, access to the system log (log files), etc.

For more information on the services offered by JMap Server, see the JMap Server Services section.

JMapExtensionRequest class

You must implement a class derived from the JMapExtensionRequest class. This class provides your extension with all the information it needs to perform its work. Requests are typically initiated on the client side and passed to JMap Server for processing by your extension. In this class, you can include all the required properties, but make sure these are all serializable.

When your extension is initialized, the type of your query (full class name, including package) is associated with your extension. This way, when JMap Server receives this type of query, it is automatically directed to your extension (processRequest method). For more information on how to make the connection between your query and your extension, refer to the Deploying Server Extensions section.

For more information on programming requests, refer to the Client-Server Communication section.

JMapExtensionResponse class

You must also implement a class derived from the JMapServerResponse class. This class is intended to provide information resulting from the execution of your query. The processRequest method of your extension must return an instance of this class. Depending on the nature of the query, the response may either return a large amount of information or just a query execution status (success, failure, etc.). You can include all the required properties in your class, but make sure they are all serializable.

For more information on programming responses, see the Client-Server Communication section.

JMap Server Services

JMap Server Class

The JMapServer class is the main class from which you can access JMap Server’s various services. This class is a singleton. You can therefore access it from anywhere using the static method JMapServer.getInstance().

JMapHome

JMap Server’s home path is accessed using the static method getJMapHome() of the JMapServer class. It can be useful to know this path when you wish to read or write data in JMap Server’s subdirectories.

Logging

The JMap Server logging tool can record events in log files. The tool’s class is Logger and it is a singleton. Thus, you can access the single instance using the static Logger.getInstance() method.

The various versions of the log method are used to store messages, depending on the type of information to be recorded.

The following table shows the most commonly used methods of the Logger class.

The various message levels are defined by constants of the Logger class.

• LEVEL_DEBUG

• LEVEL_INFO

• LEVEL_WARNING

• LEVEL_ERROR

• LEVEL_FATAL

The following code example shows how to log a message with the various methods.

// Logs a message of level INFO

Logger.getInstance().log(Logger.LEVEL_INFO, "Extension ABC recieved a request for ...");

// Logs a message of level WARNING, tagged to user etardif

Logger.getInstance().log(Logger.LEVEL_WARNING, "Something occurred in Extension ABC ...", "etardif");

// Logs a message of level ERROR, and includes the exception stack trace

Exception e = ...;

Logger.getInstance().log(Logger.LEVEL_ERROR, "An unexpected error occurred in Extension ABC ...", e);

Databases

The connections to the relational databases that JMap Server is connected are available through programming. This greatly simplifies data access because you do not need to open, close and manage the connections to these databases.

JMap Server manages database connections in connection pools. These pools function as follows: when a connection is required, it is borrowed from the pool. It is then used briefly to execute one or more queries. Lastly and most importantly, the connection is returned to the pool and is once again available for other needs. Thus, connections are never closed.

The getDBConnPool(int) and getDBConnPool(String) methods allow you to get a connection pool (instance of the DatabaseConnectionPool class) using its numeric ID or name.

The following table shows the most commonly used methods of the DatabaseConnectionPool class.

The following source code example shows how to use a pool of connections to databases.

DatabaseConnectionPool pool = JMapServer.getInstance().getDBConnPool("parcels");

Connection conn = null;

try

{

conn = pool.borrowConnection();

// use connection to do queries.....

}

catch (SQLException e)

{

e.printStackTrace();

} finally

{

// It is very important to return the connection to the pool.

// Doing it in a finally clause is a good practice

if (conn != null)

pool.returnConnection(conn);

}

Extracting spatial data

Spatial data can be extracted using the JMap Server data manager (JMapServerDataManager class). The data manager can be accessed using the getDataManager() method of the JMapServer class.

The following table shows the most commonly used methods of the JMapServerDataManager class.

To extract data, you can also use filters. Filters are objects that control what data must be extracted based on various criteria.

Filter classes are all derived from the abstract class QueryFilter. The following table shows all the types of filters that are available.

The following source code example shows how to extract spatial data using a spatial filter.

JMapServerProject serverProject = ...

JMapServerVectorLayer serverLayer = ...

Polygon region = ...

final JMapServerDataManager dataMgr = JMapServer.getInstance().getDataManager();

// Create a new spatial filter for all elements that intersect the polygon

final SpatialQueryFilter newFilter = new SpatialQueryFilter();

newFilter.setGeometry(region);

newFilter.setType(SpatialQueryFilter.SPATIAL_OP_INTERSECTS);

// Set the projection on the filter to indicate the coordinate system of the geometry

newFilter.setProjection(serverProject.getProject().getMapProjection());

// Do the extraction using the data manager. All attributes of the layer will be included

JMapGeoElement[] result = dataMgr.extractElements(serverProject, serverLayer,

new QueryFilter[]{newFilter},

serverLayer.getBoundAttributes() );

Sending emails

The sendMail() static method of the MailService class allows you to send emails from JMap Server. In order for the emails to be sent successfully, JMap Server must be connected to an SMTP server. This connection can be configured during the JMap installation or it can be defined in the Settings section of JMap Admin.

String to = "jo32@gmail.com;ann122@hotmail.com";

String from = "admin@123map.com";

try

{

MailService.sendMail(MailService.toAddresses(to), "Map extraction completed", "The data was extracted successfully and is available here.", new InternetAddress(from));

}

catch (AddressException e)

{

e.printStackTrace();

}

catch (Exception e)

{

e.printStackTrace();

}

Session Manager

The JMap Server Session Manager (JMapServerSessionManager class) is responsible for managing active sessions in the system. Among other things, it provides access to the user connected to a session by using the session ID. This session number is accessible from every request received by JMap Server, including queries destined to server extensions. The session manager can therefore be used to know the identity of the user who initiated a query.

The following code example shows how to access the user who initiated a query.

public JMapExtensionResponse processRequest(JMapExtensionRequest request)

{

int sessionId = request.getSessionId();

User user = JMapServer.getInstance().getSessionManager().getSessionUser(sessionId);

System.out.println("##### Request originating from user: " + user.getName() + " (" + user.getFullName() + ")");

...

}

User Manager

The User Manager (UserManager interface) provides access to the list of users and groups used by JMap Server for access control. It also allows you to access user information. If you develop a server extension that must manage its own list of permissions, it can be very useful to access the list of users that the system uses.

The getUserManager() method of the JMapServer class returns the User Manager (class that implements the UserManager interface) being used.

The following table shows the most useful methods of the UserManager class.

The User class contains the information on a user (full name, email address, etc.).

Workspaces

In JMap, workspaces are spaces used for individual storage of user data. Each workspace is actually a separate subdirectory of JMap Server. The workspaces are used to store contexts created by users. As a programmer, you can use them to store data.

The getWorkSpaceManager() method of the JMapServer class allows you to access the workspaces manager (WorkSpaceManager class), which provides some useful methods related to worskpaces. By default, workspaces are located in the JMap_HOME / workspaces directory.

The following table shows the most useful methods of the WorkSpaceManager class.

Deploying Server Extensions

To be deployed in JMap Server, server extensions must follow certain rules. If these rules are met, the extension appears in the Extensions section of JMap Admin.

1. Group extension classes in an archive (JAR)

   All the classes of the extension must be contained in a single JAR archive file. Use a meaningful and unique name.

2. Include a manifest file

   The extension archive must include a manifest.mf file with the following entries:

   Here is an example of the contents of a manifest file:

   extension_class: jmap.extensions.tracking.server.TrackingExtension

   extension_name: Tracking

   extension_request: jmap.extensions.tracking.common.TrackingRequest

   extension_response: jmap.extensions.tracking.common.TrackingResponse

   extension_version: 5.0.0010

3. Place the file in the correct directory

   The JAR file of the extension must be placed in the server extensions directory (JMAP_HOME/extensions).

4. (Optional) Place the files from the configuration interface of the extension in the appropriate directory

   The files that make up the configuration interface (JSP pages) must be copied to the directory used for this purpose (JMAP_HOME/jmapadmin/extensions).

Configuration Interfaces for Server Extensions

Each server extension may include a configuration interface integrated to JMap Admin. Using this interface, JMap administrators can configure the operational parameters of your extension (e.g. security, database connectivity, a layer selection, etc.). Note that this interface is completely optional.

This interface consists of one or more JSP pages. The main JSP page (which is called first) must absolutely have the same name as the extension class. For example, if the class name of the server extension is

jmap.extensions.tracking.server.TrackingServerExtension

then the main JSP page must be

jmap.extensions.tracking.server.TrackingServerExtension.jsp

For more information on programming these JSP pages, refer to the examples included in the SDK.

Preparing the Environment

Remote debugging environment

It may be useful to have remote debugging for the JMap Server extensions. Once deployed, these extensions are executed directly in the JMap Server process. It is therefore only possible to debug such extensions remotely. The Java Runtime Environment allows for remote debugging by adding a special parameter in the JMap Server environment. You will then be able to perform a server connection from Eclipse and monitor the execution of your JMap extensions step by step.

To activate remote debugging in JMap Server, you must modify the file startjmapserver.vmoptions located in the JMap_HOME/bin directory. The line starting with -Xdebug should be added.

-Xmx768m

-XX:MaxPermSize=256m

-Djava.awt.headless=true

-Dfile.encoding=ISO-8859-1

-Xdebug

-Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=8000

Next, you must restart JMap Server. JMap Server will then be in debug mode and it will be awaiting commands from Eclipse. It is not recommended to activate the debug mode in a production environment, as it significantly decreases system performance.

In Eclipse, you must create a remote debugging configuration using the same parameters given in the configuration file shown above (these are the default parameters).

JMap Pro Startup Parameters

The JMap Pro application takes certain parameters when it is started up. These parameters specify the address of the JMap Server, the communication ports, the project to open, and many other options.

Parameters are passed to the application in various ways, depending on its starting mode. Java and JavaWebStart applet parameters are passed in the application’s JNLP file. Application parameters are passed to the command line or can be specified in an Ant script.

The following example shows the parameters passed to the command line to start a JMap Pro application that opens the project The World and loads the extension Showcase.

-appclassname jmap.viewers.docking.AppDocking -server jmap3.k2geospatial.com -directport 7003

-project "The world" -extensions jmap.examples.showcase.extension.ShowCaseClientExtension

The following table describes the various parameters:

JMap Pro extensions are modules developed in Java that can be added to JMap Pro to enhance its features. Extensions are specified as parameters for applications and are initialized when said applications are launched. Typically, extensions are integrated to the GUI of a JMap Pro application by inserting the buttons and menus that activate the functions provided by the extension.

To develop an extension and make it available to users, you must perform the following two steps:

1. Develop your extension by creating a Java class derived from the JMapClientExtension class;

2. Deploy your extension in JMap Server so it may be accessed by the JMap Pro applications.

See the following sections for more information.

Programming JMap Pro Extensions

To program JMap Pro extensions, it is important to follow a set of simple rules. This section describes these programming rules.

JMapClientExtension class

The first step towards developing a JMap Pro extension consists of programming a class derived from the abstract class JMapClientExtension. This class contains the following 3 methods, which are called at different moments in the life cycle of the extension:

Parameters are passed to the extension with the init() method, using a Map<String, String> collection. In JMap, there are two predefined parameters that match constants defined in the JMapClientExtension class:

• EXTENSION_PARAMETER_GUI_VISIBLE: Indicates whether the extension’s GUI components (other than toolbars) must be visible when the application is launched.

• EXTENSION_PARAMETER_TOOLBAR_VISIBLE: Indicates whether the extension’s toolbars must be visible when the application is launched.

These parameters contain true or false values and they are set by the JMap Administrator when a JMap Pro application is deployed. Your extension must comply with these parameters. An extension can also receive its own settings, which would be set by the JMap Administrator.

The following code example shows how to access the settings from the init() method.

public void init(JMapApplicationContext appContext, Map<String, String> mapExtensionParameters)

{

String param = mapExtensionParameters.get(JMapClientExtension.EXTENSION_PARAMETER_TOOLBAR_VISIBLE);

boolean toolbarVisible = Boolean.parseBoolean(param);

...

}

JMapApplicationContext class

The JMapApplicationContext class is very useful for extension development because it provides access to a set of general application resources. This class is a singleton. Therefore, the instance can easily be accessed from anywhere using the static JMapApplicationContext.getInstance() method.

JMapApplication class

The JMapApplication class represents the JMap application. It offers methods that provide access to application resources (GUI, event logs, etc.). It also provides methods to perform tasks in a simple way (create a new map, close the project, etc.).

Most commonly used methods of the JMapApplication class:

Programming Extension Requests

As a developer of JMap Pro extensions, you will probably be developing applications that need to communicate between the client side and JMap Server. Whether you need to communicate with your own extension on the server side or to make general requests to JMap Server, the programming principle is the same.

For more information on client-server communication in JMap, refer to the Client-Server Communication section.

Programming the request

To create your request class, you must observe the two following rules:

• The class should be derived from the JMapExtensionRequest class;

• All of the class’s properties must be serializable.

You are free to add all the properties and methods that are useful to executing your request. These properties and methods can be used by your extension on the server side.

The following source code example demonstrates how to program a simple request.

// This request is used to save a new citizen complaint

public class SaveComplaintExtensionRequest extends JMapExtensionRequest

{

private String citizenName;

private int requestType;

public void setCitizenName(String citizenName)

{

this.citizenName = citizenName;

}

public String getCitizenName()

{

return this.citizenName;

}

public void setRequestType(int requestType)

{

this.requestType = requestType;

}