Notice: This Wiki is now read only and edits are no longer possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
Difference between revisions of "EclipseLink/Development/Dynamic/Design PublicAPI"
(→Dynamic Persistence Design: Public API) |
|||
(24 intermediate revisions by the same user not shown) | |||
Line 1: | Line 1: | ||
− | == | + | __NOTOC__ |
+ | == Public API == | ||
+ | This page captures the design of the public API - introduced in the new package <code>org.eclipse.persistence.dynamic</code> - <br /> | ||
+ | that allows developers to define and use dynamic entities. | ||
− | + | [[Image:Dynpersist.png|678px|middle]] | |
− | + | ; public interface '''DynamicEntity''' | |
− | + | * Primary interface of a dynamic persistent entity. This is the API an application uses to interact with an entity. | |
+ | <code>DynamicEntity</code> is the public interface for dealing with dynamic persistent objects.<br /> | ||
+ | The purpose of dynamic persistent objects is to enable (simple) data access when only mapping information is available <br /> and no concrete Java model is present (specifically, no <tt>.class</tt> files .) | ||
− | + | Applications using <code>DynamicEntity</code>'s can access the persistent state using property names which correspond to <br /> the mapped attributes in the underlying EclipseLink descriptors. For properties mapped to containers (<code>Collection</code>,<code>Map</code>, etc.),<br /> | |
− | + | the property is retrieved then the resulting container can be manipulated. | |
− | * [http://dev.eclipse.org/svnroot/rt/org.eclipse.persistence/incubator/dynamic/branches/1.1.0/org.eclipse.persistence.core.dynamic/src/org/eclipse/persistence/dynamic/DynamicHelper.java DynamicHelper.java | + | To discover meta-data about a DynamicEntity's properties, see the <code>DynamicHelper</code> class |
+ | ; '''Since:''' | ||
+ | : EclipseLink 1.2/2.0 | ||
+ | {| width="60%" border="1" cellpadding="3" | ||
+ | |- class="TableHeadingColor" bgcolor="#CCCCFF" | ||
+ | ! colspan="2" align="left" | <font size="+1"> '''Method Summary'''</font> | ||
+ | |- class="TableRowColor" bgcolor="white" | ||
+ | | width="1%" align="right" valign="top" | <font size="-1"> | ||
+ | {| | ||
+ | |- align="right" | ||
+ | | nowrap="NOWRAP" | <font size="-1"> <code><T> T</code></font> | ||
+ | |} | ||
+ | </font> | ||
+ | | <code>'''get'''(String propertyPath)</code><br />Return the persistence value for the given property as the specified type. | ||
+ | |- class="TableRowColor" bgcolor="white" | ||
+ | | width="1%" align="right" valign="top" | <font size="-1"> <code>boolean</code></font> | ||
+ | | <code>'''isSet'''(String propertyPath)</code><br />Discover if a property has a persistent value | ||
+ | |- class="TableRowColor" bgcolor="white" | ||
+ | | width="1%" align="right" valign="top" | <font size="-1"> <code>DynamicEntity</code></font> | ||
+ | | <code>'''set'''(String propertyPath, Object value)</code><br />Set the persistence value for the given property to the specified value | ||
+ | |} | ||
+ | <br/> | ||
+ | ; public interface '''EntityType''' | ||
+ | * Provides access to the type information (meta-model) as well as functioning as a factory for new instances | ||
+ | An <code>EntityType</code> provides a metadata facade into the EclipseLink object-relational metadata (descriptors & mappings)<br /> | ||
+ | with specific knowledge of the entity types being dynamic. | ||
+ | ; '''Since:''' | ||
+ | : EclipseLink 1.2/2.0 | ||
+ | {| width="60%" border="1" cellpadding="3" | ||
+ | |- class="TableHeadingColor" bgcolor="#CCCCFF" | ||
+ | ! colspan="2" align="left" | <font size="+1"> '''Method Summary'''</font> | ||
+ | |- class="TableRowColor" bgcolor="white" | ||
+ | | width="1%" align="right" valign="top" | <font size="-1"><code>boolean</code></font> | ||
+ | | <code>'''containsProperty'''(String propertyName)</code><br /> | ||
+ | |- class="TableRowColor" bgcolor="white" | ||
+ | | width="1%" align="right" valign="top" | <font size="-1"><code>String</code></font> | ||
+ | | <code>'''getClassName'''()</code><br /> | ||
+ | |- class="TableRowColor" bgcolor="white" | ||
+ | | width="1%" align="right" valign="top" | <font size="-1"><code>o.e.p.descriptors.ClassDescriptor</code></font> | ||
+ | | <code>'''getDescriptor'''()</code><br /> | ||
+ | |- class="TableRowColor" bgcolor="white" | ||
+ | | width="1%" align="right" valign="top" | <font size="-1"><code>Class<?></code></font> | ||
+ | | <code>'''getJavaClass'''()</code><br /> | ||
+ | |- class="TableRowColor" bgcolor="white" | ||
+ | | width="1%" align="right" valign="top" | <font size="-1"><code>String</code></font> | ||
+ | | <code>'''getName'''()</code><br />Return the entity type's name. | ||
+ | |- class="TableRowColor" bgcolor="white" | ||
+ | | width="1%" align="right" valign="top" | <font size="-1"><code>int</code></font> | ||
+ | | <code>'''getNumberOfProperties'''()</code><br />The current number of properties. | ||
+ | |- class="TableRowColor" bgcolor="white" | ||
+ | | width="1%" align="right" valign="top" | <font size="-1"><code>EntityType</code></font> | ||
+ | | <code>'''getParentType'''()</code><br /> | ||
+ | |- class="TableRowColor" bgcolor="white" | ||
+ | | width="1%" align="right" valign="top" | <font size="-1"><code>java.util.List<String></code></font> | ||
+ | | <code>'''getPropertiesNames'''()</code><br />The current names of properties. | ||
+ | |- class="TableRowColor" bgcolor="white" | ||
+ | | width="1%" align="right" valign="top" | <font size="-1"><code>int</code></font> | ||
+ | | <code>'''getPropertyIndex'''(String propertyName)</code><br /> | ||
+ | |- class="TableRowColor" bgcolor="white" | ||
+ | | width="1%" align="right" valign="top" | <font size="-1"><code>Class<?></code></font> | ||
+ | | <code>'''getPropertyType'''(int propertyIndex)</code><br /> | ||
+ | |- class="TableRowColor" bgcolor="white" | ||
+ | | width="1%" align="right" valign="top" | <font size="-1"><code>Class<?></code></font> | ||
+ | | <code>'''getPropertyType'''(String propertyName)</code><br /> | ||
+ | |- class="TableRowColor" bgcolor="white" | ||
+ | | width="1%" align="right" valign="top" | <font size="-1"><code>DynamicEntity</code></font> | ||
+ | | <code>'''newInstance'''()</code><br /> | ||
+ | |} | ||
+ | <br /> | ||
+ | * [http://dev.eclipse.org/svnroot/rt/org.eclipse.persistence/incubator/dynamic/branches/1.1.0/org.eclipse.persistence.core.dynamic/src/org/eclipse/persistence/dynamic/DynamicHelper.java DynamicHelper.java ] | ||
** Helper to lookup types | ** Helper to lookup types | ||
− | + | <br /> | |
− | * | + | ; public class '''EntityTypeBuilder''' |
− | + | * Factory for creating dynamic types and bootstrapping using XML | |
+ | The EntityTypeBuilder is a factory class for creating and extending dynamic entity types. After being constructed in either usage the application can then use the provided API to customize mapping information of the type. | ||
+ | ; '''Since:''' | ||
+ | : EclipseLink 1.2 | ||
+ | {| width="100%" border="1" cellpadding="3" | ||
+ | |- class="TableHeadingColor" bgcolor="#CCCCFF" | ||
+ | ! colspan="2" align="left" | <font size="+1"> '''Constructor Summary'''</font> | ||
+ | |- class="TableRowColor" bgcolor="white" | ||
+ | | <code>'''EntityTypeBuilder(Class<?> dynamicClass, o.e.p.dynamic.EntityType parentType, String...tableNames)'''</code><br />Create an EntityType for a new dynamic type. | ||
+ | |- class="TableRowColor" bgcolor="white" | ||
+ | | <code>'''EntityTypeBuilder(o.e.p.internal.dynamic.DynamicClassLoader dcl, o.e.p.descriptors.ClassDescriptor descriptor, o.e.p.dynamic.EntityType parentType)'''</code><br />Create an EntityTypeBuilder for an existing descriptor. | ||
+ | |} | ||
+ | {| width="100%" border="1" cellpadding="3" | ||
+ | |- class="TableHeadingColor" bgcolor="#CCCCFF" | ||
+ | ! colspan="2" align="left" | <font size="+1"> '''Method Summary'''</font> | ||
+ | |- class="TableRowColor" bgcolor="white" | ||
+ | | width="1%" align="right" valign="top" | <font size="-1"> <code>o.e.p.mappings.AggregateObjectMapping</code></font> | ||
+ | | <code>'''addAggregateObjectMapping'''(String name, o.e.p.dynamic.EntityType refType, boolean allowsNull)</code><br />TODO | ||
+ | |- class="TableRowColor" bgcolor="white" | ||
+ | | width="1%" align="right" valign="top" | <font size="-1"> <code>o.e.p.mappings.DirectCollectionMapping</code></font> | ||
+ | | <code>'''addDirectCollectionMapping'''(String name, String targetTable, String valueColumn, Class<?> valueType, String...fkFieldNames)</code><br />TODO | ||
+ | |- class="TableRowColor" bgcolor="white" | ||
+ | | width="1%" align="right" valign="top" | <font size="-1"> <code>o.e.p.mappings.DirectToFieldMapping</code></font> | ||
+ | | <code>'''addDirectMapping'''(String name, Class<?> javaType, String fieldName)</code><br />Allows <code>DirectToFieldMapping</code> (@Basic) mapping to be added to a dynamic type through API. | ||
+ | |- class="TableRowColor" bgcolor="white" | ||
+ | | width="1%" align="right" valign="top" | <font size="-1"> <code>void</code></font> | ||
+ | | <code>'''addManyToManyMapping'''(String name, o.e.p.dynamic.EntityType refType, String relationshipTableName)</code><br />TODO | ||
+ | |- class="TableRowColor" bgcolor="white" | ||
+ | | width="1%" align="right" valign="top" | <font size="-1"> <code>o.e.p.mappings.OneToManyMapping</code></font> | ||
+ | | <code>'''addOneToManyMapping'''(String name, o.e.p.dynamic.EntityType refType, String...fkFieldNames)</code><br />TODO | ||
+ | |- class="TableRowColor" bgcolor="white" | ||
+ | | width="1%" align="right" valign="top" | <font size="-1"> <code>o.e.p.mappings.OneToOneMapping</code></font> | ||
+ | | <code>'''addOneToOneMapping'''(String name, o.e.p.dynamic.EntityType refType, String...fkFieldNames)</code><br />Allows <code>OneToOneMapping</code> (@OneToOne and @ManyToOne) mappings to be added to a dynamic type through API. | ||
+ | |- class="TableRowColor" bgcolor="white" | ||
+ | | width="1%" align="right" valign="top" | <font size="-1"> <code>void</code></font> | ||
+ | | <code>'''addToSession'''(o.e.p.sessions.DatabaseSession session, boolean createMissingTables, boolean generateFKConstraints)</code><br /> | ||
+ | |- class="TableRowColor" bgcolor="white" | ||
+ | | width="1%" align="right" valign="top" | <font size="-1"> <code>static void</code></font> | ||
+ | | <code>'''addToSession'''(o.e.p.sessions.DatabaseSession session, boolean createMissingTables, boolean generateFKConstraints, o.e.p.dynamic.EntityType...types)</code><br />Add one or more EntityType instances to a session and optionally generate needed tables with or without FK constraints. | ||
+ | |- class="TableRowColor" bgcolor="white" | ||
+ | | width="1%" align="right" valign="top" | <font size="-1"> <code>void</code></font> | ||
+ | | <code>'''configureSequencing'''(o.e.p.sequencing.Sequence sequence, String numberName, String numberFieldName)</code><br /> | ||
+ | |- class="TableRowColor" bgcolor="white" | ||
+ | | width="1%" align="right" valign="top" | <font size="-1"> <code>void</code></font> | ||
+ | | <code>'''configureSequencing'''(String numberName, String numberFieldName)</code><br /> | ||
+ | |- class="TableRowColor" bgcolor="white" | ||
+ | | width="1%" align="right" valign="top" | <font size="-1"> <code>o.e.p.dynamic.EntityType</code></font> | ||
+ | | <code>'''getType'''()</code><br /> | ||
+ | |- class="TableRowColor" bgcolor="white" | ||
+ | | width="1%" align="right" valign="top" | <font size="-1"> <code>static o.e.p.sessions.Project</code></font> | ||
+ | | <code>'''loadDynamicProject'''(java.io.InputStream resourceStream, o.e.p.sessions.DatabaseLogin login, o.e.p.internal.dynamic.DynamicClassLoader dynamicClassLoader)</code><br />Load a dynamic project from deployment XML creating dynamic types for all descriptors where the provided class name does not exist. | ||
+ | |- class="TableRowColor" bgcolor="white" | ||
+ | | width="1%" align="right" valign="top" | <font size="-1"> <code>static o.e.p.sessions.Project</code></font> | ||
+ | | <code>'''loadDynamicProject'''(String resourcePath, o.e.p.sessions.DatabaseLogin login, o.e.p.internal.dynamic.DynamicClassLoader dynamicClassLoader)</code><br />Load a dynamic project from deployment XML creating dynamic types for all descriptors where the provided class name does not exist. | ||
+ | |- class="TableRowColor" bgcolor="white" | ||
+ | | width="1%" align="right" valign="top" | <font size="-1"> <code>void</code></font> | ||
+ | | <code>'''setPrimaryKeyFields'''(String... pkFieldNames)</code><br />Set the PK field names on the underlying descriptor ensuring no duplicate names are added. | ||
+ | |} | ||
* [http://dev.eclipse.org/svnroot/rt/org.eclipse.persistence/incubator/dynamic/branches/1.1.0/org.eclipse.persistence.core.dynamic/src/org/eclipse/persistence/exceptions/DynamicException.java DynamicException.java (org.eclipse.persistence.exceptions)] | * [http://dev.eclipse.org/svnroot/rt/org.eclipse.persistence/incubator/dynamic/branches/1.1.0/org.eclipse.persistence.core.dynamic/src/org/eclipse/persistence/exceptions/DynamicException.java DynamicException.java (org.eclipse.persistence.exceptions)] | ||
** Dynamic usage exception | ** Dynamic usage exception | ||
− | + | * [http://dev.eclipse.org/svnroot/rt/org.eclipse.persistence/incubator/dynamic/branches/1.1.0/org.eclipse.persistence.core.dynamic/src/org/eclipse/persistence/tools/schemaframework/DynamicSchemaManager.java DynamicSchemaManager.java (org.eclipse.persistence.tools.schemaframework)] | |
+ | ** Extended SchemaManager for allowing incremental schema generation for new dynamic types | ||
− | + | == Internal Design == | |
+ | New package <code>org.eclipse.persistence.internal.dynamic</code> |
Latest revision as of 11:41, 24 September 2009
Public API
This page captures the design of the public API - introduced in the new package org.eclipse.persistence.dynamic
-
that allows developers to define and use dynamic entities.
- public interface DynamicEntity
- Primary interface of a dynamic persistent entity. This is the API an application uses to interact with an entity.
DynamicEntity
is the public interface for dealing with dynamic persistent objects.
The purpose of dynamic persistent objects is to enable (simple) data access when only mapping information is available
and no concrete Java model is present (specifically, no .class files .)
Applications using DynamicEntity
's can access the persistent state using property names which correspond to
the mapped attributes in the underlying EclipseLink descriptors. For properties mapped to containers (Collection
,Map
, etc.),
the property is retrieved then the resulting container can be manipulated.
To discover meta-data about a DynamicEntity's properties, see the DynamicHelper
class
- Since:
- EclipseLink 1.2/2.0
Method Summary | ||
---|---|---|
|
get(String propertyPath) Return the persistence value for the given property as the specified type. | |
boolean
|
isSet(String propertyPath) Discover if a property has a persistent value | |
DynamicEntity
|
set(String propertyPath, Object value) Set the persistence value for the given property to the specified value |
- public interface EntityType
- Provides access to the type information (meta-model) as well as functioning as a factory for new instances
An EntityType
provides a metadata facade into the EclipseLink object-relational metadata (descriptors & mappings)
with specific knowledge of the entity types being dynamic.
- Since:
- EclipseLink 1.2/2.0
Method Summary | |
---|---|
boolean
|
containsProperty(String propertyName) |
String
|
getClassName() |
o.e.p.descriptors.ClassDescriptor
|
getDescriptor() |
Class<?>
|
getJavaClass() |
String
|
getName() Return the entity type's name. |
int
|
getNumberOfProperties() The current number of properties. |
EntityType
|
getParentType() |
java.util.List<String>
|
getPropertiesNames() The current names of properties. |
int
|
getPropertyIndex(String propertyName) |
Class<?>
|
getPropertyType(int propertyIndex) |
Class<?>
|
getPropertyType(String propertyName) |
DynamicEntity
|
newInstance() |
- DynamicHelper.java
- Helper to lookup types
- public class EntityTypeBuilder
- Factory for creating dynamic types and bootstrapping using XML
The EntityTypeBuilder is a factory class for creating and extending dynamic entity types. After being constructed in either usage the application can then use the provided API to customize mapping information of the type.
- Since:
- EclipseLink 1.2
Constructor Summary | |
---|---|
EntityTypeBuilder(Class<?> dynamicClass, o.e.p.dynamic.EntityType parentType, String...tableNames) Create an EntityType for a new dynamic type. | |
EntityTypeBuilder(o.e.p.internal.dynamic.DynamicClassLoader dcl, o.e.p.descriptors.ClassDescriptor descriptor, o.e.p.dynamic.EntityType parentType) Create an EntityTypeBuilder for an existing descriptor. |
Method Summary | |
---|---|
o.e.p.mappings.AggregateObjectMapping
|
addAggregateObjectMapping(String name, o.e.p.dynamic.EntityType refType, boolean allowsNull) TODO |
o.e.p.mappings.DirectCollectionMapping
|
addDirectCollectionMapping(String name, String targetTable, String valueColumn, Class<?> valueType, String...fkFieldNames) TODO |
o.e.p.mappings.DirectToFieldMapping
|
addDirectMapping(String name, Class<?> javaType, String fieldName) Allows DirectToFieldMapping (@Basic) mapping to be added to a dynamic type through API.
|
void
|
addManyToManyMapping(String name, o.e.p.dynamic.EntityType refType, String relationshipTableName) TODO |
o.e.p.mappings.OneToManyMapping
|
addOneToManyMapping(String name, o.e.p.dynamic.EntityType refType, String...fkFieldNames) TODO |
o.e.p.mappings.OneToOneMapping
|
addOneToOneMapping(String name, o.e.p.dynamic.EntityType refType, String...fkFieldNames) Allows OneToOneMapping (@OneToOne and @ManyToOne) mappings to be added to a dynamic type through API.
|
void
|
addToSession(o.e.p.sessions.DatabaseSession session, boolean createMissingTables, boolean generateFKConstraints) |
static void
|
addToSession(o.e.p.sessions.DatabaseSession session, boolean createMissingTables, boolean generateFKConstraints, o.e.p.dynamic.EntityType...types) Add one or more EntityType instances to a session and optionally generate needed tables with or without FK constraints. |
void
|
configureSequencing(o.e.p.sequencing.Sequence sequence, String numberName, String numberFieldName) |
void
|
configureSequencing(String numberName, String numberFieldName) |
o.e.p.dynamic.EntityType
|
getType() |
static o.e.p.sessions.Project
|
loadDynamicProject(java.io.InputStream resourceStream, o.e.p.sessions.DatabaseLogin login, o.e.p.internal.dynamic.DynamicClassLoader dynamicClassLoader) Load a dynamic project from deployment XML creating dynamic types for all descriptors where the provided class name does not exist. |
static o.e.p.sessions.Project
|
loadDynamicProject(String resourcePath, o.e.p.sessions.DatabaseLogin login, o.e.p.internal.dynamic.DynamicClassLoader dynamicClassLoader) Load a dynamic project from deployment XML creating dynamic types for all descriptors where the provided class name does not exist. |
void
|
setPrimaryKeyFields(String... pkFieldNames) Set the PK field names on the underlying descriptor ensuring no duplicate names are added. |
- DynamicException.java (org.eclipse.persistence.exceptions)
- Dynamic usage exception
- DynamicSchemaManager.java (org.eclipse.persistence.tools.schemaframework)
- Extended SchemaManager for allowing incremental schema generation for new dynamic types
Internal Design
New package org.eclipse.persistence.internal.dynamic