Return-Path: X-Original-To: archive-asf-public-internal@cust-asf2.ponee.io Delivered-To: archive-asf-public-internal@cust-asf2.ponee.io Received: from cust-asf.ponee.io (cust-asf.ponee.io [163.172.22.183]) by cust-asf2.ponee.io (Postfix) with ESMTP id DB3D4200C59 for ; Sun, 2 Apr 2017 19:45:47 +0200 (CEST) Received: by cust-asf.ponee.io (Postfix) id DA546160B8E; Sun, 2 Apr 2017 17:45:47 +0000 (UTC) Delivered-To: archive-asf-public@cust-asf.ponee.io Received: from mail.apache.org (hermes.apache.org [140.211.11.3]) by cust-asf.ponee.io (Postfix) with SMTP id 23A23160BC4 for ; Sun, 2 Apr 2017 19:45:43 +0200 (CEST) Received: (qmail 14516 invoked by uid 500); 2 Apr 2017 17:45:43 -0000 Mailing-List: contact commits-help@polygene.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: dev@polygene.apache.org Delivered-To: mailing list commits@polygene.apache.org Received: (qmail 13461 invoked by uid 99); 2 Apr 2017 17:45:42 -0000 Received: from git1-us-west.apache.org (HELO git1-us-west.apache.org) (140.211.11.23) by apache.org (qpsmtpd/0.29) with ESMTP; Sun, 02 Apr 2017 17:45:42 +0000 Received: by git1-us-west.apache.org (ASF Mail Server at git1-us-west.apache.org, from userid 33) id 9AD5AE38E5; Sun, 2 Apr 2017 17:45:42 +0000 (UTC) Content-Type: text/plain; charset="us-ascii" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit From: paulmerlin@apache.org To: commits@polygene.apache.org Date: Sun, 02 Apr 2017 17:46:16 -0000 Message-Id: <74fdfc1838984874bffaf6e6bd941813@git.apache.org> In-Reply-To: <0088a29e2e0d476a907e84190e3d8c97@git.apache.org> References: <0088a29e2e0d476a907e84190e3d8c97@git.apache.org> X-Mailer: ASF-Git Admin Mailer Subject: [36/51] [abbrv] polygene-java git commit: Serialization API and SPI javadoc archived-at: Sun, 02 Apr 2017 17:45:48 -0000 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 Authored: Mon Mar 13 10:07:02 2017 +0100 Committer: Paul Merlin 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 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. * - *

- * Serialization implementations should be tagged with theses at assembly time so that consumers can - * specify which format they need. - *

+ * 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. - ~ - ~ -->

Serialization API.

+

+ {@link Serialization} extends {@link Serializer} and {@link Deserializer}. +
+ {@link SerializationException} is thrown when something goes wrong. +

+

+ Serialization implementations should be tagged with {@link Serialization.Format} at assembly time so that consumers + can specify which format they need: +

+
@Service @Tagged( Serialization.Format.JSON ) Serialization serialization;
+

+ {@link Serializer}s and {@link Deserializers} provides methods and functions to (de)serialize objects + and set of objects. +

+

+ 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. +

+

+ The serialization behavior can be influenced using {@link Serializer.Options}. +

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: + * + *
    + *
  • {@link Identity}
    • + *
  • {@link EntityReference}
    • + *
  • {@link BigDecimal}
    • + *
  • {@link BigInteger}
    • + *
  • {@link Instant}
    • + *
  • {@link ZonedDateTime}
    • + *
  • {@link OffsetDateTime}
    • + *
  • {@link LocalDateTime}
    • + *
  • {@link LocalDate}
    • + *
  • {@link LocalTime}
    • + *
  • {@link Duration}
    • + *
  • {@link Period}
    • + *
+ * + * 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 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 { Function 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 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. - ~ - ~ --> - -

Serialization SPI.

- + +

Serialization SPI.

+

+ 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}. +

+

+ This package also contains base implementations, mixins and helpers for serialization API implementations: +

+

Base implementations

+
    +
  • + Use {@link AbstractTextSerializer} and {@link AbstractTextDeserializer} as a basis to implement the + serialization API for text representations. +
    • +
  • + Use {@link AbstractBinarySerializer} and {@link AbstractBinaryDeserializer} as a basis to implement the + serialization API for binary representations. +
    • +
  • + Use {@link AbstractSerializer} and {@link AbstractDeserializer} if you need to handle text/binary conversion + yourself. +
    • +
+

+ Mixins +

+
    +
  • {@link BuiltInConverters} provides built-in {@link Converter}s for types supported by the Polygene Runtime.
    • +
+