JMap Server Services

JMap Server Class

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

JMapHome

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

Logging

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

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

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

Most commonly used methods of the Logger class

log(int, String)

Logs a message of the specified level.

log(int, String, String)

Logs a message of the specified level associated with the specified user.

log(int, String, Throwable)

Logs a message of the specified level and the trace of the exception passed as a parameter.

log(int, String, Throwable, String)

Logs a message of the specified level, associated with the specified user, and the trace of the exception passed as a parameter.

setLogLevel(int)

Changes the level of the messages that will be recorded.

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

•LEVEL_DEBUG
•LEVEL_INFO
•LEVEL_WARNING
•LEVEL_ERROR
•LEVEL_FATAL

 

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

 

  // Logs a message of level INFO

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

 

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

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

 

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

  Exception e = ...;

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

 

 

Databases

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

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

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

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

 

Most commonly used methods of the DatabaseConnectionPool class

borrowConnection()

Borrows a JDBC connection from the pool. The connection is then reserved exclusively.

returnConnection(Connection)

Returns a JDBC connection borrowed from the pool. It is very important to call this method after using a connection.

getStatus()

Provides the status of the connection pool. Can be called to validate that the pool is working correctly before borrowing a connection. The possible statuses are defined by constants of the ConnectionPoolInfo class (CONNECTION_NOT_TESTED, CONNECTION_ERROR or CONNECTION_OK).

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

 

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

  Connection conn = null;

 

  try

  {

    conn = pool.borrowConnection();

   

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

   

  }

  catch (SQLException e)

  {

    e.printStackTrace();

  }

  finally

  {

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

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

    if (conn != null)

      pool.returnConnection(conn);

  }

 

 

Extracting spatial data

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

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

 

Most commonly used methods of the JMapServerDataManager class

extractElements (JMapServerProject, JMapServerVectorLayer, QueryFilter[], Attribute[])

Extracts the spatial data and attributes that pass the filters passed as parameters, for the specified of the specified project. Only attributes that are specified in the last parameter are included in the result.

extractElements (String)

Extracts spatial data and its attributes based on the query passed as parameters. The general syntax for queries is the following:

select element from $ $ source {$ {project} $ PROJECT_NAME layer layer_name {}} WHERE condition

Example:

select element from $ $ source {$ {project} The World Countries {$ layer}} Where COUNTRY = 'Peru'

extractElements (String, long[])

Extracts spatial data and its attributes based on to the query passed as parameters and the list of identifiers specified. Only items whose identifier is in the list are returned.

extractElements (String, long[], OrientedRectangle)

Extracts spatial data and its attributes based on the query passed as parameters, the list of identifiers and the region specified. Only elements whose identifier is in the list and who intersect the region are returned.

 

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

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

 

Types of query filters

AttributeFilter

Sets a condition based on a data attribute. The condition is defined by an attribute and a set of values​​. Only data for which the attribute has a value included in the set of values will pass the filter.

GeometryTypesFilter

Sets a condition based on the type of data geometry. The condition is defined by one or more types of geometries. Only data with a geometry type matching the filter will pass the filter.

SpatialQueryFilter

Sets a spatial condition. Only data meeting the condition will pass the filter. The condition is defined by a geometry and a constraint. For example: all geometries that intersect the specified polygon, all geometries that contain the specified point, etc.

SQLQueryFilter

Sets a condition in SQL. This is the equivalent of the where clause in an SQL query. The where clause is interpreted by the database system that contains the data.

 

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

JMapServerProject serverProject = ...

JMapServerVectorLayer serverLayer = ...

Polygon region = ...

 

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

 

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

final SpatialQueryFilter newFilter = new SpatialQueryFilter();

 

  newFilter.setGeometry(region);

  newFilter.setType(SpatialQueryFilter.SPATIAL_OP_INTERSECTS);

 

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

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

 

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

JMapGeoElement[] result = dataMgr.extractElements(serverProject,

                                                    serverLayer,

                                                    new QueryFilter[]{newFilter},

                                                    serverLayer.getBoundAttributes() );

 

 

Sending emails

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

 

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

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

 

  try

  {

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

  }

  catch (AddressException e)

  {

    e.printStackTrace();

  }

  catch (Exception e)

  {

    e.printStackTrace();

  }

 

 

Session Manager

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

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

 

public JMapExtensionResponse processRequest(JMapExtensionRequest request)

{

  int sessionId = request.getSessionId();

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

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

 

   ...

 }

 

 

User Manager

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

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

 

Most commonly used methods of the UserManager class

getUser(String)

Returns the user (instance of the User class) whose name is specified as a parameter.

getGroup(String)

Returns the group (instance of the Group class) whose name is specified as a parameter.

users()

Returns the list of users (instances of the User class) used by JMap Server.

groups()

Returns the list of groups (instances of the Group class) used by JMap Server.

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

 

Workspaces

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

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

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

 

Most commonly used methods of the WorkSpaceManager class

getUserWSDirectory(String)

Returns the full path to the workspace directory for the user specified as a parameter.

emptyUserWS(String)

Erases all the content of the workspace for the user specified as a parameter.

deleteUserWS(String)

Clears the workspace directory of the user specified as a parameter.