This topic is organized in the following sections:
Installing as prebuilt plugins
The recommended practice for Geronimo is to set up a workflow using Geronimo plugins and maven from development through test and production. To demonstrate this, the samples are built into plugins suitable for the Jetty and Tomcat Web containers in Geronimo. Many samples require database access. This is encapsulated into a separate plugin (sample-datasource).
TODO: Demonstrate how to swap databases using plugins; see also the roller plugin
In any case, to install samples as plugins you need to build them first.
For installation you need a Geronimo server with a Web container installed, such as the geronimo-jetty-minimal or geronimo-jetty6-javaee5 servers (or the equivalent Tomcat variations).
Installing through the administrative console
If you are using one of the Java EE 5 server assemblies you can use the administrative console to install the plugins. Go to the plugins page, push the Show Plugins button, find the sample(s) you want to install, and click Install. Be sure to select only plugins for the Web container you have installed (e.g. jetty plugins for the Jetty web container). Any necessary dependencies such as the sample-datasource plugin will be installed automatically. There are equivalent command line functions (described next under #Installing through GShell) if you are using one of the minimal assemblies that does not include the administrative console.
Installing through GShell
For this you can use any Geronimo server such as one of the minimal assemblies or even the framework assembly. After starting geronimo, run
deploy/list-plugins in another terminal window and follow the instructions. Installing a sample plugin will install the sample-datasource plugin and all other dependencies. Alternatively if you build using
you can find a server with the sample installed in directories such as
-Pit is currently only available in the samples branches/2.2 (2.2.1-SNAPSHOT) and trunk (3.0-SNAPSHOT), not in branches/2.1 (2.1.3-SNAPSHOT) or tags/samples-parent-2.1.2 (2.1.2)
Building from source
Downloading the source code
The first time building samples it is required that you build from the top level directory. After the initial build, you can do subsequent builds of specific samples as necessary.
You need svn and maven installed on your system.
Maven v 2.2.1 or later is required for building Geronimo 2.2 samples.
To check out the 2.2 samples:
Alternatively, you could choose to work with the active 2.2 branch of samples. This will allow you to work with the latest changes in samples but will also expose you to a branch that is under active development and so things may be in flux from day to day:
svn co https://svn.apache.org/repos/asf/geronimo/samples/branches/2.2 gsamples-2.2
Depending on when you look you may find earlier or released versions of the samples under samples/branches and samples/tags. You can browse in any web browser to see what's there. The trunk for samples always contains samples for the highest level version under development https://svn.apache.org/repos/asf/geronimo/samples/trunk
Building the samples
Build the samples using this command:
If you run into the "Could not scan module for TLD files...Filename too long" problem when using Windows platform, please check out samples to a short directory (14 characters or less).
There are minimal integration tests to assure that the sample plugins can be installed on the framework server. To run this tests use this command:
The integration tests are not available prior to Geronimo Samples 2.2
Deploying the built samples as Java EE artifacts
With the sample datasource installed as a plugin
After building the sample projects you can find suitable geronimo plans for a sample <sample> in
(or the equivalent -tomcat directory). For most samples you will have to install the sample-datasource plugin first. Samples can be deployed from the administrative console "deploy new" on a suitable server or using GShell
deploy/deploy. Note that in this case you have to start with a server with all the required bits already installed, not the framework server. Since this installation method is not tested automatically it is more likely to be broken than the plugin method.
Making life even harder for yourself
You can also install the sample datasource as a javaee artifact using the plan we generate when building the plugin, install the sample datasource using the administrative console using the database wizard, and run the sql by hand rather than relying on the geronimo DBInitializationGBean.
Installing the sample datasource as a Java EE artifact
Before you install any sample applications, deploy the
org.tranql/tranql-connector-derby-embed-xa/1.4/rar connector located in the geronimo repo at
org/tranql/tranql-connector-derby-embed-xa/1.4/tranql-connector-derby-embed-xa-1.4.rar with the plan at
sample-datasource/target/resources/META-INF/plan.xml using the admin console "deploy new" or GShell. This will have exactly the same effect as installing the sample-datasource plugin.
Installing the sample datasource through the admin console database wizard
Create a new datasource using the admin console database wizard, selecting the derby-embed-xa type and naming the database "SampleDatabase" and the datasource "SampleTxDatasource". The admin console will come up with a module Id different from what the samples need, so you have to map them in var/config/artifact_aliases.properties. Insert a line like this:
replacing 2.2 with the appropriate sample version and adjusting the right hand side as necessary. Be sure geronimo is stopped when you edit artifact_aliases.properties.
Manually initializing the database.
Samples that need database connectivity have the database initialized by default by using a DBInitializationGBean to run an sql script. Alternatively here we describe how to initialize the database by hand. In a production scenario most likely your db will be set up by a DBA rather than either of these methods.
- Remove the DBInitializationGBean from the sample plan
- In the console DB Manager page, use the Create DB function to create a database named SampleDatabase.
- In the console DB Manager page select the SampleDatabase in Use DB, paste the script found in the sql file located in the project (ear or war) that builds the top level javaee artifact into the text box, and run it.
- Deploy and run the application using the modified plan.
Maven Generated Site for viewing javadoc or source xref
Geronimo Samples 2.2 release did not generate the maven site for javadoc and source xref view. Cause Geronimo site scheme for 2.2 has some problem.
There is a maven generated site for samples which can be used to view javadoc and source. It can be found here:
To navigate to javadoc and source code (xref) for each sample do the following:
- select "Geronimo Samples :: Samples" under Modules in the left-hand navigation
- select a specific sample from the left-hand navigation under Modules
- to view javadoc or source (xref) you must navigate down to a module that includes source such as a war or ejb. For example, if you are interested in viewing the servlets associated with the bank sample you would choose the following modules:
- under Modules select "Geronimo Samples :: bank"
- under Modules select "Geronimo Samples :: bank :: WAR"
- once you are at a module that contains source you can then select "Project Reports" and from the information provided choose either JavaDocs or Source Xref.