Difference between revisions of "EclipseLink/Examples/DBWS/DBWSIntermediateAttribute"

From Eclipsepedia

Jump to: navigation, search
 
(19 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 +
<css>
 +
  .source-java5 {padding:4px;border:1px solid black; background-color: white;}
 +
  .source-xml {padding:4px;border:1px solid black; background-color: white;}
 +
  .source-text {padding:4px;border:1px solid black; background-color: white;}
 +
</css>
 +
__NOTOC__
 +
 
== Naming Convention for schema elements ==
 
== Naming Convention for schema elements ==
 
As seen in the Basic Table example, the {{:EclipseLink/Examples/DBWS/DBWSBasicTable#gen_schema}}
 
As seen in the Basic Table example, the {{:EclipseLink/Examples/DBWS/DBWSBasicTable#gen_schema}}
 
Converting the database metadata into the names of <element-tag>'s is the job of <code>o.e.p.tools.dbws.NamingConventionTransformer</code>'s
 
Converting the database metadata into the names of <element-tag>'s is the job of <code>o.e.p.tools.dbws.NamingConventionTransformer</code>'s
<source lang="java5" enclose="div">
+
<source lang="java5">
 
public interface NamingConventionTransformer {
 
public interface NamingConventionTransformer {
  
Line 17: Line 24:
 
</source>
 
</source>
  
In the <tt>eclipselink-dbwsutils.jar</tt>, there are built-in transformers that form a [http://en.wikipedia.org/wiki/Chain-of-responsibility_pattern <i>Chain-of-Responsibility</i>]
+
In the <tt>eclipselink-dbwsutils.jar</tt>, the built-in transformers form a [http://en.wikipedia.org/wiki/Chain-of-responsibility_pattern <i>Chain-of-Responsibility</i>]
 
+
 
[[Image:NCTChainOfResponsibility.png|650px]]
 
[[Image:NCTChainOfResponsibility.png|650px]]
<br clear="all"/>
+
<br/>
 
+
<br/>
 
In the <tt>o.e.p.tools.dbws.NamingConventionTransformer</tt> services file, the transformer chain is listed in order:
 
In the <tt>o.e.p.tools.dbws.NamingConventionTransformer</tt> services file, the transformer chain is listed in order:
 
<source lang="text" enclose="div">
 
<source lang="text" enclose="div">
Line 37: Line 43:
 
</source>
 
</source>
  
=== Changing an <element-tag> to an "attrib
+
=== User-Provided NamingConventionTransformer ===
It is possible to change an <element-tag> to an "attribute" with a custom transformer:
+
It is possible to change an <element-tag> to an "attribute" with a custom transformer. The user sub-classes <tt>o.e.p.tools.dbws.DefaultNamingConventionTransformer</tt>. <br/>
 +
For example, given the table <tt>SIMPLE_TABLE</tt>
 +
<source lang=sql enclose="div">
 +
CREATE TABLE SIMPLE_TABLE (
 +
  ID NUMERIC NOT NULL,
 +
  NAME VARCHAR(25),
 +
  SINCE DATE,
 +
  PRIMARY KEY (ID)
 +
)
 +
</source> the following <code>NamingConventionTransformer</code> will:
 +
* name the schema element '<tt>simple</tt>'
 +
* make the element names lowercase
 +
* have the <tt>ID</tt> field represented as an attribute
 +
<source lang=java5>
 +
package foo.bar.blah;
 +
 
 +
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;
 +
        }
 +
        return ELEMENT;
 +
    }
 +
}
 +
</source>
 +
produces the schema:
 +
<source lang=xml enclose="div">
 +
<?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:element name="since" type="xsd:date" 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 custom transformer 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="text" enclose="div">
 +
customtransformer.jar
 +
 +
+---META-INF
 +
|  |  MANIFEST.MF
 +
|  | 
 +
|  \---services
 +
|          org.eclipse.persistence.tools.dbws.NamingConventionTransformer
 +
            contains 1 line:
 +
              foo.bar.blah.MyNamingConventionTransformer
 +
|         
 +
\---foo
 +
    \---bar
 +
        \---blah
 +
            |  MyNamingConventionTransformer.class
 +
</source>
 +
<br />
 +
<b>NB</b> - the custom transformer's <tt>customtransformer.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 <code>DBWSBuilder</code> utility. In addition, the <code>DBWSBuilder</code> utility <b>always</b> re-builds the <i>Chain-of-Responsibility</i> with the <tt>SQLX2003Transformer</tt> at the end to ensure that any transformer, default or custom, produces legal characters according to the SQL/X(2003) specification.
 +
 
 +
[[Category:EclipseLink/Example/DBWS]]

Latest revision as of 10:06, 7 October 2010


[edit] Naming Convention for schema elements

As seen in the Basic Table example, the DBWSBuilder-generated eclipselink-dbws-schema.xsd file derives <element-tag> names from the Database table metadata:

<?xml version="1.0" encoding="UTF-8"?>
<xsd:schema
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xmlns:xsd="http://www.w3.org/2001/XMLSchema"
 >
  <xsd:complexType name="empType">
    <xsd:sequence>
      <xsd:element name="empno" type="xsd:int" xsi:nil="false"/>
      <xsd:element name="ename" type="xsd:string" xsi:nil="true"/>
      <xsd:element name="job" type="xsd:string" xsi:nil="true"/>
      <xsd:element name="mgr" type="xsd:int" minOccurs="0" xsi:nil="true"/>
      <xsd:element name="hiredate" type="xsd:dateTime" xsi:nil="true"/>
      <xsd:element name="sal" type="xsd:decimal" xsi:nil="true"/>
      <xsd:element name="comm" type="xsd:int" minOccurs="0" xsi:nil="true"/>
      <xsd:element name="deptno" type="xsd:int" xsi:nil="true"/>
    </xsd:sequence>
  </xsd:complexType>
</xsd:schema>

Converting the database metadata into the names of <element-tag>'s is the job of o.e.p.tools.dbws.NamingConventionTransformer's

public interface NamingConventionTransformer {
 
    public enum ElementStyle {
        ELEMENT, ATTRIBUTE, NONE
    };
 
    public String generateSchemaName(String tableName);
 
    public String generateElementAlias(String originalElementName);
 
    public ElementStyle styleForElement(String originalElementName);
}

In the eclipselink-dbwsutils.jar, the built-in transformers form a Chain-of-Responsibility NCTChainOfResponsibility.png

In the o.e.p.tools.dbws.NamingConventionTransformer services file, the transformer chain is listed in order:

eclipselink-dbwsutils.jar
|  
+---META-INF
|   |   MANIFEST.MF
|   |  
|   \---services
|           org.eclipse.persistence.tools.dbws.NamingConventionTransformer
            contains 3 lines:
              org.eclipse.persistence.tools.dbws.ToLowerTransformer
              org.eclipse.persistence.tools.dbws.TypeSuffixTransformer
              org.eclipse.persistence.tools.dbws.SQLX2003Transformer

[edit] User-Provided NamingConventionTransformer

It is possible to change an <element-tag> to an "attribute" with a custom transformer. The user sub-classes o.e.p.tools.dbws.DefaultNamingConventionTransformer.
For example, given the table SIMPLE_TABLE

CREATE TABLE SIMPLE_TABLE (
  ID NUMERIC NOT NULL,
  NAME VARCHAR(25),    
  SINCE DATE,
  PRIMARY KEY (ID)
)
the following NamingConventionTransformer will:
  • name the schema element 'simple'
  • make the element names lowercase
  • have the ID field represented as an attribute
package foo.bar.blah;
 
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;
        }
        return ELEMENT;
    }
}

produces the schema:

<?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:element name="since" type="xsd:date" 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 custom transformer 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:

customtransformer.jar
|  
+---META-INF
|   |   MANIFEST.MF
|   |  
|   \---services
|           org.eclipse.persistence.tools.dbws.NamingConventionTransformer
            contains 1 line:
              foo.bar.blah.MyNamingConventionTransformer
|          
\---foo
    \---bar
        \---blah
            |   MyNamingConventionTransformer.class


NB - the custom transformer's customtransformer.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 re-builds the Chain-of-Responsibility with the SQLX2003Transformer at the end to ensure that any transformer, default or custom, produces legal characters according to the SQL/X(2003) specification.