svn commit: r1674514 - in /db/jdo/trunk/api/src/java/javax/jdo: AttributeConverter.java annotations/Convert.java annotations/Converter.java annotations/Converts.java

[an...@apache.org]

Author: andyj
Date: Sat Apr 18 14:13:06 2015
New Revision: 1674514

URL: http://svn.apache.org/r1674514
Log:
[JDO-709] Initial merge of Matthew's proposal for attribute converters. Note that this concentrates solely on class and field/property specification (and ignores package, and its optional subpackages/subtypes attributes), with the idea that we get something to cater for the 95% use-case initially and think about adding those others in a later issue. Added copyright header to the patch

Added:
    db/jdo/trunk/api/src/java/javax/jdo/AttributeConverter.java
    db/jdo/trunk/api/src/java/javax/jdo/annotations/Convert.java
    db/jdo/trunk/api/src/java/javax/jdo/annotations/Converter.java
    db/jdo/trunk/api/src/java/javax/jdo/annotations/Converts.java

Added: db/jdo/trunk/api/src/java/javax/jdo/AttributeConverter.java
URL: http://svn.apache.org/viewvc/db/jdo/trunk/api/src/java/javax/jdo/AttributeConverter.java?rev=1674514&view=auto
==============================================================================
--- db/jdo/trunk/api/src/java/javax/jdo/AttributeConverter.java (added)
+++ db/jdo/trunk/api/src/java/javax/jdo/AttributeConverter.java Sat Apr 18 14:13:06 2015
@@ -0,0 +1,42 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package javax.jdo;
+
+/**
+ * Converts persistent attribute values (fields or properties) to different
+ * values stored in the underlying datastore and vice versa.
+ * [TBD: 
+ * <ul>
+ * <li>should we require that converters need access to any other information, e.g metadata? passed into the constructor</li>
+ * <li>otherwise we assume there is a default constructor, and is instantiable using the current JDO class loader(s)</li>
+ * </ul>]
+ * 
+ * @param <A> The type of persistent attribute (field or property).
+ * @param <D> The type to be used in the datastore.
+ */
+public interface AttributeConverter<A, D> {
+
+	/**
+	 * Converts the given persistent attribute value to its representation in the datastore.
+	 */
+	D convertToDatastore(A attributeValue);
+
+	/**
+	 * Converts the given datastore value to its representation as a persistent attribute.
+	 */
+	A convertToAttribute(D datastoreValue);
+}

Added: db/jdo/trunk/api/src/java/javax/jdo/annotations/Convert.java
URL: http://svn.apache.org/viewvc/db/jdo/trunk/api/src/java/javax/jdo/annotations/Convert.java?rev=1674514&view=auto
==============================================================================
--- db/jdo/trunk/api/src/java/javax/jdo/annotations/Convert.java (added)
+++ db/jdo/trunk/api/src/java/javax/jdo/annotations/Convert.java Sat Apr 18 14:13:06 2015
@@ -0,0 +1,61 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package javax.jdo.annotations;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+import javax.jdo.AttributeConverter;
+
+/**
+ * Specifies that a given type should be converted before being stored to, and after being retrieved from
+ * the datastore using the given {@link AttributeConverter}.
+ *
+ * If this annotation is placed on a type, then the conversion applies to all fields or properties whose types
+ * match the entity type of the given {@link AttributeConverter}.
+ * If {@link #name()} is not the empty string, then the conversion only holds for the field or property
+ * whose name matches the given name. Placing this annotation on a class allow
+ * for centralized configuration of class-scoped {@link AttributeConverter}s.
+ * Any {@link Convert} annotations placed on attributes within the annotated
+ * type override this annotation.
+ * 
+ * If this annotation is placed on a field or property, then {@link #name()} is ignored and the annotated
+ * attribute's type must be assignment-compatible with the {@link AttributeConverter}'s entity type argument.
+ */
+@Retention(RetentionPolicy.RUNTIME)
+@Target({ElementType.TYPE, ElementType.METHOD, ElementType.FIELD })
+public @interface Convert {
+
+	/**
+	 * The {@link AttributeConverter} to use for conversion.
+	 */
+	@SuppressWarnings("rawtypes")
+	Class<? extends AttributeConverter> value();
+
+	/**
+	 * Whether this conversion is enabled. True by default.
+	 */
+	boolean enabled() default true;
+
+	/**
+	 * The name of the field or property to which this conversion applies.
+	 * Ignored if this annotation is on a field or property.
+	 */
+	String name() default "";
+}

Added: db/jdo/trunk/api/src/java/javax/jdo/annotations/Converter.java
URL: http://svn.apache.org/viewvc/db/jdo/trunk/api/src/java/javax/jdo/annotations/Converter.java?rev=1674514&view=auto
==============================================================================
--- db/jdo/trunk/api/src/java/javax/jdo/annotations/Converter.java (added)
+++ db/jdo/trunk/api/src/java/javax/jdo/annotations/Converter.java Sat Apr 18 14:13:06 2015
@@ -0,0 +1,33 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package javax.jdo.annotations;
+
+import java.lang.annotation.Retention;
+import java.lang.annotation.Target;
+
+import static java.lang.annotation.ElementType.TYPE;
+import static java.lang.annotation.RetentionPolicy.RUNTIME;
+
+/**
+ * Attribute placed on an AttributeConverter to define whether the JDO persistence process should
+ * by default apply the specified converter for the type.
+ */
+@Target(TYPE)
+@Retention(RUNTIME)
+public @interface Converter {
+	boolean autoApply() default false;
+}

Added: db/jdo/trunk/api/src/java/javax/jdo/annotations/Converts.java
URL: http://svn.apache.org/viewvc/db/jdo/trunk/api/src/java/javax/jdo/annotations/Converts.java?rev=1674514&view=auto
==============================================================================
--- db/jdo/trunk/api/src/java/javax/jdo/annotations/Converts.java (added)
+++ db/jdo/trunk/api/src/java/javax/jdo/annotations/Converts.java Sat Apr 18 14:13:06 2015
@@ -0,0 +1,35 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package javax.jdo.annotations;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * Container annotation to allow for multiple {@link Convert} annotations.
+ */
+@Retention(RetentionPolicy.RUNTIME)
+@Target({ ElementType.PACKAGE, ElementType.TYPE })
+public @interface Converts {
+
+	/**
+	 * The conversion specifications to be configured.
+	 */
+	Convert[] value();
+}