USING JUMPSTART IN GLASSFISH 3.1.2

WARNING Use GlassFish 3.1.2, not 3.1.2.2, because the latter seems to have introduced a class-loader issue - it throws "java.lang.ClassNotFoundException: javax.persistence.spi.PersistenceProvider".
If you find a solution please please send it here.

These notes apply to GlassFish 3.1.2. They were tested with GlassFish 3.1.2 and JumpStart 6.4.0.

Contents
Prepare GlassFish
Build and deploy JumpStart
Build and deploy and integration test JumpStart
Use JumpStart
How to run integration tests from Eclipse
How to debug the client side
How to debug the server side

Prepare GlassFish
These instructions prepare GlassFish with the following elements:

Web Server	Business Server	Persistence	Database Server	Logger
Tomcat	GlassFish's EJB3	Hibernate	Derby	Log4j
(GlassFish's default)	(GlassFish's default)	(Added by us. We could use GlassFish's embedded TopLink except that JumpStart has a small dependency on Hibernate)	(GlassFish's default)	(Added by us)

• Start by doing a normal working GlassFish 3.1.2 installation:
  • To get it, go to GlassFish Downloads, locate GlassFish Server Open Source Edition 3.1.2 and choose the Download link.
  • Locate the Full Platform distribution for your operating system (eg. glassfish-3.1.2-unix.sh) and download it.
  • Move it to a suitable location (eg. /devel/).
  • At the bottom of the Download page there is a link to the Installation Guide. Click on it and follow the guide's instructions.
  • See if the Admin Console is running by trying http://localhost:4848. If the web page is found then it is running.
  • If it is NOT running, do this: at the bottom of the Download page there is a link to the Quick Start Guide. Click on it and follow the guide's instructions until the Admin Console is running.
  • Log in with the username and password you chose during installation.
  • Log out.
  • Stop glassfish from the command line with asadmin stop-domain domain1 .


• Ensure GlassFish will use Java 1.6:
  • Open the glassfish/config/asenv.conf file and modify the property AS_JAVA to use Java 1.6.


• Start Derby and GlassFish, eg. from the command line like this:
  
  • asadmin start-database
  • asadmin start-domain domain1
  • Go to the Admin Console web page, eg. http://localhost:4848/. Log in.


• Add Hibernate:
  • In Eclipse, open the project's data_util.properties file and modify the property add.hibernate.to.dir eg. to /devel/glassfish-3.1.2/glassfish/domains/domain1/lib/
  • Drag data_util.xml to the Ant view and run its target add-hibernate-to-a-server.
  • Check glassfish's lib (eg. /devel/glassfish-3.1.2/glassfish/domains/domain1/lib/) now has the Hibernate jars, (eg. hibernate-core-4.*.jar).


• Add log4j configuration:
  • From business/src/main/resources/conf-log4j-server-side/ copy log4j.properties to the server's config, eg. glassfish/domains/domain1/config/ .
  • In the Admin Console, choose Configurations > server-config > JVM Settings > JVM Options .
  • Add -Dlog4j.configuration=file:///${com.sun.aas.instanceRoot}/config/log4j.properties .
  • Click Save.


• Add the data source jdbc/JumpStartDS:
  • In the Admin Console, choose Resources > JDBC > JDBC Resources
  • Add new resource jdbc/JumpStartDS using the Derby Pool.
    The name of this resource is crucial - it is referred to by name in JumpStart's persistence.xml as the jta-data-source. Incidentally, the build will source persistence.xml from business/src/main/resources/persistence-descriptor/glassfish-hibernate-derby-persistence.xml.


• Set VM arguments (also known as options):
  
  • In the Admin Console, choose Configurations > server-config > JVM Settings > JVM Options.
  • Add options. Here are some to consider. They are explained further here: tapestry, uploading files, hibernate, 64-bit. This may be useful too: JVM options.

    -Dtapestry.production-mode=false	Tells the Tapestry ExceptionReport page to display full details of the exception, which is great during development. When set to true (which is the default since T5.0.10), Tapestry's ExceptionReport page will display an abbreviated report so as to avoid disclosing details of your application's internals.
    -Dtapestry.compress-whitespace=false	Tells Tapestry not to compress whitespace as it generates a page from a template. Makes the generated page source much easier to read eg. when you tell your browser to display the page source.
    -Dtapestry.application-version=xxxx	RECOMMENDED FOR A PRODUCTION ENVIRONMENT. It is explained here.
    -Dtapestry.hmac-passphrase=xxxx	ESSENTIAL FOR A PRODUCTION ENVIRONMENT. It is explained here.
    -Dupload.filesize-max=8000000	ESSENTIAL for JumpStart. Tells Apache Commons Upload to limit the size, in bytes, of upload files.
    -Djumpstart.upload-path=/tmp	ESSENTIAL for JumpStart. Tells JumpStart where to save uploaded files.
    -Dhibernate.hbm2ddl.auto=update	ESSENTIAL for JumpStart initially. Great during development, but NOT RECOMMENDED IN A PRODUCTION ENVIRONMENT because data can be lost. Tells Hibernate to automatically bring the database structure into line with the app's entity definitions at every restart. A better value for production is validate.
    -server	Chooses the "server" JVM (which is optimised for speed). If you add -server, remove -client if it is present.
    -D64	Indicates you're running Java 1.6 in 64-bit mode (eg. in OS X on an Intel Core 2 Duo).



• Restart GlassFish, eg. from the command line like this:
  
  • asadmin stop-domain domain1
  • asadmin start-domain domain1


• Set the build properties: in the JumpStart project's build.properties file, edit the value of these properties:
  • deployment.server.type
  • deployment.persistence.descriptor
  • deployment.server.dir

Build and deploy JumpStart

Here we use Ant to clean, compile, unit test, package, deploy to the server, and wait for it to load.
The deployed package is jumpstart.ear.

• In Eclipse, drag build.xml to the Ant view and run its target clean-compile-test-package-deploytoserver-checkactive.
• If you get an error about JAVA_HOME, read this. Use a JDK 1.6 tools.jar.
• If you get an error saying *** The app was not ready after nn seconds, try doubling the value of deployment.wait.for.start in the JumpStart project's build.properties file.

Build and deploy and integration test JumpStart

Here we use Ant to clean, compile, unit test, package, deploy to the server, wait for it to load, and run the business integration test suite.
The deployed package is jumpstart.ear. The tests remotely call the JumpStart business layer services exposed by the server.

• In Eclipse, drag build.xml to the Ant view and run its target clean-compile-test-package-deploytoserver-integrationtest.
• If you get an error about JAVA_HOME, read this. Use a JDK 1.6 tools.jar.

Use JumpStart

Ensure the command line is using Java 1.6: the commands java -version and javac -version must return a variant of 1.6, eg. 1.6.0_13.

If GlassFish is not running, start it (as above).

Before you use JumpStart for the first time in a new server, you need to build it, deploy it, and run an integration test.

Then, while the database (Derby) is running, populate it:

• Open your preferred SQL client (we used SQuirreL SQL Client).
• Find a Derby driver (we pointed to javadb/lib/derbyclient.jar in the GlassFish directory).
• Connect to the database server (jdbc:derby://localhost:1527/sun-appserv-samples;create=true, initial user is APP, password APP).
• Execute the SQL found in business/src/dev/data/initial_data.sql .

Now you can visit JumpStart with your web browser at http://yourserver:8080/jumpstart.

How to run integration tests from Eclipse

First, build and deploy JumpStart as described above.

Second, create a User Library over GlassFish:

• In Eclipse, choose Window > Preferences > Java > Build Path > User Libraries (or in OS X, choose Eclipse > Preferences... > Java > Build Path > User Libraries), and
• Create a new user library called glassfish-3.1.2-client-lib, then
• Add these Glassfish server jars to the new user library:
  • glassfish/lib/gf-client.jar
  • glassfish/domains/domain1/lib/hibernate-commons-annotations-4.*.jar
  • glassfish/domains/domain1/lib/hibernate-core-4.*.jar
  • glassfish/domains/domain1/lib/hibernate-entitymanager-4.*.jar
  • glassfish/domains/domain1/lib/javassist-3.*.jar
  • glassfish/domains/domain1/lib/jboss-logging-3.*.jar
  • glassfish/domains/domain1/lib/jboss-logging-processor-1.*.jar.
  • javadb/lib/derbyclient.jar

Third, run the business integration test suite from Eclipse:

Choose Run > Run Configurations.... The relevant window will appear. Right-click on JUnit and choose New. Set Test Runner to JUnit 4. Set the other variables to values similar to those shown in the screen shot on the right.

Click on the Classpath tab. Remove the (default classpath) entry. Click on User Entries. Add folder business/src/test/conf-remote-glassfish/ . Add folder collapsed/jumpstart.war/WEB-INF/classes/ . Add user library glassfish-3.1.2-client-lib . Add all JARs from these folders: business/src/main/lib-compile/ business/src/main/lib-runtime/ (actually, lib-runtime is empty) business/src/test/lib-test/ Move the two folders to the top. It avoids conflicts.

• Click Run.
• Watch the results in the JUnit View panel. In the Console View you might see lots of exceptions but that's normal. The JUnit View will tell you quickly whether the tests succeeded or not.
• Problems? Eclipse might not be ready for junit - see Could not create task or type of type: junit.

How to debug the client side

To debug, for example, the client side of the integration tests, use Run > Debug Configurations... instead of Run > Run Configurations.... Eclipse will then stop at breakpoints, display variables, enable single-stepping, etc. in the test suite.

How to debug the server side

To debug any part of JumpStart as it runs in the server you'll need to be running GlassFish in debug mode. There are a couple of ways to do it:

• Start GlassFish in debug mode

  We'll use port 8787 in this explanation, but it's OK to use any free port.

  Earlier, we described setting various JVM options. To run GlassFish in debug, include these JVM options:

  -Xdebug -Xrunjdwp:transport=dt_socket,address=8787,server=y,suspend=y

  Restart GlassFish, and you will see it pauses at this message:

  Listening for transport dt_socket at address: 8787

  In Eclipse, right-click on your project and choose Debug As > Debug Configurations... and the Debug Configurations window will appear.

  1. Right-click on Remote Java Application and choose New.
  2. Set the Port to 8787.
  3. Enable Allow termination of remote VM.
  4. Click on Debug.

  GlassFish resumes startup, and Eclipse will now stop at breakpoints, display variables, do single-stepping, etc. on any Java in the project.

• Control GlassFish server from Eclipse
  
  There's a GlassFish plug-in for Eclipse but I haven't tried it: http://www.brasee.com/displayPost.htm?postId=42