Diamond Systems provides a simple Java client API which can be used to communicate with the DALI server over the Internet via SOAP. The SOAP API is abstracted for quick and easy development so developers can have functional and professional applications in little time.
This client is based on the open source java SOAP client from the Apache Foundation called AXIS. This is a high quality implementation which is widely used. You can read more about it at http://ws.apache.org/.
DALI Java requires Java run-time to run. Developers require Java compilers to compile their programs. For developers using the DALI Java Bean with ErgoTech, please refer to the Java DK section of this manual. To install Java, please go to java.com and follow instructions on downloading the Java SDK
DALI Java comes in one Jar file, dali_Java.jar.
dali_Java.jar contains DALI Java API and all Java Classes
necessary for developing DALI Java Applications. To install DALI Java please
do the following:
Go to or create the directory that DALI Java is to be installed. A sample
directory for Windows developers would be C:\DALI_Java
Copy
and paste dali_Java.jar into the directory.
Developers
will also have to install Apache Axis for DALI Java to work.
Developers can download Apache Axis from http://ws.apache.org/axis/.
Developers can obtain difference release by clicking on the Release
option on the side bar. Diamond Systems suggests releases 1.1 rc2 or newer
Windows Developers should download the .zip file while Linux or Unix related
operating system developers should download the tar.gz file.
After downloading the file developers should unzip or untar the files to a
temporary directory
After downloading and unzipping Axis, go into the directory of Apache Axis. Go
into the "lib" directory. Copy all jar files except axis-ant.jar into the same
directory as dali_Java.jar (for Windows developers this might be
C:\DALI_Java)
The following is section of an applet
public void run() {
String DALIURL = "http://192.168.1.252:8444/dali/soap/prom";
DaliClass daliclass = new DaliClass();
ADSettings adsettings;
int channel = 0;
adsettings = new ADSettings();
adsettings.range = 5;
adsettings.gain = 1;
adsettings.polarity = "BIPOLAR";
try{
one = daliclass.ADSample(DALIURL, channel, adsettings);
}
catch(Exception e) {
System.err.println("in run invoke "+e.toString());
}
}
The above code demonstrates how to perform a DALI ADSample function call. Below is a breakdown of the above code.
Please refer to Javadoc section of the manual for an API reference.
Here is a quick break down and tutorial of the DALI Java structures
Contains information for setting up A/D settings.
| public int range | A/D range. Valid input 5 or 10 |
| public int gain | A/D gain. Valid input 1, 2, 4, 8. |
| public String polarity | A/D polarity. Valid input "BIPOLAR" or "UNIPOLAR". |
Contains information of boards on DALI Server.
| public String board | String that uniquely identifies the board on the DALI server. |
| public String boardtype | Diamond Systems assigned product name |
| public int baseaddress | Base address of board |
Contains information of a board's channels
| public int channel | Channel number |
| public String type | Channel type. Valid ranges "DA", "AD", "DIOIN", "DIOOUT" |
| public String security | Channel security. Valid ranges "PUBLIC", "LOGIN" |
Contains information for security authentication
| public String username | Username string |
| public String password | Password string |
Handles all DALI calls to DALI server via SOAP protocol.
Definitions:
ServiceExceptionException is thrown when a connection cannot be made |
public String getMessage() Returns the cause of exception as string |
JAXRPCExceptionException is thrown when internal SOAP parameters are incorrect. This exception should never be thrown. |
public String getMessage() Returns the cause of exception as string |
AxisFaultException is thrown when an error occurs performing the function call or security permission is denied. |
public String getMessage() Returns the cause of exception as string |
DALIClass() Default constructor, takes no parameters. |
public synchronized boolean Ping(String url)Synchronized function that pings the DALI Server. Throws Exception: |
String url Server URL. Unique address of the DALI server on the network. Includes the IP address of the DALI server, the port to connect to, and the unique identification of the board that is being accessed. Refer to the Definitions for Server URL |
| If successful returns true, else false |
public synchronized int ADSample(String url, int channel, ADSettings settings)public synchronized int ADSample(String url, int channel, ADSettings settings, DALI_Authen authentication)Synchronized function that performs an A/D Sample. Throws Exception: |
String url Server URL. Unique address of the DALI server on the network. Includes the IP address of the DALI server, the port to connect to, and the unique identification of the board that is being accessed. Refer to the Definitions for Server URL |
int channel A/D channel to sample |
ADSettings settings ADSettings class for setting A/D range, gain, and polarity |
DALI_Authen authentication Structure that contains information of Username and Password |
| If successful returns the A/D sample value. Else throws a SOAP exception |
public synchronized int[] ADSampleMultiple(String url, int channel, int count, int hertz, ADSettings settings)public synchronized int[] ADSampleMultiple(String url, int channel, int count, int hertz, ADSettings settings, DALI_Authen authentication)Synchronized function that performs multiple A/D Samples. Will sample up to the number of count at a rate of hertz. Throws Exception: |
String url Server URL. Unique address of the DALI server on the network. Includes the IP address of the DALI server, the port to connect to, and the unique identification of the board that is being accessed. Refer to the Definitions for Server URL |
int channel A/D channel to sample |
int count Number of A/D samples function will obtain |
int hertz Rate of A/D Sample |
ADSettings settings ADSettings class for setting A/D range, gain, and polarity |
DALI_Authen authentication Structure that contains information of Username and Password |
| If success returns integer array of A/D sample values. Else throws a SOAP exception |
public synchronized int[] ADScan(String url, int low_channel, int high_channel, ADSettings settings)public synchronized int[] ADScan(String url, int low_channel, int high_channel, ADSettings settings, DALI_Auth authentication)Synchronized function that performs A/D Scan. Throws Exception: |
String url Server URL. Unique address of the DALI server on the network. Includes the IP address of the DALI server, the port to connect to, and the unique identification of the board that is being accessed. Refer to the Definitions for Server URL |
int low_channel A/D low channel to scan |
int high_channel A/D high channel to scan |
ADSettings settings ADSettings class for setting A/D range, gain, and polarity |
DALI_Authen authentication Structure that contains information of Username and Password |
| If success returns integer array of A/D scan values. Else throws a SOAP exception |
public synchronized int[] ADScanMultiple(String url, int low_channel, int high_channel, int count, int hertz, ADSettings settings)public synchronized int[] ADScanMultiple(String url, int low_channel, int high_channel, int count, int hertz, ADSettings settings, DALI_Authen authentication)Synchronized function that performs A/D Scan at a user specified rate up to a user specified number of samples. Throws Exception: |
String url Server URL. Unique address of the DALI server on the network. Includes the IP address of the DALI server, the port to connect to, and the unique identification of the board that is being accessed. Refer to the Definitions for Server URL |
int low_channel A/D low channel to scan |
int high_channel A/D high channel to scan |
int count Total number of A/D samples to obtain |
int hertz Rate of A/D scan. |
ADSettings settings ADSettings class for setting A/D range, gain, and polarity |
DALI_Authen authentication Structure that contains information of Username and Password |
| If success returns integer array of A/D scan values. Array size of count. Else throws a SOAP exception |
public synchronized boolean DAConvert(String url, int channel, int value)public synchronized boolean DAConvert(String url, int channel, int value, DALI_Authen authentication)Synchronized function that performs D/A convert Throws Exception: |
String url Server URL. Unique address of the DALI server on the network. Includes the IP address of the DALI server, the port to connect to, and the unique identification of the board that is being accessed. Refer to the Definitions for Server URL |
int channel D/A channel to output |
int value D/A value to output |
DALI_Authen authentication Structure that contains information of Username and Password |
| If success returns true. Else throws SOAP exception. |
public synchronized boolean DAConvertScan(String url, int low_channel, int high_channel, int[] values)public synchronized boolean DAConvertScan(String url, int low_channel, int high_channel, int[] values, DALI_Authen authentication)Synchronized function that performs D/A convert scan Throws Exception: |
String url Server URL. Unique address of the DALI server on the network. Includes the IP address of the DALI server, the port to connect to, and the unique identification of the board that is being accessed. Refer to the Definitions for Server URL |
int low_channel D/A low channel to output |
int high_channel D/A high channel to output |
int[] values Array of D/A values |
DALI_Authen authentication Structure that contains information of Username and Password |
| If success returns true. Else throws SOAP exception |
public synchronized boolean DIOOutputByte(String url, int channel, int value)public synchronized boolean DIOOutputByte(String url, int channel, int value)Synchronized function that performs DIO output byte. Throws Exception: |
String url Server URL. Unique address of the DALI server on the network. Includes the IP address of the DALI server, the port to connect to, and the unique identification of the board that is being accessed. Refer to the Definitions for Server URL |
int channel DIO channel to output |
int value int value to output |
DALI_Authen authentication Structure that contains information of Username and Password |
| If success returns true. Else throws SOAP exception |
public synchronized boolean DIOOutputBit(String url, int channel, int bit, byte value)public synchronized boolean DIOOutputBit(String url, int channel, int bit, byte value, DALI_Authen authentication)Synchronized function that performs DIO output bit. Throws Exception: |
String url Server URL. Unique address of the DALI server on the network. Includes the IP address of the DALI server, the port to connect to, and the unique identification of the board that is being accessed. Refer to the Definitions for Server URL |
int channel DIO channel to output |
int bit Bit to output to |
byte value Bit value to output |
DALI_Authen authentication Structure that contains information of Username and Password |
| If success returns true. Else throws SOAP exception |
public synchronized int DIOInputByte(String url, int channel)public synchronized int DIOInputByte(String url, int channel, DALI_Authen authentication)Synchronized function that performs DIO input byte. Throws Exception: |
String url Server URL. Unique address of the DALI server on the network. Includes the IP address of the DALI server, the port to connect to, and the unique identification of the board that is being accessed. Refer to the Definitions for Server URL |
int channel DIO channel to input |
DALI_Authen authentication Structure that contains information of Username and Password |
| If success returns input byte value. Else throws SOAP exception |
public synchronized byte DIOInputBit(String url, int channel, int bit)public synchronized byte DIOInputBit(String url, int channel, int bit, DALI_Authen authentication)Synchronized function that performs DIO input bit Throws Exception: |
String url Server URL. Unique address of the DALI server on the network. Includes the IP address of the DALI server, the port to connect to, and the unique identification of the board that is being accessed. Refer to the Definitions for Server URL |
int channel DIO channel to input |
int bit Bit to read from. |
DALI_Authen authentication Structure that contains information of Username and Password |
| If success returns input bit value. Else throws SOAP exception |
public synchronized Channel[] getChannelInfo(String url)Synchronized function that returns all channel information of the board Throws Exception: |
String url Server URL. Unique address of the DALI server on the network. Includes the IP address of the DALI server, the port to connect to, and the unique identification of the board that is being accessed. Refer to the Definitions for Server URL |
| If success returns Channel array. Each Channel instance contains information of channel number, channel type, and security. If fail throws SOAP exception |
public synchronized Board[] getBoardInfo(String url)Synchronized function that returns all board information on the DALI server. Throws Exception: |
String url Server URL. Unique address of the DALI server on the network. Includes the IP address of the DALI server, the port to connect to, and the unique identification of the board that is being accessed. Refer to the Definitions for Server URL |
| If success returns Board array. Each Board instance contains information of unique board identification string, Diamond Systems board product name, and base address. If fail throws SOAP exception |
public synchronized int DAReadBack(String url, int channel)public synchronized int DAReadBack(String url, int channel, DALI_Authen authentication)Synchronized function that reads back D/A output value. Throws Exception: |
String url Server URL. Unique address of the DALI server on the network. Includes the IP address of the DALI server, the port to connect to, and the unique identification of the board that is being accessed. Refer to the Definitions for Server URL |
int channel D/A channel to read back |
DALI_Authen authentication Structure that contains information of Username and Password |
| If success returns integer D/A value. If fail throws SOAP exception |
public synchronized int DIOReadBackByte(String url, int channel)public synchronized int DIOReadBackByte(String url, int channel, DALI_Authen authentication)Synchronized function that reads back DIO output value. Throws Exception: |
String url Server URL. Unique address of the DALI server on the network. Includes the IP address of the DALI server, the port to connect to, and the unique identification of the board that is being accessed. Refer to the Definitions for Server URL |
int channel DIO port to read back |
DALI_Authen authentication Structure that contains information of Username and Password |
| If success returns int of DIO value. If fail throws SOAP exception |
public synchronized byte DIOReadBackBit(String url, int channel, int bit)public synchronized byte DIOReadBackBit(String url, int channel, int bit, DALI_Authen authentication)Synchronized function that reads back DIO output bit value. Throws Exception: |
String url Server URL. Unique address of the DALI server on the network. Includes the IP address of the DALI server, the port to connect to, and the unique identification of the board that is being accessed. Refer to the Definitions for Server URL |
int channel DIO port to read back |
int bi DIO bit to read back |
DALI_Authen authentication Structure that contains information of Username and Password |
| If success returns byte of DIO bit value. If fail throws SOAP exception |
To compile the program developers must use Javac, the Java compiler provided by Sun.Java.
To compile type the following:
Javac -classpath (your classpath here) XXX.JavaClass Path is the directory that contains dali_Java.jar and all Apache Axis Jar files. This directory must be included to compile successfully
Jar files are easy ways for developers to group and distribute their application. This is a quick guide and developers should refer to Sun.Java documentation on Jar files.
To create Jar files, developers must first "Package" up their files. Another words all the class files should belong to the same package. To package up files, insert the following code at the top of the .Java files.
package XXX;
Where XXX is to be replaced by the package name. In the case of dali_Java.jar, xxx is com.diamondsystems.dali. After all the Java files are compiled, developers should create a directory that corresponds to the XXX of the package name. In the case of dali_Java.jar, it is three directories, with the "dali" directory nested in the "diamondsystems" directory which is in term nested in the "com" directory. Copy and paste all the class files into the most deeply nested directory, in this case "dali". Return to the directory where "com" is nested. Type the following command
jar cvf XXX.jar -C ./ com
This will create a Jar file of the name XXX.jar. The cvf option are standard options for creating a Jar file. -C will make the Jar utility package up all files in the "com" directory.
Jar File is Created!
To use applets add the following line of code in the html:
<APPLET CODE="xxx.class" Archive="Applet.jar, axis.jar, jaxrpc.jar,
commons-logging.jar, commons-discovery.jar, saaj.jar, wsdl4j.jar, log4j-1.2.4.jar"
Codebase="./" WIDTH=592 HEIGHT=296>
In the above applet the xxx.class is the class with the main applet functions. Applet.jar is the file that contains xxx.class. All other jar files are Apache Axis files that are necessary for Axis.
Please refer to http://www.verisign.com/products/signing/index.html?sl=060309 or other services for buying certificates. Verisign also provides a guide explaining why and how to obtain certificates and how to sign applets.
NOTE: Developers MUST sign all .jar files that are part of the