Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

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

m
m
 
(13 intermediate revisions by 2 users not shown)
Line 1: Line 1:
{{EclipseLink_API
+
{{EclipseLink_UserGuide
|1=*[http://www.eclipse.org/eclipselink/api/ org.eclipse.persistence.platform.database.DatabasePlatform]
+
|info=y
|2=*[http://www.eclipse.org/eclipselink/api/ org.eclipse.persistence.database.platform.converters.StructConverter]
+
|api=y
 +
|apis=
 +
*[http://www.eclipse.org/eclipselink/api/latest/org/eclipse/persistence/platform/database/DatabasePlatform.html @DatabasePlatform]
 +
*[http://www.eclipse.org/eclipselink/api/latest/org/eclipse/persistence/annotations/StructConverter.html @StructConverter]
 
}}
 
}}
=@StructConverter Annotation=
 
  
The <tt>@StructConverter</tt> is an EclipseLink-specific annotation. You can add it to an <tt>org.eclipse.persistence.platform.database.DatabasePlatform</tt> using its <tt>addStructConverter</tt> method to enable custom processing of <tt>java.sql.Struct</tt> types.
+
=@StructConverter=
 +
 
 +
<tt>@StructConverter</tt> is an EclipseLink-specific annotation. You can add it to an <tt>org.eclipse.persistence.platform.database.DatabasePlatform</tt> using its <tt>addStructConverter</tt> method to enable custom processing of <tt>java.sql.Struct</tt> types.
 
<source lang="java">  
 
<source lang="java">  
 
  @Target({TYPE, METHOD, FIELD})
 
  @Target({TYPE, METHOD, FIELD})
Line 14: Line 18:
 
  }
 
  }
 
</source>
 
</source>
This table lists attributes of the <tt>@StructConverter</tt> annotation.
 
  
<span id="Table 19-10"></span>
+
{{EclipseLink_AttributeTable
{| class="RuleFormalWideMax" dir="ltr" title="Attributes of the @StructConverter Annotation" summary="Lists attributes of the @StructConverter annotation" width="100%" border="1" frame="border" rules="all" cellpadding="3" frame="border" rules="all"
+
|caption=@StructConverter Annotation Attributes
|- align="left" valign="top"
+
|content=<tr>
! id="r1c1-t15" align="left" valign="bottom" | '''Attribute'''
+
<td>'''<tt>name</tt>'''</td>
! id="r1c2-t15" align="left" valign="bottom" | '''Description'''
+
<td>The <tt>String</tt> name for your converter. Ensure that this name is unique across the persistence unit.</td>
! id="r1c3-t15" align="left" valign="bottom" | '''Default'''
+
<td></td>
! id="r1c4-t15" align="left" valign="bottom" | '''Required or Optional'''
+
<td>Yes</td>
|- align="left" valign="top"
+
</tr>
| id="r2c1-t15" headers="r1c1-t15" align="left" |
+
<tr>
<tt>name</tt>
+
<td>'''<tt>converter</tt>'''</td>
| headers="r2c1-t15 r1c2-t15" align="left" |
+
<td>The converter class as a <tt>String</tt>. This class must implement the EclipseLink <tt>org.eclipse.persistence.mappings.converters.Converter</tt> interface.</td>
Set this attribute to the <tt>String</tt> name for your converter. Ensure that this name is unique across the persistence unit.
+
<td></td>
| headers="r2c1-t15 r1c3-t15" align="left" |
+
<td>Yes</td>
no default
+
</tr>
| headers="r2c1-t15 r1c4-t15" align="left" |
+
}}
required
+
|- align="left" valign="top"
+
| id="r3c1-t15" headers="r1c1-t15" align="left" |
+
<tt>converter</tt>
+
| headers="r3c1-t15 r1c2-t15" align="left" |
+
Set this attribute to the converter class as a <tt>String</tt>. This class must implement the EclipseLink <tt>org.eclipse.persistence.mappings.converters.Converter</tt> interface.
+
| headers="r3c1-t15 r1c3-t15" align="left" |
+
no default
+
| headers="r3c1-t15 r1c4-t15" align="left" |
+
required
+
|}
+
  
  
This example shows how to define the <tt>@StructConverter</tt>.
+
The following example shows how to define the <tt>@StructConverter</tt>.
  
<span id="Example 19-10"></span>
+
<span id="Example: @StructConverter Annotation"></span>
''''' Defining the @StructConverter'''''
+
======''Example: @StructConverter Annotation''======
 
<source lang="java">
 
<source lang="java">
 
  @StructConverter(name="MyType",
 
  @StructConverter(name="MyType",
Line 57: Line 49:
 
EclipseLink will throw an exception if you add more than one <tt>StructConverter</tt> that affects the same Java type.
 
EclipseLink will throw an exception if you add more than one <tt>StructConverter</tt> that affects the same Java type.
  
A <tt>@StructConverter</tt> exists in the same namespaces as <tt>[[#How to Use the @Converter Annotation|@Converter]]</tt>. EclipseLink will throw a validation exception if you add a <tt>Converter</tt> and a <tt>StructConverter</tt> of the same name.
+
A <tt>@StructConverter</tt> exists in the same namespaces as <tt>@Converter</tt>. EclipseLink will throw a validation exception if you add a <tt>Converter</tt> and a <tt>StructConverter</tt> of the same name.
 
{{EclipseLink_Note
 
{{EclipseLink_Note
|note=You can also configure structure converters in a <tt>sessions.xml</tt> file (see [[#What You May Need to Know About EclipseLink JPA Overriding Mechanisms|What You May Need to Know About EclipseLink JPA Overriding Mechanisms]]).}}
+
|note=You can also configure structure converters in a <tt>sessions.xml</tt> file.}}
 
+
  
  
 
==Using Structure Converters to Configure Mappings==
 
==Using Structure Converters to Configure Mappings==
  
In EclipseLink, a <tt>DatabasePlatform</tt> (see [[Introduction%20to%20Data%20Access%20(ELUG)#Database Platforms|Database Platforms]]) holds a structure converter. An <tt>org.eclipse.persistence.database.platform.converters.StructConverter</tt> affects all objects of a particular type read into the <tt>Session</tt> that has that <tt>DatabasePlatform</tt>. This prevents you from configuring the <tt>StructConverter</tt> on a mapping-by-mapping basis. To configure mappings that use the <tt>StructConverter</tt>, you call their <tt>setFieldType(java.sql.Types.STRUCT)</tt> method. You must call this method on all mappings that the <tt>StructConverter</tt> will affect – if you do not call it, errors might occur.
+
In EclipseLink, a <tt>DatabasePlatform</tt> holds a structure converter. An <tt>org.eclipse.persistence.database.platform.converters.StructConverter</tt> affects all objects of a particular type read into the <tt>Session</tt> that has that <tt>DatabasePlatform</tt>. This prevents you from configuring the <tt>StructConverter</tt> on a mapping-by-mapping basis. To configure mappings that use the <tt>StructConverter</tt>, you call their <tt>setFieldType(java.sql.Types.STRUCT)</tt> method. You must call this method on all mappings that the <tt>StructConverter</tt> will affect – if you do not call it, errors might occur.
  
The JPA specification requires all <tt>@Basic</tt> mappings (see [[Introduction%20to%20EclipseLink%20JPA%20(ELUG)#@Basic|@Basic]]) that map to a non-primitive or a non-primitive-wrapper type have a serialized converter added to them. This enables certain <tt>STRUCT</tt> types to map to a field without serialization.
+
The JPA specification requires all <tt>@Basic</tt> mappings that map to a non-primitive or a non-primitive-wrapper type have a serialized converter added to them. This enables certain <tt>STRUCT</tt> types to map to a field without serialization.
  
You can use the existing <tt>[[#How to Use the @Convert Annotation|@Convert]]</tt> annotation with its <tt>value</tt> attribute set to the <tt>StructConverter</tt> name – in this case, EclipseLink will apply appropriate settings to the mapping. This setting will be required on all mappings that use a type for which a <tt>StructConverter</tt> has been defined. Failing to configure the mapping with the <tt>@Convert</tt> will cause an error.
+
You can use the existing <tt>@Convert</tt> annotation with its <tt>value</tt> attribute set to the <tt>StructConverter</tt> name – in this case, EclipseLink will apply appropriate settings to the mapping. This setting will be required on all mappings that use a type for which a <tt>StructConverter</tt> has been defined. Failing to configure the mapping with the <tt>@Convert</tt> will cause an error.
  
For more information, see the following:
 
* [[Introduction%20to%20Object-Relational%20Data%20Type%20Mappings%20(ELUG)#Object-Relational Data Type Structure Mapping|Object-Relational Data Type Structure Mapping]]
 
* [[Introduction%20to%20Object-Relational%20Data%20Type%20Descriptors%20(ELUG)|Object-Relational Data Type Descriptors]]
 
  
  
Line 79: Line 67:
 
{{EclipseLink_JPA
 
{{EclipseLink_JPA
 
|previous=[[EclipseLink/UserGuide/JPA/Basic_JPA_Development/Mapping/Basic_Mappings/Default_Conversions_and_Converters/ObjectTypeConverter|@ObjectTypeConverter]]
 
|previous=[[EclipseLink/UserGuide/JPA/Basic_JPA_Development/Mapping/Basic_Mappings/Default_Conversions_and_Converters/ObjectTypeConverter|@ObjectTypeConverter]]
|next=[[EclipseLink/UserGuide/JPA/Basic_JPA_Development/Mapping/Basic_Mappings/Default_Conversions_and_Converters/Converter/Convert|@Convert]]
+
|next=[[EclipseLink/UserGuide/JPA/Basic JPA Development/Mapping/Basic Mappings/Default Conversions and Converters/Convert|@Convert]]
 
|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.1.0
 
}}
 
}}

Latest revision as of 10:08, 5 May 2011


Eclipselink-logo.gif
EclipseLink
Website
Download
Community
Mailing ListForumsIRCmattermost
Issues
OpenHelp WantedBug Day
Contribute
Browse Source


@StructConverter

@StructConverter is an EclipseLink-specific annotation. You can add it to an org.eclipse.persistence.platform.database.DatabasePlatform using its addStructConverter method to enable custom processing of java.sql.Struct types.

 
 @Target({TYPE, METHOD, FIELD})
 @Retention(RUNTIME)
 public @interface StructConverter {
    String name();
    String converter(); 
 }
@StructConverter Annotation Attributes
Attribute Description Default Required?
name The String name for your converter. Ensure that this name is unique across the persistence unit. Yes
converter The converter class as a String. This class must implement the EclipseLink org.eclipse.persistence.mappings.converters.Converter interface. Yes


The following example shows how to define the @StructConverter.

Example: @StructConverter Annotation
 @StructConverter(name="MyType",
     converter="myproject.converters.MyStructConverter")

You can specify the @StructConverter annotation anywhere in an Entity with the scope being the whole session.

EclipseLink will throw an exception if you add more than one StructConverter that affects the same Java type.

A @StructConverter exists in the same namespaces as @Converter. EclipseLink will throw a validation exception if you add a Converter and a StructConverter of the same name.

Elug note icon.png

Note: You can also configure structure converters in a sessions.xml file.


Using Structure Converters to Configure Mappings

In EclipseLink, a DatabasePlatform holds a structure converter. An org.eclipse.persistence.database.platform.converters.StructConverter affects all objects of a particular type read into the Session that has that DatabasePlatform. This prevents you from configuring the StructConverter on a mapping-by-mapping basis. To configure mappings that use the StructConverter, you call their setFieldType(java.sql.Types.STRUCT) method. You must call this method on all mappings that the StructConverter will affect – if you do not call it, errors might occur.

The JPA specification requires all @Basic mappings that map to a non-primitive or a non-primitive-wrapper type have a serialized converter added to them. This enables certain STRUCT types to map to a field without serialization.

You can use the existing @Convert annotation with its value attribute set to the StructConverter name – in this case, EclipseLink will apply appropriate settings to the mapping. This setting will be required on all mappings that use a type for which a StructConverter has been defined. Failing to configure the mapping with the @Convert will cause an error.



Eclipselink-logo.gif
Version: 2.1.0
Other versions...

Copyright © Eclipse Foundation, Inc. All Rights Reserved.