1. Vineet Reynolds
  2. Java EE 6-Galleria

Wiki

Clone wiki

Java EE 6-Galleria / SettingUpTheApplication

Setting up the Environment

The environment of the application can be broadly classified into several parts - the development, test and the QA/production environments. A developer can setup the application on his local workstation that is different from a central QA or a production environment. The application was of course, not written with high expectations of being a Flickr or a Google Picasa replacement :) so the term "production" should be interpreted as a central environment where the application built by a CI server is hosted.

Assumptions

This assumes that you have the following software:

  • Mercurial
  • the Java SDK (obviously)
  • Maven 3.x (might work with 2.x)
  • Derby 10.5 (might on older versions)
  • GlassFish 3.1.1 (untested on other versions)
  • Jacoco (for code coverage)

Creating the database instances

The application uses Derby, but this can be changed to other databases. For now, we shall examine the setup procedure for the Derby.

Start the Derby ij tool on your local workstation:

java -jar %DERBY_HOME%/lib/derbyrun.jar ij

Connect to the Derby instance using the listed connect string. This will create a Derby instance, if it does not exist.

connect 'jdbc:derby://localhost:1527/GALLERIATEST;create=true';

The above Derby instance would be used for running unit and integration tests in the application.

The application uses dbdeploy as a database change management tool. Incremental updates to the physical database model are stored in dbdeploy scripts, under the src/main/sql directory of the galleria-ejb module. Dbdeploy will detect any undeployed scripts in a database instance, and apply them during relevant phases of the Maven build lifecycle.

If you need a dedicated Derby instance to serve as a development environment where you can extend the application's data model before writing a dbdeploy change script, then you can create another Derby instance and perform your development against that instance.

Create the dbdeploy changelog table, which will enable dbdeploy to track all deployed changes.

CREATE TABLE changelog (
  change_number DECIMAL(22,0) NOT NULL,
  complete_dt TIMESTAMP NOT NULL,
  applied_by VARCHAR(100) NOT NULL,
  description VARCHAR(500) NOT NULL
);

ALTER TABLE changelog ADD CONSTRAINT Pkchangelog PRIMARY KEY (change_number);

If you wish to setup a production environment in your local workstation, create a Derby database called GALLERIA:

connect 'jdbc:derby://localhost:1527/GALLERIA;create=true';

The GlassFish domains

Create a new GlassFish domain:

C:\glassfish3\bin>asadmin create-domain --portbase 10000 --nopassword test-domain

Create a new connection pool and a JNDI datasource in the newly created domain, by modifying the GlassFish domain configuration:

    ...
    <jdbc-connection-pool driver-classname="" datasource-classname="org.apache.derby.jdbc.ClientDataSource40" res-type="javax.sql.DataSource" description="" name="GalleriaPool" ping="true">
      <property name="User" value="APP"></property>
      <property name="DatabaseName" value="GALLERIATEST"></property>
      <property name="RetrieveMessageText" value="true"></property>
      <property name="Password" value="APP"></property>
      <property name="ServerName" value="localhost"></property>
      <property name="Ssl" value="off"></property>
      <property name="SecurityMechanism" value="4"></property>
      <property name="TraceFileAppend" value="false"></property>
      <property name="TraceLevel" value="-1"></property>
      <property name="PortNumber" value="1527"></property>
      <property name="LoginTimeout" value="0"></property>
    </jdbc-connection-pool>
    <jdbc-resource pool-name="GalleriaPool" description="" jndi-name="jdbc/galleriaDS"></jdbc-resource>

  <servers>
    <server name="server" config-ref="server-config">
    ...
    <resource-ref ref="jdbc/galleriaDS"></resource-ref>
    </server>
  </servers>

The above domain configuration entries, create a new connection pool that connects to the GALLERIATEST Derby database. It also registers a new JNDI datasource with the previously defined connection pool, at jdbc/galleriaDS.

One must also create a new JDBC Realm in the GlassFish domain, that uses the previously created datasource:

    ...
    <auth-realm classname="com.sun.enterprise.security.auth.realm.jdbc.JDBCRealm" name="GalleriaRealm">
      <property name="jaas-context" value="jdbcRealm"></property>
      <property name="encoding" value="Hex"></property>
      <property name="password-column" value="PASSWORD"></property>
      <property name="datasource-jndi" value="jdbc/galleriaDS"></property>
      <property name="group-table" value="USERS_GROUPS"></property>
      <property name="charset" value="UTF-8"></property>
      <property name="user-table" value="USERS"></property>
      <property name="group-name-column" value="GROUPID"></property>
      <property name="digest-algorithm" value="SHA-512"></property>
      <property name="user-name-column" value="USERID"></property>
    </auth-realm>
    ...

To create another GlassFish domain for the production instance on the same local workstation, run the command (notice the change in the portbase):

C:\glassfish3\bin>asadmin create-domain --portbase 11000 --nopassword production-domain

and make the configuration changes, this time pointing the connection pool to the GALLERIA database. The datasource and JAAS JDBC Realm configuration remains unchanged (especially for the JNDI names).

Update the Maven settings

Adding the JBoss repositories

Configure Maven to use the JBoss public repository, as outlined in this JBoss Community document. Your Maven settings.xml should now contain a profile like the following:

<profile>
    <id>jboss-repos</id>
    <activation>
        <activeByDefault>true</activeByDefault>
    </activation>
    <repositories>
        <repository>
            <id>jboss-public-repository-group</id>
            <name>JBoss Public Maven Repository Group</name>
            <url>https://repository.jboss.org/nexus/content/groups/public-jboss/</url>
            <layout>default</layout>
            <releases>
                <enabled>true</enabled>
                <updatePolicy>never</updatePolicy>
            </releases>
            <snapshots>
                <enabled>true</enabled>
                <updatePolicy>never</updatePolicy>
            </snapshots>
        </repository>
        <repository>
            <id>jboss-releases-repository-group</id>
            <name>JBoss Releases Maven Repository Group</name>
            <url>https://repository.jboss.org/nexus/content/repositories/releases/</url>
            <layout>default</layout>
            <releases>
                <enabled>true</enabled>
                <updatePolicy>never</updatePolicy>
            </releases>
            <snapshots>
                <enabled>false</enabled>
                <updatePolicy>never</updatePolicy>
            </snapshots>
        </repository>
    </repositories>
</profile>

Adding a Sonar profile

Sonar can be used to perform continuous inspection of the project codebase.

The guide will assume that you've installed Sonar. If you haven't done so, you can follow the instructions at the Sonar wiki.

For now, we'll assume that you've installed Sonar, and that you're using MySQL instead of Apache Derby as the Sonar DB. You could modify the settings to suit your own database. Considering the below snippet reproduced from the Sonar wiki page on using Maven, MySQL has been installed on a machine with IP 192.168.1.101 listening on port 3306. A MySQL user Id sonar with sonar as password, has been created. The web application server hosting Sonar is also running at 192.168.1.101 listening on port 9000.

When you run the sonar:sonar goal, these settings from the profile would be used by the Sonar Maven plugin. The jacoco.agent.path property specified in this profile, will be used in a project-specific sonar profile that is specified during the execution of the sonar:sonar goal. To obtain this library download it from the Jacoco site.

<profile>
    <!-- WARNING: Replace values as appropriate to your environment -->
    <id>sonar</id>
    <activation>
        <activeByDefault>true</activeByDefault>
    </activation>
    <properties>
        <!-- EXAMPLE FOR MYSQL -->
        <sonar.jdbc.url>jdbc:mysql://192.168.1.101:3306/sonar?useUnicode=true&amp;characterEncoding=utf8</sonar.jdbc.url>
        <sonar.jdbc.driverClassName>com.mysql.jdbc.Driver</sonar.jdbc.driverClassName>
        <sonar.jdbc.username>sonar</sonar.jdbc.username>
        <sonar.jdbc.password>sonar</sonar.jdbc.password>

        <!-- SERVER ON A REMOTE HOST -->
        <sonar.host.url>http://192.168.1.101:9000</sonar.host.url>

        <!-- Provide the path to the jacoco agent library -->
        <jacoco.agent.path>C:\Apps\jacoco-0.5.4.201107171441\lib\jacocoagent.jar</jacoco.agent.path>
    </properties>
</profile>

Configuring the development profile

The development profile is used for executing the unit and integration tests. Create one as shown below. You may need to use values that are specific to your environment, especially if you've modified the values during creation of the test Derby and GlassFish domains.

This profile contains the necessary properties that are required for a successful build of the application on a local developer workstation.

Following is a description of the properties specified here:

  • galleria.derby.testInstance.jdbcUrl - The JDBC connection string for the test database instance.
  • galleria.derby.testInstance.user - The user Id of the account on the test database instance.
  • galleria.derby.testInstance.password - The password of the account on the test database instance.
  • galleria.glassfish.testDomain.glassfishDirectory - The local of the GlassFish directory, within the GlassFish installation.
  • galleria.glassfish.testDomain.domainName - The name of the GlassFish domain that would be used for testing.
  • galleria.glassfish.testDomain.passwordFile - The password file for the test GlassFish domain.
  • galleria.glassfish.testDomain.adminPort - The administration port of the test GlassFish domain.
  • galleria.glassfish.testDomain.httpPort - The HTTP listener port of the test GlassFish domain.
  • galleria.glassfish.testDomain.httpsPort - The HTTPS listener port of the test GlassFish domain.
<!-- WARNING: Replace values as appropriate to your environment -->
<profile>
    <id>development</id>
    <activation>
        <activeByDefault>true</activeByDefault>
    </activation>
    <properties>
        <galleria.derby.testInstance.jdbcUrl>jdbc:derby://localhost:1527/GALLERIATEST</galleria.derby.testInstance.jdbcUrl>
        <galleria.derby.testInstance.user>APP</galleria.derby.testInstance.user>
        <galleria.derby.testInstance.password>GALLERIA</galleria.derby.testInstance.password>
        <galleria.glassfish.testDomain.user>admin</galleria.glassfish.testDomain.user>
        <galleria.glassfish.testDomain.glassfishDirectory>C:/Apps/glassfish3/glassfish/</galleria.glassfish.testDomain.glassfishDirectory>
        <galleria.glassfish.testDomain.domainName>domain1</galleria.glassfish.testDomain.domainName>
        <galleria.glassfish.testDomain.passwordFile>C:/Apps/glassfish3/glassfish/domains/domain1/config/local-password</galleria.glassfish.testDomain.passwordFile>
        <galleria.glassfish.testDomain.adminPort>10048</galleria.glassfish.testDomain.adminPort>
        <galleria.glassfish.testDomain.httpPort>10080</galleria.glassfish.testDomain.httpPort>
        <galleria.glassfish.testDomain.httpsPort>10081</galleria.glassfish.testDomain.httpsPort>
    </properties>
</profile>

Configuring the production profile

The production profile would be used by the build script, only to deploy changes onto a production instance. On a local developer workstation, this may be used to create a reference environment, that is similar to a production one.

Create the profile as shown below. You may need to use values that are specific to your environment, especially if you've modified the values during creation of the production Derby and GlassFish domains.

Following is a description of the properties specified here:

  • galleria.derby.productionInstance.jdbcUrl - The JDBC connection string for the production database instance.
  • galleria.derby.productionInstance.user - The user Id of the account on the production database instance.
  • galleria.derby.productionInstance.password - The password of the account on the production database instance.
  • galleria.glassfish.productionDomain.glassfishDirectory - The location of the GlassFish directory, within the GlassFish installation.
  • galleria.glassfish.productionDomain.domainName - The name of the GlassFish domain that would be used for running the application.
  • galleria.glassfish.productionDomain.passwordFile - The password file for the production GlassFish domain.
  • galleria.glassfish.productionDomain.adminPort - The administration port of the production GlassFish domain.
  • galleria.glassfish.productionDomain.httpPort - The HTTP listener port of the production GlassFish domain.
  • galleria.glassfish.productionDomain.httpsPort - The HTTPS listener port of the production GlassFish domain.
<!-- WARNING: Replace values as appropriate to your environment -->
<profile>
    <id>production</id>
    <activation>
        <activeByDefault>true</activeByDefault>
    </activation>
    <properties>
        <galleria.derby.productionInstance.jdbcUrl>jdbc:derby://localhost:1527/GALLERIA</galleria.derby.productionInstance.jdbcUrl>
        <galleria.derby.productionInstance.user>APP</galleria.derby.productionInstance.user>
        <galleria.derby.productionInstance.password>GALLERIA</galleria.derby.productionInstance.password>
        <galleria.glassfish.productionDomain.user>admin</galleria.glassfish.productionDomain.user>
        <galleria.glassfish.productionDomain.glassfishDirectory>C:/glassfish3/glassfish/</galleria.glassfish.productionDomain.glassfishDirectory
        <galleria.glassfish.productionDomain.domainName>production-domain</galleria.glassfish.productionDomain.domainName>
        <galleria.glassfish.productionDomain.passwordFile>C:/glassfish3/glassfish/domains/production-domain/config/local-password</galleria.glassfish.productionDomain.passwordFile>
        <galleria.glassfish.productionDomain.adminPort>11048</galleria.glassfish.productionDomain.adminPort>
        <galleria.glassfish.productionDomain.httpPort>11080</galleria.glassfish.productionDomain.httpPort>
        <galleria.glassfish.productionDomain.httpsPort>11081</galleria.glassfish.productionDomain.httpsPort>
    </properties>
</profile>

Setup the project in your IDE

Clone the source code repository

C:\workspaces>hg clone https://bitbucket.org/VineetReynolds/java-ee-6-galleria

Instructions for Eclipse

Import the previously clone Mercurial repository into Eclipse.

One can also clone the repository directly from BitBucket without running the hg clone command.

You may need to configure Eclipse to use the local Maven installation with the above Maven profiles, instead of the embedded Maven installation (provided by the m2e plugin).

Updated