PhotoXChange is a standard J2EE web application. Configuration settings are required for both the web application itself, and for the application server.

Web application configuration

To configure the web application, the following configuration settings must be done:

Where Parameter Name Meaning Default value
WEB-INF/classes/ org.wamblee.photos.properties org.wamblee.photos.path Full path name of the directory where photos are stored. This directory must be created beforehand. A path that works on some developer's system but most likely not on yours.
org.wamblee.photos.realm The security domain used. This must match with the JNDI name specified in WEB-INF/jboss-web.xml and it must also correspond with a security domain configured in the application server. PhotoXChange
org.wamblee.photos.security.userprincipal The classname of the principal class representing the user. org.jboss.security.SimplePrincipal
org.wamblee.photos.admingroup The name of the administrator group. administrators

Database Setup

The only currently supported database is MySQL.

MySQL Setup

The aim of the MySQL setup is to setup a database with the following properties:

  • The InnoDB storage engine is used
  • Transaction isolation level is repeatable read
  • A single user is created with all rights
Selecting the storage engine

First of all, MySQL must be configured to use the InnoDB storage engine for the photos database. This can be done in two ways:

  • Configuration setting; Edit the my.cnf configuration file (usually located in /etc on *nix systems and add the following lines to the [mysqld] section:
    default-table-type = INNODB 

    After this, restart mysql.

  • After creating the database tables: For every database table execute the command
    alter table TABLE_NAME engine = INNODB
    to change the storage engine for that table to INNODB.
Create the database

Now create a MySQL database

 mysqladmin -u root -p create photoxchange 

Where root is the user name of the administrator and photoxchange is the name of the database.

Create a user on the database by logging in as administrator

 mysql -u root -p photoxchange 

and creating a user that has access to the database

 grant all on * to username identified by 'password'; 

This creates a user that can access the database from the same host the database is running on. If MySQL is running on a different machine than the application server, consult the MySQL manuals for information on how to configure access for that user.


After creating the database check the transaction settings by logging on to the photoxchange database as administrator and executing the command

 show variables 

The value of the tx_isolation variable should be REPEATABLE-READ. If this not the case, set the transaction level globally for all databases by specifying

 transaction-isolation = REPEATABLE-READ 

In the [mysqld] section of the my.cnf file. It is also possible to set the transaction isolation level for one database only using


See the MySQL manuals for more details.

Creating the database schema

Populate the database by executing the sql scripts provided with the delivery on the database. On *nix systems:

 mysql -u username -p photoxchange < setup.sql 

After this, execute the command show table status; to check that the tables indeed use the InnoDB storage engine.

Populating the database

The photos application will perform the following initializations automatically at startup.

Initialization performed When?
Initialization of users with one user 'erik' and one administrator 'admin', both having password 'abc123'. When no users have been defined.
Initialization of authorization rules. When no authorization rules exist.

Application Server Setup

For each supported application server, a separate section is provided.

JBoss 4

For JBoss, configuration amounts to configuring the datasource and the security domain, The name of the security domain must match that specified in configuration settings.

Datasource Setup

First of all, the database driver for MySQL must be installed by copying the driver jar mysql-connector-java-3.x.y-bin.jar from the MySQL web site to the server/default/lib directory of JBoss.

Next, the datasource must be configured by copying a photos-ds.xml file to the server/default/deploy directory of the application server and choosing the correct username and password.

Security Setup

To configure security, add the following security domain configuration to login-config.xml in the server/default/conf directory of the server:

            <application-policy name="PhotoXChange">
                <login-module code="org.jboss.security.auth.spi.DatabaseServerLoginModule" flag="required">
                  <module-option name="unauthenticatedIdentity">guest</module-option>
                  <module-option name="dsJndiName">java:/PhotoXChange</module-option>
                  <module-option name="principalsQuery">
                  <module-option name="rolesQuery">
                    select g.name, 'Roles' from USERS u, USER_GROUPS ug, GROUPS g 
                    where u.id = ug.user_id and ug.group_id = g.id and u.name = ?
                  <module-option name="hashAlgorithm">MD5</module-option>
                  <module-option name="hashEncoding">hex</module-option>

Note the module option dsJndiName which refers to the previously configured datasource. Also, note the module options hashEncoding and hashAlgorithm which specify that passwords should be stored as a base 16 MD5 hash.

Glassfish 2


Since most applications and 3rd party products require log4j and glassfish by default does not have this, log4j support must be added as follows:

  • Create a directory lib/log onder glassfish and put the log4j jar and log4j.properties file there.
  • Add the fully qualified path to the log4j.jar into the classpath of Glassfish together with the directory that contains the log4j.properties file. You can do that in the web UI: Application Server/JVM Settings/Paths and the entries are separated by a return. Use the system path.
  • Restart glassfish.
Datasource setup

First of all, the database driver for MySQL must be installed by copying the driver jar mysql-connector-java-3.x.y-bin.jar from the MySQL web site to the server/default/lib directory of JBoss. Next, the datasource must be configured by configuring a connection pool and a JDBC resource with JNDI name identical to the previously configured datasource. The connection pool must be configured with the following properties:

  • user: The database user name.
  • password: The database password.
  • URL: For instance jdbc:mysql://localhost:3306/photoxchange is photoxchange is the name of the database.

Configuration of the JDBC resource is straightforward.

Security setup

To setup security, FlexibleJdbcRealm is required. This requires several steps:

  • Copy the FlexibleJdbcRealm to the glassfish lib directory and restart glassfish.
  • Edit config/login.conf of the glassfish domain to add mapping of the realm to the flexible JdbcRealm login module:
     PhotoXChangeRealm {
                    org.wamblee.glassfish.auth.FlexibleJdbcLoginModule required; }; 
    Here, PhotoXChangeRealm is the name of the configured securty realm.
  • In glassfish administration console in security, select default principal to role mapping to make sure that roles and groups are identical.
  • Configure the security realm with the following properties
    sql.groupsSELECT g.name FROM USERS u, USER_GROUPS ug, GROUPS g WHERE u.id = ug.user_id and ug.group_id = g.id AND u.name = ?
    datasource.jndiDatasource JNDI name configured before, e.g. jdbc/PhotoXChange

Managing users and groups

This release of PhotoXChange provides a rudimentary user interface for managing users and groups. This interface can be accessed by logging in as administrator and clicking on 'Administration'.

Alternatively, users and groups may be modified using direct SQL. The table below shows some common scenarios

Scenario Howto
Changing a password update USERS set password = md5('password') where user = 'username'. The MD5 encoded password can also be generated using openssl: echo -n PASSWORD | openssl dgst -md5 -hex
Adding a user Add a new row to the USERS table and add a new row to the USER_GROUPS table to add the user to a group.
Adding a group Add a new row to the GROUPS table.
Adding a user to a group Add an entry to the USER_GROUPS table