Details
-
Improvement
-
Status: Closed
-
Major
-
Resolution: Incomplete
-
1.2 branch
-
None
Description
Here is an excerpt from the feature descritpion of the Cayenne xdocs file.
I felt this becomes important when reengineering databases or creating new objects in the Modeler, so I placed it in the Modeler guide though the implementation resides in the Cayenne core.
I couldn't place it in the Wiki because the common-tasks-section has not been entered there yet.
Heiko Erhardt
When reverse engineering a database or synchronizing object
entities with database entities, Cayenne applies various
rules for converting database names to object, member and
relationship names. Also, a sequence generator definition may be
created automatically for each reverse-engineered database entitiy.
The file cayenne-naming.properties in the .cayenne directory
in the classpath allows for customizing the behavior of
the Cayenne modeler and the database loader to some extent.
The .cayenne/cayenne-naming.properties will be searched
in the classpath. Just like the cayenne-log.properties file,
You may copy the file from within the cayenne.jar archive and
place it into an archive or folder that will be prepended
to the classpath. Cayenne will read the contents of this
file only once, so note that you must restart the Cayenne
modeler if you change the file's contents.
Strategies.
The naming algorithm is implemented
using the strategy pattern, which allows you to plug in your
own naming implementations. The naming strategy must implement
the org.objectstyle.cayenne.util.NamingStrategy
interface and can extend from the default naming strategy
org.objectstyle.cayenne.util.DefaultNamingStrategy class.
You may specify the strategy class name in the cayenne-naming.properties
file.
Likewise, a key generator strategy may be specified.
It must implement org.objectstyle.cayenne.access.DbLoaderKeyGeneratorStrategy
and may extend from DbLoaderPropertyBasedKeyGeneratorStrategy.
Name Conversion.
In general, names of
object entities or object members are generated by converting
the underscore-based database names to proper Java names.
This behaviour is hard-coded at the moment.
However, before this conversion is performed, some modifications
may be applied.
Entity Naming.
Sometimes, database tables are named
in a plural form whereas Java class names reflect the singular form
if a term. If your set the <code>Naming.SingularizeObjEntities</code>
property to true, the database entity name will be converted to its
singular form by stripping the traling "s". For exceptions to this rule
where this simple operation won't do (e. g. "ADDRESSES"), you may specify
the singular form of the entity using the <code>Naming.Singular.</code>
property prefix (e. g. <code>Naming.Singular.ADDRESSES=ADDRESS</code>).
object entities or object members are generated by converting
the underscore-based database names to proper Java names.
This behaviour is hard-coded at the moment.
However, before this conversion is performed, some modifications
may be applied.
Attribute Naming.
It may be desirable to remove an auto-generated
prefix from database column names before converting the to Java member names
in order to generate object property names. The <code>Naming.DbAttributeNamePrefixToRemove</code>
property supports this. If specified, any text up to (and including) the
specified prefix will be removed. For example, some database design tools
automatically add a table-specific prefix to all column names of the table
like "PERS_FIRST_NAME". The property entry
<code>Naming.DbAttributeNamePrefixToRemove=_</code>
will remove everything up to the first underscore, leaving "FIRST_NAME"
for generating the object attribute name.
Relationship Naming.
The relationship naming controls
the names of the generated relationship getter, setter, addition and removal
methods of a data object class.
The default naming strategy of the cayenne-naming.properties file supports specifying
prefixes and postfixes for to-one and to-many relations. By default, to-one
relations will be prefixed by "TO_", resuling in the method prefix "to" (e. g. a
relation to the "PAINTING" entity will result in a "setToPainting" setter method.
To-many relations will have the postfix "_ARRAY", resuling in "addToPaintingArray"
adder methods.
Setting for example
<code>Naming.ToOneRelationPrefix=</code>
and
<code>Naming.ToManyRelationSuffix=_LIST</code>
will remove the "to" prefix from to-one relations and change the to-many postfix to "List".
The <code>org.objectstyle.cayenne.util.RelationsshipFkNamingStrategy</code> naming strategy
extends the default naming strategy. It will add the name of the foreign key of a relationship
before the target entity name to the relationsship name. This has two advantages:
1. Relations between the same entities (e. g. two relations between entity A and entity B)
will have a speaking difference instead of merely a running number appended in order to
make the unique (e. g. "goodPainting" and "badPainting" instead of "painting" and "painting1").
2. It might be more descriptive than just using the target entity name.
Similar to <code>Naming.DbAttributeNamePrefixToRemove</code>, the
Similar to <code>Naming.Relationship.AttrNamePrefixToRemove</code> allows to remove
a prefix from the foreign key before applying it to the name conversion.
For example, for foreign keys like "PAINTING_ID_GOOD", the property entry
<code>Naming.Relationship.AttrNamePrefixToRemove=ID</code> will leave the "GOOD"
text for relationship name generation, resulting in a method name like
"setGoodPainting".
Key Generator Settings.
As with Cayenne object naming, a key generator
definition can be bound to each reverse-engineered database entity using a pluggable
strategy class, which must implement the
org.objectstyle.cayenne.access.DbLoaderKeyGeneratorStrategy interface.
The default implementation is the
org.objectstyle.cayenne.access.DbLoaderPropertyBasedKeyGeneratorStrategy class.
The properties of the cayenne-naming.properties file allow to specify
the generator type, key cache size and the name of the generator (i. e. the name
of the sequence). It may be generated from the table name or the entire name or a prefix of
the key attribute.