SICS Naming Service

SICS Naming Service

Brief Description #

The SICS Naming Service (SNS) is responsible for mapping users to SICS Workstations. The SNS is a JEE web application based on JAX-WS and the METRO web services stack.It must be run within a JEE application server.

The list of registered users / workstations is persisted (stored) in a SICS database. The SNS connects to the database via a JNDI datasource.

SNS is stateless. That is, each web service request will read data from the database. There is no caching. This allows for running SNS in a clustered setup, and also protects against loss of data if the SNS should abend.

SNS Configuration #

Some properties of SNS are configurable:

  • Port number on which the SNS will listen and accept incoming calls for its published Web Services. This is configured in the JEE container (Tomcat, WebSphere, etc) where SNS is deployed.
  • List of IP addresses, from which SNS will accept (consider as valid) requests for the ‘LOOKUP REGISTERED USER’ service. The list must be contained in a file which is defined as a context-parameter allowed.ip.address.file in web.xml. The context-parameter may be missing, or the defined file may be empty, in which case SNS will accept any lookup request.
  • When the automatic cleanup process should run and how often each workstation is to be checked/verified, see paragraphAutomatic cleanup of dead sessionsbelow.

Automatic cleanup of dead sessions #

The SNS is set up to automatically remove dead sessions, i.e. check registered workstations, and de-register those which do not respond.

A clean-up process starts at regular intervals ("verificationInterval") and (re-)check registered workstations. To avoid checking workstations too often a workstations check interval must be specified ("verificationAge").

The feature is enabled for new versions of SICS. The default value for verificationInterval is 10 seconds and verificationAge is 240 seconds.

The automatic cleanup process can be configured and turned on/off by setting values in the file WEB-INF\sns.properties and restart the SNS.

#   Specify how often automatic verification of workstations should 
#   be carried out. 
#   The interval is in seconds.
#   
#   If for example the interval is 60 seconds the verification process 
#   will start up every 60 second.
#   If the process takes more than 60 seconds a new process will be 
#   started when the first one is finished even if that is more than 
#   60 seconds ago.  
# 
#   The verification process can be inactivated by setting the
#   verificationInterval to 0 seconds.
verificationInterval=10
#
#   Specify an interval in number of seconds. 
#   Any registration entry with a 'last verified' timestamp older than 
#   this number will be attempted 
#   verified when the automatic verification process executes.
verificationAge=240

Note that by setting the verificationInterval to 0 the automatic cleanup process will be inactivated and no cleanup will take place.

Also note that the SNS web application locate the sns.properties file from the context parameter sns.properties.file in WEB-INF\web.xml.

<context-param>
  <param-name>sns.properties.file</param-name>
  <param-value>WEB-INF/sns.properties</param-value>
</context-param>

So if you want to rename the sns.properties file or change it location on disk you should change the for the sns.propeties.file context parameter and restart the SNS.

Status and current values for the automatic cleanup process is shown in bottom of the SNS administration web page.

live_desktop_and_sns_server_4.png

Web Services #

These are the Web Services published by SNS. All parameters are mandatory unless otherwise indicated.

Service requests may be sent via http or https.

Registration of SICS Workstation #

Usage #

  • Use of this service is intended for SICS Workstation only.

Incoming parameters #

  • SICS User Name, Database Name, Database Schema, OS (Windows) User Name, Port Number.

Processing #

  • (Unless otherwise indicated, ‘user’ refers to the SICS User Name.)
  • SNS will extract the IP address of the calling SICS Workstation from the incoming Web Service request.
  • SNS will update its list of registered users / workstations. This list will be persisted in one or more tables in a SICS database. A user may register several times, with the same and/or different IP addresses and the same and/or different database information. However, for each unique combination of user name and database information, only the most recently registered workstation (IP address and port number) will be remembered by SNS.
  • For authentication purposes, SNS will associate a random token (a text string) with this registration. The use of this token is described elsewhere in this specification.
  • Considering what is mentioned above, the list of registered users will actually be a list of registration entries. Each entry is identified by the user name & database information, and contains the user’s OS User Name, the IP address, the port number and the assigned token.
  • In further detail, the registration takes place as follows: SNS looks up the user in its list of registered users, using the user name and database information as lookup key.
  • a) If an entry is not found, a new entry is created, in which the IP address and port number will be set to the IP address and port number of the current registration call.
  • b) If an entry is found, this entry’s IP address and port number will be replaced with the IP address and port number of the current registration call.
  • In both cases will a new token be assigned, and the provided OS User Name will be remembered (although it has no use except being shown as information on the SNS administration web page).

Response #

  • Token to be used by the SICS Workstation for listening for incoming Web Service calls.

De-registration of SICS Workstation #

Usage #

  • Use of this service is intended for SICS Workstation only.

Incoming parameters #

  • SICS User Name, OS (Windows) User Name, database information and port number.

Processing #

  • SNS will extract the IP address of the calling SICS Workstation from the incoming Web Service request.
  • SNS will look up the user in its list of registered users, using the user name and database information as lookup key.
  • If an entry is found, it will be removed IF AND ONLY IF the entry’s IP address and port number match the IP address and port number of the current de-registration call.
  • The OS User Name will be ignored.

Response #

  • A normal response with no data.

Lookup Registered User #

Usage #

  • Use of this service is intended for external applications that need to query for the address of a user’s SICS Workstation instance.

Incoming parameters #

  • SICS User Name and database information

Processing #

  • SNS will verify validity of request: The IP address of the sender must be one of those listed in the SNS configuration file (unless this list is empty/missing).
  • If the request is valid, SNS will look up the user in the list of registered users, using the user name and database information as lookup key.

Response #

  • The response data structure consists of 4 fields: IP address, port number, token, and message.
  • If the request is valid and the user is registered, SNS will answer the IP address of the SICS Workstation, the port number, the token, and an empty message.
  • If the request is valid but the user is not registered, SNS will answer an informative message and no value in the three other fields.
  • If the request is not valid, SNS will answer an informative message and no value in the three other fields.

Is Available (Ping) Service #

Usage #

  • Use of this service is intended for external monitoring applications.

Incoming parameters #

  • No parameters

Processing #

  • SNS will respond if it is available and functioning correctly

Response #

  • A simple boolean (true) response indicating that the SNS is available and working correctly