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:28:55 UTC
[32/48] polygene-java git commit: POLYGENE-191 Documentation
POLYGENE-191 Documentation
Project: http://git-wip-us.apache.org/repos/asf/polygene-java/repo
Commit: http://git-wip-us.apache.org/repos/asf/polygene-java/commit/ecae40d0
Tree: http://git-wip-us.apache.org/repos/asf/polygene-java/tree/ecae40d0
Diff: http://git-wip-us.apache.org/repos/asf/polygene-java/diff/ecae40d0
Branch: refs/heads/serialization-3.0
Commit: ecae40d0550e35774e4f998bb824e9697e19e039
Parents: dbda948
Author: Paul Merlin <pa...@apache.org>
Authored: Mon Feb 27 15:27:24 2017 +0100
Committer: Paul Merlin <pa...@apache.org>
Committed: Mon Mar 13 16:27:47 2017 +0100
----------------------------------------------------------------------
core/api/src/docs/serialization.txt | 16 +--
.../api/value/DocumentationSupport.java | 58 +---------
core/spi/src/docs/serialization.txt | 108 ++++++++++++-------
.../AbstractBinaryDeserializer.java | 7 ++
.../serialization/AbstractBinarySerializer.java | 2 +
.../serialization/AbstractTextDeserializer.java | 7 ++
.../serialization/AbstractTextSerializer.java | 2 +
.../src/docs/serialization-javaxjson.txt | 24 ++++-
...avaxJsonValueCompositeSerializationTest.java | 22 +++-
.../src/docs/serialization-javaxxml.txt | 20 +++-
...JavaxXmlValueCompositeSerializationTest.java | 4 +
.../src/docs/serialization-msgpack.txt | 17 ++-
...sagePackValueCompositeSerializationTest.java | 4 +
13 files changed, 175 insertions(+), 116 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/polygene-java/blob/ecae40d0/core/api/src/docs/serialization.txt
----------------------------------------------------------------------
diff --git a/core/api/src/docs/serialization.txt b/core/api/src/docs/serialization.txt
index e789125..68939f9 100644
--- a/core/api/src/docs/serialization.txt
+++ b/core/api/src/docs/serialization.txt
@@ -14,10 +14,6 @@
[[core-api-serialization,Serialization]]
= Serialization =
-// TODO Reword with the following outline
-// Preamble - What is it for? What can I use it with?, see <<extensions>>
-// Use cases - Value, collections/streams & arrays of values
-
State can be serialized and deserialized using the Serialization API which is a Service API implemented
by SPI and extensions.
@@ -29,7 +25,7 @@ The Serialization mechanism apply to the following object types :
* EntityReference,
* Iterable & Stream,
* Map,
- * Plain Value.
+ * Plain Values.
Nested Plain Values, EntityReferences, Iterables, Streams, Maps, ValueComposites are supported.
EntityComposites and EntityReferences are serialized as their identity string.
@@ -47,10 +43,7 @@ Plain Values can be one of :
* Double or double,
* BigInteger,
* BigDecimal,
- * Date,
- * DateTime (JodaTime),
- * LocalDateTime (JodaTime),
- * LocalDate (JodaTime).
+ * java.time types.
TIP: Serialization behaviour can be tuned with options.
Every +Serializer+ methods can take a +Serializer.Options+ object that contains flags to change how some
@@ -64,8 +57,7 @@ Methods of +Serializer+ allow to specify if the serialized state should contain
serialized value. Having type information in the serialized payload allows to keep actual ValueComposite types and by so
circumvent +AmbiguousTypeException+ when deserializing.
-Core Runtime provides a default Serialization system based on the
-https://github.com/douglascrockford/JSON-java[org.json] Java library producing and consuming JSON.
+Core Runtime provides a default Serialization system based on `javax.json` types.
Let's see how it works in practice.
@@ -103,7 +95,7 @@ In this second example, we ;
. declare a ValueComposite,
. assemble it,
- . assemble a Serialization Service backed by the +org.json+ package,
+ . assemble a Serialization Service backed by the +javax.json+ types,
. get the +Serializer+ and +Deserializer+ Services injected,
. create a new Value instance,
. use the +Serializer#serialize()+ method to get a JSON representation of the Value,
http://git-wip-us.apache.org/repos/asf/polygene-java/blob/ecae40d0/core/api/src/test/java/org/apache/polygene/api/value/DocumentationSupport.java
----------------------------------------------------------------------
diff --git a/core/api/src/test/java/org/apache/polygene/api/value/DocumentationSupport.java b/core/api/src/test/java/org/apache/polygene/api/value/DocumentationSupport.java
index 4de963b..2f55c83 100644
--- a/core/api/src/test/java/org/apache/polygene/api/value/DocumentationSupport.java
+++ b/core/api/src/test/java/org/apache/polygene/api/value/DocumentationSupport.java
@@ -29,13 +29,8 @@ import java.util.stream.Stream;
import org.apache.polygene.api.injection.scope.Service;
import org.apache.polygene.api.property.Property;
import org.apache.polygene.api.serialization.Deserializer;
-import org.apache.polygene.api.serialization.Serialization;
import org.apache.polygene.api.serialization.Serializer;
-import org.apache.polygene.api.structure.Application;
-import org.apache.polygene.api.structure.Module;
-import org.apache.polygene.bootstrap.Assembler;
import org.apache.polygene.bootstrap.AssemblyException;
-import org.apache.polygene.bootstrap.Energy4Java;
import org.apache.polygene.bootstrap.ModuleAssembly;
import org.apache.polygene.test.AbstractPolygeneTest;
import org.junit.Test;
@@ -46,8 +41,8 @@ import static org.junit.Assert.assertThat;
/**
* Snippets:
- * - default : default ValueSerialization
- * - service : assembled service ValueSerialization
+ * - default : default Serialization
+ * - service : assembled service Serialization
* - io : i/o usage
*/
public class DocumentationSupport extends AbstractPolygeneTest
@@ -61,7 +56,6 @@ public class DocumentationSupport extends AbstractPolygeneTest
@Override
public void assemble( ModuleAssembly module )
- throws AssemblyException
{
module.values( SomeValue.class ); // (2)
}
@@ -161,54 +155,6 @@ public class DocumentationSupport extends AbstractPolygeneTest
}
// END SNIPPET: io
- @Test
- // TODO Move to SPI !
- // TODO Include in each Serialization extensions documentation
- public void assembledWithValuesModuleSerialization()
- throws Exception
- {
- Application app = new Energy4Java().newApplication(
- applicationFactory ->
- {
- Assembler[][][] pancakes = new Assembler[][][]
- {
- {
- {
- valuesModule ->
- {
- valuesModule.layer().setName( "SINGLE-Layer" );
- valuesModule.setName( "VALUES-Module" );
-
- valuesModule.values( SomeValue.class );
- }
- },
- {
- servicesModule -> servicesModule.setName( "SERVICES-Module" )
- }
- }
- };
- return applicationFactory.newApplicationAssembly( pancakes );
- } );
- app.activate();
- try
- {
- SomeValue someValue = someNewValueInstance();
-
- Module servicesModule = app.findModule( "SINGLE-Layer", "SERVICES-Module" );
- Serialization stateSerialization = servicesModule.findService( Serialization.class ).get();
-
- String json = stateSerialization.serialize( someValue );
- assertThat( json, equalTo( "{\"foo\":\"bar\"}" ) );
-
- SomeValue someNewValue = stateSerialization.deserialize( module, SomeValue.class, json );
- assertThat( someNewValue, equalTo( someValue ) );
- }
- finally
- {
- app.passivate();
- }
- }
-
private SomeValue someNewValueInstance()
{
ValueBuilder<SomeValue> builder = valueBuilderFactory.newValueBuilder( SomeValue.class );
http://git-wip-us.apache.org/repos/asf/polygene-java/blob/ecae40d0/core/spi/src/docs/serialization.txt
----------------------------------------------------------------------
diff --git a/core/spi/src/docs/serialization.txt b/core/spi/src/docs/serialization.txt
index dca8955..d2d2580 100644
--- a/core/spi/src/docs/serialization.txt
+++ b/core/spi/src/docs/serialization.txt
@@ -20,64 +20,96 @@
[[core-spi-serialization,Serialization SPI]]
= Serialization SPI =
+TIP: Find Serialization extensions in the <<extensions>> list.
+
== Overview ==
The Polygene\u2122 Core Runtime use Serialization to provide string representation of ValueComposites via their `toString()`
method, and, their instantiation from the very same representation via the `newValueFromSerializedState(..)` method of
the ValueBuilderFactory API.
+[snippet,java]
+--------------
+source=core/api/src/test/java/org/apache/polygene/api/value/DocumentationSupport.java
+tag=default
+--------------
+
In each Module, if no Serialization service is assembled, a default one supporting the JSON format is used.
-// TODO Add sample usage of the Serialization service
+[snippet,java]
+--------------
+source=core/api/src/test/java/org/apache/polygene/api/value/DocumentationSupport.java
+tag=service
+--------------
-== Implementation notes ==
+== Text or Binary?
-Simply implement Serialization to create an extension for the Serialization SPI.
-The Core SPI module provides adapters to create pull-parsing capable Serializers and pull-parsing and tree-parsing
-capable Deserializers.
+The Core SPI provides adapters for text or bytes based serialization, extends the following types to implement a custom
+serialization.
-The behaviour described here apply to all Serialization services implemented using the Core SPI adapters. Note that
-nothing stops you from implementing an extension for the Serialization SPI without relying on theses adapters.
+For text based serialization:
-Theses adapters are tailored for serialization mechanisms that support the following two structures that can be nested:
+[snippet,java]
+--------------
+source=core/spi/src/main/java/org/apache/polygene/spi/serialization/AbstractTextSerializer.java
+tag=text
+--------------
- * a collection of name/value pairs. In various languages, this is realized as an object, record, struct,
- dictionary, hash table, keyed list, or associative array,
- * an ordered list of values. In most languages, this is realized as an array, vector, list, or sequence ;
+[snippet,java]
+--------------
+source=core/spi/src/main/java/org/apache/polygene/spi/serialization/AbstractTextDeserializer.java
+tag=text
+--------------
-in other words, a JSON-like structure.
+For bytes based serialization:
+
+[snippet,java]
+--------------
+source=core/spi/src/main/java/org/apache/polygene/spi/serialization/AbstractBinarySerializer.java
+tag=binary
+--------------
+
+[snippet,java]
+--------------
+source=core/spi/src/main/java/org/apache/polygene/spi/serialization/AbstractBinaryDeserializer.java
+tag=binary
+--------------
-Special attention is taken when dealing with Maps. They are serialized as an ordered list of collections of
-name/value pairs to keep the Map order for least surprise. That way, even when the underlying serialization mechanism
-do not keep the collection of name/value pairs order we can rely on it being kept.
+== JSON or XML?
-Here is a sample Map with two entries in JSON notation to make things clear:
+The Core SPI provides JSON and XML serialization respectively based on `javax.json` and `javax.xml` types and APIs to
+work directly with these types so you can work with the actual object representations without serializing to text or
+bytes. They both rely on the text serialization adapters shown above.
-[source,javascript]
-----
-[
- { "key": "foo", "value": "bar" },
- { "key": "cathedral", "value": "bazar" }
-]
-----
+Here is an example using the `JsonSerialization` service:
-Among Plain Values (see the <<core-api-value,Serialization API>> section) some are considered primitives to
-underlying serialization mechanisms and by so handed/come without conversion to/from implementations.
+[snippet,java]
+--------------
+source=extensions/serialization-javaxjson/src/test/java/org/apache/polygene/serialization/javaxjson/JavaxJsonValueCompositeSerializationTest.java
+tag=json-serialization
+--------------
-Primitive values can be one of:
+And another using the `XmlSerialization` service:
- * String,
- * Boolean or boolean,
- * Integer or int,
- * Long or long,
- * Short or short,
- * Byte or byte,
- * Float or float,
- * Double or double.
+[snippet,java]
+--------------
+source=extensions/serialization-javaxxml/src/test/java/org/apache/polygene/serialization/javaxxml/JavaxXmlValueCompositeSerializationTest.java
+tag=xml-serialization
+--------------
-Serialization is always done in a streaming manner using a pull-parsing based approach.
-Deserialization is done in a streaming manner using a pull-parsing based approach except when encountering a
-ValueComposite. ValueComposite types are deserialized using a tree-parsing based approach.
+== Implementation notes ==
+
+Simply implement Serialization to create an extension for the Serialization SPI.
+The Core SPI module provides adapters to create Serializers and Deserializers.
-All this means that you can serialize and deserialize large collections of values without filling the heap.
+The behaviour described here apply to all Serialization services implemented using the Core SPI adapters. Note that
+nothing stops you from implementing an extension for the Serialization SPI without relying on theses adapters.
+
+Theses adapters are tailored for serialization mechanisms that support the following two structures that can be nested:
+
+ * a collection of name/value pairs. In various languages, this is realized as an object, record, struct,
+ dictionary, hash table, keyed list, or associative array,
+ * an ordered list of values. In most languages, this is realized as an array, vector, list, or sequence ;
+
+in other words, a JSON-like structure.
http://git-wip-us.apache.org/repos/asf/polygene-java/blob/ecae40d0/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 a8f2c2c..7e2d19a 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
@@ -28,7 +28,14 @@ import org.apache.polygene.api.type.ValueType;
import static java.util.stream.Collectors.joining;
+// START SNIPPET: binary
+/**
+ * Base Binary Deserializer.
+ *
+ * Implementations work on bytes, this base deserializer decode Strings from Base64 to produce bytes.
+ */
public abstract class AbstractBinaryDeserializer extends AbstractDeserializer
+// END SNIPPET: binary
{
@Override
public <T> T deserialize( ModuleDescriptor module, ValueType valueType, Reader state )
http://git-wip-us.apache.org/repos/asf/polygene-java/blob/ecae40d0/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 e673ad7..0cf17eb 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
@@ -26,12 +26,14 @@ import org.apache.polygene.api.common.Optional;
import static java.nio.charset.StandardCharsets.UTF_8;
+// START SNIPPET: binary
/**
* Base Binary Serializer.
*
* Implementations work on bytes, this base serializer encode these bytes in Base64 to produce Strings.
*/
public abstract class AbstractBinarySerializer extends AbstractSerializer
+// END SNIPPET: binary
{
@Override
public void serialize( Options options, Writer writer, @Optional Object object )
http://git-wip-us.apache.org/repos/asf/polygene-java/blob/ecae40d0/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 0575489..d87dd6d 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
@@ -24,7 +24,14 @@ import org.apache.polygene.api.type.ValueType;
import static java.nio.charset.StandardCharsets.UTF_8;
+// START SNIPPET: text
+/**
+ * Base Text Deserializer.
+ *
+ * Implementations work on Strings, this base deserializer decode bytes in UTF-8 to produce strings.
+ */
public abstract class AbstractTextDeserializer extends AbstractDeserializer
+// END SNIPPET: text
{
@Override
public <T> T deserialize( ModuleDescriptor module, ValueType valueType, InputStream state )
http://git-wip-us.apache.org/repos/asf/polygene-java/blob/ecae40d0/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 3d8bb16..2c2b83c 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
@@ -25,12 +25,14 @@ import org.apache.polygene.api.common.Optional;
import static java.nio.charset.StandardCharsets.UTF_8;
+// START SNIPPET: text
/**
* Base Text Serializer.
*
* Implementations work on Strings, this base serializer encode these strings in UTF-8 to produce bytes.
*/
public abstract class AbstractTextSerializer extends AbstractSerializer
+// END SNIPPET: text
{
public void serialize( Options options, OutputStream output, @Optional Object object )
{
http://git-wip-us.apache.org/repos/asf/polygene-java/blob/ecae40d0/extensions/serialization-javaxjson/src/docs/serialization-javaxjson.txt
----------------------------------------------------------------------
diff --git a/extensions/serialization-javaxjson/src/docs/serialization-javaxjson.txt b/extensions/serialization-javaxjson/src/docs/serialization-javaxjson.txt
index f9aee3f..60cfa30 100644
--- a/extensions/serialization-javaxjson/src/docs/serialization-javaxjson.txt
+++ b/extensions/serialization-javaxjson/src/docs/serialization-javaxjson.txt
@@ -25,7 +25,25 @@
source=extensions/serialization-javaxjson/dev-status.xml
--------------
-// TODO Preamble - link to <<core-api-serialization>> and <<core-spi-serialization>>
-// TODO Document usage of JsonSerialization
+`Serialization` service backed by `javax.json` types.
+See <<core-api-serialization>> and <<core-spi-serialization>>.
+
+include::../../build/docs/buildinfo/artifact.txt[]
+
+This extension comes with https://johnzon.apache.org/[Apache Johnzon] as a default `javax.json` provider.
+You can exclude its dependency and replace it by the one of your choice.
+
// TODO Include sample model and its output from test code & resources
-// TODO Assembly - Serialization extension or sole Service, settings & adapters
+
+== Assembly ==
+
+Assembly is done using the provided Assembler:
+
+[snippet,java]
+----
+source=extensions/serialization-javaxjson/src/test/java/org/apache/polygene/serialization/javaxjson/JavaxJsonValueCompositeSerializationTest.java
+tag=assembly
+----
+
+Note that this assembler is optional as Polygene assemble this service by default if no Serialization service is declared.
+
http://git-wip-us.apache.org/repos/asf/polygene-java/blob/ecae40d0/extensions/serialization-javaxjson/src/test/java/org/apache/polygene/serialization/javaxjson/JavaxJsonValueCompositeSerializationTest.java
----------------------------------------------------------------------
diff --git a/extensions/serialization-javaxjson/src/test/java/org/apache/polygene/serialization/javaxjson/JavaxJsonValueCompositeSerializationTest.java b/extensions/serialization-javaxjson/src/test/java/org/apache/polygene/serialization/javaxjson/JavaxJsonValueCompositeSerializationTest.java
index 5fe4f5f..404a143 100644
--- a/extensions/serialization-javaxjson/src/test/java/org/apache/polygene/serialization/javaxjson/JavaxJsonValueCompositeSerializationTest.java
+++ b/extensions/serialization-javaxjson/src/test/java/org/apache/polygene/serialization/javaxjson/JavaxJsonValueCompositeSerializationTest.java
@@ -23,6 +23,7 @@ import javax.json.JsonObject;
import javax.json.JsonValue;
import org.apache.polygene.api.injection.scope.Service;
import org.apache.polygene.api.unitofwork.UnitOfWork;
+import org.apache.polygene.bootstrap.ModuleAssembly;
import org.apache.polygene.spi.serialization.JsonSerialization;
import org.apache.polygene.test.serialization.AbstractValueCompositeSerializationTest;
import org.junit.Test;
@@ -32,12 +33,26 @@ import static org.junit.Assert.assertThat;
public class JavaxJsonValueCompositeSerializationTest extends AbstractValueCompositeSerializationTest
{
+ // START SNIPPET: assembly
+ @Override
+ public void assemble( ModuleAssembly module )
+ {
+ new JavaxJsonSerializationAssembler().assemble( module );
+ // END SNIPPET: assembly
+ super.assemble( module );
+ // START SNIPPET: assembly
+ }
+ // END SNIPPET: assembly
+
+ // START SNIPPET: json-serialization
@Service
- private JsonSerialization jsonSerialization;
+ JsonSerialization jsonSerialization;
+ // END SNIPPET: json-serialization
@Test
public void valueCompositeJsonEquality()
{
+ // START SNIPPET: json-serialization
try( UnitOfWork uow = unitOfWorkFactory.newUnitOfWork() )
{
Some some = buildSomeValue( moduleInstance, uow, "42" );
@@ -50,11 +65,12 @@ public class JavaxJsonValueCompositeSerializationTest extends AbstractValueCompo
// Deserialize using Module API
Some some2 = moduleInstance.newValueFromSerializedState( Some.class, stateString );
- assertThat( "Value equality", some, equalTo( some2 ) );
+ assertThat( "Deserialized Value equality", some, equalTo( some2 ) );
JsonObject jsonState2 = Json.createReader( new StringReader( some2.toString() ) ).readObject();
- assertThat( "JSON equality", jsonState, equalTo( jsonState2 ) );
+ assertThat( "value.toString() JSON equality", jsonState, equalTo( jsonState2 ) );
}
+ // END SNIPPET: json-serialization
}
}
http://git-wip-us.apache.org/repos/asf/polygene-java/blob/ecae40d0/extensions/serialization-javaxxml/src/docs/serialization-javaxxml.txt
----------------------------------------------------------------------
diff --git a/extensions/serialization-javaxxml/src/docs/serialization-javaxxml.txt b/extensions/serialization-javaxxml/src/docs/serialization-javaxxml.txt
index 6fe6d75..aef6392 100644
--- a/extensions/serialization-javaxxml/src/docs/serialization-javaxxml.txt
+++ b/extensions/serialization-javaxxml/src/docs/serialization-javaxxml.txt
@@ -25,6 +25,22 @@
source=extensions/serialization-javaxxml/dev-status.xml
--------------
-// TODO Document usage of XmlSerialization
+`Serialization` service backed by `javax.xml` types.
+See <<core-api-serialization>> and <<core-spi-serialization>>.
+
+include::../../build/docs/buildinfo/artifact.txt[]
+
+This extension make use of the Java runtime default `javax.xml` provider.
+You can add dependencies to replace it by the one of your choice.
+
// TODO Include sample model and its output from test code & resources
-// TODO Assembly - Serialization extension or sole Service, settings & adapters
+
+== Assembly ==
+
+Assembly is done using the provided Assembler:
+
+[snippet,java]
+----
+source=extensions/serialization-javaxxml/src/test/java/org/apache/polygene/serialization/javaxxml/JavaxXmlValueCompositeSerializationTest.java
+tag=assembly
+----
http://git-wip-us.apache.org/repos/asf/polygene-java/blob/ecae40d0/extensions/serialization-javaxxml/src/test/java/org/apache/polygene/serialization/javaxxml/JavaxXmlValueCompositeSerializationTest.java
----------------------------------------------------------------------
diff --git a/extensions/serialization-javaxxml/src/test/java/org/apache/polygene/serialization/javaxxml/JavaxXmlValueCompositeSerializationTest.java b/extensions/serialization-javaxxml/src/test/java/org/apache/polygene/serialization/javaxxml/JavaxXmlValueCompositeSerializationTest.java
index 27bebc2..b86a2dc 100644
--- a/extensions/serialization-javaxxml/src/test/java/org/apache/polygene/serialization/javaxxml/JavaxXmlValueCompositeSerializationTest.java
+++ b/extensions/serialization-javaxxml/src/test/java/org/apache/polygene/serialization/javaxxml/JavaxXmlValueCompositeSerializationTest.java
@@ -33,12 +33,16 @@ import static org.xmlunit.matchers.CompareMatcher.isSimilarTo;
// TODO Assert deserialization from formatted XML, whitespaces are a problem ATM
public class JavaxXmlValueCompositeSerializationTest extends AbstractValueCompositeSerializationTest
{
+ // START SNIPPET: assembly
@Override
public void assemble( ModuleAssembly module )
{
new JavaxXmlSerializationAssembler().assemble( module );
+ // END SNIPPET: assembly
super.assemble( module );
+ // START SNIPPET: assembly
}
+ // END SNIPPET: assembly
// START SNIPPET: xml-serialization
@Service
http://git-wip-us.apache.org/repos/asf/polygene-java/blob/ecae40d0/extensions/serialization-msgpack/src/docs/serialization-msgpack.txt
----------------------------------------------------------------------
diff --git a/extensions/serialization-msgpack/src/docs/serialization-msgpack.txt b/extensions/serialization-msgpack/src/docs/serialization-msgpack.txt
index ad50c08..3ae0fa4 100644
--- a/extensions/serialization-msgpack/src/docs/serialization-msgpack.txt
+++ b/extensions/serialization-msgpack/src/docs/serialization-msgpack.txt
@@ -25,6 +25,19 @@
source=extensions/serialization-msgpack/dev-status.xml
--------------
-// TODO Document usage of MessagePackSerialization
+`Serialization` service backed by http://msgpack.org/[MessagePack] that produce and consume binary payloads.
+See <<core-api-serialization>> and <<core-spi-serialization>>.
+
+include::../../build/docs/buildinfo/artifact.txt[]
+
// TODO Include sample model and its output from test code & resources
-// TODO Assembly - Serialization extension or sole Service, settings & adapters
+
+== Assembly ==
+
+Assembly is done using the provided Assembler:
+
+[snippet,java]
+----
+source=extensions/serialization-msgpack/src/test/java/org/apache/polygene/serialization/msgpack/MessagePackValueCompositeSerializationTest.java
+tag=assembly
+----
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/polygene-java/blob/ecae40d0/extensions/serialization-msgpack/src/test/java/org/apache/polygene/serialization/msgpack/MessagePackValueCompositeSerializationTest.java
----------------------------------------------------------------------
diff --git a/extensions/serialization-msgpack/src/test/java/org/apache/polygene/serialization/msgpack/MessagePackValueCompositeSerializationTest.java b/extensions/serialization-msgpack/src/test/java/org/apache/polygene/serialization/msgpack/MessagePackValueCompositeSerializationTest.java
index 204f991..dd9291e 100644
--- a/extensions/serialization-msgpack/src/test/java/org/apache/polygene/serialization/msgpack/MessagePackValueCompositeSerializationTest.java
+++ b/extensions/serialization-msgpack/src/test/java/org/apache/polygene/serialization/msgpack/MessagePackValueCompositeSerializationTest.java
@@ -22,10 +22,14 @@ import org.apache.polygene.test.serialization.AbstractValueCompositeSerializatio
public class MessagePackValueCompositeSerializationTest extends AbstractValueCompositeSerializationTest
{
+ // START SNIPPET: assembly
@Override
public void assemble( ModuleAssembly module )
{
new MessagePackSerializationAssembler().assemble( module );
+ // END SNIPPET: assembly
super.assemble( module );
+ // START SNIPPET: assembly
}
+ // END SNIPPET: assembly
}