[db-jdo-site] branch main updated: Basic docs for AttributeConverters

[an...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

andyj pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/db-jdo-site.git


The following commit(s) were added to refs/heads/main by this push:
     new 0d5104e  Basic docs for AttributeConverters
0d5104e is described below

commit 0d5104eaa6d24b0a5a07b5b273b9b41e57f92167
Author: andyjefferson <an...@datanucleus.org>
AuthorDate: Mon Apr 11 08:08:56 2022 +0100

    Basic docs for AttributeConverters
---
 src/main/asciidoc/field_types.adoc | 104 +++++++++++++++++++++++++++++++++++++
 1 file changed, 104 insertions(+)

diff --git a/src/main/asciidoc/field_types.adoc b/src/main/asciidoc/field_types.adoc
index 2e32127..728fb5f 100644
--- a/src/main/asciidoc/field_types.adoc
+++ b/src/main/asciidoc/field_types.adoc
@@ -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*. 
+
+