First JVx Application (Step by Step)

picture_as_pdf

To develop an application with JVx, a special folder structure is recommended. This simplifies the build process and separates any dependencies between client and server. This structure is to be created as follows:

A conventional structure:

can also be used on request. However, the documentation refers to the recommended structure.

Once the folder structure has been created, copy the library jvxclient.jar to the folder libs/client and the library jvx.jar to the folder libs/server. Both libraries are contained in the JVx binary package.

Once the configuration steps have been performed, a new project can be created with Eclipse:

• File / New / Java Project
• Note that the project has to be set up in the application folder firstapp
  
• Remove the src folder from the Source Folders
  Set the folders src.client, src.server and test as Source Folder
  
• Add the jvx.jar library, from the project directory JVxFirstApp/libs/server
  
• The project can now be created

The project is shown in Eclipse as follows:

The src folder can be deleted for consistency as it is not needed in our application.

On the server side, the application needs a configuration file for the settings that only concern the application. For the configuration of the server, an extra configuration file is needed. First, we create the file for the application:

• File / New / File - config.xml
  (created directly in the application folder JVxFirstApp)
  

The file is filled as follows:

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>

The server configuration file must be stored in the folder ../JVxFirstApp/rad/server.

However, the folder does not appear in our Eclipse project because it is at a higher folder level. The configuration file could be created directly in the file system, or we can create a folder link in our project:

• File / New / Folder
  

The configuration file can then be created:

• File / New / File - config.xml
  

The file is filled as follows:

config.xml

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

The server does not need any special parameters for our application.

For the client, we now need a class of type jvx.rad.application.IApplication. A standard implementation of JVx is implemented via com.sibvisions.rad.application.Application. We then derive our client from it and thereby create a class in the directory src.client with the following 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

It is now time for the first start of the application. To do so, we set up a Runtime configuration:

• Run / Run Configurations… / Application - New launch configuration - with the settings:
  
  

The application can now be started and looks as follows:

The first login attempt fails with the following message:

Userfile 'users.xml' does not exist!

This file was defined in the config.xml file of the application; however, it has not yet been created. We do so now here:

• File / New / File - users.xml
  

We fill the file with the following:

users.xml

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

Any number of user lines can be entered!

Now the login to the application works perfectly. However, to fulfill our task, we still need the possibility to display or edit a database table. We will now turn to this part of the task.

Before we create a workscreen, we prepare the application to display the workscreen. To do so, we extend our FirstApplication class as follows:

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

We now create the client class for our workscreen:

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

and use the following 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

The workscreen is now ready and can be integrated in the application. We now implement the missing call:

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

The client implementation is now finished. Before we can use the application, we must create the missing server classes. We create the following classes:

• 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

The application is now fully implemented and ready to run. So as to be able to work with the application, we need a database with the CONTACTS table that we want to access. The configuration of HyperSQL DB is not described in detail in this document, as the examples on the project page are detailed and sufficient. In the next chapter, you will find a short summary of the necessary steps.

The following steps should take place to create and start a HyperSQL DB.

• Copy the HyperSQL JDBC-Driver (hsqldb.jar) to the directory ../JVxFirstApp/libs/server/
• Add the JDBC-Driver to the CLASSPATH of the JVxFirstApp Project
• Create a database with the alias firstappdb and the following table:
  

  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)
  )

• Start the database, e.g.:
  

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

Once the database has been started, the application can also be started. The final application should look as follows:

The source code and the Eclipse project can be found in the Download section.