Page Edited : GMOxDOC21 : Sample Applications

Sample Applications has been edited by Donald Woods (Oct 20, 2008).

Change summary:

reorg flow

Content:

Availabl= e Sample Applications

app-per-port - Running multiple web apps on d= ifferent ports
bank - EJB = sample application
calculator - Using EJB 3.0 Functions
customer - Si= mple ejb application with a JPA entity
dbtester - DB Pool Testing sam= ple application
inventory - Simple Database Access Application<= /li>
jaxws-calculator - Simple Web Service with JAX-WS
jms-mdb - JMS and M= DB Sample Application
ldap-sample-app - LDAP Sample Application
<= a href=3D"/confluence/display/GMOxDOC21/myphonebook+-+Very+Simple+Entity+EJ= B+Example" title=3D"myphonebook - Very Simple Entity EJB Example">myphonebo= ok - Very Simple Entity EJB Example
mytime - Very Simple Session EJB Example
not-in-svn - Inbound J= CA example
sendmail - Using Geronimo's Default JavaMa= il Session
timereport - Web Application Security Sample

Installi= ng as Prebuilt Plugins

The recommended practice for Geronimo is to set up a workflow using gero= nimo plugins and maven from development through test and production. To de= monstrate this, the samples are built into plugins suitable for the jetty a= nd 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 roll= er 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 install= ed, such as the geronimo-jetty-minimal or geronimo-jetty6-javaee5 servers (= or the equivalent tomcat variations).

In= stalling through the admin console.

If you are using one of the javaee5 server assemblies you can use the ad= min 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 dependencie= s such as the sample-datasource plugin will be installed automatically. Th= ere are equivalent command line functions (described next under Installing = through gshell) if you are using one of the minimal assemblies that does no= t include the admin console.

Installing t= hrough gshell

For this you can use any geronimo server such as one of the minimal asse= mblies or even the framework assembly. After starting geronimo, run ./bin/= gsh deploy/list-plugins in another terminal window and follow the instructi= ons. Installing a sample plugin will install the sample-datasource plugin a= nd all other dependencies. Alternatively if you build using

mvn clean install -Pit

you can find a server with the sample installed in directories such as <= /p>

<sample>/<sample>-jetty/target/geronimo-framework-=
<version>/.

-Pit is currently only available in the samples trunk (2.2-SNAPSHOT) and= not branches/2.1 (2.1.3-SNAPSHOT) or tags/samples-parent-2.1.2 (2.1.2)

Building from Sou= rce

Downloading= the Source Code

The first time building samples it is required that you build from the t= op 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.0.9 or later is required for building Geronimo 2.1 samples.

To check out the 2.1.2 samples:

svn co https://svn.apache.org/repos/asf/geronimo/sa=
mples/tags/samples-parent-2.1.2/ gsamples-2.1.2

Alternatively, you could choose to work with the active 2.1 branch of sa= mples. 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 th= ings may be in flux from day to day:
svn co https://svn.apache.org/repos/asf/geronimo/samples/branches/2.1 3D"" gsamples-2.1

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 sa= mples for the highest level version under development = https://svn.apache.org/= repos/asf/geronimo/samples/trunk

Building the Samp= les

Build using

mvn clean install

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 sh= ort directory (14 characters or less).

There are minimal integration tests to assure that the sample plugins ca= n be installed on the framework server. To run this tests use

mvn clean install -Pit

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

<sample>/<sample>-jetty/target/resources/META-INF/=
plan.xml

(or the equivalent -tomcat directory). For most samples you will need t= o install the sample-datasource plugin first. Samples can be deployed from= the admin console "deploy new" on a suitable server or using gshell ./bin/= gsh deploy/deploy. Note that in this case you need to start with a server = with all the required bits already installed, not the framework server. Si= nce this installation method is not tested automatically it is more likely = to be broken than the plugin method.

Maki= ng life even harder for yourself

You can also install the sample datasource as a javaee artifact using th= e plan we generate when building the plugin, install the sample datasource = using the admin console using the database wizard, and run the sql by hand = rather than relying on the geronimo DBInitializationGBean.

Installing the sample datasource as a javaee 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-embe= d-xa-1.4.rar with the plan at sample-datasource/target/resources/META-INF/p= lan.xml using the admin console "deploy new" or gshell. This will have ex= actly 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, selecti= ng the derby-embed-xa type and naming the database "SampleDatabase" and the= datasource "SampleTxDatasource". The admin console will come up with a mo= dule Id different from what the samples need, so you have to map them in va= r/config/artifact_aliases.properties. Insert a line like this:

org.apache.geronimo.samples/sample-datasource/2.1.2=
/car=3Dconsole.dbpool/SampleDatabase/1.0/car

replacing 2.2-SNAPSHOT with the appropriate sample version and adjusting= the right hand side as necessary. Be sure geronimo is stopped when you ed= it artifact_aliases.properties.

Man= ually initializing the database.

Samples that need database connectivity have the database initialized by= default by using a DBInitializationGBean to run an sql script. Alternative= ly 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. =09
Deploy and run the application using the modified plan.

Maven Generated Site for viewing javadoc or source xref

There is a maven generated site for samples which can be used to view ja= vadoc and source. It can be found here:

G= eronimo Samples 2.1.2

To navigate to javadoc and source code (xref) for each sample do the fol= lowing:

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 interes= ted in viewing the servlets associated with the bank sample you would choos= e the following modules: =09
1. under Modules select "Geronimo Samples :: bank"
2. under Modules select "Geronimo Samples :: bank :: WAR"
=09
once you are at a module that contains source you can then select "P= roject Reports" and from the information provided choose either JavaDocs or= Source Xref