Creating an online project management application

From JVantage

Contents 1 Introduction 1.1 The Root Context 2 Creating an Application 3 Defining the Company Entity 3.1 If the Data Source is Not Valid 3.2 Creating a Table 3.3 Company Table 4 Summary

Introduction

This tutorial provides step-by-step instructions for creating an online project management application. This application will be similar to the demo application that comes as part of the jVantage download. A high-level overview of the application can also be viewed as a multi-media presentation from the jVantage home page, however the multi-media presentation skips over many of the details that are covered here.

The Root Context

When you first login to jVantage, the page you see is the root context (click on the image to the right to see an example). The root context view is basically the jVantage development environment home page. It shows information about the overall jVantage instance and the list of applications it contains.

The attached image shows the default state of jVantage when it is initially installed. Note that because the development environment is also a jVantage application, the list includes three applications that are part of jVantage itself, plus a demonstration application.

This list includes:

ACL 

Acess Control application. This application actually has little direct functionality, instead it houses configuration information that reflects the security settings you define directly within the applications you create.

jVantage 

The jVantage development environment is actually a jVantage application, which means it is listed along with all of the other applications.

Project Manager

The project manager is a sample application that ships with jVantage. It can be used to experience and experiment with the development capabilities of jVantage.

PropertyService

jVantage allows property profiles to be created for any reason and for any use. Although it is often desirable to place property files on the filesystem, it is sometimes preferable to create a property profile within jVantage which can then be accessed directly from your applications using the property service API.

Creating an Application

To create an application, click on the create application button on the root context page.

Creating an application begins with an application definition record, which includes high-level information such as its name and where its data should be stored. After this, application behavior can be defined as needed. We're going to call our application pm2, for project manager 2. The description field provides a short summary of what the application does. Note that the data entered here is leveraged later during generation of online help, so it is important to provide a reasonable value.

The Help Template URL field tells jVantage where to find templates that should be used when generating online help. The Theme similarly indicates which template theme should be used for the application being developed. More information about these fields can be found in the reference section of the online documentation. The DataSource indicates where information that your application manages will be stored. New data sources can be created for each application, allowing the associated data to be kept separate. For this tutorial, we will use the default data source. The default data source value can vary from one system to another.

All applications names must be unique across the entire jVantage instance and may not contain spaces or special characters. This is because the application name is sometimes leveraged to construct paths to files or other artifacts, and avoiding spaces can prevent problems on some operating systems and contexts. The red asterisks indicate which fields on the form are required, meaning that they cannot be left blank when the form is submitted. The small, encircled "i" icons indicate that pop-up help is available for the associated field, which can be seen by hovering over the icon with your mouse. Later in this tutorial we will see how easy it is to add this type of help to your applications. Once the record is submitted the root context will reflect the new application as shown below.

Click on the pm2 application link to enter that application's development area. A little later in the tutorial we will revisit the root context page to see how to start and stop applications, and view session and log information.

Defining the Company Entity

The first thing we will do is create an entity that represents the company that owns the projects that the project manager application will manage. Later we will define other entities such as departments and employees that work on and sponsor the projects we will keep track of. The following screenshot shows the primary development page for our new project management application.

If the Data Source is Not Valid

Notice that the data source name on the right side of the page contains the value jdbc/jVantageDS_oops followed with the words not bound. Although the data source was correctly entered on the application creation form, we purposely changed its value for this tutorial to demonstrate how jVantage behaves when it is unable to contact the underlying database for a given application. If you see the not bound error, it means the jVantage is not able to contact the underlying database that is indicated in the named data source. This can happen because the database itself is down, networks problems have occurred and connectivity to the database has been lost, or the data source descriptor itself is incorrect. In any case, jVantage will not allow further development on the application until connectivity has been restored. Notice the menu on the upper left, which says Show Tables. There is no option to create a new table because of the data source problem.

To correct a data source, click on the modify application option from the menu at the bottom of the screen. This menu is called the definitions menu because it provides access to the create, read, update, and delete (CRUD) functionality appropriate for the entity currently being displayed. In this case we are looking at an application entity, when we clicked on modify this application we are given the option of correcting this error. Notice that many additional fields are shown on the modify page of the application definition record than were shown when we first added the record. Remember, the jVantage development environment is also a jVantage application. To get this functionality, these fields were defined as visible on modify and invisible on add, we will visit these modifiers later in the tutorial.

After correcting the error and returning to the application page by submitting the form, we can see that the not bound error is no longer displayed and we now have the option of creating a new table.

Another thing that is worth pointing out is the default value of the Home URL, the Logout URL, Acess Denied URL and Application Stopped URL fields. Since no entities have been defined for the application as yet, none of these URLs that specify the entry and exit points of the application have valid values. Until at least one entity is created, jVantage inserts default values as placeholders into the fields until actual locations can be specified. In a little while, when we create the company entity, jVantage will I dramatically populate these fields with URLs that use that entity as the entry point into the application. All of these fields can be changed at a later time.

Creating a Table

The first thing we'll do in creating a company entity is define the company table. The application state (data) for all jVantage entities is stored in a relational database. jVantage does not support object databases. When defining an entity, the fields that makeup the entity state are first specified. It is important to note that the reason we refer to our application objects as entities rather than just tables is because the tables are only used for storing application state; many additional behaviors can and will be associated with these entities elsewhere in the jVantage development environment. This combination of state and behavior is what constitutes a jVantage entity, just like it does in applications built using other technologies.

Here is a brief overview of the fields on this forum:

Table Name 

Specifies the name that the table will have in the underlying database itself. Therefore, the table must be named according to the conventions enforced by the database. Most databases do not allow spaces or special characters in their table names. The default dictionary type used to validate the table name is called tableName. It enforces a set of rules that are applicable to most relational databases via regular expressions. This dictionary type can be modified to suit your needs if necessary.

Entity Name 

The name that will be used to identify the entity in generated code. although it is not necessary, jVantage supports the ability to generate XML files, JavaBeans and other Java artifacts that leverage the entity name. Usually, the Entity Name will be the same as the Singular Element Name, but not always.

Description 

This is a brief description of the entity. Again, although we are specifying details about the table, we are also specifying information about the entity itself. In fact, most of the information on this form is relevant to the company as an entity rather than just a database table. As with the application description, this description is also used in the generation of online help so it is important to provide brief but meaningful information.

Singular and Plural Element Names 

jVantage provides contextual information about the entities each application contains by leveraging that information provided during the development process through forms like this one. The singular and plural element names tell jVantage how to intelligently refer to the data in the application. For instance, jVantage will use the singular and plural element names to create menu options such as Show all Companies or Modify this Company.

Secure with SSL 

If any of the information associated with an entity is sensitive and should therefore be encrypted before being transmitted over a network, this checkbook should be checked. jVantage takes a somewhat unique approach to handling SSL in that when an entity is marked as SSL, jVantage automatically watches for transmission of any data associated with the entity and reverts to SSL automatically. tThis is true even on pages where data from the entity is displayed with data from other entities that may not be sensitive, such as on what we call it the normalized view. A denormalized view, is a page in an application that contains data from more than one entity.

Database Singleton 

When a table is marked as a database singleton, jVantage ensures that only one instance of that entity can be created within the application. This designation as a database singleton also subtly impacts the handling and behavior of the entity and the application. For instance, when dealing with an entity of any type within an application, jVantage typically provides options for allowing that entity to be modified, or to create new entities and delete them. Entities that have been specified as database singletons cannot be created or deleted, instead, they are automatically created by jVantage and can only be modified from that point forward. Of course, these behaviors can be further influenced through the use of access control.

Company Table

After submitting the form jVantage automatically adds the table to the table list of the application view as shown below.

jVantage has also created a table that corresponds to the entity in the underlying database. You can view the database meta information by clicking on the table in the list and selecting Actions | Database Meta Data from the relationship menu. In fact, you can also create unique indexes for the table to optimize its performance from within jVantage using the database metadata feature. We will do this later in the tutorial for another entity type.

Futhermore, notice that the URL fields have been updated automatically to reflect the addition of the company entity. This only happens once. As new entities are added to the application, the fields remain unchanged unless modified directly by a developer.

Summary

In this section we created an application table called PM2_COMPANY for an online Project Management application by defining a table definition entry. jVantage used the information we entered to create a table in the underlying database where all data related to the entity will be stored and managed.

In the next section we will further define the Company entity by adding meaningful attributes such as a name, description, and even a photo of our building. We will then immediately go into the application and begin using it to populate the company information before adding more application functionality.

Project Management Tutorial - Adding Entity Attributes