javax.persistence.Convert Maven / Gradle / Ivy
Show all versions of jakarta.persistence-api Show documentation
/*
* Copyright (c) 2011, 2019 Oracle and/or its affiliates. All rights reserved.
*
* This program and the accompanying materials are made available under the
* terms of the Eclipse Public License v. 2.0 which is available at
* http://www.eclipse.org/legal/epl-2.0,
* or the Eclipse Distribution License v. 1.0 which is available at
* http://www.eclipse.org/org/documents/edl-v10.php.
*
* SPDX-License-Identifier: EPL-2.0 OR BSD-3-Clause
*/
// Contributors:
// Petros Splinakis - 2.2
// Linda DeMichiel - 2.1
package javax.persistence;
import java.lang.annotation.Repeatable;
import java.lang.annotation.Target;
import java.lang.annotation.Retention;
import static java.lang.annotation.ElementType.TYPE;
import static java.lang.annotation.ElementType.METHOD;
import static java.lang.annotation.ElementType.FIELD;
import static java.lang.annotation.RetentionPolicy.RUNTIME;
/**
* Specifies the conversion of a Basic field or property. It is
* not necessary to use the Basic annotation or corresponding
* XML element to specify the Basic type.
*
* The Convert annotation should not be used to specify
* conversion of the following: Id attributes, version attributes,
* relationship attributes, and attributes explicitly denoted as
* Enumerated or Temporal. Applications that specify such conversions
* will not be portable.
*
*
The Convert annotation may be applied to a basic
* attribute or to an element collection of basic type (in which case
* the converter is applied to the elements of the collection). In
* these cases, the attributeName element must not be
* specified.
*
*
The Convert annotation may be applied to an embedded
* attribute or to a map collection attribute whose key or value is of
* embeddable type (in which case the converter is applied to the
* specified attribute of the embeddable instances contained in the
* collection). In these cases, the attributeName
* element must be specified.
*
*
To override conversion mappings at multiple levels of embedding,
* a dot (".") notation form must be used in the attributeName
* element to indicate an attribute within an embedded attribute. The
* value of each identifier used with the dot notation is the name of the
* respective embedded field or property.
*
*
When the Convert annotation is applied to a map containing
* instances of embeddable classes, the attributeName element
* must be specified, and "key." or "value."
* must be used to prefix the name of the attribute that is to be converted
* in order to specify it as part of the map key or map value.
*
*
When the Convert annotation is applied to a map to specify
* conversion of a map key of basic type, "key" must be used
* as the value of the attributeName element to specify that
* it is the map key that is to be converted.
*
*
The Convert annotation may be applied to an entity class
* that extends a mapped superclass to specify or override a conversion
* mapping for an inherited basic or embedded attribute.
*
*
* Example 1: Convert a basic attribute
*
* @Converter
* public class BooleanToIntegerConverter
* implements AttributeConverter<Boolean, Integer> { ... }
*
* @Entity
* public class Employee {
* @Id long id;
*
* @Convert(converter=BooleanToIntegerConverter.class)
* boolean fullTime;
* ...
* }
*
*
* Example 2: Auto-apply conversion of a basic attribute
*
* @Converter(autoApply=true)
* public class EmployeeDateConverter
* implements AttributeConverter<com.acme.EmployeeDate, java.sql.Date> { ... }
*
* @Entity
* public class Employee {
* @Id long id;
* ...
* // EmployeeDateConverter is applied automatically
* EmployeeDate startDate;
* }
*
*
* Example 3: Disable conversion in the presence of an autoapply converter
*
* @Convert(disableConversion=true)
* EmployeeDate lastReview;
*
*
* Example 4: Apply a converter to an element collection of basic type
*
* @ElementCollection
* // applies to each element in the collection
* @Convert(converter=NameConverter.class)
* List<String> names;
*
*
* Example 5: Apply a converter to an element collection that is a map or basic values.
* The converter is applied to the map value.
*
* @ElementCollection
* @Convert(converter=EmployeeNameConverter.class)
* Map<String, String> responsibilities;
*
*
* Example 6: Apply a converter to a map key of basic type
*
* @OneToMany
* @Convert(converter=ResponsibilityCodeConverter.class,
* attributeName="key")
* Map<String, Employee> responsibilities;
*
*
* Example 7: Apply a converter to an embeddable attribute
*
* @Embedded
* @Convert(converter=CountryConverter.class,
* attributeName="country")
* Address address;
*
*
* Example 8: Apply a converter to a nested embeddable attribute
*
* @Embedded
* @Convert(converter=CityConverter.class,
* attributeName="region.city")
* Address address;
*
*
* Example 9: Apply a converter to a nested attribute of an embeddable that is a map key
* of an element collection
*
* @Entity public class PropertyRecord {
* ...
* @Convert(attributeName="key.region.city",
* converter=CityConverter.class)
* @ElementCollection
* Map<Address, PropertyInfo> parcels;
* }
*
*
* Example 10: Apply a converter to an embeddable that is a map key for a relationship
*
* @OneToMany
* @Convert(attributeName="key.jobType",
* converter=ResponsibilityTypeConverter.class)
* Map<Responsibility, Employee> responsibilities;
*
*
* Example 11: Override conversion mappings for attributes inherited from a mapped superclass
*
* @Entity
* @Converts({
* @Convert(attributeName="startDate",
* converter=DateConverter.class),
* @Convert(attributeName="endDate",
* converter=DateConverter.class)})
* public class FullTimeEmployee extends GenericEmployee { ... }
*
*
* @see Converter
* @see Converts
* @see Basic
*
* @since 2.1
*/
@Repeatable(Converts.class)
@Target({METHOD, FIELD, TYPE}) @Retention(RUNTIME)
public @interface Convert {
/**
* Specifies the converter to be applied. A value for this
* element must be specified if multiple converters would
* otherwise apply.
*/
Class converter() default void.class;
/**
* The attributeName element must be specified unless the
* Convert annotation is on an attribute of basic type
* or on an element collection of basic type. In these cases, the
* attributeName element must not be specified.
*/
String attributeName() default "";
/**
* Used to disable an auto-apply or inherited converter.
* If disableConversion is true, the converter element should
* not be specified.
*/
boolean disableConversion() default false;
}