Logo IMCCE-VOParis

THE IMCCE VIRTUAL OBSERVATORY
SOLAR SYSTEM PORTAL
Observatoire de Paris / CNRS

Logo IMCCE
Portal Home Page | Report issue | Legal notice | Contact us

- WebSampConnector 1.5 -
User's Guide

This article is translated to Serbo-Croatian language
by Vera Djuraskovic from Webhostinggeeks.com.

.: Quick start

  1. Download the WebSampConnector library
  2. Unpack the archive into your Web server structure (e.g. /[web_server_path]/WebSampConnector/)
  3. Deploy the WebSampConnector methods in your Web application:
    1. Add a link pointing to the WebSampConnector Javascript file in the head of your document:
      <script type="text/javascript" src="WebSampConnector/lib/websampconnector.js"></script>
    2. Write your own Javascript methods to send messages to VO-applications, and to handle the received messages.
    3. Add a link pointing to your Javascript file in the head of your document (1):
      <script type="text/javascript" src="myWSCHandlers.js"></script>
    4. Add a button (or whatever you want) to connect the Web page to the Samp hub:
      <button onclick="WebSampConnector.connect();">Connect to the hub</button>
    5. [Optionnal] Add a hub status icon in your Web page:
      <img id="myHubStatusIcon" src="WebSampConnector/example/icons/disconnected.png" alt="Hub Status"/>
    6. Add the Samp messaging actions on your data. For example, to broadcast a VOTable:
      <button onclick="WebSampConnector.sendMsg('table.load.votable','tableId','','http://[hostname]/xxx.xml','');">Broadcast VOTable</button>
    7. [Optionnal] Add a button (or whatever you want) to disconnect the Web page from the hub:
      <button onclick="WebSampConnector.disconnect();">Disconnect from the hub</button>
      Note that, when the Web page (or the Tab) hosting the WebSampConnector applet is closed then the connection to the hub is ended and the applet is destroyed. But it is more convenient to provide a button to allow the client to disconnect when he wants.
When the Java applet will start for the first time, the client will receive a security warning asking him to trust the content from the publisher. The certificate must be accepted by the client to enable the communication between your Web page and the client's Samp hub and VO softwares. The WebSampConnector applet does not write anything on the client's side. It just need to read the .samp file of the client which is created when a Samp hub is started.

The certificate provided with the WebSampConnector toolkit is signed as:

  • Name: WebSampConnector
  • Publisher: VOParis Data Centre
  • From: [your_hostname]

If you want to be the publisher of the certificate or if you want to tune the Japplet to your convenience, you will need to install the WebSampConnector sources, to compile and sign the applet, and to install the distribution files in your Web server architecture.

If you need the WebSampConnector policy file to trust the applet, you will have to edit the samp.policy file (delivered with the sources) and to adapt the path to access to the sampclientstore (which contains the trusted certificate). Read the file keystore/keygen.howto delivered in the source tarball.

.: Installation from sources

Prerequisites
  • - the Java compiler javac. We recommend the Sun Java JDK version 1.6.x.
  • - the keytool program to manage the keystore of private keys and their associated X.509 certificate chains authenticating the corresponding public keys
  • - the jarsigner program to sign the applet
Installation
  1. Download the WebSampConnector sources
  2. Unpack the archive into your preferred workspace
  3. Edit the following files and adapt the paths to match your architecture:
    1. build.xml: provide the pathnames of the required Sun Java plugin.jar and JSamp jsamp-1.0.jar. The jsamp.dir property should also point to the compiled JSamp sources to access to the JSamp target/classes directory
    2. keystore/samp.policy: adapt the first line to match your installation
  4. [Optional] Generate your personal key pair to identified the Java applet. Refer to the keystore/keygen.howto file for information about how to proceed
  5. Compile the Java sources and install the distribution files into your Web server structure:
    ant install
    You may prefer to just compile the sources, sign the applet and export the certificate by executing:
    ant compile
  6. [Optional] Compile the Javadoc. By default it will be created in the dist/javadoc directory. You can install the Javadoc into your Web server by using the ant target 'install-javadoc'. The Javadoc is then available by default at URL:
    http://localhost/WebSampConnector/javadoc/
  7. Write your own Javascript methods to send messages to VO-applications, and to handle the received messages. Install the Javascript file in your Web server structure
  8. [Optional] Test the WebSampConnector by running the example delivered with the sources. First, install the example into your Web server structure by executing:
    ant install-example
    then test the WebSampConnector at URL:
    http://localhost/WebSampConnector/example/example.html
Feel free to improve or modify the Java applet and the Javascript library to better match your requirements. The VO-PDC team will be very thankful if you left copy to us your improvements.

.: WebSampConnector Javascript API

The Javascript methods of the WebSampConnector library are defined within the WebSampConnector namespace, so that it will not interfere with other Javascript methods your Web site is using. The Javascript API is composed of two parts:

websampconnector.js
the core implementation of the WebSampConnector library, which should not be modified unless knowing what you made
myWSCHandlers.js
your own implementation of the WebSampConnector handlers, which have to be written by yourself to fulfill the behavior of your Web application (you can name the file as you want)

To use the WebSampConnector into your Web application, you have to load the Javascript files when your Web application starts:

<head>
 <script type="text/javascript" src="WebSampConnector/lib/websampconnector.js"></script>
 <script type="text/javascript" src="myWSCHandlers.js"></script>
</head>

You may also need to override some properties of the WebSampConnector to fulfill the requirements of your installation. This is done by calling the WebSampConnector.configure() method within the head declaration of your Web page, or by adding a call to this method at the beginning of your own Javascript file (see, for example, the example/example.js file), e.g.:

WebSampConnector.configure({
   jAppletId: 'WebSampConnectorApplet',
   jAppletCodeBase:'../lib/',
   jAppletVersion: '1.5'
});

Where the variables to be changed are:

jAppletId
- Id of the applet tag hosting the WebSampConnector Java applet (e.g. WebSampConnectorApplet)
- Default: 'WebSampConnectorApplet'
jAppletCodeBase
- Absolute path to the JApplet directory (e.g. /myapplets/websampconnector/)
- Default: './'
jAppletVersion
- Version of the WebSampConnector JApplet (e.g. 1.5)
- Default: '1.5'

If you just want to use the WebSampConnector to broadcast VOTable or images or whatever else to VO-applications then you will just need to use the core library (websampconnector.js file). If you also want your Web application to receive messages coming from VO-applications then you will also need to develop your own handlers. For that, you can use as a template the example (delivered with the library) or the demo available in the download Web page.

.: WebSampConnector callback function

The WebSampConnector library implements a callback mechanism to allow the developer to know the exact moment when the Java applet was initialized in the Web browser and thus is ready to respond to instructions. By default, the callback method is an empty method called WebSampConnector.onlineHandler(). This method is last action executed by the init() method of the Java applet. You are encouraged to override the onlineHandler by your own method to notify the client that the connection with the hub is established. For example, you can update the hub status icon like that:

WebSampConnector.onlineHandler = function(status){
   example.updateStatusIcon(status);
};

Look at the example.js file to have an idea on the way of doing.

.: Java to Javascript communication

For each public Java method provided by the WebSampConnector applet, it corresponds a Javascript method which has to be used to make your Web page communicate with the hub. The mapping of the Java to Javascript communication in function of actions is as follows:
ActionJavascript methodWayJava methodNote
To build the Japplet and connect the client to a hub WebSampConnector.connect() init()(1)
To disconnect the client from the hub WebSampConnector.disconnect() disconnect()
To know the status of the connection WebSampConnector.isConnected() isConnected()
To get the registered clients WebSampConnector.getRegisteredClients() getRegisteredClients()
To get the subscribed clients to a given MType WebSampConnector.getSubscribedClients() getSubscribedClients()
To notify a message WebSampConnector.sendMsg() sendMsg()
To send a point.at.sky pattern WebSampConnector.pointAtSky() pointAtSky()
To receive a point.at.sky pattern WebSampConnector.pointAtSkyHandler() pointAtSkyHandler()
To send a table.highlight.row pattern WebSampConnector.tableHighlightRow() tableHighlightRow()
To receive a table.highlight.row pattern WebSampConnector.highlightRowHandler() highlightRowHandler()
To send a table.select.rowList pattern WebSampConnector.tableSelectRowList() tableSelectRowList()
To receive a table.select.rowList pattern WebSampConnector.selectRowListHandler() selectRowListHandler()
To receive a spectrum.load.ssa-generic pattern WebSampConnector.spectrumLoadSsaHandler() spectrumLoadSsaHandler()
To send a script to Aladin WebSampConnector.sendAladinScript() sendAladinScript()(2)
Notes:
  • 1: when the connection with the hub is established, the JApplet init() method calls the callback function provided by the client through the WebSampConnector.onlineHandler() method
  • 2: this is a special feature of Aladin which is not part of the Samp standard
All the Java methods (except init(), getRegisteredClients(), getSubscribedClients() and receiving methods) return a boolean to notify the success of the action. All the Java methods (except init()) throw an exception (SampException and java.security.PrivilegedActionException) if an error occurs.

.: Java methods

The Java methods are described in detail in the Javadoc.

.: Javascript methods

The WebSampConnector namespace defines a set of Javascript methods to manage the connection/disconnection action with a SAMP hub, and to handle messages with the registered VO applications. The delivered script allows to broadcast data (VOTable, FITS table and image, SSA spectrum), to send messages based on 'point.at.sky', 'table.highlight.row' and 'table.select.rowList' patterns, to get the registered clients, and to get the clients which have subscribed to a given MType pattern. Developers are encouraged to override the Javascript receiving and administrative methods to act as you wish it. Look at the example.js file to have an idea on the way of doing.
Administrative Messages
WebSampConnector.configure()
→ Return: void
→ Usage: This method configures the WebSampConnector.
ArgumentsTypeDescriptionDefault
jAppletIdstringJava applet IdWebSampConnectorApplet
jAppletCodeBasestringPath to the Java applet jar file./
jAppletVersionstringVersion number of the applet1.5
Example:
WebSampConnector.configure({
   jAppletId: 'WebSampConnectorApplet',
   jAppletCodeBase:'../lib/',
   jAppletVersion: '1.5'
});
WebSampConnector.connect()
→ Return: void
→ Usage: This method builds the Japplet, and connects and registers the Web browser to a running Samp hub. If the connection is successfull then the Japplet executes the WebSampConnector.onlineHandler() method.
ArgumentsTypeDescriptionNote
None---
Example:
<button onclick="WebSampConnector.connect();">Connect to the Samp hub</button>
WebSampConnector.disconnect()
→ Return: boolean
→ Usage: This method unregisters the client and terminates the connection with the hub.
ArgumentsTypeDescriptionNote
None---
Example:
<button onclick="WebSampConnector.disconnect();">Disconnect</button>
WebSampConnector.isConnected()
→ Return: boolean
→ Usage: This method allows the client to know if he is connected or not to a hub. If he's connected then the method returns true, if not it returns false.
ArgumentsTypeDescriptionNote
none---
Example:
<button onclick="WebSampConnector.isConnected();">Connection Status</button>
WebSampConnector.getRegisteredClients()
→ Return: associative array of string
→ Usage: This method retrieves the clients for those clients currently registered. The available information about the clients is:
  • - id: client Id
  • - name: client name
  • - descriptionText: client description in ascii format
  • - descriptionHtml: client description in HTML format
  • - iconUrl: client icon URL
  • - documentationUrl: client documentation URL
ArgumentsTypeDescriptionNote
None---
Example:
<button onclick="WebSampConnector.getRegisteredClients();">Get registered clients</button>
WebSampConnector.getSubscribedClients(mtype)
→ Return: associative array of string
→ Usage: This method retrieves the clients which subscribed a given MType (e.g. table.load.votable). The available information is the same as the getRegisteredClients method.
ArgumentsTypeDescriptionNote
mtypestringThe requested MType-
Example:
<button onclick="WebSampConnector.getSubscribedClients('table.load.votable');">Get subscribed clients</button>
Sending Application Messages
The following methods has to be used to send messages to the registered VO applications.
WebSampConnector.sendMsg(MType, id, name, url, keyName)
→ Return: boolean
→ Usage: This method broadcasts a message from the Web page to registered VO applications
ArgumentsTypeDescriptionNote
MType string Mtype of the data to broadcast-
id string Identifier which may be used to refer to the loaded resource in subsequent messages-
name string Name which may be used to label the loaded resource in the application GUI-
url string URL of the VOTable document to load-
keyName string Key of the identifier which may be associated to the identifier parameter (id)(1)
Example:
<button onclick="WebSampConnector.sendMsg('table.load.votable','table-id','MyFOV','http://hostname/myvotable.xml','');"> Broadcast the VOTable</button>
Notes:
  1. A Samp message is built as a map which encodes the given MType and the associated parameters. Each parameter is added to the map as a key-value pair. The MTypes (http://www.ivoa.net/cgi-bin/twiki/bin/view/IVOA/SampMTypes) which handle tables, images and spectra take three arguments: an URL pointing to the resource, an Id (optional) which may be used to refer to the loaded resource in subsequent messages, and a name (optional) which may be used to label the loaded resource in the application GUI. The name of the keys which defined the URL and name parameters are always the same: 'url' and 'name'. It is not the case of the Id parameter, for which the name of the key depends on the MType. The 'keyName' parameter of the sendMsg method allows one to provide an explicit key name to be associated to the id parameter. If you send message of MTypes 'table.load.votable', 'image.load.fits', 'table.load.fits' or 'spectrum.load.ssa-generic', the key is automatically defined by the Java applet and you don't need to provide it (just leave the keyName empty).
WebSampConnector.pointAtSky(ra, dec)
→ Return: boolean
→ Usage: This method allows the client to point a given celestial coordinate in a registered VO application
ArgumentsTypeDescriptionNote
ra double Right ascension to point (in decimal degrees)-
dec double Declination to point (in decimal degrees)-
Example:
<button onclick="WebSampConnector.pointAtSky(105.0, 6.0);">Point at RA=7h, DEC=+6d</button>
WebSampConnector.tableHighlightRow(tableId, url, row)
→ Return: boolean
→ Usage: This method allows the client to highlight a single row of an identified table by its row index
ArgumentsTypeDescriptionNote
tableId string Identifier associated with a table by a previous message(1)
url string URL of the VOTable document(1)
row int Row index (zero-based) of the row to highlight-
Example:
<button onclick="WebSampConnector.tableHighlightRow('MyFOV','http://hostname/barbara.xml', 6);">Highlight row #6</button>
Notes:
  1. The table to operate on is identified by one or both of the tableId or url arguments. At least one of these must be supplied; if both are given they should refer to the same thing
WebSampConnector.tableSelectRowList(tableId, url, rowList)
→ Return: boolean
→ Usage: This method allows the client to select a list of rows of an identified table by their row index
ArgumentsTypeDescriptionNote
tableId string Identifier associated with a table by a previous message(1)
url string URL of the VOTable document(1)
rowList int[] list of row indices (zero-based) defining which table rows are to form the selection-
Example:
<button onclick="WebSampConnector.tableSelectRowList('MyFOV','http://hostname/barbara.xml', new Array(0,1,2,3,4));">Highlight rows #0 to #4</button>
Notes:
  1. The table to operate on is identified by one or both of the tableId or url arguments. At least one of these must be supplied; if both are given they should refer to the same thing
WebSampConnector.sendAladinScript(ascript)
→ Return: boolean
→ Usage: This method allows the client to send a script to be executed by Aladin
ArgumentsTypeDescriptionNote
ascriptstring The Aladin script to send to Aladin(1)
Example:
<button onclick="WebSampConnector.sendAladinScript('get Aladin(DSS2) 198.69107026467 +9.085315305339 15arcmin; sync; get VizieR(USNO2); sync; set USNO2 shape=triangle');">Send a script to Aladin</button>
Notes:
  1. This message is a special feature of Aladin and is not part of the Samp standard
Receiving Application Messages
The following methods has to be used to receive messages from the registered VO applications. When the Java applet receives a message from the hub, it calls the following methods with the specified arguments. These methods must be completed by the client to actually handle the received messages and match the requierements of a Web application.
WebSampConnector.pointAtSkyHandler = function(ra, dec)
→ Return: void
→ Usage: This method allows the client to receive the celestial coordinates which are pointed by a VO application
ArgumentsTypeDescriptionNote
radoublethe right ascension to point (in decimal degrees)-
decdoubleContains the declination to point (in decimal degrees)-
WebSampConnector.highlightRowHandler = function(tableId, url, row)
→ Return: void
→ Usage: This method allows the client to receive a single row index of an identified table to highlight
ArgumentsTypeDescriptionNote
tableIdstringId of the table which is concerned-
urlstringURL of the table which is concerned-
rowstringRow index to highlight in the table-
WebSampConnector.selectRowListHandler = function(tableId, url, row)
→ Return: boolean
→ Usage: This method allows the client to receive a list of rows of an identified table by row index
ArgumentsTypeDescriptionNote
tableIdstringId of the table which is concerned-
urlstringURL of the table which is concerned-
rowstring[]Array of row index to highlight in the table-
WebSampConnector.spectrumLoadSsaHandler = function(url, spectrumId, name)
→ Return: boolean
→ Usage: This method allows the client to receive a spectrum to dowload
ArgumentsTypeDescriptionNote
urlstringURL of the spectrum-
spectrumIdstringthe identifier which may be used to refer to the loaded spectrum-
namestringthe name which may be used to label the loaded spectrum-