net.java.ao.schema
Class AbstractTableNameConverter

java.lang.Object
  net.java.ao.schema.AbstractTableNameConverter

All Implemented Interfaces:

TableNameConverter

Direct Known Subclasses:

CamelCaseTableNameConverter, PluralizedNameConverter, UnderscoreTableNameConverter

public abstract class AbstractTableNameConverter
extends Object
implements TableNameConverter

An abstract implementation of TableNameConverter which provides basic functionality common to most table name converters. For most use-cases, it is best to extend this class rather than directly implementing TableNameConverter.

The primary functionality provided by this class is both class and pattern mappings (between class names and generated table names). These mappings can be passed into arbitrary subclasses (such as CamelCaseTableNameConverter) allowing for maximum flexibility and control over auto-generated table names.

Most subclasses will only need to override the convertName(Class) method to accomplish most functionality.

Author:

Daniel Spiewak

Constructor Summary

protected

AbstractTableNameConverter() Initializes the class mappings and pattern mappings to empty maps.

Method Summary

void	addClassMapping(Class<? extends RawEntity<?>> clazz, String name) Adds an explicit mapping between a specific entity type and a corresponding table name.
void	addClassMappings(Map<Class<? extends RawEntity<?>>,String> mappings) Convenience method to add multiple class mappings in a single method call.
void	addPatternMapping(String pattern, String result) Adds a regular expression pattern and corresponding result mapping to the name converter.
void	addPatternMappings(Map<String,String> mappings, Iterator<String> keys) Convenience method to add multiple pattern mappings in a single shot.
protected abstract String	convertName(Class<? extends RawEntity<?>> entity) Performs the actual operation of converting a class type into a proper table name.
String	getName(Class<? extends RawEntity<?>> entity) Returns the corresponding table name for the given entity type.
protected String	postProcessName(String back) Performs second-step post-processing on converted names.
protected String	processName(String back) Performs first-step post-processing on converted names.
String	toString()

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

AbstractTableNameConverter

protected AbstractTableNameConverter()

Initializes the class mappings and pattern mappings to empty maps.

Method Detail

addClassMapping

public void addClassMapping(Class<? extends RawEntity<?>> clazz,
                            String name)

Adds an explicit mapping between a specific entity type and a corresponding table name. This is basically a centralized version of the Table annotation. This will override any name conversion and any pattern mappings available. Additionally, it will override any @Table annotation placed upon the entity interface directly. This is effectively the highest scoped method for specifying table names for correspondant class types.

Parameters:

clazz - The entity type for which the mapping will be created.

name - The table name which will be used for the given entity type.

addClassMappings

public void addClassMappings(Map<Class<? extends RawEntity<?>>,String> mappings)

Convenience method to add multiple class mappings in a single method call. This allows the things such as loading class mappings from an external file and passing them to the name converter in bulk.

Parameters:

mappings - The map of all mappings which are to be added to the name converter. Duplicate types will be overridden by the new mapping.

See Also:

addClassMapping(Class, String)

addPatternMapping

public void addPatternMapping(String pattern,
                              String result)

Adds a regular expression pattern and corresponding result mapping to the name converter. These patterns will be applied after the generic convertName(Class) value is retrieved. The pattern will not be applied to explicitly specified class names using @Table or a class mapping.

The result value is a parsed string which can contain references to matched groups within the regular expression result. Example:

Param: pattern	Param: result
(.*p)erson	{1}eople

This mapping would pluralize any name ending in "person" (match case-insensetive) and replace the name with the pluralized form. Thus, "person" would become "people", "gafferPerson" would become "gafferPeople" and so on. As you may have guessed from the example, this sort of pattern matching is used to implement pluralization in table name conversion (using PluralizedNameConverter.

Mappings are added to the head of the mapping list. Thus, added mappings override any prior mappings, including prior manual mappings. Thus mappings added sequentially will invert in order, leading to the last mapping having the highest priority in evaluation.

Parameters:

pattern - A regular expression in Java format defining the pattern which should be matched. (matching is case-insensetive)

result - A parsed String defining the value which should be substituted for all matched names.

addPatternMappings

public void addPatternMappings(Map<String,String> mappings,
                               Iterator<String> keys)

Convenience method to add multiple pattern mappings in a single shot. It's important to note that mappings must be ordered, thus the second parameter is required to enforce this ordering. Technically, just passing a LinkedHashMap would be sufficient, but enforcing the use of that particular class is annoying.

This method is in place to allow things such as loading of patterns from a properties file and importing them in bulk into the name converter. It is this technique which is used in PluralizedNameConverter to load and setup the english pluralization rules.

Mappings are added to the head of the mapping list. Thus, added mappings override any prior mappings, including prior manual mappings. The order specified by the iterator is maintained however. Thus the addition of a block of ordered mappings will occur at the head of the mappings list, but will themselves remain in order (rather than being reversed).

Parameters:

mappings - The pattern mappings to add (pattern => result).

keys - An iterator to enforce strict ordering of the patterns, allowing for the notion of eval order.

See Also:

addPatternMapping(String, String)

getName

public String getName(Class<? extends RawEntity<?>> entity)

Returns the corresponding table name for the given entity type. This method handles delegation to other functions to perform the actual conversion. More importantly, this method handles @Table annotations as well as class mappings as a short-circuit on the standard conversion algorithm. Thus if an expressed mapping is found, it will be used and returned immediately, without post-processing, pattern matching or passing "Go".

Specified by:

getName in interface TableNameConverter

Parameters:

entity - The entity type for which a corresponding field name must be generated.

Returns:

A database table name which corresponds to the given entity type.

See Also:

TableNameConverter.getName(Class)

convertName

protected abstract String convertName(Class<? extends RawEntity<?>> entity)

Performs the actual operation of converting a class type into a proper table name. This method need not concern itself with particulars of @Table annotations or pattern mappings. All of these things are handled in the getName(Class) method in the superclass implementation.

This method must run as fast as possible and should be thread-safe. If necessary, caching may be employed, but it is also within scope for such caching to be utilized within the superclass. As such, the implementation of this method should be kept extremely simple. Also note that this method may not be called for every entity type which must be converted (due to mappings, @Table overrides, etc).

Parameters:

entity - The entity type which must be converted.

Returns:

The unique table name which corresponds to the given type.

processName

protected String processName(String back)

Performs first-step post-processing on converted names. This is where pattern mappings are applied. This method is called after other conversion functions such as class mappings, convertName(Class) and so on.

Note: few implementations will need to override this method. Most conventional post-processing should be handled in the postProcessName(String) method, which is invoked after this method, passing the result.

Parameters:

back - The generated table name which should be processed to suit conventions and patterns.

Returns:

An (optionally) modified version of the given table name.

postProcessName

protected String postProcessName(String back)

Performs second-step post-processing on converted names. This method is called to perform last-stage conventions enforcement prior to utilization of the table name. This allows implementations to impose sweeping conventions such as "all table names should be uppercase" and so on. Any minor or name-specific conventions should be enforced within the processName(String) method.

The main reason for this method's existence is actually to allow for table name pluralizing on conversions imposing odd conventions, such as all uppercase or all lowercase. This method should be invoked as the last step of any table name conversion (with the exception of class mappings and @Table annotations) to allow for extremely broad-brush changes. The default implementation simply returns the passed name.

Parameters:

back - The generated table name which should be processed to suit large-scale conventions.

Returns:

An (optionally) modified version of the given table name.

toString

public String toString()

Overrides:

toString in class Object