Getting Started with WebPDA

Table of Contents

Download

WebPDA can be downloaded from here. Unzip the file. Inside the extracted folder, there are following files or folders:

webpda.war - The WAR file that can be deployed on Glassfish 4 or Tomcat 8. (The deployment on Tomcat 8 is not fully tested yet)
webpda-lib - The client JavaScript library files.
webpda-lib-min The minimized client JavaScript files

Server Side: Deploy webpda.war

webpda.war can be deployed on any JSR356 compatible servlet container. By the time when this document was written, only Glassfish 4 is fully compatible. Tomcat 8 is supposed to support JSR356, but it is still in unstable stage.

Install Glassfish 4

Glassfish 4 can be downloaded from glassfish.java.net. Follow its instruction to install it and start default domain domain1 . You may create another domain with another name, then just replace domain1 in following document with your domain name.

Configure JVM options

After Glassfish is installed and started, go to the admin page (By default it is http://localhost:4848). Navigate to Configurations>server-config>JVM Settings>JVM Options , add following JVM options as needed.

JVM option	Description
-Dorg.webpda.server.jaas_name	JAAS configuration file entry. If this is not configured, the entry name is `Default`
-Dorg.webpda.server.authorization_provider	The authorization provider. If the authorization information is configured in a file, the provider should be `org.webpda.server.core.security.FileBasedAuthorizationProvider`. This is also the default authorization provider if this property is not set. The authorization configuration file is configured from `-Dorg.webpda.server.authorization.config_file`. If the authorization information should be provided from an LDAP server, the value should be `org.webpda.server.core.security.LDAPGroupAuthorizationProvider`. Please see Authorization with LDAP.
-Dorg.webpda.server.authorization.config_file	Absolute path of the authorization configuration file. Here is an authorization file example.
-Dorg.webpda.server.pvfactory	Full class name of the PV Factory of the data interface implementation. By default, it is `org.webpda.server.datainterface.cs.pvmanager.PVManagerPVFactory`, which uses PVManager as the data interface implementation.

To connect to an EPICS system using PVManagerPVFactory, EPICS related JVM options should be set.

Here is an example of settings to connect to a local IOC and use file as authorization provider.

-Dcom.cosylab.epics.caj.CAJContext.addr_list=127.0.0.1
-Dorg.webpda.server.authorization_provider=org.webpda.server.core.security.FileBasedAuthorizationProvider
-Dorg.webpda.server.authorization.config_file=/home/WebPDA_repo/server/org.webpda.server.core/authorization.conf

Here is the authorization file example authorization.conf.

Configure authentication info

For Glassfish, the authentication information is configured in {Glasshfish_installation_dir}/glassfish/domains/domain1/config/login.conf as a regular JAAS configuration file. For other servlet container, the JAAS configuration file may be specified from JVM option -Djava.security.auth.login.config . In the JAAS configuration file, add an entry such as below example to specify the login module and its options. The login module can be any standard login module, such as LdapLoginModule coming with JRE. In below example, org.webpda.server.core.security.JaasConfigFileLoginModule is a login module that allows setting user name and password as login module options. The option key is user name and option value is password. The number of user names is not limited. For example:

Default {
    org.webpda.server.core.security.JaasConfigFileLoginModule required
    webpda="123456"
    webpda-admin="mypassword"
    jane="654321"
    fred="abcdef";
};

Restart domain

The above configurations only take effect after domain restarted. You can restart the domain from the admin page or you can use {glassfish}/bin/asadmin :

asadmin> stop-domain domain1
asadmin> start-domain domain1

Deploy webpda.war

After above items were properly configured, go to glassfish admin page > Applications page. Click on "Deploy..." button, choose "webpda.war", leave other options as default and click "OK". Click on the launch link of will provide you two links to the webpda startup page. One link starts with http:// , which use unencrypted HTTP and WebSocket connection. In this case, the WebSocket URL starts with ws:// . The other link starts with https:// which uses SSL encrypted HTTP and WebSocket connection. In this case, the WebSocket URL starts with wss:// . Click on one of the links, you will see the welcome page and be ready to roll!

Client Side: using WebPDA JavaScript API

The JavaScript API is supposed to be used with modern Web Browsers that support WebSocket.

Including js files in HTML

webpda-core.js is the core, which should be always included. webpda-cs.js includes control system data type definitions and decoding for server side that uses org.webpda.server.datainterface.cs.pvmanager.PVManagerPVFactory as PVFactory.

<!DOCTYPE html>
<html>
<head>
<script src="webpda-core.js"></script>
<script src="webpda-cs.js"></script>
</head>
<body></body>
</html>

The JavaScript API

In your script, you only need to focus on the PV and its value instead of communications. Here is the demo for the mostly used APIs. The complete JSDoc is available here.

//This the WebSocket URL 
var wsUrl = "ws://localhost:8080/webpda/webpda";

//Connect to server and login with the username and password set on server side.
var wp = new WebPDA(wsUrl, "myname", "mypassword");

// create a pv whose name is sim://noise, maximum update rate at 1hz, don't buffer value.
var pv = wp.createPV("sim://noise", 1000, false);

// add a callback to the PV that will be called whenever there is an event on the PV
pv.addCallback(function(evt, pv, data) {
    switch (evt) {
    case "conn": //connection state changed
		console.log(pv.isConnected()?"Connected":"Disconnected.");
        break;
    case "val": //Value changed. The event will be "bufVal" if value is buffered.
		//PV's value is usually a data structure that has timestamp, 
		//value, alarm and meta information.
        //Here is an example on how to extract the timestamp and
        //numeric value from PV if the PV holds numeric value        
		var pvValue = pv.getValue();
		console.log(pvValue);
		if(pvValue instanceof WebPDA_CS.VNumber){
			console.log("Timestamp: " + pvValue.timestamp + 
					" Value: " + pvValue.value);
		}        
        break;
    case "bufVal": //Buffered values changed
        // If value is buffered during the update period, 
        // it will receive an array of buffered values.
        // Each value in the array is same as a single PV value 
        // which should be handled in the same way as above.         
        break;
    case "error": //error happened
        console.log("Error: " + data);
        break;
    case "writePermission": // write permission changed.        
        console.log("Writable: " + pv.isWriteAllowed());
        break;
    case "writeFinished": // write operation finished.        
        console.log("Write finished "
					+ (data ? "successfully!" : "unsuccessfully!"));
        break;
    default:
        break;
    }
});

//Write PV. The value must be a value type that the PV can accept,
//for example, a number for PV that holds number, a string for PV that holds string.
pv.setValue(10);

//Close PV when it is not needed.
pv.close();