View source

== Prerequisites ==
Installing on the [https://glassfish.dev.java.net/ 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 [http://db.apache.org/derby/ 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 [http://www.netbeans.org/ 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 [https://glassfish.dev.java.net/ 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 [https://glassfish.dev.java.net/downloads/quickstart/index.html 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 [http://sourceforge.net/project/showfiles.php?group_id=177852 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 ===
<div class="quote">
If you plan to create a new database for jVantage rather than utilize the existing sample Derby database, skip this section and go to [[GlassFish_Installation_Guide#Creating_and_Using_a_New_Database_-_Recommended|Creating and Using a New Database]].
</div>
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.


[[Image:GlassFishConsol_JDBCResourcesBeforeDefiningjVantageDS.gif|center|List of JDBC Resources.]]


Populate the form as follows and click ''OK'':


[[Image:GlassFishConsol_CreateNewJDBCResource.gif|center|Create a JDBC Resource for jVantage.]]


<div class="quote">
'''''Important:''''' You have completed this step, now go directly to the section [[GlassFish_Installation_Guide#Deploying_jVantage|Deploying jVantage]].  The following section provides steps for setting up a new database.
</div>

=== 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.


[[Image:GlassFishConsole_CreateNewConnectionPoolStep01.gif|center|Create a new Connection Pool - Step One.]]


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.


[[Image:GlassFishConsole_CreateNewConnectionPoolStep02.gif|center|Create a new Connection Pool - Step Two.]]

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.

<div class="quote">
'''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.
</div>

==== 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.


[[Image:GlassFishConsol_JDBCResourcesBeforeDefiningjVantageDS.gif|center|List of JDBC Resources.]]


Populate the form as follows and click ''OK''.  Note that the ''Pool Name'' is ''jVantageDerbyPool'', which we just created.


[[Image:GlassFishConsol_CreateNewJDBCResourceForJVantageDatabase.gif|center|Create a JDBC Resource pointing to the new jVantage database.]]

== 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.


[[Image:GlassFishConsole_DeployAppStep01.gif|center|Deploying jVantage - step one.]]


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.


<div class="quote">
'''Note:''' Although it is ''not'' usually required, it is sometimes necessary to restart the application server after initially installing jVantage in order to activate logging.</div>