src/site/apt/how-to/definitions-db.apt - tiles - Git at Google

 ~~ $Id$
 ~~
 ~~ Licensed to the Apache Software Foundation (ASF) under one
 ~~ or more contributor license agreements.  See the NOTICE file
 ~~ distributed with this work for additional information
 ~~ regarding copyright ownership.  The ASF licenses this file
 ~~ to you under the Apache License, Version 2.0 (the
 ~~ "License"); you may not use this file except in compliance
 ~~ with the License.  You may obtain a copy of the License at
 ~~
 ~~ http://www.apache.org/licenses/LICENSE-2.0
 ~~
 ~~ Unless required by applicable law or agreed to in writing,
 ~~ software distributed under the License is distributed on an
 ~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 ~~ KIND, either express or implied.  See the License for the
 ~~ specific language governing permissions and limitations
 ~~ under the License.
 ~~
          -----------
          Loading definitions from a database
          -----------

 Loading definitions from a database

   A typical request from Tiles users was to be able to load Tiles definitions
   from a database. With Tiles 2.1, it is a pretty easy task.

   The source of the example is available in the
   {{{/download-21.html}source distribution of Tiles}}, under the "tiles-test"
   module.

 * Database design

   The first step is to design the database schema. Here we will show a small
   example that is far from perfect, anyway it will be enough for our example.
   The following is the picture of the database schema we will use.

 [../images/db-schema.png] Database schema that will be used for the example.

 * Create a Definition DAO

   Essentially, the main programming task is the development of a
   {{{../apidocs/org/apache/tiles/definition/dao/DefinitionDAO.html}definition DAO}}.
   This interface is designed to provide an easy customization of definitions
   retrieval.

   The method that you should implement is only
   {{{../apidocs/org/apache/tiles/definition/dao/DefinitionDAO.html#getDefinition(java.lang.String,%20K)}getDefinition}}.
   You don't have to implement <<<getDefinitions>>> too completely (a simple
   <<<throw UnsupportedOperationException>>> will be enough) since it won't be
   called at all.

 ** getDefinition

   This is the source of <<<getDefinition>>> in our example: the JDBC DAO support
   of Spring is used to have a cleaner code.

 -------------------------------------
 /** {@inheritDoc} */
 @SuppressWarnings("unchecked")
 public Definition getDefinition(String name, Locale locale) {
     List<Map<String, Object>> customizations = null;
     Long customizationId = null, parentCustomizationId = null;
     do {
         customizations = getJdbcTemplate().queryForList(
                 SELECT_CUSTOMIZATION_BY_NAME_SQL,
                 new Object[] { locale.toString() });
         if (!customizations.isEmpty()) {
             Map<String, Object> customization = customizations.get(0);
             customizationId = ((Number) customization.get("ID")).longValue();
             parentCustomizationId = numberToLong((Number) customization.get("PARENT_ID"));
         } else {
             locale = LocaleUtil.getParentLocale(locale);
         }
     } while (customizations.isEmpty());

     return getDefinition(name, customizationId, parentCustomizationId,
             locale);
 }
 -------------------------------------

   In other words:

   [[1]] the current customization (in this case, the client's locale) is
   identified;

   [[2]] it is tried to retrieve the locale from the DB: if it is not found, it
   tries with the parent locale (the parent locale of "en_US" is "en") until one
   is found, or the default (no locale) is used;

   [[3]] the definition for the supported minimum-parent-locale is retrieved and
   passed to the caller.

 ** Retrieval of the definition from the DB

   At this point the definition must be retrieved from the DB.

 -------------------------------------
 @SuppressWarnings("unchecked")
 protected DbDefinition getDefinition(String name, Long baseCustomizationId,
         Long baseParentCustomizationId, Locale locale) {
     DbDefinition definition = null;
     Long customizationId = baseCustomizationId;
     Long parentCustomizationId = baseParentCustomizationId;
     List<DbDefinition> definitions = null;
     boolean finished = false;
     do {
         definitions = getJdbcTemplate()
                 .query(SELECT_DEFINITION_SQL,
                         new Object[] { name, customizationId },
                         definitionRowMapper);
         if (definitions.isEmpty()) {
             if (parentCustomizationId != null) {
                 Map<String, Object> customization = getJdbcTemplate().queryForMap(
                         SELECT_CUSTOMIZATION_BY_ID_SQL,
                         new Object[] { parentCustomizationId });
                 customizationId = ((Number) customization.get("ID")).longValue();
                 parentCustomizationId = numberToLong((Number) customization.get("PARENT_ID"));
             } else {
                 finished = true;
             }
         } else {
             definition = definitions.get(0);
             finished = true;
         }
     } while (!finished);

     if (definition != null) {
         AttributeRowMapper attributeRowMapper = new AttributeRowMapper(definition);
         getJdbcTemplate().query(SELECT_ATTRIBUTES_SQL,
                 new Object[] { definition.getId() }, attributeRowMapper);
     }
     return definition;
 }
 -------------------------------------

   The steps that are followed are:

   [[1]] search for a definition that is usable with the customization id
   (id of the locale in the DB) that is suggested by the caller;

   [[2]] if the definition has not been found, the parent customization id is
   used and the operation at point 1 is done, until a definition is found;

   [[3]] if the definition has been found, the attributes are loaded from the DB.

   []

   Notice that the definition's inheritance <<is not resolved>> because it will
   be done by the implementation of
   {{{../apidocs/org/apache/tiles/definition/DefinitionsFactory.html}DefinitionsFactory}}
   that will call the definitions DAO multiple times to resolve inheritance.

   The <<<DbDefinition>>> is a simple extension of
   {{{../apidocs/org/apache/tiles/Definition.html}Definition}}
   with the addition of an id.

 * Configuration

   To use the definitions DAO we need to configure Tiles to use an alternate
   {{{../apidocs/org/apache/tiles/definition/DefinitionsFactory.html}DefinitionsFactory}}
   that is
   {{{../apidocs/org/apache/tiles/definition/LocaleDefinitionsFactory.html}LocaleDefinitionsFactory}}.
   This definitions factory resolves definitions one by one, by retrieving all
   extended definitions through calls to the definition DAO.

   Though it may seem slow, it is memory-efficient and it is effective when
   the number of definitions is high.

   Here will be using pure Java configuration. A new class extending
   {{{../apidocs/org/apache/tiles/factory/BasicTilesContainerFactory.html}BasicTilesContainerFactory}}
   must be created. It will be called <<<TestDbTilesContainerFactory>>>.
   This is the source:

 -------------------------------------
 public class TestDbTilesContainerFactory extends BasicTilesContainerFactory {

     /** {@inheritDoc} */
     @Override
     protected DefinitionDAO<Locale> createLocaleDefinitionDao(Object context,
             TilesApplicationContext applicationContext,
             TilesRequestContextFactory contextFactory, LocaleResolver resolver) {
         LocaleDbDefinitionDAO definitionDao = new LocaleDbDefinitionDAO();
         definitionDao.setDataSource((DataSource) applicationContext
                 .getApplicationScope().get("dataSource"));
         return definitionDao;
     }

     /** {@inheritDoc} */
     @Override
     protected LocaleDefinitionsFactory instantiateDefinitionsFactory(
             Object context, TilesApplicationContext applicationContext,
             TilesRequestContextFactory contextFactory, LocaleResolver resolver) {
         return new LocaleDefinitionsFactory();
    }
 }
 -------------------------------------

   Create a Tiles listener this way:

 -------------------------------------
 public class TestDbTilesListener extends AbstractTilesListener {

     @Override
     protected TilesInitializer createTilesInitializer() {
         return new TestDbTilesInitializer();
     }

     private static class TestDbTilesInitializer extends AbstractTilesInitializer {

         @Override
         protected AbstractTilesContainerFactory createContainerFactory(
                 TilesApplicationContext context) {
             return new TestDbTilesContainerFactory();
         }
     }
 }
 -------------------------------------

   In <<<web.xml>>> add this piece of configuration:

 -------------------------------------
 <listener>
   <listener-class>org.apache.tiles.test.listener.TestDbTilesListener</listener-class>
 </listener>
 -------------------------------------

   And you're done!
	~~ $Id$
	~~
	~~ Licensed to the Apache Software Foundation (ASF) under one
	~~ or more contributor license agreements. See the NOTICE file
	~~ distributed with this work for additional information
	~~ regarding copyright ownership. The ASF licenses this file
	~~ to you under the Apache License, Version 2.0 (the
	~~ "License"); you may not use this file except in compliance
	~~ with the License. You may obtain a copy of the License at
	~~
	~~ http://www.apache.org/licenses/LICENSE-2.0
	~~
	~~ Unless required by applicable law or agreed to in writing,
	~~ software distributed under the License is distributed on an
	~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
	~~ KIND, either express or implied. See the License for the
	~~ specific language governing permissions and limitations
	~~ under the License.
	~~
	-----------
	Loading definitions from a database
	-----------

	Loading definitions from a database

	A typical request from Tiles users was to be able to load Tiles definitions
	from a database. With Tiles 2.1, it is a pretty easy task.

	The source of the example is available in the
	{{{/download-21.html}source distribution of Tiles}}, under the "tiles-test"
	module.

	* Database design

	The first step is to design the database schema. Here we will show a small
	example that is far from perfect, anyway it will be enough for our example.
	The following is the picture of the database schema we will use.

	[../images/db-schema.png] Database schema that will be used for the example.

	* Create a Definition DAO

	Essentially, the main programming task is the development of a
	{{{../apidocs/org/apache/tiles/definition/dao/DefinitionDAO.html}definition DAO}}.
	This interface is designed to provide an easy customization of definitions
	retrieval.

	The method that you should implement is only
	{{{../apidocs/org/apache/tiles/definition/dao/DefinitionDAO.html#getDefinition(java.lang.String,%20K)}getDefinition}}.
	You don't have to implement <<<getDefinitions>>> too completely (a simple
	<<<throw UnsupportedOperationException>>> will be enough) since it won't be
	called at all.

	** getDefinition

	This is the source of <<<getDefinition>>> in our example: the JDBC DAO support
	of Spring is used to have a cleaner code.

	-------------------------------------
	/** {@inheritDoc} */
	@SuppressWarnings("unchecked")
	public Definition getDefinition(String name, Locale locale) {
	List<Map<String, Object>> customizations = null;
	Long customizationId = null, parentCustomizationId = null;
	do {
	customizations = getJdbcTemplate().queryForList(
	SELECT_CUSTOMIZATION_BY_NAME_SQL,
	new Object[] { locale.toString() });
	if (!customizations.isEmpty()) {
	Map<String, Object> customization = customizations.get(0);
	customizationId = ((Number) customization.get("ID")).longValue();
	parentCustomizationId = numberToLong((Number) customization.get("PARENT_ID"));
	} else {
	locale = LocaleUtil.getParentLocale(locale);
	}
	} while (customizations.isEmpty());

	return getDefinition(name, customizationId, parentCustomizationId,
	locale);
	}
	-------------------------------------

	In other words:

	[[1]] the current customization (in this case, the client's locale) is
	identified;

	[[2]] it is tried to retrieve the locale from the DB: if it is not found, it
	tries with the parent locale (the parent locale of "en_US" is "en") until one
	is found, or the default (no locale) is used;

	[[3]] the definition for the supported minimum-parent-locale is retrieved and
	passed to the caller.

	** Retrieval of the definition from the DB

	At this point the definition must be retrieved from the DB.

	-------------------------------------
	@SuppressWarnings("unchecked")
	protected DbDefinition getDefinition(String name, Long baseCustomizationId,
	Long baseParentCustomizationId, Locale locale) {
	DbDefinition definition = null;
	Long customizationId = baseCustomizationId;
	Long parentCustomizationId = baseParentCustomizationId;
	List<DbDefinition> definitions = null;
	boolean finished = false;
	do {
	definitions = getJdbcTemplate()
	.query(SELECT_DEFINITION_SQL,
	new Object[] { name, customizationId },
	definitionRowMapper);
	if (definitions.isEmpty()) {
	if (parentCustomizationId != null) {
	Map<String, Object> customization = getJdbcTemplate().queryForMap(
	SELECT_CUSTOMIZATION_BY_ID_SQL,
	new Object[] { parentCustomizationId });
	customizationId = ((Number) customization.get("ID")).longValue();
	parentCustomizationId = numberToLong((Number) customization.get("PARENT_ID"));
	} else {
	finished = true;
	}
	} else {
	definition = definitions.get(0);
	finished = true;
	}
	} while (!finished);

	if (definition != null) {
	AttributeRowMapper attributeRowMapper = new AttributeRowMapper(definition);
	getJdbcTemplate().query(SELECT_ATTRIBUTES_SQL,
	new Object[] { definition.getId() }, attributeRowMapper);
	}
	return definition;
	}
	-------------------------------------

	The steps that are followed are:

	[[1]] search for a definition that is usable with the customization id
	(id of the locale in the DB) that is suggested by the caller;

	[[2]] if the definition has not been found, the parent customization id is
	used and the operation at point 1 is done, until a definition is found;

	[[3]] if the definition has been found, the attributes are loaded from the DB.

	[]

	Notice that the definition's inheritance <<is not resolved>> because it will
	be done by the implementation of
	{{{../apidocs/org/apache/tiles/definition/DefinitionsFactory.html}DefinitionsFactory}}
	that will call the definitions DAO multiple times to resolve inheritance.

	The <<<DbDefinition>>> is a simple extension of
	{{{../apidocs/org/apache/tiles/Definition.html}Definition}}
	with the addition of an id.

	* Configuration

	To use the definitions DAO we need to configure Tiles to use an alternate
	{{{../apidocs/org/apache/tiles/definition/DefinitionsFactory.html}DefinitionsFactory}}
	that is
	{{{../apidocs/org/apache/tiles/definition/LocaleDefinitionsFactory.html}LocaleDefinitionsFactory}}.
	This definitions factory resolves definitions one by one, by retrieving all
	extended definitions through calls to the definition DAO.

	Though it may seem slow, it is memory-efficient and it is effective when
	the number of definitions is high.

	Here will be using pure Java configuration. A new class extending
	{{{../apidocs/org/apache/tiles/factory/BasicTilesContainerFactory.html}BasicTilesContainerFactory}}
	must be created. It will be called <<<TestDbTilesContainerFactory>>>.
	This is the source:

	-------------------------------------
	public class TestDbTilesContainerFactory extends BasicTilesContainerFactory {

	/** {@inheritDoc} */
	@Override
	protected DefinitionDAO<Locale> createLocaleDefinitionDao(Object context,
	TilesApplicationContext applicationContext,
	TilesRequestContextFactory contextFactory, LocaleResolver resolver) {
	LocaleDbDefinitionDAO definitionDao = new LocaleDbDefinitionDAO();
	definitionDao.setDataSource((DataSource) applicationContext
	.getApplicationScope().get("dataSource"));
	return definitionDao;
	}

	/** {@inheritDoc} */
	@Override
	protected LocaleDefinitionsFactory instantiateDefinitionsFactory(
	Object context, TilesApplicationContext applicationContext,
	TilesRequestContextFactory contextFactory, LocaleResolver resolver) {
	return new LocaleDefinitionsFactory();
	}
	}
	-------------------------------------

	Create a Tiles listener this way:

	-------------------------------------
	public class TestDbTilesListener extends AbstractTilesListener {

	@Override
	protected TilesInitializer createTilesInitializer() {
	return new TestDbTilesInitializer();
	}

	private static class TestDbTilesInitializer extends AbstractTilesInitializer {

	@Override
	protected AbstractTilesContainerFactory createContainerFactory(
	TilesApplicationContext context) {
	return new TestDbTilesContainerFactory();
	}
	}
	}
	-------------------------------------

	In <<<web.xml>>> add this piece of configuration:

	-------------------------------------
	<listener>
	<listener-class>org.apache.tiles.test.listener.TestDbTilesListener</listener-class>
	</listener>
	-------------------------------------

	And you're done!