Difference between revisions of "EclipseLink/UserGuide/JPA/Basic JPA Development/Mapping/Basic Mappings/Default Conversions and Converters/ObjectTypeConverter"

From Eclipsepedia

Jump to: navigation, search
m
m
 
(7 intermediate revisions by 2 users not shown)
Line 1: Line 1:
{{EclipseLink_UserGuide}}
+
{{EclipseLink_UserGuide
{{EclipseLink_API
+
|info=y
|1=*[http://www.eclipse.org/eclipselink/api/ org.eclipse.persistence.mappings.converters.ObjectTypeConverter]
+
|api=y
 +
|apis=
 +
*[http://www.eclipse.org/eclipselink/api/latest/org/eclipse/persistence/annotations/ObjectTypeConverter.html @ObjectTypeConverter]
 
}}
 
}}
=@ObjectTypeConverter Annotation and <object-type-converter> XML=
+
=@ObjectTypeConverter=
  
 
You can use the <tt>@ObjectTypeConverter</tt> annotation to specify an <tt>org.eclipse.persistence.mappings.converters.ObjectTypeConverter</tt> that converts a fixed number of database data value(s) to Java object value(s) during the reading and writing of a mapped attribute.
 
You can use the <tt>@ObjectTypeConverter</tt> annotation to specify an <tt>org.eclipse.persistence.mappings.converters.ObjectTypeConverter</tt> that converts a fixed number of database data value(s) to Java object value(s) during the reading and writing of a mapped attribute.
Line 17: Line 19:
 
  }
 
  }
 
</source>
 
</source>
This table lists attributes of the <tt>@ObjectTypeConverter</tt> annotation.
 
  
<span id="Table 19-9"></span>
+
{{EclipseLink_AttributeTable
{| class="RuleFormalWideMax" dir="ltr" title="Attributes of the @ObjectTypeConverter Annotation" summary="This table lists the attributes of EclipseLink JPA @ObjectTypeConverter annotation" width="100%" border="1" frame="border" rules="all" cellpadding="3" frame="border" rules="all"
+
|caption=<span>@ObjectTypeConverter Annotation Attributes</span>
|- align="left" valign="top"
+
|content=
! id="r1c1-t14" align="left" valign="bottom" | '''Attribute'''
+
<tr>
! id="r1c2-t14" align="left" valign="bottom" | '''Description'''
+
<td>'''<tt>name</tt>'''</td>
! id="r1c3-t14" align="left" valign="bottom" | '''Default'''
+
<td>Set this attribute to the <tt>String</tt> name for your converter. Ensure that this name is unique across the persistence unit</td>
! id="r1c4-t14" align="left" valign="bottom" | '''Required or Optional'''
+
<td>no default</td>
|- align="left" valign="top"
+
<td>required</td>
| id="r2c1-t14" headers="r1c1-t14" align="left" |
+
</tr>
<tt>name</tt>
+
<tr>
| headers="r2c1-t14 r1c2-t14" align="left" |
+
<td>'''<tt>dataType</tt>'''</td>
Set this attribute to the <tt>String</tt> name for your converter. Ensure that this name is unique across the persistence unit
+
<td>Set this attribute to the type stored in the database.</td>
| headers="r2c1-t14 r1c3-t14" align="left" |
+
<td><tt>void.class</tt><sup>1</sup></td>
no default
+
<td>optional</td>
| headers="r2c1-t14 r1c4-t14" align="left" |
+
</tr>
required
+
<tr>
|- align="left" valign="top"
+
<td>'''<tt>objectType</tt>'''</td>
| id="r3c1-t14" headers="r1c1-t14" align="left" |
+
<td>Set the value of this attribute to the type stored on the entity.</td>
<tt>dataType</tt>
+
<td><tt>void.class</tt><sup>1</sup></td>
| headers="r3c1-t14 r1c2-t14" align="left" |
+
<td>optional</td>
Set this attribute to the type stored in the database.
+
</tr>
| headers="r3c1-t14 r1c3-t14" align="left" |
+
<tr>
<tt>void.class</tt><sup>1</sup>
+
<td>'''<tt>conversionValues</tt>'''</td>
| headers="r3c1-t14 r1c4-t14" align="left" |
+
<td>Set the value of this attribute to the array of conversion values (instances of <tt>ConversionValue</tt><nowiki>: </nowiki><tt>String objectValue</tt> and <tt>String dataValue</tt>. See the [[#Example: @ObjectTypeConverter Annotation|@ObjectTypeConverter Annotation]] example, to be used with the object converter.</td>
optional
+
<td>no default</td>
|- align="left" valign="top"
+
<td>required</td>
| id="r4c1-t14" headers="r1c1-t14" align="left" |
+
</tr>
<tt>objectType</tt>
+
<tr>
| headers="r4c1-t14 r1c2-t14" align="left" |
+
<td>'''<tt>defaultObjectValue</tt>'''</td>
Set the value of this attribute to the type stored on the entity.
+
<td>Set the value of this attribute to the default object value. Note that this argument is for dealing with legacy data if the data value is missing.</td>
| headers="r4c1-t14 r1c3-t14" align="left" |
+
<td>empty <tt>String</tt></td>
<tt>void.class</tt><sup>1</sup>
+
<td>optional</td>
| headers="r4c1-t14 r1c4-t14" align="left" |
+
</tr>
optional
+
}}
|- align="left" valign="top"
+
 
| id="r5c1-t14" headers="r1c1-t14" align="left" |
+
<tt>conversionValues</tt>
+
| headers="r5c1-t14 r1c2-t14" align="left" |
+
Set the value of this attribute to the array of conversion values (instances of <tt>ConversionValue</tt><nowiki>: </nowiki><tt>String objectValue</tt> and <tt>String dataValue</tt>. See the [[#Example 19-9| Usage of the @ObjectTypeConverter Annotation]] example, to be used with the object converter.
+
| headers="r5c1-t14 r1c3-t14" align="left" |
+
no default
+
| headers="r5c1-t14 r1c4-t14" align="left" |
+
required
+
|- align="left" valign="top"
+
| id="r6c1-t14" headers="r1c1-t14" align="left" |
+
<tt>defaultObjectValue</tt>
+
| headers="r6c1-t14 r1c2-t14" align="left" |
+
Set the value of this attribute to the default object value. Note that this argument is for dealing with legacy data if the data value is missing.
+
| headers="r6c1-t14 r1c3-t14" align="left" |
+
empty <tt>String</tt>
+
| headers="r6c1-t14 r1c4-t14" align="left" |
+
optional
+
|}
+
 
<br><sup>1</sup> The default is inferred from the type of the persistence field or property.
 
<br><sup>1</sup> The default is inferred from the type of the persistence field or property.
  
This example shows how to use the <tt>@ObjectTypeConverter</tt> annotation to specify the <tt>Employee</tt> field <tt>gender</tt>.
+
The following example shows how to use the <tt>@ObjectTypeConverter</tt> annotation to specify the <tt>Employee</tt> field <tt>gender</tt>.
  
<span id="Example 19-9"></span>
+
<span id="Example: @ObjectTypeConverter Annotation"></span>
''''' @ObjectTypeConverter Annotation'''''
+
======''Example: @ObjectTypeConverter Annotation''======
 
<source lang="java">
 
<source lang="java">
 
  public class Employee implements Serializable{
 
  public class Employee implements Serializable{
Line 97: Line 80:
 
</source>
 
</source>
  
<span>''''' <object-type-converter> XML'''''</span>
+
You can use the <tt><object-type-converter></tt> element in the deployment descriptor as an alternative to using the <tt>@ObjectTypeConverter</tt> annotation in the source code, as shown in the following example:
 +
 
 +
======''Example: <object-type-converter> Element ''======
 
<source lang="xml">
 
<source lang="xml">
 
   <object-type-converter name="gender-converter"
 
   <object-type-converter name="gender-converter"
Line 110: Line 95:
  
 
{{EclipseLink_JPA
 
{{EclipseLink_JPA
|previous=[[EclipseLink/UserGuide/JPA/Basic_JPA_Development/Mapping/Basic_Mappings/Default_Conversions_and_Converters/TypeConverter|Type Converter]]
+
|previous=[[EclipseLink/UserGuide/JPA/Basic_JPA_Development/Mapping/Basic_Mappings/Default_Conversions_and_Converters/TypeConverter|@TypeConverter]]
|next=[[EclipseLink/UserGuide/JPA/Basic_JPA_Development/Mapping/Basic_Mappings/Default_Conversions_and_Converters/StructConverter|Struct Converter]]
+
|next=[[EclipseLink/UserGuide/JPA/Basic_JPA_Development/Mapping/Basic_Mappings/Default_Conversions_and_Converters/StructConverter|@StructConverter]]
 
|up=[[EclipseLink/UserGuide/JPA/Basic_JPA_Development/Mapping/Basic_Mappings/Default_Conversions_and_Converters|Default Conversions and Converters]]
 
|up=[[EclipseLink/UserGuide/JPA/Basic_JPA_Development/Mapping/Basic_Mappings/Default_Conversions_and_Converters|Default Conversions and Converters]]
|version=2.1.0
+
|version=2.2.0 DRAFT
 
}}
 
}}

Latest revision as of 10:05, 5 May 2011


link="http://wiki.eclipse.org/EclipseLink"
EclipseLink
Website
Download
Community
Mailing ListForumsIRC
Bugzilla
Open
Help Wanted
Bug Day
Contribute
Browse Source

[edit] @ObjectTypeConverter

You can use the @ObjectTypeConverter annotation to specify an org.eclipse.persistence.mappings.converters.ObjectTypeConverter that converts a fixed number of database data value(s) to Java object value(s) during the reading and writing of a mapped attribute.

 @Target({TYPE, METHOD, FIELD})
 @Retention(RUNTIME)
 public @interface ObjectTypeConverter {
    String name();
    Class dataType() default void.class;
    Class objectType() default void.class;
    ConversionValue[] conversionValues();
    String defaultObjectValue() default "";
 }
@ObjectTypeConverter Annotation Attributes
Attribute Description Default Required?
name Set this attribute to the String name for your converter. Ensure that this name is unique across the persistence unit no default required
dataType Set this attribute to the type stored in the database. void.class1 optional
objectType Set the value of this attribute to the type stored on the entity. void.class1 optional
conversionValues Set the value of this attribute to the array of conversion values (instances of ConversionValue: String objectValue and String dataValue. See the @ObjectTypeConverter Annotation example, to be used with the object converter. no default required
defaultObjectValue Set the value of this attribute to the default object value. Note that this argument is for dealing with legacy data if the data value is missing. empty String optional


1 The default is inferred from the type of the persistence field or property.

The following example shows how to use the @ObjectTypeConverter annotation to specify the Employee field gender.

[edit] Example: @ObjectTypeConverter Annotation
 public class Employee implements Serializable{
     ...
     @ObjectTypeConverter (
         name="genderConverter",
         dataType=java.lang.String.class,
         objectType=java.lang.String.class,
         conversionValues={
             @ConversionValue(dataValue="F", objectValue="Female"),
             @ConversionValue(dataValue="M", objectValue="Male")}
     )
     @Convert("genderConverter")
     public String getGender() {
         return gender;
     }
     ...
 }

You can use the <object-type-converter> element in the deployment descriptor as an alternative to using the @ObjectTypeConverter annotation in the source code, as shown in the following example:

[edit] Example: <object-type-converter> Element
  <object-type-converter name="gender-converter"
	object-type="model.Gender" data-type="java.lang.String">
	<conversion-value object-value="Male" data-value="M" />
	<conversion-value object-value="Female" data-value="F" />
  </object-type-converter>



Eclipselink-logo.gif
Version: 2.2.0 DRAFT
Other versions...