Jump to: navigation, search

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

m
m
Line 3: Line 3:
 
|2=*[http://www.eclipse.org/eclipselink/api/ org.eclipse.persistence.database.platform.converters.StructConverter]
 
|2=*[http://www.eclipse.org/eclipselink/api/ org.eclipse.persistence.database.platform.converters.StructConverter]
 
}}
 
}}
=@StructConverter Annotation=
+
=@StructConverter Annotation and <struct-converter> XML=
  
 
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.
 
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.
Line 78: Line 78:
  
 
{{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|ObjectType Converter]]
|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/Converter/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
 
}}
 
}}

Revision as of 14:14, 17 June 2010


Elug api package icon.png Key API {{{apis}}}

@StructConverter Annotation and <struct-converter> XML

The @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(); 
 }

This table lists attributes of the @StructConverter annotation.

Attribute Description Default Required or Optional

name

Set this attribute to the String name for your converter. Ensure that this name is unique across the persistence unit.

no default

required

converter

Set this attribute to the converter class as a String. This class must implement the EclipseLink org.eclipse.persistence.mappings.converters.Converter interface.

no default

required


This example shows how to define the @StructConverter.

Defining the @StructConverter

 @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 (see What You May Need to Know About EclipseLink JPA Overriding Mechanisms).


Using Structure Converters to Configure Mappings

In EclipseLink, a DatabasePlatform (see Database Platforms) 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 (see @Basic) 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.

For more information, see the following:


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