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/develop Commit: 0c0dbee926e2c9409cd63c674206ea363271ff12 Parents: cf842f4 Author: Paul Merlin <[email protected]> Authored: Mon Mar 13 10:07:02 2017 +0100 Committer: Paul Merlin <[email protected]> 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>
