Skip to content
Permalink
Browse files
Basic docs for AttributeConverters
  • Loading branch information
andyjefferson committed Apr 11, 2022
1 parent e921e8f commit 0d5104eaa6d24b0a5a07b5b273b9b41e57f92167
Showing 1 changed file with 104 additions and 0 deletions.
@@ -387,3 +387,107 @@ can be used as part of the primary key.
|icon:check[]

|===


[[attributeconverter]]
=== JDO Attribute Converters

JDO3.2 introduces an API for conversion of an attribute of a _PersistenceCapable_ object to its datastore value.
You can define a "converter" that will convert to the datastore value and back from it, implementing this interface.
This is particularly useful where you have a field type that would not normally be readily persistable, but by defining
the conversion it becomes simple.

[source,java]
-----
public interface AttributeConverter<X,Y>
{
public Y convertToDatastore(X attributeValue);
public X convertToAttribute (Y datastoreValue);
}
-----

so if we have a simple converter to allow us to persist fields of type URL in a String form in the datastore, like this

[source,java]
-----
public class URLStringConverter implements AttributeConverter<URL, String>
{
public URL convertToAttribute(String str)
{
if (str == null)
{
return null;
}
URL url = null;
try
{
url = new java.net.URL(str.trim());
}
catch (MalformedURLException mue)
{
throw new IllegalStateException("Error converting the URL", mue);
}
return url;
}
public String convertToDatastore(URL url)
{
return url != null ? url.toString() : null;
}
}
-----

and now in our _PersistenceCapable_ class we mark any URL field as being converted using this converter

[source,java]
-----
@PersistenceCapable
public class MyClass
{
@PrimaryKey
long id;
@Convert(URLStringConverter.class)
URL url;
...
}
-----

or using XML metadata

[source,xml]
-----
<field name="url" converter="mydomain.package.URLStringConverter"/>
-----

A further use of `AttributeConverter` is where you want to apply type conversion to the key/value of a Map field, or to the element of a Collection field.
The Collection element case is simple, you just specify the `@Convert` against the field and it will be applied to the element.
If you want to apply type conversion to a key/value of a map do this.

[source,java]
-----
@Key(converter=URLStringConverter.class)
Map<URL, OtherEntity> myMap;
-----

or using XML metadata

[source,xml]
-----
<field name="myMap">
<key converter="mydomain.package.URLStringConverter"/>
</field>
-----


NOTE: You can register a _default_ `AttributeConverter` for a java type when constructing the PMF via persistence properties.
These properties should be of the form *javax.jdo.option.typeconverter.{javatype}* and the value is the class name of the `AttributeConverter`.

NOTE: You CANNOT use an `AttributeConverter` for a _PersistenceCapable_ type. This is because a _PersistenceCapable_ type requires special treatment, such as attaching a StateManager etc.

NOTE: The `AttributeConverter` objects shown here are *stateless*.


0 comments on commit 0d5104e

Please sign in to comment.