Page edited by Andrus Adamchik

Changes (2)

Full Content

This is a design document. As of 3.0 Cayenne doesn't include this feature.

TODO: Will Need to adjust this design to match 3.1 realities of a simpler stack

Multiple Deployment Units

Users can organize their persistent classes and object relational mapping files into separate deployment units, such as .jar files, .war files and class folders. Each deployment unit must have "cayenne.xml" descriptor and a set of related DataNode and DataMap XML files. At runtime Cayenne will merge mapping information from all deployment units into a single access stack using a set of rules described below.

"cayenne.xml" Lookup Rules

As described in the previous deployment chapters, "cayenne.xml" is by default looked up in the root of each classpath location (such as top of a ".jar" file, a "WEB-INF/classes" folder, etc.), or in WEB-INF/ folder of a web application. Or it can be placed in a package or a subfolder per customization instructions.

Merging Configuration from Multiple Deployment Units

If multiple deployment units contain "cayenne.xml" descriptors in the default or custom locations above, all descriptors will be merged together. Cayenne will do merging on its own using a set of default rules. Most of the merging behavior can be further customized by the user. The following merge rules are applied:

All Units Are Equal. There is no "master" descriptor. All descriptors are considered equal and the order in which they are merged is undefined and should not be relied upon.
Domains Are Merged By Name. Names of Cayenne DataDomains are used to match and combine together DataMaps and DataNodes from different deployment units.
Domain Names Can Be Aliased to Control Merging. Users may have no control over the domain naming of third-party libraries. To ensure that those libraries are merged into the right domains, they can create domain name aliases via MergeContext class API:

MergeContext context = ...
context.mergeDomainAs("unit1", "domain1", "myAppDomain");

If the code in a deployment unit relies on the domain name and aliases are used, it should use deployment unit name (optionally specified in the modeler) and domain name when looking up domain:

Configuration config = ....
DataDomain domain = config.getDomain("unit1", "domain1");

Conflicting DataMaps Are Auto-Aliased. If more than one DataMap with the same name is being merged into a given domain, Cayenne automatically creates a name alias for the second, third and following conflicting DataMaps. The naming conflict is logged but no exception is thrown.

Default DataNode. If a DataDomain has only one DataNode, all DataMaps are automatically linked to this DataNode. If there are multiple DataNodes, a "default" DataNode can be specified via the MergeContext. All unlinked DataMaps will use this DataNode:

MergeContext context = ...
context.setDefaultNode("unit1", "domain1", "myNode");

Conflicting DataNodes Are Auto-Aliased. If more than one DataNode with the same name is being merged into a given domain, Cayenne automatically creates a name alias for the second, third and following conflicting DataNodes. The naming conflict is logged but no exception is thrown.

Conflicting DbEntities, Procedures, Queries Are Ignored. If more than one DbEntity (Procedure, Query) with the same name is defined across the DataMaps merged into the same domain, only one entity (Procedure, Query) will be preserved. The reset will be ignored. There is no way to control which entity stays.

Conflicting ObjEntities Are Ignored / Listeners Merged. If more than one ObjEntity with the same name is defined across the DataMaps merged into the same domain, only one entity will be preserved. The reset will be ignored. There is no way to control which entity stays. However entity listeners are combined together. This way listeners can be defined in a unit separate from the unit that defined ObjEntity.

Change Notification Preferences

View Online | View Changes | Add Comment

[CONF] Apache Cayenne > Runtime Metadata Merging

Runtime Metadata Merging