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

View class

In JMap, the View 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 View 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.

To receive a view’s events, you must implement the ViewEventListener interface and register it with the view using the addViewEventListener() method, as shown in the example below.

View view = ...

view.addViewEventListener(new ViewEventListener()

{

@Override

public void viewToolChangedOccurred(ViewToolChangedEvent e)

{

}

...

});

Note that the ViewAdapter adapter can also be used to simplify the development of a listener.

The table below shows the events triggered by the View class.

For more information on events in Java, see the Java Tutorial.

ViewState class

The ViewState class contains some view properties that define its state at a given time (scale, scope, transformation, etc.). Several methods in the JMap API take an instance of ViewState as a parameter. It is possible to get the state of a view by calling the getViewState() method of the View class.

ViewManager class

The view manager (ViewManager class) is responsible for managing one or more views that are present in the application. This class has methods that allow you to perform operations on all the views of the application and to know at any time which view is active (i.e. in focus).

The table below shows the main methods of the ViewManager class.

Events of the ViewManager class

The View Manager triggers events associated with the state of its views. To get these events, you must implement the ViewManagerEventListener interface and register it with the view manager using the addViewManagerEventListener() method, as shown in the following example.

View view = ...

ViewManager viewManager = view.getLayerManager();

viewManager.addViewManagerEventListener(new ViewManagerEventListener()

{

@Override

public void viewAdded(ViewAddedEvent e)

{

}

...

});

Note that the ViewManagerAdapter adapter can also be used to simplify the development of a listener.

The table below shows the events triggered by the ViewManager class.

It is also possible to register a listener to the View Manager to get the events generated by all the views associated with the layer manager. This may be more convenient than registering a listener on each view separately. To do so, use the addViewEventListener method of the ViewManager class.

ViewUtil class

The ViewUtil class provides useful methods to work with the view.

The table below shows the mains methods of the ViewUtil class.

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

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

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.

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

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 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 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 section.

JMapExtensionRequest class

JMapExtensionResponse class

JMap Server Services

JMap Server Class

JMapHome

Logging

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.

• 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 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

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

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

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 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 following table shows the most useful methods of the UserManager class.

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.

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.

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:

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.

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 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()));

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()

}

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

JMapApplication class

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.

Programming the request

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

• 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;

}

public int getRequestType()

{

return this.requestType;

}

}

Programming the response

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

• All of the class’ properties should be serializable.

You are free to add all properties and methods that are useful to returning the information regarding the request’s execution to the client. These properties and methods can operate from the client side by your extension after the request is executed on the server.

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

// This response is returned to client after a citizen complaint save request was executed

public class SaveComplaintExtensionResponse extends JMapExtensionResponse

{

private long uniqueId;

public void setUniqueId(long uniqueId)

{

this.uniqueId = uniqueId;

}

public long getUniqueId()

{

return this.uniqueId;

}

}

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 process must occur in order to manage the error. In this case, the getMessage() method allows you to generate a message explaining the cause of the error.

GUI Integration

Some client extensions can be completely invisible to the user but the majority of extensions are integrated into the JMap Pro GUI. This integration can take many forms. The initGui() method must be used to initialize the graphical interface of an extension.

JMapGuiService class

The main methods of the JMapGuiService class are listed below:

JMapGuiFactory class

Integration examples

Adding a button to an existing toolbar

// This button will be in a group thus only onebutton can be pressed among this group.

AbstractButton button = guiFactory.createToggleButton(new ButtonAction(),

appContext.getApplication().getGuiService().getMainButtonGroup());

// Add the button on the Zoom and Pan toolbar.

appContext.getApplication().getGuiService().getToolBar("ZOOM_PAN").add(button);

Adding a toolbar

The following code example shows how to create a toolbar using the JMapGuiFactory class. In this example, the JMapApplicationActionManager class is used to access the buttons’ actions. This class can manage single instances of actions. Afterwards, two buttons are created and added to the bar. Finally, the toolbar is added vertically, on the right side of the application. Notice the HashMap of properties that is used to place the toolbar. This principle is used with all components to specify their characteristics.

// Create the new toolbar final ToolBar

toolBar = guiFactory.createToolBar("SHOWCASE", "JMap example showcase");

// Create and add buttons on toolbar

toolBar.add( guiFactory.createToggleButton(applicationActionManager.getAction(CreatePolygonAction.class), jmapGuiService.getMainButtonGroup())

);

toolBar.add( guiFactory.createButton(applicationActionManager.getAction(ShowDockingPanelAction.class))

);

// Adds the new toolbar vectically to the right side of the application frame.

HashMap<String, Object> properties = new HashMap<String, Object>();

properties.put("CONTEXT_INIT_SIDE", new Integer(SwingConstants.EAST)); // Dock to the east

jmapGuiService.addToolBar(toolBar, properties);

Adding a window

// Create a panel with the needed components

final JPanel panel = new JPanel();

...

// Set the properties of the dockable panel.

HashMap<String, Object> properties = new HashMap<String, Object>();

properties.put("KEY", COMPONENT_KEY); // Will be used to reference the panel

properties.put("TITLE", "JMap 7 SDK showcase."); // Will be displayed on the title bar

properties.put("CONTEXT_INIT_SIDE", SwingConstants.EAST); // Tells JMap to dock the panel to the east of the frame

appContext.getApplication().getGuiService().addDockableComponent(panel, properties);

Adding a menu

The following code example shows how to create and add a menu to the interface.

// Create menu and add items to it

JMenu menu = new JMenu("SDK");

JMenuItem item1 = new JMenuItem("Item 1");

JMenuItem item2 = new JMenuItem("Item 2");

this.menu.add(item1); this.menu.add(item2);

// Add menu to menu bar at position 4

appContext.getApplication().getGuiService().getMenuBar().add(menu, 4);

Adding a menu item to an existing menu

// Add 2 menu items to existing menus TOOLS and HELP

JMenuItem item3 = new JMenuItem("Item 3");

JMenuItem item4 = new JMenuItem("Item 4");

appContext.getApplication().getGuiService().addMenuItem("TOOLS", item3, false);

appContext.getApplication().getGuiService().addMenuItem("HELP", item4, false);

Adding an item to the map pop-up menu

The following code shows how to add a section of items to the map’s pop-up menu. This menu appears when the user right-clicks on the map. In addition, the menu item is only active if the user has clicked on at least one element of a map layer. Otherwise, the menu item will be disabled.

final ViewMenuAction menuAction = new ViewMenuAction();

// Obtain the currently active view

View view = JMapApplicationContext.getInstance().getViewManager().getActiveView();

if (view != null)

{

// Add a separatr and a menu item

view.addPopupMenuSeparator();

view.addPopupMenuAction(menuAction);

}

// Register an event listener with the View Manager so that we are notified when the view popup menu is about to be displayed

JMapApplicationContext.getInstance().getViewManager().addViewEventListener(new ViewAdapter()

{

@Override

public void viewPopupMenuShowing(ViewPopupMenuShowingEvent e)

{

// Enable map menu item only if the user clicked on some element

K2DElement[] elements = e.getView().getLayerManager().getElementsAtPoint(e.getWcCoord(), e.getView().getViewState(), false);

menuAction.setEnabled(elements.length > 0);

}

});

Adding a section to a layer’s settings window

Abstract methods of the AbstractLayerSettingsCustomPage class:

// Obtain a reference to the ShowLayerSettingsAction

instance ShowLayerSettingsAction showLayerSettingsAction = (ShowLayerSettingsAction)appContext.getApplicationActionManager()

.getAction(ShowLayerSettingsAction.class);

// Add the custom panel for the Cities layer

showLayerSettingsAction.addLayerSettingsCustomPage(SDKLayerSettingsPanel.class.getName(), layerCities.getId());

Adding a custom button to the layer manager

You can add buttons associated with a layer in the layer manager. These buttons can be used to trigger custom actions that are specific to a layer. The buttons are added in different ways in the hierarchical section and list section.

The following source code example shows how to add a button to the Cities layer.

// Obtain layer instance from layer manager

Layer layerCities = appContext.getViewManager().getLayerManager().getLayer("Cities");

JMapGuiService guiService = appContext.getApplication().getGuiService();

JMapGuiFactory guiFactory = guiService.getGuiFactory();

AbstractButton abstractButton = guiFactory.createButton(new ButtonAction());

// Add the button to the 'More options' of the LayerTreeBar (hierarchy) for the layer Cities

guiService.getLayerTreeBar().addCustomButton(abstractButton, layerCities.getId());

// Add the button to the LayerPanel of the LayerBar (list) for the layer Cities

LayerPanel layerPanel = guiService.getLayerBar().getLayerPanel(layerCities.getId());

Button button = new Button(new ButtonAction(), false, new Dimension(18, 18));

layerPanel.addCustomButton(button);

Deploying JMap Pro Extensions

To be deployed within JMap Pro applications, client extensions must follow certain rules. If these rules are met, the extension appears in the deployment section of JMap Admin.

1. Group extension classes in an archive (JAR)

   All classes and resources (images, etc.) of the extension must be contained in a single JAR archive file. Use a meaningful and unique name, as this name will be used in the following steps.

2. Include a manifest file

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

   Here is an example of a manifest file's content:

   extension_class: jmap.extensions.edition.EditionExtension

   extension_name: Edition

   extension_version: 1.0.0049

3. Provide a JNLP file

   The JNLP file is required. It describes the deployed library. The file must have the same name as the extension's JAR file (except for the .jnlp extension). The following example shows the parts that must be changed in bold.

   <?xml version="1.0" encoding="utf-8"?>

   <!-- JNLP File for Extension libraries -->

   <jnlp

   spec="1.0+" codebase="http://$JMAPSERVER_HOST$:$JMAPSERVER_WEBPORT$$PATH$/edition_client"

   href="edition_client.jnlp">

   <information>

   <title>Edition Extension</title>

   <vendor>K2 Geospatial</vendor>

   <description>Edition Extension</description>

   <description kind="short">Edition Extension</description>

   </information>

   <security> <all-permissions/> </security>

   <resources> <jar href="edition_client.jar"/> </resources>

   <component-desc/>

   </jnlp>

4. Place the files in the correct directory.

   All files that make up the extension (JAR, JNLP, and other files) must be placed in a directory created specifically for the extension and located within the directory for Client Extensions (JMap_HOME/extensions/client). The name of the extension's directory must be identical to the name of the extension's JAR. The following image shows how files and directories are organized in Windows for K2 Geospatial's Edition extension.

Signing Extensions

The signature of a Java library certifies that the library comes from an identifiable source and that its content has not been altered. The user who executes the library’s code can trust the authenticity of the library. This is even more important when the library requires system access that can cause security issues such as data access, network access, etc.

The Java API documentation for JMap 7 is available online at .

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 setCureentTool(Tool) of the View or ViewManager 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 Tool 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 onToolClicked() 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.

The following table lists the classes for drawing tools available in JMap. All these classes are derived from the ToolDraw class.

The following table lists the most commonly used methods of the ToolDraw class.

The following code example shows a tool derived from ToolDrawPolygon that inherits all of its drawing capabilities.

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

}

}

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

The JMap Extensiom Builder is a tool that allows you to quickly generate the source code for JMap client and server extensions. The generated source code is basic, and you must complete it in order to implement the functions of your extension. This tool helps you save time by allowing developers to focus on the real purpose of their development activity instead of dealing with the technical details of programming and deploying JMap extensions.

The tool has a GUI and may also be used in the command line, without a GUI. The parameters accepted by the extension builder are shown below. Note that they are all optional, and default values are used for the missing parameters.

The easiest way to run the extension builder is to use the Ant script provided with the tool. The parameters passed to the tool can be modified within the Ant script.

ant -f extensionbuilder.xml

The extension builder can also be executed using the command line (on Mac or Linux, replace “” with “” in the classpath).

java -classpath extensionbuilder.jar;../../lib/kheops_util.jar jmap.sdk.tools.extensionbuilder.ExtensionBuilder -name extensionname -class classname -dest destfolder -target target -gui true\false

After running the tool, the target directory contains the sources of the extension generated as well as some other files. If a client extension was requested (client or both options), there will be a JNLP file, a keystore.jks file (for your client extension’s signature), and a featureslist.properties file. If a server extension was requested (server or both options), there will be a JSP file (configuration interface of server extension). An Ant script (build.xml) is also created in the directory. This script can be used to compile the extension and generate the JAR archives for the client and server.

The following image shows the structure of the generated files.

To run the Ant script, simply run the ant command from the destination directory. After the script has been run, the dist directory will contain all the files to be deployed on JMap Server. The following image shows the structure of the generated files.