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/DBWS/NamingConventionTransformer"
(→User-Provided NamingConventionTransformer) |
|||
(24 intermediate revisions by the same user not shown) | |||
Line 1: | Line 1: | ||
− | __NOTOC__ | + | <css> |
+ | .source-sql {padding:1em;border:1px solid black; background-color: white;} | ||
+ | .source-java5 {padding:1em;border:1px solid black; background-color: white;} | ||
+ | .source-xml {padding:1em;border:1px solid black; background-color: white;} | ||
+ | .source-text {padding:1em;border:1px solid black; background-color: white;} | ||
+ | </css> | ||
+ | __NOTOC__ | ||
== DBWS Schema Naming Convention Transformers == | == DBWS Schema Naming Convention Transformers == | ||
Line 12: | Line 18: | ||
| Mike Norman | | Mike Norman | ||
| 1.0 | | 1.0 | ||
+ | |- | ||
+ | | 091211 | ||
+ | | Mike Norman | ||
+ | | 2.0 - add Optimistic Lock field support ([https://bugs.eclipse.org/bugs/show_bug.cgi?id=249600 bug 249600]) | ||
|} | |} | ||
Line 18: | Line 28: | ||
The DBWSBuilder utility should allow the user to alter the names of the generated schema types. <br/> | The DBWSBuilder utility should allow the user to alter the names of the generated schema types. <br/> | ||
The algorithm currently in use is very simple: | The algorithm currently in use is very simple: | ||
− | * table name | + | * table name → to_lowercase → add suffix 'Type' → translate any characters un-supported by XML<sup>1</sup> → top-level element type in <tt>.xsd</tt> file |
− | * column name | + | * column name → to_lowercase → translate characters → element tag name<sup>2</sup> |
<sup>1</sup> - same algorithm documented as part of the SQL/X(2003) specification (a.k.a. ISO/IEC 9075-14:2003 Part 14) <br/> | <sup>1</sup> - same algorithm documented as part of the SQL/X(2003) specification (a.k.a. ISO/IEC 9075-14:2003 Part 14) <br/> | ||
<sup>2</sup> - All columns expressed as XML elements | <sup>2</sup> - All columns expressed as XML elements | ||
Line 25: | Line 35: | ||
=== Proposed new Interface <tt>org.eclipse.persistence.tools.dbws.NamingConventionTransformer</tt> === | === Proposed new Interface <tt>org.eclipse.persistence.tools.dbws.NamingConventionTransformer</tt> === | ||
The proposed fix for [https://bugs.eclipse.org/bugs/show_bug.cgi?id=234677 bug 234677] is the introduction of a new Interface class: | The proposed fix for [https://bugs.eclipse.org/bugs/show_bug.cgi?id=234677 bug 234677] is the introduction of a new Interface class: | ||
− | <source lang= | + | <source lang=java5> |
package org.eclipse.persistence.tools.dbws; | package org.eclipse.persistence.tools.dbws; | ||
Line 56: | Line 66: | ||
::API passes in the name of the table's column so that it is available for parsing, but the NamingConventionTransformer implementation does not have to use it | ::API passes in the name of the table's column so that it is available for parsing, but the NamingConventionTransformer implementation does not have to use it | ||
* <tt>ElementStyle styleForElement</tt> | * <tt>ElementStyle styleForElement</tt> | ||
− | :allows one to change the XML schema style for a given table column - transform to an XML element (default), an attribute or neither | + | :allows one to change the XML schema style for a given table column - transform to an XML element (default), an attribute, or neither which means that the specified table column will not be mapped. |
<br clear="all"/> | <br clear="all"/> | ||
− | [[Image:NCTChainOfResponsibility.png| | + | [[Image:NCTChainOfResponsibility.png|650px]] |
<br clear="all"/> | <br clear="all"/> | ||
<pre> | <pre> | ||
Line 74: | Line 84: | ||
\---tools | \---tools | ||
\---dbws | \---dbws | ||
− | |||
| ... | | ... | ||
− | + | | DBWSBuilder.class | |
− | + | | ... | |
− | + | | DefaultNamingConventionTransformer.class | |
+ | | NamingConventionTransformer.class | ||
+ | | SQLX2003Transformer.class | ||
+ | | ToLowerTransformer.class | ||
+ | | TypeSuffixTransformer.class | ||
+ | | ... | ||
</pre> | </pre> | ||
− | In the <tt>org.eclipse.persistence.tools.dbws.NamingConventionTransformer</tt> services file | + | In the <tt>org.eclipse.persistence.tools.dbws.NamingConventionTransformer</tt> services file, the transformer chain is listed in order: |
:<tt>org.eclipse.persistence.tools.dbws.ToLowerTransformer | :<tt>org.eclipse.persistence.tools.dbws.ToLowerTransformer | ||
:org.eclipse.persistence.tools.dbws.TypeSuffixTransformer | :org.eclipse.persistence.tools.dbws.TypeSuffixTransformer | ||
Line 86: | Line 100: | ||
==== User-Provided NamingConventionTransformer ==== | ==== User-Provided NamingConventionTransformer ==== | ||
− | A user may provide their own NamingConventionTransformer by sub-classing <tt>org.eclipse.persistence.tools.dbws.DefaultNamingConventionTransformer</tt>. For example, for the table | + | A user may provide their own NamingConventionTransformer to override the default behaviour by sub-classing <tt>org.eclipse.persistence.tools.dbws.DefaultNamingConventionTransformer</tt>. For example, for the table |
<source lang=sql> | <source lang=sql> | ||
CREATE TABLE IF NOT EXISTS SIMPLE_TABLE ( | CREATE TABLE IF NOT EXISTS SIMPLE_TABLE ( | ||
Line 98: | Line 112: | ||
* make the schema element <tt>simple</tt> | * make the schema element <tt>simple</tt> | ||
* make the element names lowercase | * make the element names lowercase | ||
− | * have the <tt>ID</tt> field represented as | + | * have the <tt>ID</tt> field represented as an attribute, and |
* skip the <tt>SINCE</tt> field | * skip the <tt>SINCE</tt> field | ||
− | <source lang= | + | <source lang=java5> |
import org.eclipse.persistence.tools.dbws.DefaultNamingConventionTransformer; | import org.eclipse.persistence.tools.dbws.DefaultNamingConventionTransformer; | ||
import static org.eclipse.persistence.tools.dbws.NamingConventionTransformer.ElementStyle.ATTRIBUTE; | import static org.eclipse.persistence.tools.dbws.NamingConventionTransformer.ElementStyle.ATTRIBUTE; | ||
Line 130: | Line 144: | ||
} | } | ||
</source> | </source> | ||
− | The user must package their provided NamingConventionTransformer class in a <tt>.jar</tt>-file and identify it as a service by creating a file called <tt>org.eclipse.persistence.tools.dbws.NamingConventionTransformer</tt> in the <tt>META-INF/services</tt> directory with the full-qualified classname of the transformer: | + | <source lang=xml> |
− | <pre> | + | <?xml version="1.0" encoding="UTF-8"?> |
+ | <xsd:schema targetNamespace="urn:simple" xmlns="urn:simple" elementFormDefault="qualified" xmlns:xsd="http://www.w3.org/2001/XMLSchema"> | ||
+ | <xsd:complexType name="simple"> | ||
+ | <xsd:sequence> | ||
+ | <xsd:element name="name" type="xsd:string" minOccurs="0"/> | ||
+ | </xsd:sequence> | ||
+ | <xsd:attribute name="id" type="xsd:decimal" use="required"/> | ||
+ | </xsd:complexType> | ||
+ | <xsd:element name="simple" type="simple"/> | ||
+ | </xsd:schema> | ||
+ | </source> | ||
+ | The user <b>must</b> package their provided NamingConventionTransformer class in a <tt>.jar</tt>-file and identify it as a service by creating a file called <tt>org.eclipse.persistence.tools.dbws.NamingConventionTransformer</tt> in the <tt>META-INF/services</tt> directory with the full-qualified classname of the transformer: | ||
+ | <pre class="box"> | ||
+ | mynamingtrans.jar | ||
+ | | | ||
+ | +---META-INF | ||
+ | | | MANIFEST.MF | ||
+ | | | | ||
+ | | \---services | ||
+ | | org.eclipse.persistence.tools.dbws.NamingConventionTransformer | ||
+ | | | ||
+ | \---foo | ||
+ | \---bar | ||
+ | \---blah | ||
+ | | MyNamingConventionTransformer | ||
+ | </pre> | ||
+ | In the <tt>org.eclipse.persistence.tools.dbws.NamingConventionTransformer</tt> services file, a single line with the full-qualified classname of the transformer <tt>foo.bar.blah.MyNamingConventionTransformer</tt> is required. | ||
+ | <b>NB</b> - the user-provided NamingConventionTransformer's <tt>.jar</tt>-file <b>must</b> be <i>ahead</i> of the <tt>eclipselink-dbwsutils.jar</tt> in order for it to be picked up by the DBWSBuilder utility. In addition, the DBWSBuilder utility <b>always</b> builds the <i>Chain-of-Responsibility</i> with the <tt>SQLX2003Transformer</tt> at the end to ensure that any transform, default or user-provided, is composed of legal characters according to the SQL/X(2003) specification. | ||
+ | |||
+ | |||
+ | === DBWS utility enhancement: auto-detect Optimistic Lock Fields === | ||
+ | [https://bugs.eclipse.org/bugs/show_bug.cgi?id=249600 bug 249600] <br/> | ||
+ | The DBWSBuilder utility should, upon examining the metadata for a table, search for a well-known column (e.g. <tt>VERSION</tt>) | ||
+ | and automatically setup the DBWS OR project (in <tt>eclipselink-dbws-or.xml</tt>) with a <tt>o.e.p.internal.descriptors.OptimisticLockingPolicy</tt>. | ||
+ | |||
+ | At runtime, if a Web service client tries to update a row with 'old' information, then an <tt>OptimisticLockException</tt> is thrown: <br/> | ||
+ | Let us suppose that the database contains the most up-to-date version of the entity: | ||
+ | {| border="1" cellpadding="5" cellspacing="1" | ||
+ | ! style="border-width: 1px;border-style: solid;border-color: #ccc;padding: 5px;background-color: #ffffff;text-align: left;vertical-align: top;color: #003366;"|row | ||
+ | ! style="border-width: 1px;border-style: solid;border-color: #ccc;padding: 5px;background-color: #e9e9f2;text-align: right;vertical-align: top;color: #003366;"|ID | ||
+ | ! style="border-width: 1px;border-style: solid;border-color: #ccc;padding: 5px;background-color: #e9e9f2;text-align: left;vertical-align: top;color: #003366;"|NAME | ||
+ | ! style="border-width: 1px;border-style: solid;border-color: #ccc;padding: 5px;background-color: #e9e9f2;text-align: left;vertical-align: top;color: #003366;"|DESCRIPT | ||
+ | ! style="border-width: 1px;border-style: solid;border-color: #ccc;padding: 5px;background-color: #e9e9f2;text-align: right;vertical-align: top;color: #003366;"|VERSION | ||
+ | |- | ||
+ | |1 | ||
+ | |1 | ||
+ | |name | ||
+ | |this is ver 3 | ||
+ | |3 | ||
+ | |- | ||
+ | |} | ||
+ | A SOAPMessage contains an update based on an older version: | ||
+ | <source lang=xml> | ||
+ | <?xml version="1.0" encoding="UTF-8"?> | ||
+ | <env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/"> | ||
+ | <env:Header/> | ||
+ | <env:Body> | ||
+ | <srvc:update_optlockType> | ||
+ | <srvc:theInstance> | ||
+ | <optlockType> | ||
+ | <id>1</id> | ||
+ | <name>name</name> | ||
+ | <descript>this is ver 2</descript> | ||
+ | <version>1</version> | ||
+ | </optlockType> | ||
+ | </srvc:theInstance> | ||
+ | </srvc:update_optlockType> | ||
+ | </env:Body> | ||
+ | </env:Envelope> | ||
+ | </source> | ||
+ | Without the <tt>OptimisticLockingPolicy</tt>, the update ("this is ver 2") would overwrite the committed data of version 2. | ||
+ | <pre> | ||
+ | Exception [EclipseLink-5010] (Eclipse Persistence Services - @VERSION@.@QUALIFIER@): org.eclipse.persistence.exceptions.OptimisticLockException | ||
+ | Exception Description: The object [{Optlock 1}] cannot be merged because it has changed or been deleted since it was last read. | ||
+ | Class> optlocktest.Optlock | ||
</pre> | </pre> | ||
+ | There are a number of '5xxx' error codes: | ||
+ | <pre> | ||
+ | NO_VERSION_NUMBER_WHEN_DELETING = 5001; | ||
+ | OBJECT_CHANGED_SINCE_LAST_READ_WHEN_DELETING = 5003; | ||
+ | NO_VERSION_NUMBER_WHEN_UPDATING = 5004; | ||
+ | OBJECT_CHANGED_SINCE_LAST_READ_WHEN_UPDATING = 5006; | ||
+ | MUST_HAVE_MAPPING_WHEN_IN_OBJECT = 5007; | ||
+ | NEED_TO_MAP_JAVA_SQL_TIMESTAMP = 5008; | ||
+ | UNWRAPPING_OBJECT_DELETED_SINCE_LAST_READ = 5009; | ||
+ | OBJECT_CHANGED_SINCE_LAST_MERGE = 5010; | ||
+ | STATEMENT_NOT_EXECUTED_IN_BATCH = 5011; | ||
+ | </pre> | ||
+ | |||
+ | When the DBWSBuilder utility scans the meta-data for a table, if it finds a column called <tt>VERSION</tt>, it will automatically augment the | ||
+ | OR Project's descriptor for that table with a <tt>VersionLockingPolicy</tt> keyed to that field. However, if the user wishes to change the | ||
+ | name of the 'magic' Optimistic Lock field, a custom <tt>NamingConventionTransformer</tt> can be used: | ||
+ | <source lang=java5> | ||
+ | import org.eclipse.persistence.tools.dbws.DefaultNamingConventionTransformer; | ||
+ | |||
+ | public class CustomOptLockFieldNamingConventionTransformer extends DefaultNamingConventionTransformer { | ||
+ | |||
+ | // lock field name is not | ||
+ | // org.eclipse.persistence.tools.dbws.NamingConventionTransformer.DEFAULT_OPTIMISTIC_LOCKING_FIELD | ||
+ | @Override | ||
+ | public String getOptimisticLockingField() { | ||
+ | return "VER"; | ||
+ | } | ||
+ | } | ||
+ | </source> |
Latest revision as of 10:44, 7 October 2010
DBWS Schema Naming Convention Transformers
Document History
Date | Author | Version Description & Notes |
---|---|---|
080911 | Mike Norman | 1.0 |
091211 | Mike Norman | 2.0 - add Optimistic Lock field support (bug 249600) |
DBWS utility enhancement: Naming convention of generated schema types
bug 234677
The DBWSBuilder utility should allow the user to alter the names of the generated schema types.
The algorithm currently in use is very simple:
- table name → to_lowercase → add suffix 'Type' → translate any characters un-supported by XML1 → top-level element type in .xsd file
- column name → to_lowercase → translate characters → element tag name2
1 - same algorithm documented as part of the SQL/X(2003) specification (a.k.a. ISO/IEC 9075-14:2003 Part 14)
2 - All columns expressed as XML elements
Proposed new Interface org.eclipse.persistence.tools.dbws.NamingConventionTransformer
The proposed fix for bug 234677 is the introduction of a new Interface class:
package org.eclipse.persistence.tools.dbws; public interface NamingConventionTransformer { public enum ElementStyle { ELEMENT, ATTRIBUTE, NONE }; public String generateSchemaName(String tableName); public String generateElementAlias(String originalElementName); public ElementStyle styleForElement(String originalElementName); } public class DefaultNamingConventionTransformer implements NamingConventionTransformer { // user-provided transformer must extended this class . . . }
The algorithm above will be converted to a series of transformers (operating as a Chain-of-Responsibility) that cooperate together to transform the database table's metadata
(table name, table columns) into the schema's top-level types.
- generateTableAlias
- allows one to alter the auto-generated Schema name
- API passes in the name of the table so that it is available for parsing (e.g. remove prefix/suffix, convert to upper/lower/CamelCase, etc), but the NamingConventionTransformer implementation does not have to use it.
- generateElementAlias
- allows one to alter the auto-generated XML schema element names
- API passes in the name of the table's column so that it is available for parsing, but the NamingConventionTransformer implementation does not have to use it
- ElementStyle styleForElement
- allows one to change the XML schema style for a given table column - transform to an XML element (default), an attribute, or neither which means that the specified table column will not be mapped.
eclipselink-dbwsutils.jar | +---META-INF | | MANIFEST.MF | | | \---services | org.eclipse.persistence.tools.dbws.NamingConventionTransformer | \---org \---eclipse \---persistence \---tools \---dbws | ... | DBWSBuilder.class | ... | DefaultNamingConventionTransformer.class | NamingConventionTransformer.class | SQLX2003Transformer.class | ToLowerTransformer.class | TypeSuffixTransformer.class | ...
In the org.eclipse.persistence.tools.dbws.NamingConventionTransformer services file, the transformer chain is listed in order:
- org.eclipse.persistence.tools.dbws.ToLowerTransformer
- org.eclipse.persistence.tools.dbws.TypeSuffixTransformer
- org.eclipse.persistence.tools.dbws.SQLX2003Transformer
User-Provided NamingConventionTransformer
A user may provide their own NamingConventionTransformer to override the default behaviour by sub-classing org.eclipse.persistence.tools.dbws.DefaultNamingConventionTransformer. For example, for the table
CREATE TABLE IF NOT EXISTS SIMPLE_TABLE ( ID NUMERIC NOT NULL, NAME VARCHAR(25), SINCE DATE, PRIMARY KEY (ID) )
The following NamingConventionTransformer will:
- make the schema element simple
- make the element names lowercase
- have the ID field represented as an attribute, and
- skip the SINCE field
import org.eclipse.persistence.tools.dbws.DefaultNamingConventionTransformer; import static org.eclipse.persistence.tools.dbws.NamingConventionTransformer.ElementStyle.ATTRIBUTE; import static org.eclipse.persistence.tools.dbws.NamingConventionTransformer.ElementStyle.ELEMENT; import static org.eclipse.persistence.tools.dbws.NamingConventionTransformer.ElementStyle.NONE; public class MyNamingConventionTransformer extends DefaultNamingConventionTransformer { @Override public String generateSchemaAlias(String tableName) { return super.generateSchemaAlias("simple"); } @Override public String generateElementAlias(String originalElementName) { return super.generateElementAlias(originalElementName.toLowerCase()); } @Override public ElementStyle styleForElement(String elementName) { if ("id".equalsIgnoreCase(elementName)) { return ATTRIBUTE; } else if ("since".equalsIgnoreCase(elementName)) { return NONE; } return ELEMENT; } }
<?xml version="1.0" encoding="UTF-8"?> <xsd:schema targetNamespace="urn:simple" xmlns="urn:simple" elementFormDefault="qualified" xmlns:xsd="http://www.w3.org/2001/XMLSchema"> <xsd:complexType name="simple"> <xsd:sequence> <xsd:element name="name" type="xsd:string" minOccurs="0"/> </xsd:sequence> <xsd:attribute name="id" type="xsd:decimal" use="required"/> </xsd:complexType> <xsd:element name="simple" type="simple"/> </xsd:schema>
The user must package their provided NamingConventionTransformer class in a .jar-file and identify it as a service by creating a file called org.eclipse.persistence.tools.dbws.NamingConventionTransformer in the META-INF/services directory with the full-qualified classname of the transformer:
mynamingtrans.jar | +---META-INF | | MANIFEST.MF | | | \---services | org.eclipse.persistence.tools.dbws.NamingConventionTransformer | \---foo \---bar \---blah | MyNamingConventionTransformer
In the org.eclipse.persistence.tools.dbws.NamingConventionTransformer services file, a single line with the full-qualified classname of the transformer foo.bar.blah.MyNamingConventionTransformer is required.
NB - the user-provided NamingConventionTransformer's .jar-file must be ahead of the eclipselink-dbwsutils.jar in order for it to be picked up by the DBWSBuilder utility. In addition, the DBWSBuilder utility always builds the Chain-of-Responsibility with the SQLX2003Transformer at the end to ensure that any transform, default or user-provided, is composed of legal characters according to the SQL/X(2003) specification.
DBWS utility enhancement: auto-detect Optimistic Lock Fields
bug 249600
The DBWSBuilder utility should, upon examining the metadata for a table, search for a well-known column (e.g. VERSION)
and automatically setup the DBWS OR project (in eclipselink-dbws-or.xml) with a o.e.p.internal.descriptors.OptimisticLockingPolicy.
At runtime, if a Web service client tries to update a row with 'old' information, then an OptimisticLockException is thrown:
Let us suppose that the database contains the most up-to-date version of the entity:
row | ID | NAME | DESCRIPT | VERSION |
---|---|---|---|---|
1 | 1 | name | this is ver 3 | 3 |
A SOAPMessage contains an update based on an older version:
<?xml version="1.0" encoding="UTF-8"?> <env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/"> <env:Header/> <env:Body> <srvc:update_optlockType> <srvc:theInstance> <optlockType> <id>1</id> <name>name</name> <descript>this is ver 2</descript> <version>1</version> </optlockType> </srvc:theInstance> </srvc:update_optlockType> </env:Body> </env:Envelope>
Without the OptimisticLockingPolicy, the update ("this is ver 2") would overwrite the committed data of version 2.
Exception [EclipseLink-5010] (Eclipse Persistence Services - @VERSION@.@QUALIFIER@): org.eclipse.persistence.exceptions.OptimisticLockException Exception Description: The object [{Optlock 1}] cannot be merged because it has changed or been deleted since it was last read. Class> optlocktest.Optlock
There are a number of '5xxx' error codes:
NO_VERSION_NUMBER_WHEN_DELETING = 5001; OBJECT_CHANGED_SINCE_LAST_READ_WHEN_DELETING = 5003; NO_VERSION_NUMBER_WHEN_UPDATING = 5004; OBJECT_CHANGED_SINCE_LAST_READ_WHEN_UPDATING = 5006; MUST_HAVE_MAPPING_WHEN_IN_OBJECT = 5007; NEED_TO_MAP_JAVA_SQL_TIMESTAMP = 5008; UNWRAPPING_OBJECT_DELETED_SINCE_LAST_READ = 5009; OBJECT_CHANGED_SINCE_LAST_MERGE = 5010; STATEMENT_NOT_EXECUTED_IN_BATCH = 5011;
When the DBWSBuilder utility scans the meta-data for a table, if it finds a column called VERSION, it will automatically augment the OR Project's descriptor for that table with a VersionLockingPolicy keyed to that field. However, if the user wishes to change the name of the 'magic' Optimistic Lock field, a custom NamingConventionTransformer can be used:
import org.eclipse.persistence.tools.dbws.DefaultNamingConventionTransformer; public class CustomOptLockFieldNamingConventionTransformer extends DefaultNamingConventionTransformer { // lock field name is not // org.eclipse.persistence.tools.dbws.NamingConventionTransformer.DEFAULT_OPTIMISTIC_LOCKING_FIELD @Override public String getOptimisticLockingField() { return "VER"; } }