Creole Example

tutorial.creole

Example content only to show Creole markup in a Github wiki page.

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)

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:

#!bat
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.

#!sql
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:

#!bat
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:

#!xml
    ...
    <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:

#!xml

    ...
    <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):

#!bat
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).

Setup the project in your IDE

Clone the source code repository

#!bat
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.