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.

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

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 (JMapApplicationLauncher class), which covers the type of application (applet, Java Web Start or standalone Java) and instantiates the application class (instance of the JMapApplication class) to be used. The second level is the JMap Pro application; it is driven by its abstract class, JMapApplication, which provides all the services required to ensure its proper operation. Since the JMapApplication 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 (JMapClientExtension class) to add new features to applications. JMap Pro extension development is explained in the following section.

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

Application services

Application context

When initializing the application, all useful instances that define the application’s execution context are stored in a singleton of the JMapApplicationContext class.

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

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.

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

}

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.

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

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.

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

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.

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.

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

}

}

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:

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.

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

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

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

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.

Examples

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

Managing Tools

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

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:

Working With Vector Styles

Recommendations

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

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

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

});

JMap Web’s design allows the embedding of JMap Web deployments into your own web applications. This section details the necessary steps to enable application embedding.

Copying the JMap Web Libraries and Dependencies to Your Web Server

Your deployed JMap Web applications, as they are now being served by JMap’s embedded Tomcat instance, contain the libraries and web services required for application embedding. Your application’s files are located in the /applications/deployed directory of your JMap Server.

Among those files is the jmap directory. It contains all necessary resources required to embed your JMap deployment. This directory and its contents must be copied to your web server and be accessible by your web application’s pages.

JMap Web’s dependencies will be loaded as part of the initialization process prior to displaying the map. For more details regarding the initialization process refer to the JMap Web’s Initialization Process section of this document.

• JQuery is required during the map initialization process and as such must be present in your application’s document.

• Including JMap Web’s dependencies’s stylesheets will alter the styles of your document. Currently, there is unfortunately no way to avoid this.

Authorizing Cross-Origin Resource Sharing

In order to allow JMap Web Deployments to be embedded, a few tweaks to your deployment’s web.xml files are necessary.

• Modifying the deployment’s web.xml file will require you to unload/load your deployment. This can be done in JMap Admin’s deployment section.

• All modifications to your deployment’s files will be lost if you update the deployment or its template’s files.

Included in your deployed application’s directory is an embed_example.html file. It serves as an example of a JMap Web embedded application. Open that file in a text editor to see how application embedding is done.

You can copy that file to a separate web server in order to confirm that Cross-Origin Resource Sharing and the X-frame-options were properly enabled.

Embedding a map in an iframe:

To display JMap Web in an iframe, simply add the iframe with the “scr” attribute pointing to the JMap Web deployment.

<!-- Add this if you use google maps features in your deployment --> <iframe height="450px" width="600px" src="https://jmap7.jmaponline.net/montreal_web"></iframe>

You can also pass a sessionId, see the embed_example page on how to retreive a session Id from the REST API.

<!-- Add this if you use google maps features in your deployment --> <iframe height="450px" width="600px" src="https://jmap7.jmaponline.net/montreal_web?sessionId=123456789"></iframe>

You will most likely be displaying the map from another origin, to allow the application to be displayed from another origin, the next step is to update your deployment and add your allowed origins in the advanced options.

If you encounter this message in the web console, make sure you allow the origin in the X-frame-options with options “Any” or “Allow-from”:

Refused to display 'https://jmap7.jmaponline.net/montreal_web/' in a frame because it set 'X-Frame-Options' to 'sameorigin'.

Embedding a map in a Div

To have the application code ready you will need to add the following lines in the <head> portion of the document where you wish to embed your deployment.

*Note that the code in /jmap is available without login because it is allowed in the bypass filter of your deployment.

<!-- Add this if you use google maps features in your deployment --> <script type="text/javascript" src="https://maps.googleapis.com/maps/api/js?v=3.36&key=YOURGOOGLEMAPKEY"></script> <link rel="stylesheet" href="[YourDeploymentAdress]/jmap/css/jmap.min.css"> <script type="text/JavaScript" src="[YourDeploymentAdress]/jmap/jmap.min.js"></script>

• You might need to adjust the relative path mentioned above.•Including JQuery is not necessary if you already use it. JMap Web requires a minimum version of 2.2.4 to assure most functionalities

• Be aware that this will replace your JQuery librairy, if you need to keep a specific version, consider using an iframe instead.

To initialize the map, you will need to provide an empty div into which the map will be created.

// <div id="map" style="height: 600px; width: 600px;"></div>

Note the JMap Web tool bar takes a static height of 45 pixels.

Include the following Javascript to trigger map initialization without Authorization.

// <script type="text/JavaScript">  
$(document).ready(function() {   
var options = {    
// The URL of your deployed application. This must be an address that your users may access.    url: 'http://192.168.0.80:8080/web_deployment',   
};     
JMap.initialize(document.getElementById('map'), options);  
}); 
</script>

The JMap.initialize function that is called above is the same as the one that was detailed previously here. You may customize the embedded application by specifying those same configuration properties in a mapConfig object literal supplied in the options argument.

Dealing with Authentication in a Div

If you enabled controlled access on your JMap Web deployment, you will need to authenticate as a JMap User prior to initializing the map.

The following is provided as an example and IS NOT a recommended way of authenticating yourself to JMap Server:

// <script type="text/JavaScript">   
$(document).ready(function() {    
$.ajaxSetup({     
xhrFields: {      
withCredentials: **true**     
}    
});      
$.ajax('http://192.168.0.80:8080/web_deployment/ajaxdispatch', {     
data: {      
action: 'ping'     
},     
beforeSend: function(xhr) {      
// Replace 'USERNAME:PASSWORD' with a valid string value.      
xhr.setRequestHeader('Authorization', 'Basic ' + btoa(**'USERNAME:PASSWORD'**));     
},    
}).done(function(data, textStatus, jqXHR) {     
var options = {      
url: 'http://192.168.0.80:8080/web_deployment'      
mapConfig: {},      
onMapInit: function() {       
console.log('Map was initialized.');      
}     
};       
JMap.initialize(document.getElementById('map'), options);    
});   
}); 
</script>

Dealing with CORS (Cross-Origin Resource Sharing)

If your map is located within the div of a page that is hosted on a different Origin that of your JMap Server, you will need to modify the Cors filter options of your web.xml file.

Check the Tomcat documentation here

Instantiate and map the CORS filter, start by activating the Cross-Origin Ressource Sharing option in the Advanced Options of the Deployment’s Wizard and skip to the end.

Open the web.xml and look for the CorsFilter settings.

<filter>

<filter-name>CorsFilter</filter-name>

<filter-class>org.apache.catalina.filters.CorsFilter</filter-class>

<init-param>

<param-name>cors.allowed.headers</param-name>

<param-value>Content-Type,X-Requested-With,accept,Origin,Access-Control-Request-Method,Access-Control-Request-Headers,Authorization,Cookie</param-value>

</init-param>

<init-param>

<param-name>cors.exposed.headers</param-name>

<param-value>Access-Control-Allow-Origin,Access-Control-Allow-Credentials</param-value>

</init-param>

</filter>

<filter-mapping>

<filter-name>CorsFilter</filter-name>

<url-pattern>/*</url-pattern>

</filter-mapping>

Example for a map embedded without Authorization requirements, needs to allow anonymous login.

<filter>

<filter-name>JMapLoginFilter_index</filter-name>

<!-- ... -->

<init-param>

<param-name>httpauthentication</param-name>

<param-value>false</param-value>

</init-param>

</filter>

<!-- ... -->

<filter>

<filter-name>CorsFilter</filter-name>

<filter-class>org.apache.catalina.filters.CorsFilter</filter-class>

<init-param>

<param-name>cors.allowed.origins</param-name>

<param-value>*</param-value>

</init-param>

<init-param>

<param-name>cors.allowed.headers</param-name>

<param-value>Content-Type,X-Requested-With,Origin,Cookie</param-value>

</init-param>

<init-param> <param-name>cors.exposed.headers</param-name>

<param-value>sessionId</param-value>

</init-param>

</filter>

<filter-mapping>

<filter-name>CorsFilter</filter-name>

<url-pattern>/*</url-pattern>

</filter-mapping>

Example for a map embedded with Authorization requirement

Note that the wildcard (*) mark is not allowed in the origins list when you require authentication with Access-Control-Request-Headers, and credientials support must be set to true.

<filter>

<filter-name>JMapLoginFilter_index</filter-name>

<!-- ... -->

<init-param>

<param-name>httpauthentication</param-name>

<param-value>true</param-value>

</init-param>

</filter>

<!-- ... -->

<filter>

<filter-name>CorsFilter</filter-name>

<filter-class>org.apache.catalina.filters.CorsFilter</filter-class>

<init-param>

<param-name>cors.allowed.origins</param-name>

<param-value>http://192.168.0.37:8081,https://www.google.com</param-value>

</init-param>

<init-param>

<param-name>cors.allowed.methods</param-name>

<param-value>GET,POST,HEAD,OPTIONS,PUT,DELETE</param-value>

</init-param>

<init-param>

<param-name>cors.allowed.headers</param-name>

<param-value>Content-Type,X-Requested-With,accept,Authorization,Origin,Access-Control-Request-Method,Access-Control-Request-Headers,x-auth-token,Cookie</param-value>

</init-param>

<init-param>

<param-name>cors.exposed.headers</param-name>

<param-value>Access-Control-Allow-Origin,Access-Control-Allow-Credentials,sessionId</param-value>

</init-param>

<init-param>

<param-name>cors.support.credentials</param-name>

<param-value>true</param-value>

</init-param>

</filter>

<filter-mapping>

<filter-name>CorsFilter</filter-name>

<url-pattern>/*</url-pattern>

</filter-mapping>

This section details how to develop for JMap Web as well as how to integrate JMap Web into other web applications.

JMap Web is a web application that uses technologies such as HTML5, JavaScript, CSS and JSON. The JMap Web application is built on top of third-party JavaScript libraries including OpenLayers, jQuery and many others.

General Information

Brief Overview of JMap Web’s Design

JMap Web provides a web application capable of interacting with JMap Server. Its user interface is primarily intended for use on laptop and desktop web browsers.

The key elements of a deployed JMap Web application are the following:

• The client: Can be described as a single-page application (index.jsp). The client is considered the web page as it is rendered in the user’s web browser.

• A Web Map Service: Provides access to the map’s tiles.

• The AJAX Dispatcher: A web service to which HTTP requests are sent. The AJAX Dispatcher then dispatches the request to the appropriate “Action Handler”. This will be further discussed in the Sending Server Requests and Custom Actions section of this document.

Third-party JavaScript Libraries Used

At the time of writing this document, JMap Web currently uses the following third-party Javascript libraries. Your extensions may leverage these libraries without any additional configuration. The following table includes a brief description of how JMap Web uses these libraries.

JMap Javascript Libraries and Their Architecture

In addition to the libraries previously mentioned, JMap Web also includes its own libraries based on OpenLayers’s Class base type. This allows JMap Web to benefit from object oriented programming paradigms in a Javascript context (which usually favors a more prototypal and functionnal approach).

A JMap Javascript library essentially consists of a collection of Javascript files, styles sheets (CSS) and resources (images, sounds, etc.).

JMap Javascript libraries have been designed for use in different application templates of the “JMap Web” deployment type. By spreading the code across several libraries, code reuse is possible in various environments such as JMap Web. JMap Javascript libraries define unique behavior for specific contexts.

JMap Web uses the following JMap Javascript libraries:

• core

• desktop_ui

Reusable model classes are usually defined in the core library. As such, it is frequently used and is included in the vast majority of “JMap Web” application templates.

The core library is written in JavaScript ES5. In addition to JMap model classes, it includes custom OpenLayers controls and layers, HTML5 functionality wrappers and more. The core library is JMap Web lowest level Javascript library. It handles general tasks such as the initialization process of the map. All other library is then loaded on top of it as an extension.

As for desktop_ui, it mostly contains classes that focus on user interface elements. It directly makes use of the DataTables, jQuery and Twitter Bootstrap Javascript libraries. All visual elements that are not managed by OpenLayers are defined within desktop_ui.

JMap Web Public API

Included in JMap 7 is JMap Web’s public API which allows developers to easily integrate with JMap functionalities.

A generated JSdoc documentation of the javascript API is available online at http://dev.k2geospatial.com/jmap/web/api/7.0/.

JMap Web’s Initialization Process

Before moving onto the creation of a JMap Web extension, this section will explain JMap Web’s initialization process.

The JMap Web application template’s files are located in $JMAP_HOME$/applications/templates/html/web/index.jsp

This is the web document that will be served by JMap Server as the application is being requested by the user. Open this file in a text editor application. As you can notice, both jQuery and a jmap.min.js are loaded in the head portion of the document.

Further down, the map is initialized once the document is ready for manipulation.

var options = {

url: '$APPLICATION_PROTOCOL$://$APPLICATION_HOST$:$APPLICATION_WEBPORT$$PATH$',

language: '$LANGUAGE_CODE$',

embedded: true,

mapConfig: {

// Configuration properties

},

onMapInit: function() {

console.log('Map was initialized.');

}

};

$(document).ready(function() {

JMap.initialize(document.getElementById('map'), options);

});

JMap.initialize(map, options)

The JMap.initialize function is defined in the jmap.min.js file. It loads all necessary dependencies and will then initialize all of the application’s required objects. Among those objects are the globally available JMap.app and JMap.app.map.

The JMap.app object is an instance of the core library’s Application class. The JMap.app.map object is an instance of the ol.Map class.

The mapConfig object may include the following properties to customize the application. The default value is identified in bold.