5 TANGO Java API

THIS CHAPTER DOCUMENTS THE JAVA API FOR THE TANGO DATABASE AND DEVICE SERVERS.

1 Introduction

1 Description

This chapter documents the high level interface for Java.

Remarks:

This java api is based on Jacorb ORB implementation. The Jacorb and Tango classes are both available in TangORB.jar file.

2 Basic Philosophy

The basic philosophy is to have high level classes for the database, properties, device, group and database object info. Classes also exist for sending and receiving database or device values.
All classes and data types are defined in fr.esrf.TangoApi package. Group related classes are in a package called fr.esrf.TangoApi.Group. Event related classes are in a package called fr.esrf.TangoApi.events

3 Classes

1 Data object classes

DeviceData:

Obect used to send and receive data on device.

DbDatum:

Object used to put or get properties on database.

DbDevInfo:

Object used to read device information on database.

DbDevImportInfo:

Object used to read imported device information on database.

DbDevExportInfo:

Object used to read exported device information on database.

2 Asynchronous callback related classes

CallBack:

Object called at asynchronous call reply

CmdDoneEvent:

Object to pass asynchronous command reply data to a CallBack object.

ReadAttrEvent:

Object to pass asynchronous read_attribute reply data to a CallBack object.

AttrWrittenEvent:

Object to pass asynchronous write_attribute reply data to a CallBack object.

3 Devices and Database access classes

DeviceProxy:

Device access (aggregates DbDevice class).

Group:

Multiple device access class

Database:

Direct access to TANGO database.

DbClass:

Class properties access to TANGO database.

DbServer:

Server properties access to TANGO database.

DbDevice

Device properties access to TANGO database.

4 Reporting errors

For the device and database classes, most methods throw a DevFailed exception in case of error. See Writing a TANGO Device Server chapter Reporting Errors () , except those which specified.
In opposite, for the data object classes, only the specified method throw DevFailed exception in case of error.
The reason field could be set to:

• TangoApi_TANGO_HOST_NOT_SET : The TANGO_HOST environment variable has not been set or has been set with a syntax error.
• TangoApi_DATABASE_CONNECTION_FAILED : The database server cannot be connected (bad TANGO_HOST or database server stopped).
• TangoApi_CANNOT_IMPORT_DEVICE : The device is exported but cannot be connected.
• TangoApi_DEVICE_NOT_EXPORTED : The device has not be exported.

5 Compiling a Java client

1 Supported java release

Tango client written using Java language needs release 1.5.0 (or above) of the Java environment.

2 Setting CLASSPATH and other environment variables

To correctly compile a Java Tango client, the CLASSPATH environment variable must be set to :

• The jar file with all the Tango, TangoDs, TangoApi and Jacorb package classes. This file is named TangORB.jar
• The jar file with all the JDK classes (not always necessary, could be implicit)
• Your own package directory

For UNIX like operating system, setting environment variable is done with the export or setenv command depending on the shell used. For Windows, setting environment variable is possible from the control panel.
The client/server timeout as been fixed by default to 3000 milliseconds but it can be set to another value a startup using TANGO_TIMEOUT environement variable.
eg : java -DTANGO_HOST=hal:20000 -DTANGO_TIMEOUT=5000 mypackage.MyClient
Will start MyClient class using the database server running on the host named hal on port 20000 with a command timeout of 5 seconds.

2 Reference manual

The Tango Java API documentation is now managed using the Java tool javadoc and is available online at

Tango Java API reference documentation