Introduction to WebSockets in INTGeoServer

Starting July 5th, 2017, INTGeoServer can be accessed through through WebSockets in addition to classic HTTP requests. A WebSocket is a full-duplex data transport protocol standardized in 2011.

A client code using WebSockets is known as a client end point. Client end points are more complex to implement than classic HTTP clients but have a higher performance profile.

A server code using WebSockets is known as a server end point. You do not need to implement any end point in INTGeoServer, server end points are transparent to developers just like servlets are transparent to developers.

For example, to query the serverinfo web service using the classic HTTP protocol, you would typically access this address:

http://myserver.mycompany.com/INTGeoServer/json/serverinfo

In this address, json is the identifier of the servlet being accessed and serverinfo is the name of the web service. In INTGeoServer, the servlet identifier is identical for all services, only the service name changes. In HTTP terminology, the service is uniquely identified by its pathInfo. The pathInfo in this case is /serverinfo

Just like the servlet address is identical for all services, the server end point address is identical for all services:

ws://myserver.mycompany.com/INTGeoServer/jsonendpoint

The message sent by the client end point is formatted in the JSON format and contains the requested service name, preceded by a /

Example: {"pathInfo":"/serverinfo","json":{}}

The attached DemoWebSockets.java client class creates this output:

INFO: webSocketGet ws://localhost:8080/INTGeoServer/jsonendpoint with path info /serverinfo

Sent:{"pathInfo":"/serverinfo","json":{}}

Received:{"name":"INT GeoServer","version":"2.58","build":"150-3ae07c4f44bb37c46a790e58bde4c39e4f214c28","fileProviderEncoders":"plain","fileSeparator":"\\","fileProvider":"Default","homePath":"D:\\INT_GEOSERVER_HOME","localTime":{"day":5,"dayOfYear":186,"month":6,"year":2017,"hour":4,"minute":46,"second":5,"millisecond":948},"intViewerGeoServer":{"type":"expires","expiration":{"daysUntilExpiration":90,"day":3,"dayOfYear":276,"month":9,"year":2017}}}

The serverinfo web service is the simplest web service as it doesn't require any parameter. If parameters are needed, they should be passed in the message as part of the json attribute.

Sample client code

Here is the main part of the code reading the content of a WebSocket:

Running the sample client code

There are several gotchas that you need to be aware of to use WebSockets.

The distributions of Tomcat do not include a tomcat-juli.jar file that is needed to support WebSockets out of the box. This file is attached at the bottom of this page. Add this .jar file to your tomcat/lib directory to support WebSockets (Ex: D:\Apache\apache-tomcat-8.5.16\lib\tomcat-juli.jar)

Oracle JDK's doesn't include a implementation of WebSocket clients, only a public API. You need to add a "tyrus-standalone" library to run your client project.

Other libraries are also needed by the tyrus libraries. The NetBeans screenshot above shows all libraries required to run the test class. Except for the tyrus library itself, they are all part of the INTGeoServer distribution and can be found in webapps/INTGeoServer/WEB-INF/lib .

Disabling WebSocket capabilities

By default, INTGeoServer is configured to allow access through WebSockets.

To disable WebSockets completely, add the following line to your layer.xml file:

<folder name="com.interactive.intgeoapi.server.endpoints.AbstractIntGeoServerEndPointListener">

<file name="com.interactive.intgeo.server.lifecycle.DisableAllIntGeoServerEndPointListener.instance"/>

</folder>

Optionally, you can remove instead the WebSocketsSupport.jar file from the WEB-INF/lib directory.