polygene-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From paulmer...@apache.org
Subject [36/51] [abbrv] polygene-java git commit: Serialization API and SPI javadoc
Date Sun, 02 Apr 2017 17:46:16 GMT
Serialization API and SPI javadoc

POLYGENE-231


Project: http://git-wip-us.apache.org/repos/asf/polygene-java/repo
Commit: http://git-wip-us.apache.org/repos/asf/polygene-java/commit/0c0dbee9
Tree: http://git-wip-us.apache.org/repos/asf/polygene-java/tree/0c0dbee9
Diff: http://git-wip-us.apache.org/repos/asf/polygene-java/diff/0c0dbee9

Branch: refs/heads/serialization-3.0
Commit: 0c0dbee926e2c9409cd63c674206ea363271ff12
Parents: cf842f4
Author: Paul Merlin <paulmerlin@apache.org>
Authored: Mon Mar 13 10:07:02 2017 +0100
Committer: Paul Merlin <paulmerlin@apache.org>
Committed: Sun Apr 2 19:16:23 2017 +0200

----------------------------------------------------------------------
 .../api/serialization/Deserializer.java         |  5 +++
 .../api/serialization/Serialization.java        | 10 +++---
 .../polygene/api/serialization/Serializer.java  |  6 ++++
 .../polygene/api/serialization/package.html     | 23 ++++++++++--
 .../AbstractBinaryDeserializer.java             |  2 ++
 .../serialization/AbstractBinarySerializer.java |  2 ++
 .../spi/serialization/AbstractDeserializer.java |  7 ++++
 .../spi/serialization/AbstractSerializer.java   |  7 ++++
 .../serialization/AbstractTextDeserializer.java |  2 ++
 .../serialization/AbstractTextSerializer.java   |  2 ++
 .../spi/serialization/BuiltInConverters.java    | 21 +++++++++++
 .../spi/serialization/JsonDeserializer.java     |  3 ++
 .../spi/serialization/JsonSerialization.java    |  3 ++
 .../spi/serialization/JsonSerializer.java       |  3 ++
 .../spi/serialization/XmlDeserializer.java      |  3 ++
 .../spi/serialization/XmlSerialization.java     |  3 ++
 .../spi/serialization/XmlSerializer.java        |  2 +-
 .../polygene/spi/serialization/package.html     | 37 +++++++++++++++++---
 18 files changed, 127 insertions(+), 14 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/polygene-java/blob/0c0dbee9/core/api/src/main/java/org/apache/polygene/api/serialization/Deserializer.java
----------------------------------------------------------------------
diff --git a/core/api/src/main/java/org/apache/polygene/api/serialization/Deserializer.java
b/core/api/src/main/java/org/apache/polygene/api/serialization/Deserializer.java
index 7ab1c44..0b633dd 100644
--- a/core/api/src/main/java/org/apache/polygene/api/serialization/Deserializer.java
+++ b/core/api/src/main/java/org/apache/polygene/api/serialization/Deserializer.java
@@ -24,6 +24,11 @@ import java.util.stream.Stream;
 import org.apache.polygene.api.structure.ModuleDescriptor;
 import org.apache.polygene.api.type.ValueType;
 
+/**
+ * Deserializer.
+ *
+ * Provides methods and functions to deserialize objects and set of objects.
+ */
 public interface Deserializer
 {
     <T> T deserialize( ModuleDescriptor module, ValueType valueType, InputStream state
);

http://git-wip-us.apache.org/repos/asf/polygene-java/blob/0c0dbee9/core/api/src/main/java/org/apache/polygene/api/serialization/Serialization.java
----------------------------------------------------------------------
diff --git a/core/api/src/main/java/org/apache/polygene/api/serialization/Serialization.java
b/core/api/src/main/java/org/apache/polygene/api/serialization/Serialization.java
index ff1d32f..8bf005b 100644
--- a/core/api/src/main/java/org/apache/polygene/api/serialization/Serialization.java
+++ b/core/api/src/main/java/org/apache/polygene/api/serialization/Serialization.java
@@ -18,17 +18,15 @@
 package org.apache.polygene.api.serialization;
 
 /**
- *
+ * Serialization extends {@link Serializer} and {@link Deserializer}.
  */
 public interface Serialization extends Serializer, Deserializer
 {
     /**
-     * Serialization format @Service tags.
+     * Serialization format {@literal @Service} tags.
      *
-     * <p>
-     *     Serialization implementations should be tagged with theses at assembly time so
that consumers can
-     *     specify which format they need.
-     * </p>
+     * Serialization implementations should be tagged with theses at assembly time so that
consumers can
+     * specify which format they need.
      */
     interface Formats
     {

http://git-wip-us.apache.org/repos/asf/polygene-java/blob/0c0dbee9/core/api/src/main/java/org/apache/polygene/api/serialization/Serializer.java
----------------------------------------------------------------------
diff --git a/core/api/src/main/java/org/apache/polygene/api/serialization/Serializer.java
b/core/api/src/main/java/org/apache/polygene/api/serialization/Serializer.java
index bdbe482..39e15b1 100644
--- a/core/api/src/main/java/org/apache/polygene/api/serialization/Serializer.java
+++ b/core/api/src/main/java/org/apache/polygene/api/serialization/Serializer.java
@@ -26,6 +26,12 @@ import java.util.function.Function;
 import java.util.stream.Stream;
 import org.apache.polygene.api.common.Optional;
 
+/**
+ * Serializer.
+ *
+ * All implementations must handle all {@link Options}, they might extend them to provide
more control.
+ * See their respective documentation for the details.
+ */
 public interface Serializer
 {
     void serialize( Options options, Writer writer, @Optional Object object );

http://git-wip-us.apache.org/repos/asf/polygene-java/blob/0c0dbee9/core/api/src/main/java/org/apache/polygene/api/serialization/package.html
----------------------------------------------------------------------
diff --git a/core/api/src/main/java/org/apache/polygene/api/serialization/package.html b/core/api/src/main/java/org/apache/polygene/api/serialization/package.html
index fc2a3bd..467fc65 100644
--- a/core/api/src/main/java/org/apache/polygene/api/serialization/package.html
+++ b/core/api/src/main/java/org/apache/polygene/api/serialization/package.html
@@ -14,11 +14,30 @@
   ~  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.
-  ~
-  ~
   -->
 <html>
 <body>
 <h2>Serialization API.</h2>
+<p>
+    {@link Serialization} extends {@link Serializer} and {@link Deserializer}.
+    <br/>
+    {@link SerializationException} is thrown when something goes wrong.
+</p>
+<p>
+    Serialization implementations should be tagged with {@link Serialization.Format} at assembly
time so that consumers
+    can specify which format they need:
+</p>
+<pre><code>@Service @Tagged( Serialization.Format.JSON ) Serialization serialization;</code></pre>
+<p>
+    {@link Serializer}s and {@link Deserializers} provides methods and functions to (de)serialize
objects
+    and set of objects.
+</p>
+<p>
+    Serialized representations might be textual (e.g. {@literal JSON} and {@literal XML})
or binary.
+    Implementations are free to use any codec to encode/decode from/to text and bytes but
it must be bi-directional.
+</p>
+<p>
+    The serialization behavior can be influenced using {@link Serializer.Options}.
+</p>
 </body>
 </html>

http://git-wip-us.apache.org/repos/asf/polygene-java/blob/0c0dbee9/core/spi/src/main/java/org/apache/polygene/spi/serialization/AbstractBinaryDeserializer.java
----------------------------------------------------------------------
diff --git a/core/spi/src/main/java/org/apache/polygene/spi/serialization/AbstractBinaryDeserializer.java
b/core/spi/src/main/java/org/apache/polygene/spi/serialization/AbstractBinaryDeserializer.java
index 7e2d19a..5cf2660 100644
--- a/core/spi/src/main/java/org/apache/polygene/spi/serialization/AbstractBinaryDeserializer.java
+++ b/core/spi/src/main/java/org/apache/polygene/spi/serialization/AbstractBinaryDeserializer.java
@@ -33,6 +33,8 @@ import static java.util.stream.Collectors.joining;
  * Base Binary Deserializer.
  *
  * Implementations work on bytes, this base deserializer decode Strings from Base64 to produce
bytes.
+ *
+ * See {@link AbstractBinarySerializer}.
  */
 public abstract class AbstractBinaryDeserializer extends AbstractDeserializer
 // END SNIPPET: binary

http://git-wip-us.apache.org/repos/asf/polygene-java/blob/0c0dbee9/core/spi/src/main/java/org/apache/polygene/spi/serialization/AbstractBinarySerializer.java
----------------------------------------------------------------------
diff --git a/core/spi/src/main/java/org/apache/polygene/spi/serialization/AbstractBinarySerializer.java
b/core/spi/src/main/java/org/apache/polygene/spi/serialization/AbstractBinarySerializer.java
index 0cf17eb..c17ffb4 100644
--- a/core/spi/src/main/java/org/apache/polygene/spi/serialization/AbstractBinarySerializer.java
+++ b/core/spi/src/main/java/org/apache/polygene/spi/serialization/AbstractBinarySerializer.java
@@ -31,6 +31,8 @@ import static java.nio.charset.StandardCharsets.UTF_8;
  * Base Binary Serializer.
  *
  * Implementations work on bytes, this base serializer encode these bytes in Base64 to produce
Strings.
+ *
+ * See {@link AbstractBinaryDeserializer}.
  */
 public abstract class AbstractBinarySerializer extends AbstractSerializer
 // END SNIPPET: binary

http://git-wip-us.apache.org/repos/asf/polygene-java/blob/0c0dbee9/core/spi/src/main/java/org/apache/polygene/spi/serialization/AbstractDeserializer.java
----------------------------------------------------------------------
diff --git a/core/spi/src/main/java/org/apache/polygene/spi/serialization/AbstractDeserializer.java
b/core/spi/src/main/java/org/apache/polygene/spi/serialization/AbstractDeserializer.java
index 17982f3..b373160 100644
--- a/core/spi/src/main/java/org/apache/polygene/spi/serialization/AbstractDeserializer.java
+++ b/core/spi/src/main/java/org/apache/polygene/spi/serialization/AbstractDeserializer.java
@@ -32,6 +32,13 @@ import org.apache.polygene.api.type.MapType;
 import org.apache.polygene.api.type.ValueType;
 import org.apache.polygene.spi.module.ModuleSpi;
 
+/**
+ * Base Deserializer.
+ *
+ * Provides default implementations for convenience API methods.
+ *
+ * See {@link AbstractSerializer}.
+ */
 public abstract class AbstractDeserializer implements Deserializer
 {
     protected static final ValueType ENTITY_REF_LIST_VALUE_TYPE = CollectionType.listOf(
EntityReference.class );

http://git-wip-us.apache.org/repos/asf/polygene-java/blob/0c0dbee9/core/spi/src/main/java/org/apache/polygene/spi/serialization/AbstractSerializer.java
----------------------------------------------------------------------
diff --git a/core/spi/src/main/java/org/apache/polygene/spi/serialization/AbstractSerializer.java
b/core/spi/src/main/java/org/apache/polygene/spi/serialization/AbstractSerializer.java
index b5f10ff..3269adb 100644
--- a/core/spi/src/main/java/org/apache/polygene/spi/serialization/AbstractSerializer.java
+++ b/core/spi/src/main/java/org/apache/polygene/spi/serialization/AbstractSerializer.java
@@ -27,6 +27,13 @@ import java.util.stream.StreamSupport;
 import org.apache.polygene.api.common.Optional;
 import org.apache.polygene.api.serialization.Serializer;
 
+/**
+ * Base Serializer.
+ *
+ * Provides default implementations for convenience API methods.
+ *
+ * See {@link AbstractDeserializer}.
+ */
 public abstract class AbstractSerializer implements Serializer
 {
     @Override

http://git-wip-us.apache.org/repos/asf/polygene-java/blob/0c0dbee9/core/spi/src/main/java/org/apache/polygene/spi/serialization/AbstractTextDeserializer.java
----------------------------------------------------------------------
diff --git a/core/spi/src/main/java/org/apache/polygene/spi/serialization/AbstractTextDeserializer.java
b/core/spi/src/main/java/org/apache/polygene/spi/serialization/AbstractTextDeserializer.java
index d87dd6d..f61db14 100644
--- a/core/spi/src/main/java/org/apache/polygene/spi/serialization/AbstractTextDeserializer.java
+++ b/core/spi/src/main/java/org/apache/polygene/spi/serialization/AbstractTextDeserializer.java
@@ -29,6 +29,8 @@ import static java.nio.charset.StandardCharsets.UTF_8;
  * Base Text Deserializer.
  *
  * Implementations work on Strings, this base deserializer decode bytes in UTF-8 to produce
strings.
+ *
+ * See {@link AbstractTextSerializer}.
  */
 public abstract class AbstractTextDeserializer extends AbstractDeserializer
 // END SNIPPET: text

http://git-wip-us.apache.org/repos/asf/polygene-java/blob/0c0dbee9/core/spi/src/main/java/org/apache/polygene/spi/serialization/AbstractTextSerializer.java
----------------------------------------------------------------------
diff --git a/core/spi/src/main/java/org/apache/polygene/spi/serialization/AbstractTextSerializer.java
b/core/spi/src/main/java/org/apache/polygene/spi/serialization/AbstractTextSerializer.java
index 2c2b83c..aa9821d 100644
--- a/core/spi/src/main/java/org/apache/polygene/spi/serialization/AbstractTextSerializer.java
+++ b/core/spi/src/main/java/org/apache/polygene/spi/serialization/AbstractTextSerializer.java
@@ -30,6 +30,8 @@ import static java.nio.charset.StandardCharsets.UTF_8;
  * Base Text Serializer.
  *
  * Implementations work on Strings, this base serializer encode these strings in UTF-8 to
produce bytes.
+ *
+ * See {@link AbstractTextDeserializer}.
  */
 public abstract class AbstractTextSerializer extends AbstractSerializer
 // END SNIPPET: text

http://git-wip-us.apache.org/repos/asf/polygene-java/blob/0c0dbee9/core/spi/src/main/java/org/apache/polygene/spi/serialization/BuiltInConverters.java
----------------------------------------------------------------------
diff --git a/core/spi/src/main/java/org/apache/polygene/spi/serialization/BuiltInConverters.java
b/core/spi/src/main/java/org/apache/polygene/spi/serialization/BuiltInConverters.java
index a6392ff..0c1b774 100644
--- a/core/spi/src/main/java/org/apache/polygene/spi/serialization/BuiltInConverters.java
+++ b/core/spi/src/main/java/org/apache/polygene/spi/serialization/BuiltInConverters.java
@@ -37,6 +37,27 @@ import org.apache.polygene.api.type.ValueType;
 
 /**
  * Built-in serialization converters.
+ *
+ * Mixin for {@link org.apache.polygene.api.serialization.Serialization} implementations
that provides built-in
+ * {@link Converter}s for the following types:
+ *
+ * <ul>
+ *     <li>{@link Identity}</li>
+ *     <li>{@link EntityReference}</li>
+ *     <li>{@link BigDecimal}</li>
+ *     <li>{@link BigInteger}</li>
+ *     <li>{@link Instant}</li>
+ *     <li>{@link ZonedDateTime}</li>
+ *     <li>{@link OffsetDateTime}</li>
+ *     <li>{@link LocalDateTime}</li>
+ *     <li>{@link LocalDate}</li>
+ *     <li>{@link LocalTime}</li>
+ *     <li>{@link Duration}</li>
+ *     <li>{@link Period}</li>
+ * </ul>
+ *
+ * Note that this does not include {@link String} nor primitive values and their boxed counterparts.
+ * {@literal Serialization} implementations must handle those.
  */
 @Mixins( BuiltInConverters.Mixin.class )
 public interface BuiltInConverters

http://git-wip-us.apache.org/repos/asf/polygene-java/blob/0c0dbee9/core/spi/src/main/java/org/apache/polygene/spi/serialization/JsonDeserializer.java
----------------------------------------------------------------------
diff --git a/core/spi/src/main/java/org/apache/polygene/spi/serialization/JsonDeserializer.java
b/core/spi/src/main/java/org/apache/polygene/spi/serialization/JsonDeserializer.java
index a0dac71..30060ef 100644
--- a/core/spi/src/main/java/org/apache/polygene/spi/serialization/JsonDeserializer.java
+++ b/core/spi/src/main/java/org/apache/polygene/spi/serialization/JsonDeserializer.java
@@ -39,6 +39,9 @@ import org.apache.polygene.spi.module.ModuleSpi;
 
 import static java.util.stream.Collectors.joining;
 
+/**
+ * {@literal javax.json} deserializer.
+ */
 public interface JsonDeserializer extends Deserializer
 {
     <T> T fromJson( ModuleDescriptor module, ValueType valueType, JsonValue state );

http://git-wip-us.apache.org/repos/asf/polygene-java/blob/0c0dbee9/core/spi/src/main/java/org/apache/polygene/spi/serialization/JsonSerialization.java
----------------------------------------------------------------------
diff --git a/core/spi/src/main/java/org/apache/polygene/spi/serialization/JsonSerialization.java
b/core/spi/src/main/java/org/apache/polygene/spi/serialization/JsonSerialization.java
index a98e70f..f41078b 100644
--- a/core/spi/src/main/java/org/apache/polygene/spi/serialization/JsonSerialization.java
+++ b/core/spi/src/main/java/org/apache/polygene/spi/serialization/JsonSerialization.java
@@ -19,6 +19,9 @@ package org.apache.polygene.spi.serialization;
 
 import org.apache.polygene.api.serialization.Serialization;
 
+/**
+ * {@literal javax.json} serialization.
+ */
 public interface JsonSerialization extends Serialization, JsonSerializer, JsonDeserializer
 {
 }

http://git-wip-us.apache.org/repos/asf/polygene-java/blob/0c0dbee9/core/spi/src/main/java/org/apache/polygene/spi/serialization/JsonSerializer.java
----------------------------------------------------------------------
diff --git a/core/spi/src/main/java/org/apache/polygene/spi/serialization/JsonSerializer.java
b/core/spi/src/main/java/org/apache/polygene/spi/serialization/JsonSerializer.java
index 54dd92b..9ec1863 100644
--- a/core/spi/src/main/java/org/apache/polygene/spi/serialization/JsonSerializer.java
+++ b/core/spi/src/main/java/org/apache/polygene/spi/serialization/JsonSerializer.java
@@ -28,6 +28,9 @@ import javax.json.JsonValue;
 import org.apache.polygene.api.common.Optional;
 import org.apache.polygene.api.serialization.Serializer;
 
+/**
+ * {@literal javax.json} serializer.
+ */
 public interface JsonSerializer extends Serializer
 {
     <T> Function<T, JsonValue> toJsonFunction( Options options );

http://git-wip-us.apache.org/repos/asf/polygene-java/blob/0c0dbee9/core/spi/src/main/java/org/apache/polygene/spi/serialization/XmlDeserializer.java
----------------------------------------------------------------------
diff --git a/core/spi/src/main/java/org/apache/polygene/spi/serialization/XmlDeserializer.java
b/core/spi/src/main/java/org/apache/polygene/spi/serialization/XmlDeserializer.java
index 9e559c8..f61e533 100644
--- a/core/spi/src/main/java/org/apache/polygene/spi/serialization/XmlDeserializer.java
+++ b/core/spi/src/main/java/org/apache/polygene/spi/serialization/XmlDeserializer.java
@@ -34,6 +34,9 @@ import org.w3c.dom.Document;
 import org.xml.sax.InputSource;
 import org.xml.sax.SAXException;
 
+/**
+ * {@literal javax.xml} deserializer.
+ */
 public interface XmlDeserializer extends Deserializer
 {
     <T> T fromXml( ModuleDescriptor module, ValueType valueType, Document state );

http://git-wip-us.apache.org/repos/asf/polygene-java/blob/0c0dbee9/core/spi/src/main/java/org/apache/polygene/spi/serialization/XmlSerialization.java
----------------------------------------------------------------------
diff --git a/core/spi/src/main/java/org/apache/polygene/spi/serialization/XmlSerialization.java
b/core/spi/src/main/java/org/apache/polygene/spi/serialization/XmlSerialization.java
index 12fda54..c4b7f37 100644
--- a/core/spi/src/main/java/org/apache/polygene/spi/serialization/XmlSerialization.java
+++ b/core/spi/src/main/java/org/apache/polygene/spi/serialization/XmlSerialization.java
@@ -19,6 +19,9 @@ package org.apache.polygene.spi.serialization;
 
 import org.apache.polygene.api.serialization.Serialization;
 
+/**
+ * {@literal javax.xml} serialization.
+ */
 public interface XmlSerialization extends Serialization, XmlSerializer, XmlDeserializer
 {
 }

http://git-wip-us.apache.org/repos/asf/polygene-java/blob/0c0dbee9/core/spi/src/main/java/org/apache/polygene/spi/serialization/XmlSerializer.java
----------------------------------------------------------------------
diff --git a/core/spi/src/main/java/org/apache/polygene/spi/serialization/XmlSerializer.java
b/core/spi/src/main/java/org/apache/polygene/spi/serialization/XmlSerializer.java
index 32ce539..afffe5f 100644
--- a/core/spi/src/main/java/org/apache/polygene/spi/serialization/XmlSerializer.java
+++ b/core/spi/src/main/java/org/apache/polygene/spi/serialization/XmlSerializer.java
@@ -36,7 +36,7 @@ import org.w3c.dom.Document;
 import org.w3c.dom.Node;
 
 /**
- * XML State Serializer.
+ * {@literal javax.xml} serializer.
  */
 public interface XmlSerializer extends Serializer
 {

http://git-wip-us.apache.org/repos/asf/polygene-java/blob/0c0dbee9/core/spi/src/main/java/org/apache/polygene/spi/serialization/package.html
----------------------------------------------------------------------
diff --git a/core/spi/src/main/java/org/apache/polygene/spi/serialization/package.html b/core/spi/src/main/java/org/apache/polygene/spi/serialization/package.html
index 2e2f188..8078138 100644
--- a/core/spi/src/main/java/org/apache/polygene/spi/serialization/package.html
+++ b/core/spi/src/main/java/org/apache/polygene/spi/serialization/package.html
@@ -14,11 +14,38 @@
   ~  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.
-  ~
-  ~
   -->
 <html>
-    <body>
-        <h2>Serialization SPI.</h2>
-    </body>
+<body>
+<h2>Serialization SPI.</h2>
+<p>
+    This package contains specialized serialization APIs for the {@literal JSON} and {@literal
XML} formats.
+    See {@link @JsonSerialization}, based on {@literal javax.json},
+    and {@link XmlSerialization}, based on {@literal javax.xml}.
+</p>
+<p>
+    This package also contains base implementations, mixins and helpers for serialization
API implementations:
+</p>
+<p><strong>Base implementations</strong></p>
+<ul>
+    <li>
+        Use {@link AbstractTextSerializer} and {@link AbstractTextDeserializer} as a basis
to implement the
+        serialization API for text representations.
+    </li>
+    <li>
+        Use {@link AbstractBinarySerializer} and {@link AbstractBinaryDeserializer} as a
basis to implement the
+        serialization API for binary representations.
+    </li>
+    <li>
+        Use {@link AbstractSerializer} and {@link AbstractDeserializer} if you need to handle
text/binary conversion
+        yourself.
+    </li>
+</ul>
+<p>
+    <strong>Mixins</strong>
+</p>
+<ul>
+    <li>{@link BuiltInConverters} provides built-in {@link Converter}s for types supported
by the Polygene Runtime.</li>
+</ul>
+</body>
 </html>


Mime
View raw message