A Simple TINE Java Client (GUI)

Introduction

TINE console client applications play an important role in middle-layer servers, automatic servers, scripts, diagnostic checks, etc. Client applications requiring a user interface are best written as GUI applications.

The example below is a simple java client code module which obtains the sine curve from the simple console server example, and illustrates both synchronous and asynchronous calls. It makes use of the acop java bean for graphical display of the sine wave.

Step 1 Create a SineClient class

Create a new java project and make sure that tine.jar and acop.jar are included in the library list on otherwise on the class path. In this example, we'll assume this is a java project in Eclipse called "SINE-gui", where a package "tineSineClientGUIExample" has been created with a class called "SineClient". In Eclipse make sure the class is added as a 'visual' class.

Assuming that the top level visual container is a Swing JFrame, you should put a JPanel in the center position, go to the properties of the Jpanel and set the layout manager to 'null'. If you like layout manager and know what you're doing then you can ignore these suggestions. However for the sake of presenting a simple (Visual Basic - like) example we'll turn it off.

If the acop bean does not show up in the bean list, then select "Choose Bean" and type "acop" and select the Acop bean from the list. Now drag this over the JPanel and place and size it however you like it.

At this stage, the generated code should look something like the following:

/*
 * Created on Apr 8, 2004
 *
 * To change the template for this generated file go to
 * Window>Preferences>Java>Code Generation>Code and Comments
 */
package tineSineClientGUIExample;
 
import javax.swing.JFrame;
 
public class SineClient extends JFrame
{
  private javax.swing.JPanel jContentPane = null;
  private javax.swing.JPanel jPanel = null;
  private acop.Acop acop = null;
  public static void main(String[] args)
  {
  }
  public SineClient()
  {
    super();
    initialize();
  }
  private void initialize()
  {
    this.setSize(300, 200);
    this.setContentPane(getJContentPane());
  }
  private javax.swing.JPanel getJContentPane()
  {
    if (jContentPane == null)
    {
      jContentPane = new javax.swing.JPanel();
      jContentPane.setLayout(new java.awt.BorderLayout());
      jContentPane.add(getJPanel(), java.awt.BorderLayout.CENTER);
    }
    return jContentPane;
  }
  private javax.swing.JPanel getJPanel() 
  {
    if(jPanel == null) 
    {
      jPanel = new javax.swing.JPanel();
      jPanel.setLayout(null);
      jPanel.add(getAcop(), null);
    }
    return jPanel;
  }
  private acop.Acop getAcop() 
  {
    if(acop == null) 
    {
      acop = new acop.Acop();
      acop.setBounds(16, 16, 264, 113);
    }
    return acop;
  }
}

and your visual editor should show something like:

Note that in this example we have made no attempt to name the acop instance anything other than the suggestiong 'acop'. You could give it the name 'sinewave' or something more meaningful if you like.

Step 2 Initialization

In the main() method add

  new SineClient().show();

so that the application will display itself when it is being run. underneath the package declaration.

Add the int variable 'size' to the class, initializing it to 1024. Now add the float arrays sdat and refdat, dimensioned to size;

Set the acop properties 'AccessProtocol' to "TINE", 'AccessMode' to "POLL", 'DeviceContext' to "TEXT", 'DeviceGroup' to "SINEWAVE", 'DeviceName' to "#0", 'DeviceProperty' to "SINE". Generated code frequently places these property settings in the instantiation routine of the acop.

In the visual editor, right click on the acop and select 'Add Events', and choose 'Acop' -> 'Acop.receive'.

The generated code will add an 'AcopListener' and an AcopReceive() event stub which prints out "AcopReceive()" on the standard output.

Your SineClient.java code should now look like the following:

/*
 * Created on Apr 8, 2004
 *
 * To change the template for this generated file go to
 * Window>Preferences>Java>Code Generation>Code and Comments
 */
package tineSineClientGUIExample;
 
import javax.swing.JFrame;
 
public class SineClient extends JFrame
{
  private javax.swing.JPanel jContentPane = null;
 
  private javax.swing.JPanel jPanel = null;
  private acop.Acop acop = null;
  private static int size = 1024;
  private float[] sdat = new float[size];
  private float[] refdat = new float[size];
  public static void main(String[] args)
  {
    new SineClient().show();
  }
  public SineClient()
  {
    super();
    initialize();
  }
  private void initialize()
  {
    this.setSize(300, 200);
    this.setContentPane(getJContentPane());
  }
  private javax.swing.JPanel getJContentPane()
  {
    if (jContentPane == null)
    {
      jContentPane = new javax.swing.JPanel();
      jContentPane.setLayout(new java.awt.BorderLayout());
      jContentPane.add(getJPanel(), java.awt.BorderLayout.CENTER);
    }
    return jContentPane;
  }
  private javax.swing.JPanel getJPanel() 
  {
    if(jPanel == null) 
    {
      jPanel = new javax.swing.JPanel();
      jPanel.setLayout(null);
      jPanel.add(getAcop(), null);
    }
    return jPanel;
  }
  private acop.Acop getAcop() 
  {
    if(acop == null) 
    {
      acop = new acop.Acop();
      acop.setBounds(16, 16, 264, 113);
      acop.setAccessProtocol("TINE");
      acop.setAccessMode("POLL");
      acop.setDeviceContext("TEST");
      acop.setDeviceGroup("SINEWAVE");
      acop.setDeviceName("#0");
      acop.setDeviceProperty("SINE");
      acop.addAcopListener(new acop.AcopListener() { 
        public void AcopReceive(acop.AcopEvent e) {    
          System.out.println("AcopReceive()"); // TODO Auto-generated Event stub AcopReceive()
        }
        public void AcopMouseMove(acop.AcopEvent e) {} 
        public void AcopMouseClick(acop.AcopEvent e) {} 
        public void AcopMouseZoom(acop.AcopEvent e) {} 
        public void AcopMouseEnter(acop.AcopEvent e) {} 
        public void AcopMouseExit(acop.AcopEvent e) {} 
      });
    }
    return acop;
  }
}

Create a simple callback method called cbSineClient() and inside this method, issue an acop.ClearScreen and an acop.Draw so that the sine wave display is updated every time the receive event is fired.

Inside the initialize method you can set the 'max' and 'min' display properties for the acop display. For this simple example, we'll just set them with a priori knowledge as the range of values.

You can also obtain a 'reference' display with a synchronous 'Execute()' call inside the initialization routine, but remember to set the AccessMode to "READ" prior to the call and to set it back to "POLL" prior to making a call to 'AttachLink()', which you should also do in this routine.

The code in your SineClient.java module should now look something like:

/*
 * Created on Apr 8, 2004
 *
 * To change the template for this generated file go to
 * Window>Preferences>Java>Code Generation>Code and Comments
 */
package tineSineClientGUIExample;
 
import javax.swing.JFrame;
 
public class SineClient extends JFrame
{
  private javax.swing.JPanel jContentPane = null;
 
  private javax.swing.JPanel jPanel = null;
  private acop.Acop acop = null;
  private static int size = 1024;
  private float[] sdat = new float[size];
  private float[] refdat = new float[size];
  public static void main(String[] args)
  {
    new SineClient().show();
  }
  public SineClient()
  {
    super();
    initialize();
  }
  private void initialize()
  {
    this.setSize(300, 200);
    this.setContentPane(getJContentPane());
    acop.setAccessMode("READ");
    int rc = acop.Execute(refdat, size, null, 0);
    if (rc != 0) System.out.println(" couldn't get reference : " + acop.getStatus());
    acop.setAccessMode("POLL");
    acop.setXMin(0);
    acop.setXMax(1024);
    acop.setYMin(0);
    acop.setYMax(512);
    acop.AttachLink(sdat, size, null, 0);
  }
  private javax.swing.JPanel getJContentPane()
  {
    if (jContentPane == null)
    {
      jContentPane = new javax.swing.JPanel();
      jContentPane.setLayout(new java.awt.BorderLayout());
      jContentPane.add(getJPanel(), java.awt.BorderLayout.CENTER);
    }
    return jContentPane;
  }
  private javax.swing.JPanel getJPanel() 
  {
    if(jPanel == null) 
    {
      jPanel = new javax.swing.JPanel();
      jPanel.setLayout(null);
      jPanel.add(getAcop(), null);
    }
    return jPanel;
  }
  private void cbSineClient()
  {
    acop.ClearScreen(-1,0);
    acop.Draw(sdat,null,null,null,0,0);
  }
  private acop.Acop getAcop() 
  {
    if(acop == null) 
    {
      acop = new acop.Acop();
      acop.setBounds(16, 16, 264, 113);
      acop.setAccessProtocol("TINE");
      acop.setAccessMode("POLL");
      acop.setDeviceContext("TEST");
      acop.setDeviceGroup("SINEWAVE");
      acop.setDeviceName("#0");
      acop.setDeviceProperty("SINE");
      acop.addAcopListener(new acop.AcopListener() { 
        public void AcopReceive(acop.AcopEvent e) {    
          cbSineClient();    
        }
        public void AcopMouseMove(acop.AcopEvent e) {} 
        public void AcopMouseClick(acop.AcopEvent e) {} 
        public void AcopMouseZoom(acop.AcopEvent e) {} 
        public void AcopMouseEnter(acop.AcopEvent e) {} 
        public void AcopMouseExit(acop.AcopEvent e) {} 
      });
    }
    return acop;
  }
}

Step 3 Running the program

When you run the application, make sure the the virtual machine definition -Dtine.home is set (e.g -Dtine.home=L:\database or -Dtine.home=/usr/etc/tine). You should see a display something like the following:

To run the java application stand-alone instead of inside a development environment such as Eclipse, you should export the project as an external .jar file, for example mySineClient.jar.

In Windows, you can start the application at the command prompt by typing:

javaw -cp mySineClient.jar;tine.jar;acop.jar; -Dtine.home="L:\\database" tineSineClientGUIExample.SineClient

If the tine.home property is contained in a properties file called tine.properties and this file is in the same directory where tine.jar is located, then you can also start the application by typing:

javaw -cp mySineClient.jar;tine.jar;acop.jar; tineSineClientGUIExample.SineClient

We called the .jar file mySineClient.jar and it needs tine.jar and acop.jar on the classpath in order to start. Finally, the package name 'tineClientGUIExample' and the class containing the 'main' method that we want to start needs to be the last entry on the command line. If the package name uses long url names (in order to avoid name collisions) this all needs to be specified (i.e. your package name is de.desy.mcs.tineSineClientGUIExample for instance).

It is frequently a good idea to place system jar files together in a repository and to make use of the java.ext.dirs property switch to point to this repository. For instance, if an enviroment variable JARPATH is set to point to this repository, e.g.

set JARPATH=L:\java

then applying the property definition -Djava.ext.dirs=JARPATH% will eliminate the need for placing all necessary jar files on the classpath.

If the application jar file has a manifest which identifies the main routine to start execution, then the application can be started by typing

javaw -Djava.ext.dirs=JARPATH% -jar tineSineClientGUIExample.SineClient

If you place this command line inside a batch file, remember to use 'start' so as to avoid an open cmd window.

In UNIX you can type:

java -cp mySineClient.jar:tine.jar:acop.jar: -Dtine.home=/usr/etc/tine tineSineClientGUIExample.SineClient

Or if you use a JARPATH location such as

export JARPATH=/usr/jars

java -Djava.ext.dirs=$JARPATH -jar tineSineClientGUIExample.SineClient