You are viewing a plain text version of this content. The canonical link for it is here.
Posted to jdo-commits@db.apache.org by gi...@apache.org on 2022/04/11 07:09:57 UTC
[db-jdo-site] branch publish updated: Auto-deploy site for commit 0d5104eaa6
This is an automated email from the ASF dual-hosted git repository.
github-bot pushed a commit to branch publish
in repository https://gitbox.apache.org/repos/asf/db-jdo-site.git
The following commit(s) were added to refs/heads/publish by this push:
new 07118af Auto-deploy site for commit 0d5104eaa6
07118af is described below
commit 07118af62355fd1c63d2db6d91bd934db80cb05e
Author: andyjefferson <an...@datanucleus.org>
AuthorDate: Mon Apr 11 07:09:52 2022 +0000
Auto-deploy site for commit 0d5104eaa6
---
content/field_types.html | 136 +++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 136 insertions(+)
diff --git a/content/field_types.html b/content/field_types.html
index 3a10275..e3878b1 100644
--- a/content/field_types.html
+++ b/content/field_types.html
@@ -774,6 +774,142 @@ can be used as part of the primary key.</p>
</tbody>
</table>
</div>
+<div class="sect2">
+<h3 id="attributeconverter">JDO Attribute Converters</h3>
+<div class="paragraph">
+<p>JDO3.2 introduces an API for conversion of an attribute of a <em>PersistenceCapable</em> 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.</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="java"><span class="directive">public</span> <span class="type">interface</span> <span class="class">AttributeConverter</span><X,Y>
+{
+ <span class="directive">public</span> Y convertToDatastore(X attributeValue);
+
+ <span class="directive">public</span> X convertToAttribute (Y datastoreValue);
+}</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>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</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="java"><span class="directive">public</span> <span class="type">class</span> <span class="class">URLStringConverter</span> <span class="directive">implements</span> AttributeConverter<<span class="predefined-type">URL</span>, <span class="predefined-type">String</span>>
+{
+ <span class="directive">public</span> <span class="predefined-type">URL</span> convertToAttribute(<span class="predefined-type">String</span> str)
+ {
+ <span class="keyword">if</span> (str == <span class="predefined-constant">null</span>)
+ {
+ <span class="keyword">return</span> <span class="predefined-constant">null</span>;
+ }
+
+ <span class="predefined-type">URL</span> url = <span class="predefined-constant">null</span>;
+ <span class="keyword">try</span>
+ {
+ url = <span class="keyword">new</span> java.net.URL(str.trim());
+ }
+ <span class="keyword">catch</span> (<span class="exception">MalformedURLException</span> mue)
+ {
+ <span class="keyword">throw</span> <span class="keyword">new</span> <span class="exception">IllegalStateException</span>(<span class="string"><span class="delimiter">"</span><span class="content">Error converting the URL</span><span class="delimiter">"</span></span>, mue);
+ }
+ <span class="keyword">return</span> url;
+ }
+
+ <span class="directive">public</span> <span class="predefined-type">String</span> convertToDatastore(<span class="predefined-type">URL</span> url)
+ {
+ <span class="keyword">return</span> url != <span class="predefined-constant">null</span> ? url.toString() : <span class="predefined-constant">null</span>;
+ }
+}</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>and now in our <em>PersistenceCapable</em> class we mark any URL field as being converted using this converter</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@PersistenceCapable</span>
+<span class="directive">public</span> <span class="type">class</span> <span class="class">MyClass</span>
+{
+ <span class="annotation">@PrimaryKey</span>
+ <span class="type">long</span> id;
+
+ <span class="annotation">@Convert</span>(URLStringConverter.class)
+ <span class="predefined-type">URL</span> url;
+
+ ...
+}</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>or using XML metadata</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="xml"><span class="tag"><field</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">"</span><span class="content">url</span><span class="delimiter">"</span></span> <span class="attribute-name">converter</span>=<span class="string"><span class="delimiter">"</span><span class="content">mydomain.package.URLStringConverter</span><span class="delimiter">"</span></span><span class="tag [...]
+</div>
+</div>
+<div class="paragraph">
+<p>A further use of <code>AttributeConverter</code> 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 <code>@Convert</code> 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.</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Key</span>(converter=URLStringConverter.class)
+<span class="predefined-type">Map</span><<span class="predefined-type">URL</span>, OtherEntity> myMap;</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>or using XML metadata</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="xml"><span class="tag"><field</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">"</span><span class="content">myMap</span><span class="delimiter">"</span></span><span class="tag">></span>
+ <span class="tag"><key</span> <span class="attribute-name">converter</span>=<span class="string"><span class="delimiter">"</span><span class="content">mydomain.package.URLStringConverter</span><span class="delimiter">"</span></span><span class="tag">/></span>
+<span class="tag"></field></span></code></pre>
+</div>
+</div>
+<div class="admonitionblock note">
+<table>
+<tr>
+<td class="icon">
+<i class="fa icon-note" title="Note"></i>
+</td>
+<td class="content">
+You can register a <em>default</em> <code>AttributeConverter</code> for a java type when constructing the PMF via persistence properties.
+These properties should be of the form <strong>javax.jdo.option.typeconverter.{javatype}</strong> and the value is the class name of the <code>AttributeConverter</code>.
+</td>
+</tr>
+</table>
+</div>
+<div class="admonitionblock note">
+<table>
+<tr>
+<td class="icon">
+<i class="fa icon-note" title="Note"></i>
+</td>
+<td class="content">
+You CANNOT use an <code>AttributeConverter</code> for a <em>PersistenceCapable</em> type. This is because a <em>PersistenceCapable</em> type requires special treatment, such as attaching a StateManager etc.
+</td>
+</tr>
+</table>
+</div>
+<div class="admonitionblock note">
+<table>
+<tr>
+<td class="icon">
+<i class="fa icon-note" title="Note"></i>
+</td>
+<td class="content">
+The <code>AttributeConverter</code> objects shown here are <strong>stateless</strong>.
+</td>
+</tr>
+</table>
+</div>
+</div>
</div>
</div>
</div>