GlassFish Installation Guide
From JVantage
Contents |
Prerequisites
Installing on the GlassFish Application Server is the easiest and most straightforward way to use jVantage in terms of deployment and management for the following reasons:
- GlassFish includes a bundled instance of the Derby Relational Database, which means there is no external database to download and install, and no setup steps are required to integrate the application server with the database, such as installing a database driver or defining external data source descriptor files.
- The GlassFish console is very intuitive and responsive, providing painless and efficient deployments, easy redeployments, and links that take you directly to the applications you install from within the console itself - a feature that is oddly absent from many other application servers.
- GlassFish interoperates exceptionally well with the NetBeans IDE.
Before jVantage can be deployed, an instance of GlassFish must be installed and running on your server. Installation and Quick Start guides are available on the GlassFish project page. A good document for gaining high level familiarity with GlassFish, such as how to start and stop the server and deploy applications, can be found here. When downloading jVantage, be sure that you download a proper version for the GlassFish instance you have. If applicable, this information is provided on the jVantage download page.
Setting up the Database
Although it is not necessary to explicitly install or configure the Derby database, since it is bundled with the application server itself, it is still necessary to specify a data source that jVantage can use to communicate with it. The good news is that doing so requires minimal effort, as you'll see.
First, verify that the database is running on your server. Starting the GlassFish Application Server itself does not necessarily start the Derby database server. To start Derby, use the following command from a command prompt:
> <GlassFish-Install-Directory>/bin/asadmin start-database
Notice that there is already a connection pool for the Derby database called DerbyPool. At this point, there are two choices; you can choose the path of least resistance and configure jVantage to utilize the existing sample database, or you can create a new connection pool and database. Creating a new database is not much more difficult than using the existing one, so if you have time, this is the recommended approach. Both options are shown here.
Path of Least Resistance - Utilizing the Existing Derby Sample Database
If you plan to create a new database for jVantage rather than utilize the existing sample Derby database, skip this section and go to Creating and Using a New Database.
A JDBC Resource is essentially a simple mechanism for telling an application which connection pool to use (they can point to other things too, not just relational database connection pools, but that doesn't concern us here). In our case, we are going to create a new JDBC Resource entry that binds jVantage to the existing DerbyPool.
Here's how: locate and click on JDBC Resources in the console menu (just above Connection Pools). A list of existing JDBC Resources will display on the right, as shown below. Click on the new button.
Populate the form as follows and click OK:
Important: You have completed this step, now go directly to the section Deploying jVantage. The following section provides steps for setting up a new database.
Creating and Using a New Database - Recommended
The first thing we must do is create a Connection Pool that will allow us to connect with the new database. Fortunately, when we define the connection pool, we can create the database itself from within the GlassFish console, making the whole exercise extremely easy.
Create a Connection Pool
We're going to create a connection pool that points to a Derby database, which will run on the same server as the GlassFish itself. To do this, find and click on Connection Pools on the console menu as shown earlier in this document. A list of existing Connection Pools will display to the right. Click on the new button, then populate the form as shown below and click the next button.
On the next page, scroll downwards until you see the Properties section. We'll accept almost all of the defaults on this page, but there are a few values that we must provide, as indicated by the arrows on the image below.
This is what the fields mean:
- User
- The name that will be used by the connection pool to login to the Derby database. Although you may use any name you choose here, it is recommended that you stay with the default (APP) to avoid the need to explicitly create a corresponding schema.
- Password
- Provide a unique password. Although the example above uses the word password, this is generally a bad idea - you should choose something more difficult to guess.
- DatabaseName
- This is the name of the database itself. Derby will create a directory on your server with this name where it will store your application data.
- ConnectionAttributes
- This tells Derby to create the database if it does not exist already. Don't forget the leading semicolon (;create=true).
Submit the form.
Important: To get Derby to actually create the database, select the connection pool you just created from the list on the right by clicking on it. On the following screen, click the Ping button. This will cause the database to be created. You should see a message indicating that the ping was successful.
Create a JDBC Resource
A JDBC Resource is essentially a simple mechanism for telling an application which connection pool to use (they can point to other things too, not just relational database connection pools, but that doesn't concern us here). In our case, we are going to create a new JDBC Resource that binds jVantage to the jVantageDerbyPool we just created. Here's how.
Locate and click on JDBC Resources on the console menu (just above Connection Pools). A list of existing JDBC Resources will display on the right, as shown below. Click on the new button.
Populate the form as follows and click OK. Note that the Pool Name is jVantageDerbyPool, which we just created.
Deploying jVantage
From within the GlassFish console, select Applications > Enterprise Applications from the menu on the left, then click on the Deploy button in the panel to the right of the menu. Finally, click on the Browse button to locate and select the jVantage EAR file.
On the second deployment page; Deploy Enterprise Application (Step 2 of 2), accept the defaults by simply clicking the Finish button.
Running the jVantage Setup Tool
Once jVantage is deployed, you must configure the installation by running the setup tool. For the most part, the setup program that comes with jVantage offers reasonable defaults that allows the entire process to be completed in about three or four minutes. If you have deployed jVantage onto your local machine, at this point the setup program can be accessed at the following URL unless you have changed the default port on your GlassFish Application Server instance.
http://localhost:8080/jvantage/jvantage-setup
If you have installed on a different server, then simply substitute localhost with the name of the server as follows:
http://<hostName>:8080/jvantage/jvantage-setup
Invoke the setup tool and follow the instructions there.
