Client-Server communication

This text describes the technical details of the communication between censhare clients and the application server, advanced network scenarios with encryption, socket mapping and data compression, the necessary setups and customization options as well as the client-specific preferences and the structure of the hosts.xml-file.

The following instructions apply to all Java-based censhare clients, namely the censhare Client, the censhare Admin-Client, the censhare Render-Client and the censhare Service-Client.

Communication sequence

censhare’s Java-based client applications communicate with the application server by means of the TCP/IP protocol stack. Communication is initiated by the client application upon user login by probing the hosts network address on a negotiation port for the RMI registry. Hostname and RMI port for this initial contact are looked up in the hosts.xml-file of the censhare preferences environment. The RMI port defaults to 1099, but might be replaced with any other value by adding :portnumber to the hostaddress. The RMI port has to match the server-side RMI port definitions which are maintained with the censhare Admin-Client.

After a successful RMI registry, the application server transmits a communication port and host-address for the continuative communication between client and server. The communication port is randomly chosen by the server from a pre-defined, customizable range of communication port numbers that default to 30543-30548. Client and server then keep their communications on that port until the client application is terminated or the user logs out.

It is important to understand that the host-address and port-assignment in the hosts-preferences of the client are only used for the initial establishment of the RMI-communication, while all other subsequent communication is executed against a host and port that is disclosed by the application server anew on every login.

Binding names

Communication between server and client can be unencrypted or encrypted. The client application tells the server during initial RMI registration, whether communications should be encrypted or not by sending a binding name, which is either "corpus.RMIServer" for unencrypted communication or "corpus.RMIServerSSL" for encrypted communication. The binding name is part of the host URL.

The special binding names "corpus.RMIServerMap" and "corpus.RMIServerMapSSL" are used for socket mapping scenarios (see below).

Port numbers

In a fresh censhare install, the application server setup has the following ports predefined:

1099 for the initial RMI registry
30543-30545 for unencrypted communication (binding name "corpus.RMIServer")
30546-30548 for encrypted communication (binding name "corpus.RMIServerSSL")

All port numbers can be changed with the censhare Admin-Client. No port numbers in the range 0-1024 should be assigned, as these ports require extended administrative permissions in Unix/Linux-environments (including Mac OSX).

Please be aware, that the client hosts-preferences need to be updated every time the RMI registry port is changed!

It is not necessary to provide multiple communication ports. While a range of 3 ports is pre-set in the censhare system, this range might as well be reduced to only one port or extended to a larger number of ports. The main reason for providing a range of ports is to allow the application server some load balancing by providing multiple TCP-server-socket-processes and it depends on the number of concurrent users and network-load, whether a larger range of ports actually improves performance or not. A benchmark test under load conditions might be executed to determine the optimal port range size. This test can easily be executed, as the communication ports can be changed on the server-side without the need to adapt client preferences.

Keep in mind, that a larger range of communication ports might cause a little more effort in the network administration, as the entire range has to be maintained in VPN/NAT/Firewall configurations.

Host URLs

The censhare client applications need a hostname, port number, and binding name to establish initial contact with the application server. This information is combined in an URL string and stored in the hosts.xml client preference file. The format for this string is as follows:

[protocol]//hostname[:portnumber]/binding-name

If the port number is omitted, it defaults to 1099. The optional protocol prefix is only required for single port environments (see below).

Examples:

//192.168.86.200/corpus.RMIServer //censhare.office-on-the.net:1025/corpus.RMIServerSSL

Single port environments

It is possible to reduce the necessary services for all client-server communications to only one port, which means that the RMI registry service and communication service have to be combined.

The host URL in the client preferences requires a protocol prefix to work in a single port environment. The prefix is "rmi:" for unencrypted communication and "rmis:" for encrypted communication (these protocol prefixes are not part of the official TCP/IP protocol family and only work in the censhare environment!).

Examples for single-port host URLs:

rmi://192.168.86.200/corpus.RMIServer rmis://censhare.office-on-the.net:1025/corpus.RMIServerSSL

Port mapping

Application server and client might be separated by a Firewall. This constellation sometimes raises the demand for port mapping, which means that the client communicates to a given port that is forwarded to another port of the host by the firewall. Port mapping is supported by censhare. It is necessary to make the port definition for the client-side of the firewall for the client and to use the dedicated binding-names "corpus.RMIServerMAP" (unencrypted) and "corpus.RMIServerMapSSL" (encrypted) for the host URL in the client host preferences. Port mappings can also be used in single port environments.

Examples:

rmis://demo.censhare.de:443/corpus.RMIServerMapSSL

Compression

Communication between the censhare clients and the application server is uncompressed by default. However, a compression feature is built into censhare that transparently compresses all communication between client and server. The compression feature is activated by setting a compression level in the host settings dialog of the client application. The compression levels range from 0 (no compression) to 9 (maximum compression). Compression takes time and the higher the compression level, the more time is used up in packing and unpacking the data. It is therefore necessary to find a compression level threshold, where the time that is wasted by compression is less than the time that is saved in the network traffic of the minimized data. This effect depends on a lot of parameters, for example, the network bandwidth and the kind of data that is transported. JPEG-images for example, cannot be significantly downsized as they are already reduced, while database requests can be compressed a lot. The best way would be to do benchmark tests in the real production environment, but the following values are recommended by experience:

Compression level 0 (= no compression) in local area networks (LANs).
Compression levels 1-3 in WAN connections.
Compression levels 4-9 in rare, ultra low bandwidth conditions.

In our own benchmark tests, we could not produce statistically significant improvements with compression levels higher than 3.

All port definitions are specific to one application server. In environments with multiple application servers, individual settings can be applied to each application server. The clients follow the settings of the application server to which they connect.

All client-specific network settings are stored in the hosts.xml file.