Embedded GlassFish Web Plugin: Usage
Running your web application
The run and start goals for the Embedded GlassFish Web Plugin are configured to execute the test-compile phase. This ensures that for whatever configuration you use, with or without the test classpath, you can build and run your application by using this simple command:
mvn glassfish:run
Basic configuration
Since the Embedded GlassFish Web Plugin is available in Maven Central, configuring it is as simple as this:
<project>
...
<build>
<plugins>
<plugin>
<groupId>net.sf.opk</groupId>
<artifactId>embedded-glassfish-web-plugin</artifactId>
<version>2.1</version>
<configuration>
<!-- Here you can (for example) define JNDI resources for your application. -->
</configuration>
</plugin>
</plugins>
</build>
...
</project>
This minimal configuration starts your artifact, and any war dependencies, in an embedded GlassFish instance.
Integration testing
The start and stop goals are not executed when the plugin is defined, but they are tied to the build phases for the integration test. So to run the application in an embedded GlassFish during integration tests, you can configure the plugin like this:
<project>
...
<build>
<plugins>
<plugin>
<groupId>net.sf.opk</groupId>
<artifactId>embedded-glassfish-web-plugin</artifactId>
<version>2.1</version>
<executions>
<execution>
<id>start-integration-tests</id>
<goals>
<goal>start</goal>
</goals>
<configuration>
<!-- Here you can use a different configuration if needed. -->
</configuration>
</execution>
<execution>
<id>stop-integration-tests</id>
<goals>
<goal>stop</goal>
</goals>
</execution>
</executions>
</plugin>
</plugins>
</build>
...
</project>
Using an external DataSource
It is common in enterprise environments that developers are not allowed access to production passwords. In such cases, any DataSouce that the application uses must be defined outside the application. The Embedded GlassFish Web Plugin supports this use case. The following example defines a DataSource to an in-memory HsqlDB:
<project>
...
<build>
<plugins>
<plugin>
<groupId>net.sf.opk</groupId>
<artifactId>embedded-glassfish-web-plugin</artifactId>
<version>2.1</version>
<configuration>
<glassFishResources>/home/oscar/projects/net.sf.opk/embedded-glassfish-web-plugin/target/checkout/src/main/config/resources.xml</glassFishResources>
</configuration>
<dependencies>
<dependency>
<groupId>org.hsqldb</groupId>
<artifactId>hsqldb</artifactId>
<version>2.3.0</version>
</dependency>
</dependencies>
</plugin>
</plugins>
</build>
...
</project>
Actually, the pom.xml fragment above just defines where the DataSource and any other resources are defined. The actual definition is in the file resources.xml:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE resources PUBLIC "-//GlassFish.org//DTD GlassFish Application Server 3.1 Resource Definitions//EN"
"http://glassfish.org/dtds/glassfish-resources_1_5.dtd">
<resources>
<jdbc-connection-pool name="HsqlConnectionPool" datasource-classname="org.hsqldb.jdbc.JDBCDataSource"
non-transactional-connections="true"
steady-pool-size="3" max-pool-size="10" idle-timeout-in-seconds="300"
connection-leak-reclaim="true" connection-leak-timeout-in-seconds="60"
statement-leak-reclaim="true" statement-leak-timeout-in-seconds="60"
connection-validation-method="meta-data" is-connection-validation-required="true">
<property name="Url" value="jdbc:hsqldb:mem:TestDB"/>
<property name="User" value="sa"/>
<property name="Password" value=""/>
</jdbc-connection-pool>
<jdbc-resource pool-name="HsqlConnectionPool" jndi-name="jdbc/hsqlDataSource"/>
</resources>
Authentication
To secure your web application, you'll want to configure authentication. You can do that like so:
<project>
...
<build>
<plugins>
<plugin>
<groupId>net.sf.opk</groupId>
<artifactId>embedded-glassfish-web-plugin</artifactId>
<version>2.1</version>
<configuration>
<fileRealms>
<fileRealm>
<realmName>myAppRealm</realmName>
<users>
<user>
<username>testUser</username>
<password>secret</password>
<roles>
<role>role1</role>
<role>role2</role>
</roles>
</user>
</users>
</fileRealm>
</fileRealms>
</configuration>
</plugin>
</plugins>
</build>
...
</project>
The configuration above defines a realm with one user. The user has two roles (actually groups in GlassFish terms, but by default each group is a JavaEE role). You can use this realm using the snippet below in your web.xml. The only important part is the realm-name tag.
<login-config>
<auth-method>BASIC</auth-method>
<realm-name>myAppRealm</realm-name>
</login-config>
Extra configuration using asadmin
Sometimes, you wish you could issue specific configuration commands. This is also possible, as demonstrated by the example below. This particular example enables Comet support, but you can issue any asadmin command. In fact, the resource and authentication configurations above are also implemented using this mechanism.
<project>
...
<build>
<plugins>
<plugin>
<groupId>net.sf.opk</groupId>
<artifactId>embedded-glassfish-web-plugin</artifactId>
<version>2.1</version>
<configuration>
<extraCommands>
<extraCommand>
<command>set</command>
<parameters>
<parameter>server-config.network-config.protocols.protocol.http-1.http.comet-support-enabled="true"</parameter>
</parameters>
</extraCommand>
<extraCommand>
<command>list</command>
<parameters>
<parameter>*</parameter>
</parameters>
</extraCommand>
</extraCommands>
</configuration>
</plugin>
</plugins>
</build>
...
</project>
Using the full JavaEE API
If the JavaEE Web Profile is not sufficient, i.e. you need the full JavaEE API, you can also do this. The following pom.xml fragment substitutes the embedded GlassFish instance with the one providing the full JavaEE API:
<project>
...
<build>
<plugins>
<plugin>
<groupId>net.sf.opk</groupId>
<artifactId>embedded-glassfish-web-plugin</artifactId>
<version>2.1</version>
<dependencies>
<dependency>
<groupId>net.sf.opk</groupId>
<artifactId>embedded-glassfish-web-plugin</artifactId>
<version>2.1</version>
<exclusions>
<exclusion>
<!-- Here we exclude default: GlassFish 4.0 with the JavaEE 7 Web Profile -->
<groupId>org.glassfish.main.extras</groupId>
<artifactId>glassfish-embedded-web</artifactId>
</exclusion>
</exclusions>
</dependency>
<!-- Use this for GlassFish 4.02 with the JavaEE 7 Full Profile
<dependency>
<groupId>org.glassfish.main.extras</groupId>
<artifactId>glassfish-embedded-all</artifactId>
<version>4.0</version>
</dependency>
<!-- Use this for GlassFish 3.1.2.2 with the JavaEE 6 Full Profile
<dependency>
<groupId>org.glassfish.main.extras</groupId>
<artifactId>glassfish-embedded-all</artifactId>
<version>3.1.2.2</version>
</dependency>
-->
<!-- Use this for GlassFish 3.1.2.2 with the JavaEE 6 Web Profile
<dependency>
<groupId>org.glassfish.main.extras</groupId>
<artifactId>glassfish-embedded-web</artifactId>
<version>3.1.2.2</version>
</dependency>
-->
</dependencies>
</plugin>
</plugins>
</build>
...
</project>
As an added bonus, any ear dependencies of your artifact are also deployed when starting the embedded GlassFish instance.