Erste JVx Applikation (Schritt für Schritt)

picture_as_pdf

Für die Applikationsentwicklung mit JVx wird eine spezielle Ordnerstruktur empfohlen. Diese erleichtert den Build Prozess und trennt von vornherein Abhängigkeiten zwischen Client und Server. Diese Struktur ist wie folgt zu erstellen:

Auf Wunsch kann auch eine herkömmliche Strukturierung:

verwendet werden. Die Dokumentation bezieht sich jedoch auf die empfohlene Struktur.

Nachdem die Ordnerstruktur erstellt wurde, kopieren Sie die Bibliothek jvxclient.jar in den Ordner libs/client und die Bibliothek jvx.jar in den Ordner libs/server. Beide Bibliotheken sind im JVx Binärpaket enthalten.

Nachdem die Konfiguration durchgeführt wurde, kann mit Eclipse ein neues Projekt erstellt werden:

• File / New / Java Project
• Zu beachten ist, dass das Projekt im Applikationsverzeichnis firstapp abgelegt wird.
  
• Entfernen des src Ordner von den Source Folders
  Setzen der Ordner src.client, src.server und test als Source Folder
  
• Hinzufügen der jvx.jar Bibliothek, aus dem Projektverzeichnis JVxFirstApp/libs/server
  
• Das Projekt kann nun erstellt werden

Das Projekt wird von Eclipse nun wie folgt dargestellt:

Zur Vollständigkeit kann der src Ordner gelöscht werden. Dieser wird in unserer Applikation nicht benötigt.

Die Applikation benötigt Serverseitig eine Konfigurationsdatei für Einstellungen die nur die Applikation betreffen. Für die Konfiguration des Servers wird zusätzlich eine Konfigurationsdatei benötigt. Zuerst erstellen wir die Datei für die Applikation:

• File / New / File - config.xml
  (Erstellung direkt im Applikationsverzeichnis JVxFirstApp)
  

Die Datei wird wie folgt befüllt:

config.xml

<?xml version="1.0" encoding="UTF-8"?>
 
<application>
  <securitymanager>
    <class>com.sibvisions.rad.server.security.XmlSecurityManager</class>
    <userfile>users.xml</userfile>
  </securitymanager>
 
  <!-- predefined life-cycle object names -->
  <lifecycle>
    <mastersession>apps.firstapp.Session</mastersession>
    <application>apps.firstapp.Application</application>
  </lifecycle>  
</application>

Die Konfigurationsdatei des Servers muss im Verzeichnis ../JVxFirstApp/rad/server abgelegt werden.

Dieses Verzeichnis scheint in unserem Eclipse Projekt jedoch nicht auf, da es sich auf einer höheren Verzeichnisebene befindet. Die Konfigurationsdatei könnte direkt im Dateisystem erstellt werden oder wir erstellen einen Verzeichnis-Link in unserem Projekt:

• File / New / Folder
  

Anschließend kann die Konfigurationsdatei erstellt werden:

• File / New / File - config.xml
  

Die Datei wird wie folgt befüllt:

config.xml

<?xml version="1.0" encoding="UTF-8"?>
 
<server>
</server>

Der Server benötigt für unsere Applikation keine speziellen Parameter.

Für den Client benötigen wir nun eine Klasse die vom Typ jvx.rad.application.IApplication ist. Von JVx wird eine Standard Implementierung durch com.sibvisions.rad.application.Application implementiert. Von dieser werden wir unseren Client ableiten und erstellen somit eine Klasse, im Verzeichnis src.client, mit folgendem Source Code:

FirstApplication.java

package apps.firstapp;
 
import jvx.rad.application.genui.UILauncher;
import jvx.rad.remote.IConnection;
 
import com.sibvisions.rad.application.Application;
import com.sibvisions.rad.server.DirectServerConnection;
 
/**
 * First application with JVx, Enterprise Application Framework.
 * 
 * @author René Jahn
 */
public class FirstApplication extends Application
{
  //~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  // Initialization
  //~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
  /**
   * Creates a new instance of <code>FirstApplication</code> with a technology
   * dependent launcher.
   * 
   * @param pLauncher the technology dependent launcher
   * @throws Exception if initialization fails
   */
  public FirstApplication(UILauncher pLauncher) throws Exception
  {
    super(pLauncher);
  }
 
  //~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  // Overwritten methods
  //~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
  /**
   * {@inheritDoc}
   */
  @Override
  protected IConnection createConnection() throws Exception
  {
    return new DirectServerConnection();
  }
 
  /**
   * {@inheritDoc}
   */
  @Override
  protected String getApplicationName()
  {
    return "firstapp";
  }
 
}  // FirstApplication

Nun ist es an der Zeit für den ersten Start der Applikation. Dafür erstellen wir eine Runtime Konfiguration:

• Run / Run Configurations… / Application - New launch configuration - mit den Einstellungen:
  
  

Die Applikation kann nun gestartet werden und sollte wie folgt aussehen:

Der erste Anmeldeversuch scheitert mit dem Hinweis:

Userfile 'users.xml' does not exist!

Diese Datei wurde im config.xml der Applikation definiert, bisher jedoch noch nicht erstellt. Das holen wir an dieser Stelle nach:

• File / New / File - users.xml
  

Die Datei befüllen wir mit:

users.xml

<?xml version="1.0" encoding="UTF-8"?>
 
<users>
  <user name="admin" password="admin"/>
</users>

Es können beliebig viele user Zeilen eingetragen werden!

Nun ist die Anmeldung an die Applikation ohne Probleme möglich. Zur Erfüllung unserer Aufgabenstellung fehlt jedoch noch die Möglichkeit eine Datenbanktabelle anzuzeigen bzw. zu editieren. Diesem Teil der Aufgabe widmen wir uns jetzt.

Bevor wir den WorkScreen erstellen, bereiten wir die Applikation für die Anzeige des WorkScreens vor. Dazu erweitern wir unsere FirstApplication Klasse wie folgt:

FirstApplication.java

package apps.firstapp;
 
import jvx.rad.application.genui.UILauncher;
import jvx.rad.genui.UIImage;
import jvx.rad.genui.component.UIButton;
import jvx.rad.genui.container.UIToolBar;
import jvx.rad.genui.menu.UIMenu;
import jvx.rad.genui.menu.UIMenuItem;
import jvx.rad.remote.IConnection;
 
import com.sibvisions.rad.application.Application;
import com.sibvisions.rad.server.DirectServerConnection;
 
/**
 * First application with JVx, Enterprise Application Framework.
 * 
 * @author René Jahn
 */
public class FirstApplication extends Application
{
  //~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  // Initialization
  //~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
  /**
   * Creates a new instance of <code>FirstApplication</code> with a technology
   * dependent launcher.
   * 
   * @param pLauncher the technology dependent launcher
   */
  public FirstApplication(UILauncher pLauncher)
  {
    super(pLauncher);
  }
 
  //~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  // Overwritten methods
  //~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
  /**
   * {@inheritDoc}
   */
  @Override
  protected IConnection createConnection() throws Exception
  {
    return new DirectServerConnection();
  }
 
  /**
   * {@inheritDoc}
   */
  @Override
  protected String getApplicationName()
  {
    return "firstapp";
  }
 
  /**
  * {@inheritDoc}
  */
  @Override
  protected void afterLogin()
  {
    super.afterLogin();
 
    //configure MenuBar
 
    UIMenu menuMasterData = new UIMenu();
    menuMasterData.setText("Master data");
 
    UIMenuItem miDBEdit = createMenuItem
                          ("doOpenDBEdit", null, "DB Edit", 
                           UIImage.getImage(UIImage.SEARCH_LARGE));
 
    menuMasterData.add(miDBEdit);
 
    //insert before Help
    getMenuBar().add(menuMasterData, 1);
 
    //configure ToolBar
 
    UIToolBar tbMasterData = new UIToolBar();
 
    UIButton butDBEdit = createToolBarButton
                         ("doOpenDBEdit", null, "DB Edit", 
                          UIImage.getImage(UIImage.SEARCH_LARGE));
 
    tbMasterData.add(butDBEdit);
 
    getLauncher().addToolBar(tbMasterData);
  }
 
  //~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  // Actions
  //~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
  /**
   * Opens the edit screen.
   */
  public void doOpenDBEdit()
  {
    //TODO open the workscreen
  }
 
}  // FirstApplication

Wir erstellen nun die Client Klasse für unseren WorkScreen:

• File / New / Class
  src.client, apps.firstapp.frames.DBEditFrame
  

und verwenden folgenden Source Code:

DBEditFrame.java

package apps.firstapp.frames;
 
import jvx.rad.genui.container.UIGroupPanel;
import jvx.rad.genui.container.UIInternalFrame;
import jvx.rad.genui.control.UITable;
import jvx.rad.genui.layout.UIBorderLayout;
import jvx.rad.remote.AbstractConnection;
import jvx.rad.remote.MasterConnection;
 
import com.sibvisions.rad.application.Application;
import com.sibvisions.rad.model.remote.RemoteDataBook;
import com.sibvisions.rad.model.remote.RemoteDataSource;
 
/**
 * A simple database table editor.
 * 
 * @author René Jahn
 */
public class DBEditFrame extends UIInternalFrame
{
  //~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  // Class members
  //~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
  /** the application. */
  private Application application;
 
  /** the communication connection to the server. */
  private AbstractConnection connection;
 
  /** the DataSource for fetching table data. */
  private RemoteDataSource dataSource = new RemoteDataSource();
 
  /** the contacts tabl. */
  private RemoteDataBook rdbContacts = new RemoteDataBook();
 
  //~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  // Initialization
  //~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
  /**
   * Creates a new instance of DBEditFrame for a specific application.
   * 
   * @param pApp the application
   * @throws Throwable if the remote access fails
   */
  public DBEditFrame(Application pApp) throws Throwable
  {
    super(pApp.getDesktopPane());
 
    application = pApp;
 
    initializeModel();
    initializeUI();
  }
 
  /**
   * Initializes the model.
   * 
   * @throws Throwable if the initialization throws an error
   */
  private void initializeModel() throws Throwable
  {
    //we use a new "session" for the screen
    connection = ((MasterConnection)application.getConnection()).
    createSubConnection("apps.firstapp.frames.DBEdit");
    connection.open();
 
    //data connection
    dataSource.setConnection(connection);
    dataSource.open();
 
    //table
    rdbContacts.setDataSource(dataSource);
    rdbContacts.setName("contacts");
    rdbContacts.open();
  }
 
  /**
   * Initializes the UI.
   * 
   * @throws Exception if the initialization throws an error
   */
  private void initializeUI() throws Exception
  {
    UIGroupPanel group = new UIGroupPanel();
    group.setText("Available Contacts");
 
    UITable table = new UITable();
    table.setDataBook(rdbContacts);
 
    group.setLayout(new UIBorderLayout());
    group.add(table);
 
    //same behaviour as centered component in BorderLayout 
    setLayout(new UIBorderLayout());
    add(group); 
 
    setTitle("Contacts");
    setSize(new UIDimension(400, 500));
  } 
 
  //~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  // Overwritten methods
  //~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
  /**
   * Closes the communication connection and disposes the frame.
   */
  @Override
  public void dispose()
  {
    try
    {
      connection.close();
    }
    catch (Throwable th)
    {
      //nothing to be done
    }
    finally
    {
      super.dispose();
    }
  }
 
} // DBEditFrame

Der WorkScreen ist nun fertig und kann in die Applikation integriert werden. Wir implementieren nun den fehlenden Aufruf:

FirstApplication.java

public class FirstApplication extends Application
{
  ...
  ...
  ...
 
  /**
   * Opens the edit screen.
   * 
   * @throws Throwable if the edit frame can not be opened
   */
  public void doOpenDBEdit() throws Throwable
  {
    DBEditFrame frame = new DBEditFrame(this);
 
    configureFrame(frame);
 
    frame.setVisible(true);
  }
 
}  // FirstApplication

Die Client Implementierung ist nun abgeschlossen. Bevor wir die Applikation verwenden können müssen die fehlenden Server Klassen erstellt werden. Wir erstellen folgende Klassen:

• File / New / Class
  src.server, apps.firstapp.Application
  

Application.java

package apps.firstapp;
 
import com.sibvisions.rad.server.GenericBean;
 
/**
 * The LCO for the application.
 * 
 * @author René Jahn
 */
public class Application extends GenericBean
{
 
}  // Application

• File / New / Class
  src.server, apps.firstapp.Session
  

Session.java

package apps.firstapp;
 
import com.sibvisions.rad.persist.jdbc.DBAccess;
import com.sibvisions.rad.persist.jdbc.IDBAccess
 
/**
 * The LCO for the session.
 * 
 * @author René Jahn
 */
public class Session extends Application
{
  //~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  // User-defined methods
  //~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
  /**
   * Returns access to the database.
   * 
   * @return the database access
   * @throws Exception if a connection error occurs
   */
  public IDBAccess getDBAccess() throws Exception
  {
    DBAccess dba = (DBAccess)get("dBAccess");
 
    if (dba == null)
    {
      dba = new HSQLDBAccess();
 
      dba.setUrl("jdbc:hsqldb:hsql://localhost/firstappdb"); 
      dba.setUsername("sa");
      dba.setPassword("");
      dba.open();
 
      put("dBAccess", dba);
    }
 
    return dba;
  }  
 
}  // Session

• File / New / Class
  src.server, apps.firstapp.frames.DBEdit
  

DBEdit.java

package apps.firstapp.frames;
 
import jvx.rad.persist.IStorage;
 
import com.sibvisions.rad.persist.jdbc.DBStorage;
 
import apps.firstapp.Session;
 
/**
 * The LCO for the DBEdit WorkScreen.
 * 
 * @author René Jahn
 */
public class DBEdit extends Session
{
  //~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  // User-defined methods
  //~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
  /**
   * Returns the contacts storage.
   * 
   * @return the contacts storage
   * @throws Exception if the initialization throws an error
   */
  public IStorage getContacts() throws Exception
  {
    DBStorage dbsContacts = (DBStorage)get("contacts");
 
    if (dbsContacts == null)
    {
      dbsContacts = new DBStorage();
      dbsContacts.setDBAccess(getDBAccess());
      dbsContacts.setFromClause("CONTACTS");
      dbsContacts.setWritebackTable("CONTACTS");
      dbsContacts.open();
 
      put("contacts", dbsContacts);
    }
 
    return dbsContacts;
  }
 
}  // DBEdit

Die Applikation ist jetzt vollständig implementiert und lauffähig. Damit wir nun mit der Applikation arbeiten können benötigen wir die Datenbank inklusive Tabelle CONTACTS auf die wir zugreifen wollen. Die Konfiguration von HSQLDB wird in diesem Dokument nicht detailiert beschrieben, da die Beispiele auf der Projektseite detailiert und ausreichend sind. In nachfolgendem Kapitel finden Sie eine kurze Zusammenfassung der notwendigen Schritte.

Folgende Schritte sollten durchgeführt werden um eine HSQLDB zu erstellen und zu starten.

• Kopieren Sie den HSQLDB JDBC-Teiber (hsqldb.jar) in das Verzeichnis ../JVxFirstApp/libs/server/
• Fügen Sie den JDBC-Treiber dem CLASSPATH des JVxFirstApp Projektes hinzu
• Erstellen Sie eine Datenbank mit dem Alias firstappdb und folgender Tabelle:
  

  CREATE TABLE CONTACTS
  (
    ID            INTEGER IDENTITY,
    FIRSTNAME     VARCHAR(200) NOT NULL,
    LASTNAME      VARCHAR(200) NOT NULL,
    BIRTHDAY      DATE,
    STREET        VARCHAR(200),
    NR            VARCHAR(200),
    ZIP           VARCHAR(4),
    TOWN          VARCHAR(200)
  )

• SStarten Sie die Datenbank z.B.:
  

  java -cp ../libs/server/hsqldb.jar org.hsqldb.Server -database.0 
       file:firstappdb -dbname.0 firstappdb

Nachdem die Datenbank gestartet wurde kann die Applikation ebenfalls gestartet werden. Die fertige Applikation sollte nun wie folgt aussehen:

Den Source Code und das Eclipse Projekt finden Sie auch im Download Bereich.