|
|
| Line 1: |
Line 1: |
| − | {{EclipseLink_API
| |
| − | |1=*[http://www.eclipse.org/eclipselink/api/ org.eclipse.persistence.platform.database.DatabasePlatform]
| |
| − | |2=*[http://www.eclipse.org/eclipselink/api/ org.eclipse.persistence.database.platform.converters.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.
| |
| − | <source lang="java">
| |
| − | @Target({TYPE, METHOD, FIELD})
| |
| − | @Retention(RUNTIME)
| |
| − | public @interface StructConverter {
| |
| − | String name();
| |
| − | String converter();
| |
| − | }
| |
| − | </source>
| |
| − | This table lists attributes of the <tt>@StructConverter</tt> annotation.
| |
| − |
| |
| − | <span id="Table 19-10"></span>
| |
| − | {| 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"
| |
| − | |- align="left" valign="top"
| |
| − | ! id="r1c1-t15" align="left" valign="bottom" | '''Attribute'''
| |
| − | ! id="r1c2-t15" align="left" valign="bottom" | '''Description'''
| |
| − | ! id="r1c3-t15" align="left" valign="bottom" | '''Default'''
| |
| − | ! id="r1c4-t15" align="left" valign="bottom" | '''Required or Optional'''
| |
| − | |- align="left" valign="top"
| |
| − | | id="r2c1-t15" headers="r1c1-t15" align="left" |
| |
| − | <tt>name</tt>
| |
| − | | headers="r2c1-t15 r1c2-t15" align="left" |
| |
| − | Set this attribute to the <tt>String</tt> name for your converter. Ensure that this name is unique across the persistence unit.
| |
| − | | headers="r2c1-t15 r1c3-t15" align="left" |
| |
| − | no default
| |
| − | | 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>.
| |
| − |
| |
| − | <span id="Example 19-10"></span>
| |
| − | ''''' Defining the @StructConverter'''''
| |
| − | <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>[[#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.
| |
| − | {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]]).}}
| |
| − |
| |
| − |
| |
| − |
| |
| − | ==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.
| |
| − |
| |
| − | 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.
| |
| − |
| |
| − | 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.
| |
| − |
| |
| − | 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]]
| |
| − |
| |
| − |
| |
| − |
| |
| − | {{EclipseLink_JPA
| |
| − | |previous=[[EclipseLink/UserGuide/JPA/Basic_JPA_Development/Mapping/Basic_Mappings/Default_Conversions_and_Converters/Converter|@TypeConverter]]
| |
| − | |next=[[EclipseLink/UserGuide/JPA/Basic_JPA_Development/Mapping/Basic_Mappings/Default_Conversions_and_Converters/Converter/StructConverter|@StructConveter]]
| |
| − | |up=[[EclipseLink/UserGuide/JPA/Basic_JPA_Development/Mapping/Basic_Mappings/Default_Conversions_and_Converters|Default Conversions and Converters]]
| |
| − | |version=2.1.0
| |
| − | }}
| |
