View source for EclipseLink/UserGuide/JPA/Basic JPA Development/Mapping/Basic Mappings/Default Conversions and Converters/StructConverter

{{EclipseLink_UserGuide
|info=y
|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=

<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"> 
 @Target({TYPE, METHOD, FIELD})
 @Retention(RUNTIME)
 public @interface StructConverter {
    String name();
    String converter(); 
 }
</source>

{{EclipseLink_AttributeTable
|caption=@StructConverter Annotation Attributes
|content=<tr>
 <td>'''<tt>name</tt>'''</td>
 <td>The <tt>String</tt> name for your converter. Ensure that this name is unique across the persistence unit.</td>
 <td></td>
 <td>Yes</td>
</tr>
<tr>
 <td>'''<tt>converter</tt>'''</td>
 <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>
 <td></td>
 <td>Yes</td>
</tr>
}}


The following example shows how to define the <tt>@StructConverter</tt>.

<span id="Example: @StructConverter Annotation"></span>
======''Example: @StructConverter Annotation''======
<source lang="java">
 @StructConverter(name="MyType",
     converter="myproject.converters.MyStructConverter")
</source>

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

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>@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
|note=You can also configure structure converters in a <tt>sessions.xml</tt> file.}}


==Using Structure Converters to Configure Mappings==

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 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>@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.




{{EclipseLink_JPA
|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/Convert|@Convert]]
|up=[[EclipseLink/UserGuide/JPA/Basic_JPA_Development/Mapping/Basic_Mappings/Default_Conversions_and_Converters|Default Conversions and Converters]]
|version=2.1.0
}}