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/37c31d4a Tree: http://git-wip-us.apache.org/repos/asf/polygene-java/tree/37c31d4a Diff: http://git-wip-us.apache.org/repos/asf/polygene-java/diff/37c31d4a Branch: refs/heads/serialization-3.0 Commit: 37c31d4a0182e8bc50a3723d446df623a52731cb Parents: 9485717 Author: Paul Merlin Authored: Mon Mar 13 10:07:02 2017 +0100 Committer: Paul Merlin Committed: Mon Mar 13 11:24:42 2017 +0100 ---------------------------------------------------------------------- .../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/37c31d4a/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/37c31d4a/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/37c31d4a/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/37c31d4a/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/37c31d4a/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/37c31d4a/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/37c31d4a/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/37c31d4a/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/37c31d4a/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/37c31d4a/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/37c31d4a/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/37c31d4a/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/37c31d4a/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/37c31d4a/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/37c31d4a/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/37c31d4a/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/37c31d4a/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/37c31d4a/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.
  • +
+