MessagePack serialization

Group ID	Artifact ID	Version
org.apache.polygene.extensions	org.apache.polygene.extension.serialization-messagepack	3.0.0-SNAPSHOT

Extensions

Overview

We try to keep the Polygene™ Core Runtime as lean as possible, and a lot of the power to th e Polygene™ Platform comes via its +

Polygene™
Introduction
Tutorials
Javadoc
Samples
Core
Libraries
Extensions
Tools
Glossary

Extensions

Overview

We try to keep the Polygene™ Core Runtime as lean as possible, a nd a lot of the power to the Polygene™ Platform comes via its Extension SPI, which defines clear ways to extend the platform. There are currently the following Extensions types, -each with possibly more than one implementation;

-Value Serialization +each with possibly more than one implementation;
- +Serialization
- Entity Stores
- http://git-wip-us.apache.org/repos/asf/polygene-website/blob/51abe7dd/content/java/develop/glossary.html ---------------------------------------------------------------------- diff --git a/content/java/develop/glossary.html b/content/java/develop/glossary.html index f11e7a1..2ed52c4 100644 --- a/content/java/develop/glossary.html +++ b/content/java/develop/glossary.html @@ -1,5 +1,5 @@ -Glossary +Glossary @@ -66,35 +66,35 @@ })(); -
  Polygene™
  Introduction
  Tutorials
  Javadoc
  Samples
  Core
  Libraries
  Extensions
  Tools
  Glossary
  Glossary
  Glossary
  There are a lot of concepts in Polygene™ which may have different meanings in other contexts. So in true DDD-style -ubiquitous language, we are here listing the definitions of the terms and concepts that are being used.
  +
  Polygene™
  Introduction
  Tutorials
  Javadoc
  Samples
  Core
  Libraries
  Extensions
  Tools
  Glossary
  Glossary
  Glossary
  There are a lot of concepts in Polygene™ which may have different meanings in other contexts. So in true DDD-style +ubiquitous language, we are here listing the definitions of the terms and concepts that are being used.
  Abstract Mixin -
  An Abstract Mixin is an implementation of the MixinType interface, but is an abstract class and has not +
  An Abstract Mixin is an implementation of the MixinType interface, but is an abstract class and has not implemented all the methods.
  The Polygene™ runtime can use multiple Mixins for each MixinType interface. It is also possible to let -a Generic Mixin handle the remaining missing methods.
  +a Generic Mixin handle the remaining missing methods.
  Abstract Modifier -
  Abstract Modifiers are Modifiers that do not implement all the methods of the MixinType +
  Abstract Modifiers are Modifiers that do not implement all the methods of the MixinType interface.
  This works essentially in the same manner as the Abstract Mixin. And the methods that are not implemented -will not be part of the Invocation Stack of those methods.
  +will not be part of the Invocation Stack of those methods.
  Application -
  Application is the top level concept handled by the Polygene™ runtime instance. It holds the information about the -Layers in the application architecture. See Structure for more information.
  There is one and only one Application instance per Polygene™ Runtime instance.
  +
  Application is the top level concept handled by the Polygene™ runtime instance. It holds the information about the +Layers in the application architecture. See Structure for more information.
  There is one and only one Application instance per Polygene™ Runtime instance.
  Application Mode -
  During the Bootstrap phase an Application is given a Mode that can be test, development, staging or -production.
  See Assembly.
  +
  During the Bootstrap phase an Application is given a Mode that can be test, development, staging or +production.
  See Assembly.
  Association -
  An Association is a reference to an Entity Composite.
  References to Entities must be maintained in Associations. It is illegal to -define a Property with an Entity Composite as its type.
  +
  An Association is a reference to an Entity Composite.
  References to Entities must be maintained in Associations. It is illegal to +define a Property with an Entity Composite as its type.
  Composite -
  A Composite is an instance of a Composite Type.
  However, we often speak of Composites when we actually mean CompositeType, similarly as we often speak of objects -when we really are talking of classes in OOP.
  +
  A Composite is an instance of a Composite Type.
  However, we often speak of Composites when we actually mean CompositeType, similarly as we often speak of objects +when we really are talking of classes in OOP.
  Composite Context -
  A Composite Context is a mechanism to separate the state of a TransientComposite across two or more threads. +
  A Composite Context is a mechanism to separate the state of a TransientComposite across two or more threads. If a thread modifies a value, only that thread will see the changes, another thread will have its values protected -by the thread boundaries. Use-cases for this include user credentials on which behalf the thread is executing.
  +by the thread boundaries. Use-cases for this include user credentials on which behalf the thread is executing.
  Composite Meta Type -
  There are 5 Composite Meta Types defined in Polygene, which each share the composition features but have distinct -semantic differences.
  +
  There are 5 Composite Meta Types defined in Polygene, which each share the composition features but have distinct +semantic differences.
  Entity Composite
  ValueComposite @@ -104,37 +104,37 @@ semantic differences.
  Configuration Composite (subtype of EntityComposite)
  TransientComposite -
  +
  Composite Type -
  CompositeType is the Java interface that declares the composition, from which Composite instances can be +
  CompositeType is the Java interface that declares the composition, from which Composite instances can be created.
  Composite Type interfaces must be a sub-type of one of the 5 Composite Meta Types defined in -Polygene™ otherwise it can not be instantiated.
  +Polygene™ otherwise it can not be instantiated.
  Concern -
  A concern is a stateless Fragment, shared between invocations, that acts as an interceptor of the call to +
  A concern is a stateless Fragment, shared between invocations, that acts as an interceptor of the call to the Mixin. The Concern is a Java class, that either implements the MixinType it can be used on, or java.lang.reflect.InvocationHandler which allows it to be used on any arbitrary MixinType.
  Concerns have many purposes, but they are not intended to produce side effects (see SideEffect). Use-cases -involves;
  +involves;
  Transaction handling.
  Call Tracing.
  User security. -
  Concerns are established by the use of the @Concerns annotation on composites.
  Concern is one of the 3 kinds of Modifiers defined in Polygene.
  +
Concerns are established by the use of the @Concerns annotation on composites.
Concern is one of the 3 kinds of Modifiers defined in Polygene.
Configuration Composite -
Service Composites can have configuration associated to it and that is done via +
Service Composites can have configuration associated to it and that is done via Configuration Composites, which are a subtype of Entity Composite, as they are stored permanently in configured Entity Stores. Configuration Composites are also initialized automatically from properties files first time. Note that on consequent start-ups the properties file is not read, as the configuration is -read from the EntityStore.
ConfigurationComposite is one of the 5 Composite Meta Types defined in Polygene.
See Configure a Service to learn how to use Configuration Composites.
+read from the EntityStore.
ConfigurationComposite is one of the 5 Composite Meta Types defined in Polygene.
See Configure a Service to learn how to use Configuration Composites.
Constraint -
Constraints are a kind of validators, which are consulted prior to invoking the method call. Polygene™ currently only +
Constraints are a kind of validators, which are consulted prior to invoking the method call. Polygene™ currently only supports ParameterConstraints on methods and value constraints on Properties, but future versions will -include Constraint types for checking complete method calls and return values.
See Constraint for better understanding of its details.
See Constraints Library for ready to use Constraints.
See Create a Constraint to learn how to write your own Constraints.
Constraint is one of the 3 kinds of Modifiers defined in Polygene.
+include Constraint types for checking complete method calls and return values.
See Constraint for better understanding of its details.
See Constraints Library for ready to use Constraints.
See Create a Constraint to learn how to write your own Constraints.
Constraint is one of the 3 kinds of Modifiers defined in Polygene.
Entity Composite -
An Entity Composite, or just Entity for short, is a persisted composite with an Identity. An entity only has -scope within an UnitOfWork and is therefor inherently thread-safe.
EntityComposite is one of the 5 Composite Meta Types defined in Polygene.
+
An Entity Composite, or just Entity for short, is a persisted composite with an Identity. An entity only has +scope within an UnitOfWork and is therefor inherently thread-safe.
EntityComposite is one of the 5 Composite Meta Types defined in Polygene.
Fragment -
A part of the implementation of a Composite. There are 4 fragment types:
- +
  A part of the implementation of a Composite. There are 4 fragment types:
  Mixin
  Concern @@ -142,20 +142,20 @@ scope within an UnitOfWorkConstraint
  SideEffect. -
  +
Generic Fragment -
Generic Fragments are Fragments that implements java.lang.reflect.InvocationHandler and potentially +
Generic Fragments are Fragments that implements java.lang.reflect.InvocationHandler and potentially capable of being used for all MixinTypes. This is the direct opposite of the Typed Fragments, which -implements the MixinType interface.
+implements the MixinType interface.
Generic Mixin -
A Generic Mixin implements the java.lang.reflect.InvocationHandler. The invoke() method will be called for all +
A Generic Mixin implements the java.lang.reflect.InvocationHandler. The invoke() method will be called for all MixinType methods that the Mixin has been matched with, through the matching rules.
It is potentially possible that the Generic Mixin also implements the MixinType interface. In that case, the concrete methods will be called, but if the Mixin is also an abstract class, then the invoke() method will be -called for the methods that has been match but are not present.
+called for the methods that has been match but are not present.
Identity -
TODO
This term has no definition yet. Learn how to contribute in Writing Documentation.
+
TODO
This term has no definition yet. Learn how to contribute in Writing Documentation.
Invocation Stack -
For each method, Polygene™ will create and re-use an Invocation Stack. It will be built with the sequence of +
For each method, Polygene™ will create and re-use an Invocation Stack. It will be built with the sequence of Modifiers and an end-point that will link into the stateful Mixin.
It is important to recognize that, for memory footprint reasons, Invocation Stacks are shared across Composites of the same Composite Type. They are however thread-safe, in that Polygene™ will never bind the same Invocation Stack to more than one Composite instance during a method call, but that between method @@ -163,58 +163,58 @@ invocations the Modifiers Composite instance. Therefor, Modifiers are not expected to keep state between method invocations, and when it needs to do that, then it should reference a Mixin via the @This annotation. Polygene™ will during the binding of the Invocation Stack to the Composite, also ensure that all referenced -Mixins are correctly injected in the Invocation Stack.
+Mixins are correctly injected in the Invocation Stack.
Layer -
Polygene™ promotes a Layered application design, where Layers can only access lower Layers and not higher Layers or Layers at -the same level.
+
Polygene™ promotes a Layered application design, where Layers can only access lower Layers and not higher Layers or Layers at +the same level.
ManyAssociation -
TODO
This term has no definition yet. Learn how to contribute in Writing Documentation.
+
TODO
This term has no definition yet. Learn how to contribute in Writing Documentation.
MetaInfo -
TODO
This term has no definition yet. Learn how to contribute in Writing Documentation.
+
TODO
This term has no definition yet. Learn how to contribute in Writing Documentation.
Mixin -
The Mixin is the instance providing the stateful representation of the MixinType. This can either be a class +
The Mixin is the instance providing the stateful representation of the MixinType. This can either be a class implementing the MixinType or a java.lang.reflect.InvocationHandler that is generic to handle any or a subset -of MixinType.
+of MixinType.
MixinType -
The MixinType is the static type of a part of the Composite. The MixinType is an interface that defines the methods -to be exposed in the Composite.
+
The MixinType is the static type of a part of the Composite. The MixinType is an interface that defines the methods +to be exposed in the Composite.
Modifier -
Modifiers are stateless interceptors of method calls, that forms an Invocation Stack. The top of the +
Modifiers are stateless interceptors of method calls, that forms an Invocation Stack. The top of the Invocation Stack is linked to the Composite invocation handler and the bottom of the Invocation Stack is linked to the Mixins. Invocation Stacks are shared, -so Modifiers must assume that the member fields will only be valid within a single method invocation.
There are 3 kinds of Modifiers;
- +so Modifiers must assume that the member fields will only be valid within a single method invocation.
  There are 3 kinds of Modifiers;
  Constraint
  Concern
  SideEffect -
+

Module -

Modules defines the scope of the Composites. Modules are wired with Assemblies, and can expose -Composites as visible. Non-visible Composites are not reachable from other Modules.

Modules defines the scope of the Composites. Modules are wired with Assemblies, and can expose +Composites as visible. Non-visible Composites are not reachable from other Modules.

NamedAssociation -

TODO

This term has no definition yet. Learn how to contribute in Writing Documentation.

TODO

This term has no definition yet. Learn how to contribute in Writing Documentation.

Private Mixin -

When a @This injection refers to a MixinType which is not extended by the Composite Type the former -becomes a private MixinType.

When a @This injection refers to a MixinType which is not extended by the Composite Type the former +becomes a private MixinType.

Property -

TODO

This term has no definition yet. Learn how to contribute in Writing Documentation.

See the Leverage Properties how-to.

TODO

This term has no definition yet. Learn how to contribute in Writing Documentation.

See the Leverage Properties how-to.

Service Composite -

Service Composite is a subtype of Composite, and has a range of features built into it.

ServiceComposite is one of the 5 Composite Meta Types defined in Polygene.

See the Service Composite chapter.

Service Composite is a subtype of Composite, and has a range of features built into it.

ServiceComposite is one of the 5 Composite Meta Types defined in Polygene.

See the Service Composite chapter.

SideEffect -

A side effect is a stateless Fragment, shared between invocations, that acts as an interceptor of the call to +

A side effect is a stateless Fragment, shared between invocations, that acts as an interceptor of the call to the Mixin. The SideEffect is a Java class, that either implements the MixinType it can be used on, or java.lang.reflect.InvocationHandler which allows it to be used on any arbitrary MixinType.

SideEffects are executed after the completion of the method invocation and therefore cannot change parameters nor eventually returned object.

SideEffects have many purposes. Use-cases -involves;

+involves;
- Sending emails.
- Call Tracing.
- Domain side effects modeling. -
SideEffects are established by the use of the @SideEffects annotation on composites.
SideEffect is one of the 3 kinds of Modifiers defined in Polygene.

SideEffects are established by the use of the @SideEffects annotation on composites.

SideEffect is one of the 3 kinds of Modifiers defined in Polygene.

Structure -

Polygene™ promotes a conventional view of application structure, that computer science has been using for decades.

The definition is as follows;

+
Polygene™ promotes a conventional view of application structure, that computer science has been using for decades.
The definition is as follows;
- One Application per Polygene™ runtime instance.
- One or more Layers per Application. @@ -226,24 +226,24 @@ Zero, one or more Assemblies per Modules, so that code can only reach Composites and Objects in Modules (including itself) of the same or lower Layers.
  Each Layer has to be declared which lower Layer(s) it uses, and it is not allowed that a lower -Layer uses a higher Layer, i.e. cyclic references.
+Layer uses a higher Layer, i.e. cyclic references.

TransientComposite -

TransientComposite is a Composite Meta Type for all other cases. The main characteristics are;

+
TransientComposite is a Composite Meta Type for all other cases. The main characteristics are;
- It can not be serialized nor persisted.
- hashcode/equals are not treated specially and will be delegated to Fragment(s) implementing those methods.
- It can not be used as a Property type. -
+

UnitOfWork -

TODO

This term has no definition yet. Learn how to contribute in Writing Documentation.

TODO

This term has no definition yet. Learn how to contribute in Writing Documentation.

ValueComposite -

Usage of value objects is one of the most ignored and best return-on-investment the programmer can do. Values are +

Usage of value objects is one of the most ignored and best return-on-investment the programmer can do. Values are immutable and can be compared by value instead of memory reference. Concurrency is suddenly not an issue, since either the value exists or it doesn’t, no need for synchronization. Values are typically very easy to test and very robust to refactoring.

Polygene™ defines values as a primary meta type through the ValueComposite, as we think the benefits of values are great. The ValueComposite is very light-weight compared to the Entity Composite, and its value can still be persisted as -part of an Entity Composite via a Property.

The characteristics of a ValueComposite compared to other Composite Meta Types are;

+part of an Entity Composite via a Property.
The characteristics of a ValueComposite compared to other Composite Meta Types are;
- It is Immutable.
- Its equals/hashCode works on the values of the ValueComposite. http://git-wip-us.apache.org/repos/asf/polygene-website/blob/51abe7dd/content/java/develop/howto-assemble-application.html ---------------------------------------------------------------------- diff --git a/content/java/develop/howto-assemble-application.html b/content/java/develop/howto-assemble-application.html index 5d515c1..b51764f 100644 --- a/content/java/develop/howto-assemble-application.html +++ b/content/java/develop/howto-assemble-application.html @@ -1,5 +1,5 @@ -Assemble an Application +Assemble an Application @@ -66,9 +66,9 @@ })(); -
  Polygene™
  Introduction
  Tutorials
  Javadoc
  Samples
  Core
  Libraries
  Extensions
  Tools
  Glossary
  Overview
  Polygene™ in 2 minutes
  Polygene™ in 10 minutes
  Polygene™ in 30 minutes
  Depend on Polygene™
  Assemble an Application
  Transient Composites Tutorial
  Services Composites Tutorial
  Use contextual fragments
  Leverage Properties
  Create a Constraint
  Create a Concern
  Create a SideEffect
  Create an Entity
  Configure a Service
  Use @Invocation
  Polygene™ Build System
  Polygene™ Documentation
  Releasing Polygene™
  Assemble an Application
  We receive a lot of questions about how applications should be assembled, and since we don’t have any XML to "fill in" +
  Polygene™
  Introduction
  Tutorials
  Javadoc
  Samples
  Core
  Libraries
  Extensions
  Tools
  Glossary
  Overview
  Polygene™ in 2 minutes
  Polygene™ in 10 minutes
  Polygene™ in 30 minutes
  Depend on Polygene™
  Assemble an Application
  Transient Composites Tutorial
  Services Composites Tutorial
  Use contextual fragments
  Leverage Properties
  Create a Constraint
  Create a Concern
  Create a SideEffect
  Create an Entity
  Configure a Service
  Use @Invocation
  Polygene™ Build System
  Polygene™ Documentation
  Releasing Polygene™
  Assemble an Application
  We receive a lot of questions about how applications should be assembled, and since we don’t have any XML to "fill in" and everything is to be done programmatically, it escalates the need to provide more hands-on explanation of how this is -done.
  If you want to reproduce what’s explained in this tutorial, remember to depend on the Core Bootstrap artifact:
  At runtime you will need the Core Runtime artifact too. See the Depend on Polygene™ tutorial for details.
  Basics
  First let’s recap the structural requirements of Polygene;
  +done.
  If you want to reproduce what’s explained in this tutorial, remember to depend on the Core Bootstrap artifact:
  Table 4. Artifact
  Group ID Artifact ID Version
  org.apache.polygene.core
  org.apache.polygene.core.bootstrap
  3.0.0-SNAPSHOT
  
  At runtime you will need the Core Runtime artifact too. See the Depend on Polygene™ tut orial for details.
  Basics
  First let’s recap the structural requirements of Polygene;
  There is one and only one Application instance per Polygene™ Runtime.
  Every Application must contain one or more Layers. @@ -80,8 +80,8 @@ Each Module belong to a Layer. Layers are ordered in hierarchies, from simple to complex.
  Access to Composites are limited by visibility rules. -
  Ok, that was quite a handful. Let’s look at them one by one.
  Application
  The first one means that for each Polygene™ Runtime you start, there will be exactly one application. As far as we know, Polygene -is fully isolated, meaning there are no static members being populated and such.
  Layers
  Layers are the super-structures of an application. We have been talking about them for decades, drawn them on paper and +
  Ok, that was quite a handful. Let’s look at them one by one.
  Application
  The first one means that for each Polygene™ Runtime you start, there will be exactly one application. As far as we know, Polygene +is fully isolated, meaning there are no static members being populated and such.
  Layers
  Layers are the super-structures of an application. We have been talking about them for decades, drawn them on paper and whiteboards (or even black boards for those old enough), and sometimes organized the codebases along such boundaries. But, there has been little effort to enforce the Layer mechanism in code, although it is an extremely powerful construct. First of all it implies directional dependency and a high degree of order, spagetti code is reduced if @@ -90,16 +90,16 @@ higher layers can not reach them incidentally. You can enforce architecture to a creation of composites to go through an exposed Factory, which doesn’t require the Composite to be public. And so on. Layers have hierarchy, i.e. one layer is top of one or more layers, and is below one or more layers, except for the layers at the top and bottom. You could have disjoint layers, which can’t access each other, meaning a couple of layers -that are both the top and bottom.
  Modules
  The Module concept has also been around forever. And in Polygene™ we also makes the Modules explicit. Each Module belong to a +that are both the top and bottom.
  Modules
  The Module concept has also been around forever. And in Polygene™ we also makes the Modules explicit. Each Module belong to a Layer, and for each Module you declare the Composite and Object types for that Module, together with a Visibility rule, -one of; application, layer, module.
  Visibility
  The Visibility rules are perhaps the most powerful aspect of the above. Visibility is a mechanism that kicks in whenever +one of; application, layer, module.
  Visibility
  The Visibility rules are perhaps the most powerful aspect of the above. Visibility is a mechanism that kicks in whenever a Composite type need to be looked up. It defines both the scoping rules of the client as well as the provider. A lookup is either a direct reference, such as
  UnitOfWork unitOfWork = module.currentUnitOfWork(); PersonEntity person = unitOfWork.newEntity( PersonEntity.class );
  or an indirect lookup, such as
  UnitOfWork unitOfWork = module.currentUnitOfWork(); Person person = unitOfWork.newEntity( Person.class );
  where it will first map the Person to a reachable PersonEntity. -The algorithm is as follows;
  +The algorithm is as follows;
  Look in the callers Module, if there is one and only one Composite type matching, use it. If there are two or more Composite types matching, then throw an ambiguity exception. If there are zero, proceed to the next step.
  @@ -114,7 +114,7 @@ Look in all Layers that caller’s Layer uses. If there is one and only one Comp Throw a CompositeNotFoundException.
  The underlying principle comes down to Rickard’s "Speaker Analogy", you can hear him (and not the other speakers at the conference) because you are in the same room. I.e. if something is really close by, it is very likely that this is what -we want to use, and then the search expands outwards.
  Combining The Above
  Ok, that was a whole lot of theory and probably take you more than one read-through to fully get into your veins (slow +we want to use, and then the search expands outwards.
  Combining The Above
  Ok, that was a whole lot of theory and probably take you more than one read-through to fully get into your veins (slow acting addiction). How to structure your code is beyond the scope of this section. If you are an experienced designer, you will have done that before, and you may have started out with good intentions at times only to find yourself in a spaghetti swamp @@ -133,18 +133,14 @@ modules. See picture below.
  Image of Example of Layers
  Figure 1. Exa polygene = new Energy4Java(); // Instantiate the Application Model. - application = polygene.newApplication( new ApplicationAssembler() - { - public ApplicationAssembly assemble( - ApplicationAssemblyFactory factory ) - throws AssemblyException + application = polygene.newApplication( + factory -> { - ApplicationAssembly assembly = - factory.newApplicationAssembly(); + ApplicationAssembly assembly = factory.newApplicationAssembly(); LayerAssembly runtime = createRuntimeLayer( assembly ); LayerAssembly designer = createDesignerLayer( assembly ); LayerAssembly domain = createDomainLayer( assembly ); - LayerAssembly messaging= createMessagingLayer( assembly ); + LayerAssembly messaging = createMessagingLayer( assembly ); LayerAssembly persistence = createPersistenceLayer( assembly ); // declare structure between layers @@ -155,8 +151,7 @@ modules. See picture below.
  Image of Example of Layers
  Figure 1. Exa runtime.uses( domain ); return assembly; - } - } ); + } ); // We need to handle shutdown. installShutdownHook();