Page History

...

Design for Option #1: Property file based configuration

List and describe new manager methods, Struts actions, JSP pages, macros, etc.

First an overview. We'll implement option #1 by changing Roller so that it's database configuration comes from the Roller properties override file and by adding table auto-creation/upgrade.

Not everbody will want to use auto-create and nobody will want install-logic running in a production system, so Roller will operate in two modes, controlled by the installation.type property. In production systems, 'installation.type' should be set to 'manual' to ensure that we never show an revealing database error page or "would you like to upgrade" tables page in production.

At installation time, users can choose turn on auto-install by setting installation.type=auto. In this mode, Roller will give First an overview. Users are encouraged to use Roller auto-install because auto-install will give them informative error messages when the database setup fails, it will create the Roller tables automatically and it will even upgrade them if they need upgrade. To install Roller with auto-install these are the steps

Users with special needs, i.e. very large sites, upgrading from pre 1.2 Roller, customized data models, can choose not use auto-install. By setting installation.type=manual they can choose to do upgrades the old way, running scripts by hand.

These are the steps to install Roller with auto-install:

STEP 0 - Prerequisites: Java 5, Roller supported database, Servlet 2.4 container and JDBC driver jar in Servlet container's classpath.

...

STEP 2 - Create a roller-custom.properties file in Servlet container's classpath with the auto install option and your database connection parameters. For example:

installation.type=auto

...

database.configurationType=jdbc

...

database.jdbc.driverClass=com.mysql.jdbc.Driver

...

database.jdbc.connectionURL=jdbc:mysql://localhost:3306/rollertest

...

database.jdbc.username=scott

...

database.jdbc.password=tiger

...

STEP 3 - Deploy roller.war to your Servlet container and browse to context URI. If there is a database connection error, you'll see details in the browser. If tables need creation or upgrade, Roller will do it automatically for you on your commant.

Users with special needs (i.e. very large sites, upgrading from pre 1.2 Roller, customized data models) can choose not use auto-install – they should do upgrades the old way, running scripts by hand.

command.

Here are the specific changes to be made to enable property based installation/configuration:

Change #1: New properties -

...

COMMITTED

database.installation = (auto|manual): if auto, Roller will prompt to create/upgrade tables

...

mail.connectionType = (jndi|properties) - choose either JNDI or properties for mail session
mail.jndiName - JNDI name to be used for mail-session if type is 'jndi'
mail.hostname: Host name of mail server to be used if type is 'properties'
mail.username: Username for mail server to be used if type is 'properties'
mail.password: Password for mail server to be used if type is 'properties'

Change #2: Change implementations of the Roller interface -

...

COMMITTED

When creating persistence strategy, we rely on a DatabaseProvider class with this logic:

• If JDBC connection properties present, use them
• Else use JNDI data-source

Change #3: Change mail sending code - COMMITTED

When creating mail-session - DONE

• Create new MailProvider class to get mail-session, provider will use this logic:
  • If mail-host property is present, use it
  • Else use JNDI mail-session

Change #4: Change RollerContext initialization -

...

COMMITTED

• Change contextInitialized() so that it initializes only the UI portions of Roller
  • Move RollerImpl initialization into RollerImpl classes
• Change contextInitialized() so that it does not throw exceptions
  • We want context to load regardless of Roller configuration

Change #5: Change PersistenceSessionFilter to check database configuration - READY TO COMMIT

This logic is executed ONLY if auto-install is enabled.

• If DB connection fails
  • If installation.auto, show error page to explain what went wrong and how to fix it
  • Else, show simple error/maintenance page
• If DB does not have tables
  • If installation.auto, show table creation page/action
  • Else, show simple error/maintenance page
• If DB is older version
  • If installation.auto, show database upgrade page/action
  • Run database upgrade scripts and do upgradeDatabaseIfNeeded logic
  • Else, show simple error/maintenance page
• forward to DatabaseError action
• Else if Roller tables not found direct to CreateDatabase action
• Else if Roller tables need upgrade direct to UpgradeDatabase action

Change #6: Database creation/upgrade

...

infrastructure - READY TO COMMIT

• SQLScriptRunner: runs SQL scripts, saves messages
• DatabaseCreator: creates Roller database tables, saves messages
• DatabaseUpgrader: upgrades Roller database tables, saves messages

Change #7: Database error page/action - READY TO COMMIT

• DatabaseError.jsp
• DatabaseError.java

...

If connection cannot be made for some reason, this is what you'll see:

Change #8: Table creation page/action - READY TO COMMIT

• CreateDatabase.java
• CreateDatabase.jsp
• Tell user that tables need to be created, offer to create them
• Create tables, show user output from running creation script
• Ask user to redeploy or restart server

...

After tables are created:

Change #9: Table upgrade page/action - READY TO COMMIT

• UpgradeDatabase.java
• UpgradeDatabase.jsp
• Tell user that tables need to be updated, offer to upgrade them
• Upgrade tables, show user output from running upgrade script
• Ask user to redeploy or restart server

...