Jacva and JCA / CAJ

Java and JCA / CAJ
Kenneth Evans, J r .
October 12, 2004
Part of the EPICS “Getting Started” Lecture Series
Slightly Modified for EPICS2006 at VECC
By Kazuro Furukawa
July 13, 2006

EPICS Workshop 2006, VECC, India

Kazuro Furukawa, KEK, Jul.2006.

1

Jacva and JCA / CAJ

OutlineJ a v a
Java and EPICS
Overview of JCAExamples SimpleJCAGetSimpleJCAMonitor
JProbeEPICS Workshop 2006, VECC, India

Kazuro Furukawa, KEK, Jul.2006.

2

Jacva and JCA / CAJJavaJava is designed to be platform independent Write once, run everywhereJava programs are interpreted by anotherprogram, possibly on another machine The Java Virtual Machine (Java VM)

Java technology includes
J2SE
J2EE
apps)
J2ME

Standard Edition
Enterprise Edition (Multi-tier business
Micro Edition (Phones, PDAs, etc.)

Java is advertised to be all of these
Simpleoriented
PortableInterpreted
Dynamic

Architecture neutral
Distributed
Multithreaded
SecureEPICS Workshop 2006, VECC, India

ObjectHigh performance
RobustKazuro Furukawa, KEK, Jul.2006.

3

Jacva and JCA / CAJ

Java and EPICS
 EPICS Channel Access is native code
 Not platform independent Build cycle is edit – compile [to machine code] - link - run Pure Java Build cycle is edit – compile [to byte code] – run [anywhere] Java Native Interface [JNI] is used to access native code
 Not “Pure Java”
 No longer platform independent You generate shared object or DLL libraries that must be usedwith the Java program You can write your own JNI Not that hard if you know Channel Access The EPICS build system handles Java projects and JNI
 Ant is an alternative

EPICS Workshop 2006, VECC, India

Kazuro Furukawa, KEK, Jul.2006.

4

Jacva and JCA / CAJ

JCA

Stands for Java Channel Access
JCA is a JNI implementation of an EPICS
Channel Access client library for Java
 Provides equivalents to most of the Channel Access API
 Developed by Eric Boucher while at the APS
 Currently taken over by CosylabAvailable for download at
 http://j c a.cosylab. c o m /Latest version is 2.1.7 at Cosylab
JCA Version 1 uses EPICS Base 3.13
JCA Version 2 uses EPICS Base 3.14
 Channel Access is threaded Allows for preemptive callbacks
 Works better with Java, which is inherently threaded
EPICS Workshop 2006, VECC, India

Kazuro Furukawa, KEK, Jul.2006.

5

Jacva and JCA / CAJCAJCAJ is a Java replacement for Channel AccessDeveloped at Cosylab (Control Systems
Laboratory) Located in Ljubljana in Slovenia
 Cosylab also develops VDCT

Available for download at
 http://c a j.cosylab. c o m /Latest version is 1.0.5
Allows your programs to be “Pure Java”
Is used with JCA
 Replaces JNI implementation
 Requires replacing only one line of code
jca.createContext(JCALibrary.JNI_THREAD_SAFE);
jca.createContext( “c o m .cosylab.epics.c a j .CAJContext”) ;EPICS Workshop 2006, VECC, India

Kazuro Furukawa, KEK, Jul.2006.

6

Jacva and JCA / CAJ

Requirements
Java J2SE installed (Current [suggested]version is 1.4.2)
J C A Java libraries
 Download source and/or JAR files from the web

 Native JNI libraries
 Download from the web or build them
 Currently found with the 2.1.7 distribution
jca. d l llibjca. s oWindows
Unix (Currently Linux, Solaris, Darwin?)Your project JCA files need to be in your CLASSPATH UNIX: Shared object library needs to be in your
LD_LIBRARY_PATHWindows: DLL needs to be in your PATH
EPICS Workshop 2006, VECC, India

Kazuro Furukawa, KEK, Jul.2006.

7

Jacva and JCA / CAJ

Resources

 EPICS web pages

 http://www.a p s .a n l.g o v/epics/index.p h p Look under Extensions, then JCA

 JCA 2.1.7 API
 http://j c a.cosylab.com/apidocs/index.html

 JCA 2.1.2 API
 http://www.a p s .a n l.g o v/xfd/SoftDist/swBCDA/jca/2.1.2/a p i/inde
x .h t m lI

 CAJ 1.0.5
 http://c a j.cosylab.com/manual.html

 Java Tutorial http://java.sun.com/learning/tutorial/index.html

 J2SE Documentation
 http://java.sun.com/reference/a p i/index.html

 J2SE 1.4.2 API (Javadoc)
 http://java.sun.com/j2se/1.4.2/docs/a p i/overviewsummary.html
EPICS Workshop 2006, VECC, India

Kazuro Furukawa, KEK, Jul.2006.

8

Jacva and JCA / CAJ

JCA Packages
 Five Packages
gov.aps.j c a

Channel-Access-likegov.aps.j c a.configuration

Configuration

gov.aps.j c a. d b r

DBR types

gov.aps.j c a.event

Event handlinggov.aps.j c a. j n i

Native interface functions

EPICS Workshop 2006, VECC, India

routinesKazuro Furukawa, KEK, Jul.2006.

9

Jacva and JCA / CAJ

g o v .aps.jca

 This is the package you will use mostdirectly
Classes CASeverity
Enum CAStatus
JCALibrary Channel
Monitor Channel.ConnectionState
ValuedEnum
 Context

 Exceptions
 CAException

EPICS Workshop 2006, VECC, India

TimeoutException

Kazuro Furukawa, KEK, Jul.2006.

10

Jacva and JCA / CAJ

JCALibraryInitializes JCA

JCALibrary jca=JCALibrary.getInstance();There is only one instanceUsed to create contexts and manage JCA
configuration info
Properties
 JNI_THREAD_SAFE

preemptive Suggested for Java, which is inherently threaded JNI_SINGLE_THREADED

non-preemptive

Methods
 createContext
 getProperty
 listProperties
 getVersion, getRevision, getModification

EPICS Workshop 2006, VECC, India

Kazuro Furukawa, KEK, Jul.2006.

11

Jacva and JCA / CAJ

Context

Corresponds to a Channel Access context
Created by JCALibrary.createContext
createContext(JCALibrary.JNI_SINGLE_THREADED)
createContext(JCALibrary.JNI_THREAD_SAFE)

Controls all IO
You can have more than one context
Methods
 createChannel
 flushIO, pendIO, pendEvent, pollattachCurrentThread addContextExceptionListener,
removeContextExceptionListener addContextMessageListener,
removeContextMessageListener destroy
EPICS Workshop 2006, VECC, India

Kazuro Furukawa, KEK, Jul.2006.

12

Jacva and JCA / CAJ

ChannelRepresents a Channel Access channel
Created by Context.createChannel
createChannel(Stringname, connectionListenerl)Properties
CLOSEDDISCONNECTEDCONNECTED
NEVER_CONNECTED

Methods
 get, many overloads
 put, many overloads
getName, getConnectionState, getElementCount, etc.
 addMonitor
 addConnectionListener, removeConnectionListener addAccessRightsListener, removeAccessRightsListener destroy

EPICS Workshop 2006, VECC, India

Kazuro Furukawa, KEK, Jul.2006.

13

Jacva and JCA / CAJ

MonitorRepresents a Channel Access monitor
Created by Channel.addMonitor
addMonitor(DBRTypetype, intcount, intmask,
MonitorListenerl)Properties
ALARM

LOG

VALUE

Methods
 addMonitorListener, removeMonitorListener getMonitorListener, getMonitorListeners
 clear getChannel, getContext
 getCount, getMask, getType isMonitoringAlarm, isMonitoringLog, isMonitoringValueEPICS Workshop 2006, VECC, India

Kazuro Furukawa, KEK, Jul.2006.

14

Jacva and JCA / CAJ

MonitorListener Part of g o v. a p s. j c a.event
One method
 monitorChanged

 Example
private class MyMonitorListener implements
MonitorListener{public void monitorChanged(MonitorEvent ev) {// Call my handler
onValueChanged(ev);}}; The value and status comes with theMonitorEvent
EPICS Workshop 2006, VECC, India

Kazuro Furukawa, KEK, Jul.2006.

15

Jacva and JCA / CAJ

MonitorEvent Part of g o v. a p s. j c a.eventMethods
getDBR getStatus
statusHow you get the value
How you determine the Example
if(ev.getStatus() == CAStatus.NORMAL) {DBR dbr=ev.getDBR();double [] value=((DOUBLE)dbr).getDoubleValue();}

EPICS Workshop 2006, VECC, India

Kazuro Furukawa, KEK, Jul.2006.

16

Jacva and JCA / CAJ

Event Types
 MonitorListener GetListener PutListener AccessRightsListener ConnectionListener ContextExceptionListener ContextMessageListener

MonitorEvent
GetEvent
PutEvent
AccessRightsEvent
Connection Event
ContextExceptionEvent
ContextMessageEvent Events all inherit from CAEvent They all work similarly to Monitor
 Call the routine that fires the event when it occurs
 Add a listener with the appropriate handler Get the data from the event that is passed to your handler

EPICS Workshop 2006, VECC, India

Kazuro Furukawa, KEK, Jul.2006.

17

Jacva and JCA / CAJ

g o v .aps.jca.d b r
 Implements the EPICS DBR_xxx t y p e s
 Interfaces
 DOUBLE, FLOAT, INT, STRING, TIME, CTRL,

etc.

 Primary ClassDBR Subclasses of DBR
 DBR_Double, DBR_Float, DBR_Int, DBR_STS_Double, etc.

 Example: DBR_STS_Double Interfaces
STS, DOUBLE

 ExtendsDBR_Double

 Subclasses
DBR_GR_Double, DBR_Time_Double

EPICS Workshop 2006, VECC, India

Kazuro Furukawa, KEK, Jul.2006.

18

Jacva and JCA / CAJ

SimpleJCAGet
package simplejca;
import gov.aps.jca.*;
import gov.aps.jca.dbr.*;

EPICS Workshop 2006, VECC, India

Kazuro Furukawa, KEK, Jul.2006.

19

Jacva and JCA / CAJ

SimpleJCAGet
public class SimpleJCAGet{
public static void main(String[] args){
SimpleJCAGet simpleJCAGet = new SimpleJCAGet();
JCALibrary jca=null;Context ctxt=null;
Channel chan=null;// Parse the command line
if(!simpleJCAGet.parseCommand(args))
System.exit(1);if(!simpleJCAGet.pvSpecified) {System.err.println("No PV specified\n");System.exit(1);}EPICS Workshop 2006, VECC, India

Kazuro Furukawa, KEK, Jul.2006.

20

Jacva and JCA / CAJ

SimpleJCAGet// Initialize and searchtry {// Get the JCALibrary instancejca=JCALibrary.getInstance();// Create a non-preemptive context
context=jca.createContext(
JCALibrary.JNI_SINGLE_THREADED);// Searchchan=ctxt.createChannel(simpleJCAGet.name);// Wait for search
ctxt.pendIO(simpleJCAGet.timeout);} catch(Exception ex) {System.err.println("Search failed for " +simpleJCAGet.name + ":\n" + ex);
System.exit(1);}EPICS Workshop 2006, VECC, India

Kazuro Furukawa, KEK, Jul.2006.

21

Jacva and JCA / CAJ

SimpleJCAGet// Get the first value as a Stringtry {// Get the value
String [] value;
value=((STRING)chan.get(DBRType.STRING,1)).
getStringValue();// Wait for the get
ctxt.pendIO(simpleJCAGet.timeout);// Print the value
System.out.println("The value of " +simpleJCAGet.name+ " is " + value[0]);} catch(Exception ex) {System.err.println("Get failed for " +simpleJCAGet.name + ":\n" + ex);
System.exit(1);}EPICS Workshop 2006, VECC, India

Kazuro Furukawa, KEK, Jul.2006.

22

Jacva and JCA / CAJ

SimpleJCAGet// Clean up
try {// Clear the channel
chan.destroy();// Destroy the context
ctxt.destroy();} catch(Exception ex) {System.err.println("Clean up failed for " +simpleJCAGet.name + ":\n" + ex);
System.exit(1);}// Successful exit
System.exit(0);}EPICS Workshop 2006, VECC, India

Kazuro Furukawa, KEK, Jul.2006.

23

Jacva and JCA / CAJ

SimpleJCAGet output
java.exe -classpath<simplejca-path>\SimpleJCA.jar;<jca-path>\jca-2.1.7.jar
simplejca.SimpleJCAGet evans:calc
The value of evans:calc is 3

EPICS Workshop 2006, VECC, India

Kazuro Furukawa, KEK, Jul.2006.

24

Jacva and JCA / CAJ

SimpleJCAMonitor
 Similar to SimpleJCAGet Imports, parsing the command line, etc. are
the same We will have listeners
We will use JNI_THREAD_SAFE(preemptive)
We will use flushIO and not pendIO, etc.

EPICS Workshop 2006, VECC, India

Kazuro Furukawa, KEK, Jul.2006.

25

Jacva and JCA / CAJ

SimpleJCAMonitor/** Implementation of Connection Listener class*/private class SJCAConnectionListener implements
ConnectionListener {public void connectionChanged(ConnectionEvent ev) {onConnectionChanged(ev);}};/** Implementation of MonitorListener class*/private class SJCAMonitorListener implements
MonitorListener {public void monitorChanged(MonitorEvent ev) {onValueChanged(ev);}};

EPICS Workshop 2006, VECC, India

Kazuro Furukawa, KEK, Jul.2006.

26

Jacva and JCA / CAJ

SimpleJCAMonitor// Instance of SimpleJCAMonitor
SimpleJCAMonitor sjcam=new SimpleJCAMonitor();// Initialize JCA
try {// Get the JCALibrary instancejca=JCALibrary.getInstance();// Create a preemptive context, default configuration
ctxt=jca.createContext(JCALibrary.JNI_THREAD_SAFE);} catch(Exception ex) {System.err.println("Initialization failed for " +sjcam.name + ":\n" + ex);
System.exit(1);}EPICS Workshop 2006, VECC, India

Kazuro Furukawa, KEK, Jul.2006.

27

Jacva and JCA / CAJ

SimpleJCAMonitor// Searchtry {// Searchchan=ctxt.createChannel(sjcam.name,sjcam.new SJCAConnectionListener());
ctxt.flushIO();} catch(Exception ex) {System.err.println("Search failed for " +sjcam.name + ":\n" + ex);
System.exit(1);}EPICS Workshop 2006, VECC, India

Kazuro Furukawa, KEK, Jul.2006.

28

Jacva and JCA / CAJ

SimpleJCAMonitor

private void onConnectionChanged(ConnectionEvent ev) {Channel ch=(Channel)ev.getSource();
Context ctxt=ch.getContext();// Start a monitor on the first connection
if(connectionCounter == 0 &&ch.getConnectionState() == Channel.CONNECTED) {try {// Add a monitor listener and flush
ch.addMonitor(DBRType.STRING,1,
Monitor.VALUE|Monitor.LOG|Monitor.ALARM,
new SJCAMonitorListener());
ctxt.flushIO();} catch(Exception ex) {ex.printStackTrace();}}
EPICS Workshop 2006, VECC, India

Kazuro Furukawa, KEK, Jul.2006.

29

Jacva and JCA / CAJ

SimpleJCAMonitor// Print connection stateif(ch.getConnectionState() == Channel.CONNECTED) {System.out.println(ch.getName() + " isconnected");} else if(ch.getConnectionState() ==Channel.CLOSED) {System.out.println(ch.getName() + " is closed");} else if(ch.getConnectionState() ==Channel.DISCONNECTED) {System.out.println(ch.getName() + " isdisconnected");} else if(ch.getConnectionState() ==Channel.NEVER_CONNECTED) {System.out.println(ch.getName() + " is neverconnected");}EPICS Workshop 2006, VECC, India

Kazuro Furukawa, KEK, Jul.2006.

30

Jacva and JCA / CAJ

SimpleJCAMonitor
private void onValueChanged(MonitorEvent ev) {Channel ch=(Channel)ev.getSource();
Context ctxt=ch.getContext();// Check the status
if (ev.getStatus() != CAStatus.NORMAL) {System.err.println("monitorChanged: Bad status”);}// Get the value from the DBR
try {DBR dbr=ev.getDBR();
String [] value=((STRING)dbr).getStringValue();
System.out.print(SJCAUtils.timeStamp() + " " +getName() + ": “ + value[0]);} catch(Exception ex) {...
}}EPICS Workshop 2006, VECC, India

Kazuro Furukawa, KEK, Jul.2006.

31

Jacva and JCA / CAJ

Simple JCAMonitor output
Oct 11, 2004 10:36:43.661 Starting Simple JCA Monitor
Oct 11, 2004 10:36:44.083 Search successful for:evans:calc
CHANNEL : evans:calc
TYPE: gov.aps.jca.dbr.DBRType[DBR_DOUBLE=6]
COUNT
: 1
STATE
:
gov.aps.jca.Channel$ConnectionState[CONNECTED=2]
HOSTNAME : ctlapps4l188.aps4.anl.gov:5064
READ: trueWRITE: trueOct 11, 2004 10:36:44.208 evans:calc is connected
Oct 11, 2004 10:36:44.224 evans:calc: 2
Oct 11, 2004 10:36:44.224 evans:calc: 3...
Oct 11, 2004 10:36:53.240 evans:calc: 3
Oct 11, 2004 10:36:53.740 evans:calc: 4
Oct 11, 2004 10:36:54.036 All Done

EPICS Workshop 2006, VECC, India

Kazuro Furukawa, KEK, Jul.2006.

32

Jacva and JCA / CAJ

JProbe JProbe is a simple example that demonstrates using JCA
in a Swing GUI

EPICS Workshop 2006, VECC, India

Kazuro Furukawa, KEK, Jul.2006.

33

Jacva and JCA / CAJ

Write once, run everywhere?

EPICS Workshop 2006, VECC, India

Kazuro Furukawa, KEK, Jul.2006.

34

Jacva and JCA / CAJ

Source files for Simple JCA routines
All the source and JAR files should beavailable with the presentation
LICENSE
 SimpleJCA. j a r
 simplejca
 SimpleJCAMonitor. j a v a
 SimpleJCAGet. j a v a
 SJCAUtils. j a v a JProbe. j a r
 jprobe JProbe. j a v a MainFrame. j a v a AboutBoxPanel. j a v a

Stored as SimpleJCA. z i p
EPICS Workshop 2006, VECC, India

Kazuro Furukawa, KEK, Jul.2006.

35

Jacva and JCA / CAJ

Some Pointers to Documents
Example files
 http://www.aps.anl.gov/epics/
Documents - Training - Developing
Client Tools- Java and JCA- Example FilesBuild examples of EPICS-Base, etc
on several Platforms
http://www-linac.kek.jp/jk/win32/
http://www-linac.kek.jp/jk/linux/
http://www-linac.kek.jp/jk/darwin/
EPICS Workshop 2006, VECC, India

Kazuro Furukawa, KEK, Jul.2006.

36

Jacva and JCA / CAJ

Acknowledgements

 JCA was developed by Eric Boucher
while at the APS
Matej Sekoranja [Cosylab] has takenover JCA and is developing CAJ
Both of these people were very
helpful in getting JCA working for me

EPICS Workshop 2006, VECC, India

Kazuro Furukawa, KEK, Jul.2006.

37

Jacva and JCA / CAJ

Thank YouThis has been an

APS Controls Presentation
By Kenneth Evans, J r.
Modified for EPICS2006 at VECC
By Kazuro Furukawa

EPICS Workshop 2006, VECC, India

Kazuro Furukawa, KEK, Jul.2006.

38