You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@polygene.apache.org by pa...@apache.org on 2017/03/13 15:29:04 UTC
[41/48] polygene-java git commit: Serialization API and SPI javadoc
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/9e8d37a2
Tree: http://git-wip-us.apache.org/repos/asf/polygene-java/tree/9e8d37a2
Diff: http://git-wip-us.apache.org/repos/asf/polygene-java/diff/9e8d37a2
Branch: refs/heads/serialization-3.0
Commit: 9e8d37a2df97028296d4c7c61759fca357631cd7
Parents: cedea63
Author: Paul Merlin <pa...@apache.org>
Authored: Mon Mar 13 10:07:02 2017 +0100
Committer: Paul Merlin <pa...@apache.org>
Committed: Mon Mar 13 16:27:47 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/9e8d37a2/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/9e8d37a2/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/9e8d37a2/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/9e8d37a2/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/9e8d37a2/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/9e8d37a2/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/9e8d37a2/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/9e8d37a2/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/9e8d37a2/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/9e8d37a2/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/9e8d37a2/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/9e8d37a2/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/9e8d37a2/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/9e8d37a2/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/9e8d37a2/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/9e8d37a2/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/9e8d37a2/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/9e8d37a2/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>