http://git-wip-us.apache.org/repos/asf/polygene-website/blob/ea4d77b0/content/java/latest/core-api.html
----------------------------------------------------------------------
diff --git a/content/java/latest/core-api.html
b/content/java/latest/core-api.html
deleted file mode 100644
index d4c99e9..0000000
--- a/content/java/latest/core-api.html
+++ /dev/null
@@ -1,957 +0,0 @@
-<?xml version="1.0" encoding="UTF-8" standalone="no"?>
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd";><html
xmlns="http://www.w3.org/1999/xhtml";><head><meta http-equiv="Content-Type"
content="text/html; charset=UTF-8" /><title>Core API</title><link
rel="stylesheet" type="text/css" href="css/style.css" /><meta name="generator"
content="DocBook XSL Stylesheets V1.76.1" /><link rel="home" href="index.html"
title="" /><link rel="up" href="core.html" title="Core" /><link rel="prev"
href="core.html" title="Core" /><link rel="next"
href="core-bootstrap-assembly.html" title="Core Bootstrap" />
-
-
-<!-- favicon -->
-
-<link rel="shortcut icon" href="http://qi4j.org/favicon.ico";
type="image/vnd.microsoft.icon" />
-<link rel="icon" href="http://qi4j.org/favicon.ico"; type="image/x-icon" />
-
-<!-- style -->
-
-<link href="css/shCore.css" rel="stylesheet" type="text/css" />
-<link href="css/shCoreEclipse.css" rel="stylesheet" type="text/css" />
-<link href="css/shThemeEclipse.css" rel="stylesheet" type="text/css" />
-<link href="css/qi4j.css" rel="stylesheet" type="text/css" />
-
-<!-- Syntax Highlighter -->
-
-<script type="text/javascript" src="js/shCore.js"></script>
-<script type="text/javascript" src="js/shBrushJava.js"></script>
-<script type="text/javascript" src="js/shBrushScala.js"></script>
-<script type="text/javascript" src="js/shBrushJScript.js"></script>
-<script type="text/javascript" src="js/shBrushBash.js"></script>
-<script type="text/javascript" src="js/shBrushPlain.js"></script>
-<script type="text/javascript" src="js/shBrushXml.js"></script>
-<script type="text/javascript" src="js/shBrushGroovy.js"></script>
-<script type="text/javascript" src="js/shBrushPython.js"></script>
-<script type="text/javascript" src="js/shBrushRuby.js"></script>
-<script type="text/javascript" src="js/shBrushCSharp.js"></script>
-
-<script type="text/javascript">
- SyntaxHighlighter.defaults['tab-size'] = 4;
- SyntaxHighlighter.defaults['gutter'] = false;
- SyntaxHighlighter.defaults['toolbar'] = false;
- SyntaxHighlighter.all()
-</script>
-
-<!-- JQuery -->
-
-<script type="text/javascript" src="js/jquery-1.6.4.min.js"></script>
-
-<!-- Image Scaler -->
-
-<script type="text/javascript" src="js/imagescaler.js"></script>
-
-<!-- Table Styler -->
-
-<script type="text/javascript" src="js/tablestyler.js"></script>
-
-<!-- Qi4j WebSite Progressive Enhancement -->
-
-<link href="css/progressive-enhancement.css" rel="stylesheet" type="text/css"
/>
-<script type="text/javascript" src="js/jquery.scrollTo-1.4.2.js"></script>
-<script type="text/javascript" src="js/progressive-enhancement.js"></script>
-
-<!-- Analytics -->
- <script type="text/javascript">
- var _gaq = _gaq || [];
- _gaq.push(['_setAccount', 'UA-89723617-1']);
- _gaq.push(['_trackPageview']);
-
- (function() {
- var ga = document.createElement('script'); ga.type = 'text/javascript';
ga.async = true;
- ga.src = ('https:' == document.location.protocol ? 'https://ssl' :
'http://www') + '.google-analytics.com/ga.js';
- var s = document.getElementsByTagName('script')[0];
s.parentNode.insertBefore(ga, s);
- })();
- </script>
-
- </head><body><div xmlns="" xmlns:exsl="http://exslt.org/common";
class="logo"><a href="index.html"><img src="images/logo-standard.png"
/></a></div><div xmlns="" xmlns:exsl="http://exslt.org/common";
class="top-nav"><div xmlns="http://www.w3.org/1999/xhtml";
class="toc"><dl><dt><span class="section"><a
href="index.html#home">Zestâ¢</a></span></dt><dt><span class="section"><a
href="intro.html">Introduction</a></span></dt><dt><span class="section"><a
href="tutorials.html">Tutorials</a></span></dt><dt><span class="section"><a
href="javadocs.html">Javadoc</a></span></dt><dt><span class="section"><a
href="samples.html">Samples</a></span></dt><dt><span class="section"><span
xmlns="" href="core.html">Core</span></span></dt><dt><span class="section"><a
href="libraries.html">Libraries</a></span></dt><dt><span class="section"><a
href="extensions.html">Extensions</a></span></dt><dt><span class="section"><a
href="tools.html">Tools</a></span></dt><dt><span class="section"><a
href="glossary.html">
Glossary </a></span></dt></dl></div></div><div xmlns=""
xmlns:exsl="http://exslt.org/common"; class="sub-nav"><div
xmlns="http://www.w3.org/1999/xhtml"; class="toc"><dl><dt><span
class="section"><a
href="core.html#_overview_3">Overview</a></span></dt><dt><span
class="section"><span xmlns="" href="core-api.html">Core
API</span></span></dt><dt><span class="section"><a
href="core-bootstrap-assembly.html">Core Bootstrap</a></span></dt><dt><span
class="section"><a href="core-testsupport.html">Core Test
Support</a></span></dt><dt><span class="section"><a
href="core-functional.html">Core Functional API</a></span></dt><dt><span
class="section"><a href="core-io.html">Core I/O API</a></span></dt><dt><span
class="section"><a href="core-spi.html">Core Extension
SPI</a></span></dt><dt><span class="section"><a href="core-runtime.html">Core
Runtime</a></span></dt></dl></div></div><div class="section" title="Core
API"><div class="titlepage"><div><div><h3 class="title"><a
id="core-api"></a>Core API</
h3></div></div></div><p class="remark"><em><span
class="comment"></span></em></p><p class="devstatus-code-stable">code</p><p
class="devstatus-docs-good">docs</p><p
class="devstatus-tests-good">tests</p><p>The Zest⢠Core API is the primary
interface for client application code during the main execution phase, i.e.
after the
-application has been activated.</p><div class="table"><a
id="idm371059221680"></a><p class="title"><strong>Table 15.Â
Artifact</strong></p><div class="table-contents"><table summary="Artifact"
border="1"><colgroup><col class="col_1" /><col class="col_2" /><col
class="col_3" /></colgroup><thead><tr><th align="left" valign="top">Group
ID</th><th align="left" valign="top">Artifact ID</th><th align="left"
valign="top">Version</th></tr></thead><tbody><tr><td align="left"
valign="top"><p>org.qi4j.core</p></td><td align="left"
valign="top"><p>org.qi4j.core.api</p></td><td align="left"
valign="top"><p>2.1</p></td></tr></tbody></table></div></div><br
class="table-break" /><div class="section" title="Composition"><div
class="titlepage"><div><div><h4 class="title"><a
id="core-api-composition"></a>Composition</h4></div></div></div><p>Composition
is at the heart of COP, and refers to two different levels of
constructs;</p><div class="orderedlist"><ol class="orderedlist" type="1"><li
class="list
item">
-the ability to assemble (compose) objects from smaller pieces, called
Fragments.
-</li><li class="listitem">
-the construction of applications by assembling Composites into Modules and
Modules into Layers.
-</li></ol></div><p>In Zest, we use the term Assembly for the second case of
composition. See separate chapter.</p><p>Composition will allow library authors
a new level of flexibility in how functionality is provided to client code. More
-on that later.</p><div class="section" title="Fragments"><div
class="titlepage"><div><div><h5 class="title"><a
id="_fragments"></a>Fragments</h5></div></div></div><p>There are 4 types of
Fragments in Zest;</p><div class="itemizedlist"><ul class="itemizedlist"><li
class="listitem">
-<a class="xref" href="core-api.html#core-api-mixin" title="Mixin">Mixin</a> -
The state carrying part of a Composite.
-</li><li class="listitem">
-<a class="xref" href="core-api.html#core-api-constraint"
title="Constraint">Constraint</a> - Rules for in and out arguments, typically
used for validation.
-</li><li class="listitem">
-<a class="xref" href="core-api.html#core-api-concern"
title="Concern">Concern</a> - Interceptor of method calls. General purpose use,
often for cross-cutting behaviors.
-</li><li class="listitem">
-<a class="xref" href="core-api.html#core-api-sideeffect"
title="SideEffect">SideEffect</a> - Executed after the method call has been
completed, and unable to influence the
- outcome of the method call.
-</li></ul></div></div><div class="section" title="Composites"><div
class="titlepage"><div><div><h5 class="title"><a
id="_composites"></a>Composites</h5></div></div></div><p>There are 4 Composite
meta types. Each of these have very different characteristics and it is
important to understand
-these, so the right meta type is used for the right purpose.</p><div
class="itemizedlist"><ul class="itemizedlist"><li class="listitem">
-Entity - Classic meaning. Has an Identity. Is persistable and can be
referenced by the Identity. Can act as
- Aggregate. Entity supports Lifecycle interface. Equals is defined by the
Identity.
-</li><li class="listitem">
-Value - Values are persistable when used in a Property from an Entity. Values
are immutable, and equals is
- defined by the values of its fields.
-</li><li class="listitem">
-Service - Service is injectable to other composites and java objects. They are
not persistable, but if
- referenced from an Entity or Value, a new reference to the Service will
be injected when the Entity/Value is
- deserialized. Services are singletons. There are <span
class="emphasis"><em>hosted</em></span> and <span
class="emphasis"><em>imported</em></span> Services. The <span
class="emphasis"><em>hosted</em></span> Service has
- Configuration and its life cycle controlled by the Zest⢠runtime,
whereas the <span class="emphasis"><em>imported</em></span> Services are
external
- references.
-</li><li class="listitem">
-Transient - Short-lived composites that are not persistable.
Equals/hashCode/toString are forwarded to the
- Mixin Type declaring those methods explicitly.
-</li></ul></div><p>In versions of Zest⢠prior to 2.0 (then Qi4j), composite
types had to extend one of these 4 meta types, but in 2.0 and later, the
-meta type interface is added dynamically during <a class="xref"
href="core-bootstrap-assembly.html" title="Core Bootstrap">Assembly</a>.
-We can therefor get rid of a lot of additional types, and use Zest-free
interfaces directly;</p><pre class="programlisting brush: java">@Mixins( {
BalanceCheckMixin.class } )
-public interface BankAccount
-{
- Money checkBalance();
- [...snip...]
-
-}
-</pre><p>and declare it with;</p><pre class="programlisting brush:
java">public void assemble( ModuleAssembly module )
-{
- module.entities( BankAccount.class );
-}
-</pre></div></div><div class="section" title="Structure"><div
class="titlepage"><div><div><h4 class="title"><a
id="core-api-structure"></a>Structure</h4></div></div></div><p>Zest⢠promotes
a conventional view of application structure, that computer science has been
using for decades.</p><p>The definition is as follows;</p><div
class="itemizedlist"><ul class="itemizedlist"><li class="listitem">
-One Application per Zest⢠runtime instance.
-</li><li class="listitem">
-One or more Layers per Application.
-</li><li class="listitem">
-Zero, one or more Modules per Layer.
-</li><li class="listitem">
-Zero, one or more Assemblies per Module.
-</li></ul></div><p>The principle of this Structure is to assist the programmer
to create well modularized applications, that are easily
-extended and maintained. Zest⢠will restrict access between Modules, so that
code can only reach Composites and Objects
-in Modules (including itself) of the same or lower Layers.</p><p>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.</p></div><div class="section"
title="Application"><div class="titlepage"><div><div><h4 class="title"><a
id="core-api-application"></a>Application</h4></div></div></div><p>Every
Zest⢠runtime has <span class="emphasis"><em>one and only one</em></span>
Application in it. It is possible to run multiple Zest⢠runtimes in the same
-JVM, and it is even possible to embed a Zest⢠runtime within a Zestâ¢
Application, but there can only be one Application
-in a Zest⢠runtime.</p><p>An Application is then broken into layers and
modules are placed within those layers. Composites are placed within
-modules. This forms the Application Structure and is enforced by the Zestâ¢
runtime.</p></div><div class="section" title="Layer"><div
class="titlepage"><div><div><h4 class="title"><a
id="core-api-layer"></a>Layer</h4></div></div></div><p>A Zest⢠Application
must consist of at least one layer. More layers are common, often dividing the
application along the
-common architectural diagrams used on whiteboards, perhaps with a UI layer at
the top, followed by a service or application
-layer, then with a domain layer and finally some persistence layer at the
bottom.</p><p>Zest⢠enforces this layering by requiring the <a class="xref"
href="core-bootstrap-assembly.html" title="Core Bootstrap">Assembly</a> to
declare which layer uses which other layer. And
-<a class="xref" href="core-api.html#core-api-visibility"
title="Visibility">Visibility</a> rules define that layers below can not locate
composites in layers above. Also, defining that
-"Layer1 uses Layer2" and "Layer2 uses Layer3" does NOT imply that Layer1 has
<a class="xref" href="core-api.html#core-api-visibility"
title="Visibility">Visibility</a> to Layer3. If that
-is wanted, then it must be declared explicitly.</p></div><div class="section"
title="Module"><div class="titlepage"><div><div><h4 class="title"><a
id="core-api-module"></a>Module</h4></div></div></div><p>Modules are logical
compartments to assist developers in creating and maintaining well modularized
code. A Module only
-belongs to a single Layer, but many Modules can exist in the same Layer.
Composite access is limited to;</p><div class="itemizedlist"><ul
class="itemizedlist"><li class="listitem">
-Composites within the same Module, with Visibility set to Visibility.module
(default).
-</li><li class="listitem">
-Composites from Modules in the same Layer, with Visibility set to
Visibility.layer
-</li><li class="listitem">
-Composites from Modules in Layers below, with Visibility set to
Visibility.application
-</li></ul></div><p>Modules contains a lot of the Zest⢠infrastructure, which
are the enforcers of these wise modularization principles.</p><p>It is not
possible to modify the Modules, their resolution nor binding in any way after
the application starts.</p></div><div class="section" title="Visibility"><div
class="titlepage"><div><div><h4 class="title"><a
id="core-api-visibility"></a>Visibility</h4></div></div></div></div><div
class="section" title="ValueComposite"><div class="titlepage"><div><div><h4
class="title"><a
id="core-api-value"></a>ValueComposite</h4></div></div></div><p>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.</p><p>Zest⢠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 EntityComposite, and
its value can still be persisted as part
-of an EntityComposite via a Property.</p><p>The characteristics of a
ValueComposite compared to other Composite meta types are;</p><div
class="itemizedlist"><ul class="itemizedlist"><li class="listitem">
-It is Immutable.
-</li><li class="listitem">
-Its equals/hashCode works on both the descriptor and the values of the
ValueComposite.
-</li><li class="listitem">
-Can be used as Property types.
-</li><li class="listitem">
-Can be serialized and deserialized.
-</li></ul></div><div class="section" title="Value Serialization"><div
class="titlepage"><div><div><h5 class="title"><a
id="_value_serialization"></a>Value
Serialization</h5></div></div></div><p>Value objects can be serialized and
deserialized using the ValueSerialization API which is a Service API implemented
-by SPI and extensions.</p><div class="tip" title="Tip" style="margin-left:
0.5in; margin-right: 0.5in;"><h3 class="title">Tip</h3><p><code
class="literal">ValueSerialization extends ValueSerializer,
ValueDeserializer</code>. See the <a class="xref" href="javadocs.html"
title="Javadoc"> JavaDocs</a> for interfaces detail.</p></div><p>The
ValueSerialization mechanism apply to the following object types :</p><div
class="itemizedlist"><ul class="itemizedlist"><li class="listitem">
-ValueComposite,
-</li><li class="listitem">
-EntityReference,
-</li><li class="listitem">
-Iterable,
-</li><li class="listitem">
-Map,
-</li><li class="listitem">
-Plain Value.
-</li></ul></div><p>Nested Plain Values, EntityReferences, Iterables, Maps,
ValueComposites are supported.
-EntityComposites and EntityReferences are serialized as their identity
string.</p><p>Plain Values can be one of :</p><div class="itemizedlist"><ul
class="itemizedlist"><li class="listitem">
-String,
-</li><li class="listitem">
-Character or char,
-</li><li class="listitem">
-Boolean or boolean,
-</li><li class="listitem">
-Integer or int,
-</li><li class="listitem">
-Long or long,
-</li><li class="listitem">
-Short or short,
-</li><li class="listitem">
-Byte or byte,
-</li><li class="listitem">
-Float or float,
-</li><li class="listitem">
-Double or double,
-</li><li class="listitem">
-BigInteger,
-</li><li class="listitem">
-BigDecimal,
-</li><li class="listitem">
-Date,
-</li><li class="listitem">
-DateTime (JodaTime),
-</li><li class="listitem">
-LocalDateTime (JodaTime),
-</li><li class="listitem">
-LocalDate (JodaTime).
-</li></ul></div><div class="tip" title="Tip" style="margin-left: 0.5in;
margin-right: 0.5in;"><h3 class="title">Tip</h3><p>Serialization behaviour can
be tuned with options.
-Every <code class="literal">ValueSerializer</code> methods can take a <code
class="literal">ValueSerializer.Options</code> object that contains flags to
change how some
-values are serialized. See the <a class="xref" href="javadocs.html"
title="Javadoc"> JavaDocs</a> for more details.</p></div><p>Values of unknown
types and all arrays are considered as <code
class="literal">java.io.Serializable</code> and by so are (de)serialized to
(from)
-base64 encoded bytes using pure Java serialization. If it happens that the
value is not Serializable or the input to
-deserialize is invalid, a <code
class="literal">ValueSerializationException</code> is thrown.</p><p>Methods of
<code class="literal">ValueSerializer</code> allow to specify if the serialized
state should contain extra type information about the
-serialized value. Having type information in the serialized payload allows to
keep actual ValueComposite types and by so
-circumvent <code class="literal">AmbiguousTypeException</code> when
deserializing.</p><p>Core Runtime provides a default ValueSerialization system
based on the
-<a class="ulink" href="https://github.com/douglascrockford/JSON-java";
target="_top">org.json</a> Java library producing and consuming
JSON.</p><p>Letâs see how it works in practice.</p><pre class="programlisting
brush: java">public interface SomeValue // (1)
-{
-
- Property<String> foo();
-}
-
-@Override
-public void assemble( ModuleAssembly module )
- throws AssemblyException
-{
- module.values( SomeValue.class ); // (2)
- [...snip...]
-
-}
- [...snip...]
-
-public void defaultValueSerialization()
-{
- SomeValue someValue = someNewValueInstance( module ); // (3)
- String json = someValue.toString(); // (4)
- SomeValue someNewValue = module.newValueFromSerializedState(
SomeValue.class, json ); // (5)
- [...snip...]
-
-}
-</pre><p>Reading this first example step by step we ;</p><div
class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem">
-declare a ValueComposite,
-</li><li class="listitem">
-assemble it,
-</li><li class="listitem">
-create a new Value instance,
-</li><li class="listitem">
-use the <code class="literal">ValueComposite#toString()</code> method to get a
JSON representation of the Value,
-</li><li class="listitem">
-and finally, use the <code
class="literal">Module#newValueFromSerializedState()</code> method to create a
new Value instance from the JSON
- state.
-</li></ol></div><p><code class="literal">ValueComposite#toString()</code>
method leverage Value Serialization and by so provide JSON based
representation. The Module
-API allows to create new Value instances from serialized state.</p><p>On top
of that, Application assemblies can register different implementation of
ValueSerialization as Services to
-support more formats, see the <a class="xref" href="extensions.html"
title="Extensions">Extensions</a> section. Note that the default behaviour
described above is overriden if a
-ValueSerialization Service is visible.</p><p>Letâs see how to use the
ValueSerialization Services.</p><pre class="programlisting brush: java">public
interface SomeValue // (1)
-{
-
- Property<String> foo();
-}
-
-@Override
-public void assemble( ModuleAssembly module )
- throws AssemblyException
-{
- module.values( SomeValue.class ); // (2)
- new OrgJsonValueSerializationAssembler().assemble( module ); // (3)
-}
- [...snip...]
-
-@Service
-private ValueSerializer valueSerializer; // (4)
-@Service
-private ValueDeserializer valueDeserializer; // (4)
-
- [...snip...]
-
-public void assembledDefaultServiceSerialization()
-{
- SomeValue someValue = someNewValueInstance( module ); // (5)
- String json = valueSerializer.serialize( someValue ); // (6)
- SomeValue someNewValue = valueDeserializer.deserialize( SomeValue.class,
json ); // (7)
- [...snip...]
-
-}
-</pre><p>In this second example, we ;</p><div class="orderedlist"><ol
class="orderedlist" type="1"><li class="listitem">
-declare a ValueComposite,
-</li><li class="listitem">
-assemble it,
-</li><li class="listitem">
-assemble a ValueSerialization Service backed by the <code
class="literal">org.json</code> package,
-</li><li class="listitem">
-get the <code class="literal">ValueSerializer</code> and <code
class="literal">ValueDeserializer</code> Services injected,
-</li><li class="listitem">
-create a new Value instance,
-</li><li class="listitem">
-use the <code class="literal">ValueSerializer#serialize()</code> method to get
a JSON representation of the Value,
-</li><li class="listitem">
-and finally, use the <code
class="literal">ValueDeserializer#eserialize()</code> method to create a new
Value instance from the JSON state.
-</li></ol></div><p>Many applications need to stream data. The
ValueSerialization API support such use cases in two ways.</p><p>The first one
use classic streams.</p><pre class="programlisting brush: java">public void
assembledServiceStreamingSerialization()
-{
- [...snip...]
-
- // (1)
- Iterable<AcmeValue> data = dataSource; // Eg. Entities converted to
Values
- OutputStream output = targetStream; // Eg. streaming JSON over HTTP
-
- // (2)
- valueSerializer.serialize( data, output );
- [...snip...]
-
- // (3)
- InputStream input = sourceStream; // Eg. reading incoming JSON
-
- // (4)
- List<AcmeValue> values = valueDeserializer.deserialize(
CollectionType.listOf( AcmeValue.class ), input );
- [...snip...]
-
-}
-</pre><div class="orderedlist"><ol class="orderedlist" type="1"><li
class="listitem">
-get a handle on a source of values and an <code
class="literal">OutputStream</code>,
-</li><li class="listitem">
-serialize data into the <code class="literal">OutputStream</code>,
-</li><li class="listitem">
-get a handle on an <code class="literal">InputStream</code>,
-</li><li class="listitem">
-deserialize data from the <code class="literal">InputStream</code>.
-</li></ol></div><p>The second one use the <a class="xref" href="core-io.html"
title="Core I/O API">I/O API</a>:</p><pre class="programlisting brush:
java">public void assembledServiceIOSerialization()
- throws IOException
-{
- [...snip...]
-
- // (1)
- Iterable<AcmeValue> queryResult = dataSource; // Eg. Entities
converted to Values
- Writer writer = outputWriter; // Eg. to pipe data to another process or to
a file
-
- // (2)
- Function<AcmeValue, String> serialize = valueSerializer.serialize();
-
- // (3)
- Inputs.iterable( queryResult ).transferTo( Transforms.map( serialize,
Outputs.text( writer ) ) );
- [...snip...]
-
- // (4)
- Reader reader = inputReader;
- List<AcmeValue> values = new ArrayList<AcmeValue>();
-
- // (5)
- Function<String, AcmeValue> deserialize =
valueDeserializer.deserialize( AcmeValue.class );
-
- // Deserialization of a collection of AcmeValue from a String.
- // One serialized AcmeValue per line.
- // (6)
- Inputs.text( reader ).transferTo( Transforms.map( deserialize,
Outputs.collection( values ) ) );
- [...snip...]
-
-}
-</pre><div class="orderedlist"><ol class="orderedlist" type="1"><li
class="listitem">
-get a handle on a source of values and a <code class="literal">Writer</code>,
-</li><li class="listitem">
-prepare the serialization <code class="literal">Function</code>,
-</li><li class="listitem">
-serialize a collection of values, one serialized value per line,
-</li><li class="listitem">
-get a handle on a serialized values <code class="literal">Reader</code> and
create a new empty <code class="literal">List</code> of values,
-</li><li class="listitem">
-prepare the deserialization <code class="literal">Function</code>,
-</li><li class="listitem">
-deserialize a collection of values from read lines.
-</li></ol></div></div></div><div class="section" title="Service
Composite"><div class="titlepage"><div><div><h4 class="title"><a
id="core-api-service"></a>Service Composite</h4></div></div></div><p>Any
service added, via the ModuleAssembly.addServices(), ModuleAssembly.services()
and ModuleAssembly.importServices()
-methods, will have the ServiceComposite meta type added to it. In Zest, when
we speak of <span class="emphasis"><em>Services</em></span> we mean instances
-of <span class="emphasis"><em>ServiceComposite</em></span>.</p><p>Most
programmers are familiar with the term "Service", and after the failure of
Object Oriented Programmingâs promise
-to encapsulate all the behavior together with the objectâs state,
programmers learned that the only way to deal with
-decoupling and re-use was to make the objects into data containers and deploy
services that acted upon those data
-containers. Very much what functions did on structs back in the C and Pascal
days.</p><p>Zest⢠will bring a lot of the behavior back to the Composite
itself, but we still need Services for cross-composite
-functionality. The Zest⢠Service model is fairly simple, yet powerful and
flexible enough to accommodate most
-service-oriented patterns and ability to integrate well with external systems
whether they are in-JVM or remote,
-such as Spring, OSGi, WS-*, Rest and others.</p><p>The characteristics of a
ServiceComposite compared to other Composite meta types are;</p><div
class="itemizedlist"><ul class="itemizedlist"><li class="listitem">
-It is one singleton per declaration in bootstrap.
-</li><li class="listitem">
-It has an identity defined in bootstrap.
-</li><li class="listitem">
-It has an Activation life cycle into which Activators hook.
-</li><li class="listitem">
-It has an optional Configuration.
-</li></ul></div><p><span class="emphasis"><em>Services</em></span> in Zestâ¢
are <span class="emphasis"><em>singletons</em></span>, one instance per
definition. That means that there may exist multiple instances
-of the same service type, but they can not be created on the fly in runtime,
but has to be explicitly defined during
-<a class="xref" href="core-bootstrap-assembly.html" title="Core
Bootstrap">Assembly</a>.</p><p>By default, <span
class="emphasis"><em>Services</em></span> are not instantiated until they are
used. This means that the <span
class="emphasis"><em>ServiceComposite</em></span> instance itself
-will not exist until someone calls a method. If a <span
class="emphasis"><em>Service</em></span> needs to be instantiated when the
<span class="emphasis"><em>Module</em></span> is activated, one
-need to declare/call the instantiateOnStartup() method on the <span
class="emphasis"><em>ServiceDescriptor</em></span> during the
bootstrap.</p><div class="section" title="Service Configuration"><div
class="titlepage"><div><div><h5 class="title"><a
id="_service_configuration"></a>Service
Configuration</h5></div></div></div><p>The configuration for a service is well
supported in Zest. See the <a class="xref"
href="core-api.html#core-api-service-configuration" title="Service
Configuration">Service Configuration</a> chapter for details.</p></div><div
class="section" title="Service Activation"><div class="titlepage"><div><div><h5
class="title"><a id="_service_activation"></a>Service
Activation</h5></div></div></div><p>Services are activated (injected and
instantiated) either on application start-up, or upon first use. This is
controlled
-by calling instantiateOnStartup(), this way;</p><pre class="programlisting
brush: java">@Override
-public void assemble( ModuleAssembly module )
- throws AssemblyException
-{
- ServiceDeclaration service = module.addServices( MyDemoService.class );
- service.instantiateOnStartup();
-</pre><p>If this method is not called during assembly, the activation will
occur on first service usage.</p><p>Passivation occurs when a <a class="xref"
href="core-api.html#core-api-module" title="Module">Module</a> is deactivated,
typically because the whole application is shutting down.
-Passivation occurs in the reverse order of the activation, to ensure that
dependent services are still available for a
-passivating service.</p><p>Activators can be assembled with Services to manage
their activation.
-The easiest way is to implement the ServiceActivation interface directly in
the ServiceComposite;</p><pre class="programlisting brush: java">@Mixins(
MyActivationMixin.class )
-public static interface MyActivationDemoService
- extends ServiceComposite, ServiceActivation
-{
-}
-
-public static class MyActivationMixin
- implements ServiceActivation
-{
- @Override
- public void activateService()
- throws Exception
- {
- // Activation code
- }
-
- @Override
- public void passivateService()
- throws Exception
- {
- // Passivation code
- }
-}
-</pre><p>The activation code can also be moved outside the composite by using
the ServiceActivatorAdapter;</p><pre class="programlisting brush:
java">@Activators( MyActivator.class )
-public static interface MyOtherActivationDemoService
- extends ServiceComposite
-{
-}
-
-public static class MyActivator
- extends ServiceActivatorAdapter<MyOtherActivationDemoService>
-{
- @Override
- public void afterActivation(
ServiceReference<MyOtherActivationDemoService> activated )
- throws Exception
- {
- // Activation code
- }
-
- @Override
- public void beforePassivation(
ServiceReference<MyOtherActivationDemoService> passivating )
- throws Exception
- {
- // Passivation code
- }
-}
-</pre><p>Activators can be registered on Service assembly too, this
way;</p><pre class="programlisting brush: java">@Override
-public void assemble( ModuleAssembly module )
-{
- module.services( MyDemoService.class ).withActivators( MyActivator.class );
-}
-</pre><p>Activators assembled with the service will get their <code
class="literal">beforeActivation</code> and <code
class="literal">afterActivation</code> methods called around the
-ServiceComposite activation and their <code
class="literal">beforePassivation</code> and <code
class="literal">afterPassivation</code> around the ServiceComposite
-passivation.
-Member injection and constructor initialization occur during the activation.
The ServiceComposite can be used from the
-<code class="literal">afterActivation</code> to the <code
class="literal">beforePassivation</code> method.</p></div><div class="section"
title="Identity and Tags"><div class="titlepage"><div><div><h5 class="title"><a
id="_identity_and_tags"></a>Identity and Tags</h5></div></div></div><p>Services
has an Identity, which drives the <a class="xref"
href="core-api.html#core-api-service-configuration" title="Service
Configuration">Service Configuration</a> system and can be used to lookup a
particular service
-instance. Services can also be arbitrarily tagged, via the ServiceDescriptor.
Example;</p><pre class="programlisting brush: java">@Override
-public void assemble( ModuleAssembly module )
- throws AssemblyException
-{
- ServiceDeclaration service = module.addServices( MyDemoService.class );
- [...snip...]
-
- service.taggedWith( "Important", "Drain" );
-</pre><p>Tags are useful inside the application code to locate a particular
service instance, in case we have many. For instance;</p><pre
class="programlisting brush: java">@Service
-private List<ServiceReference<MyDemoService>> services;
-
-public MyDemoService locateImportantService()
-{
- for( ServiceReference<MyDemoService> ref : services )
- {
- ServiceTags serviceTags = ref.metaInfo( ServiceTags.class );
- if( serviceTags.hasTag( "Important" ) )
- {
- return ref.get();
- }
- }
- return null;
-}
-</pre></div></div><div class="section" title="Service Configuration"><div
class="titlepage"><div><div><h4 class="title"><a
id="core-api-service-configuration"></a>Service
Configuration</h4></div></div></div><p>Configuration in Zest⢠is for Zestâ¢
<a class="xref" href="core-api.html#core-api-service" title="Service
Composite">ServiceComposite</a> only. The Configuration is stored in a visible
Entity
-Store and is therefor runtime modifiable and not static in properties or XML
files as in most other dependency
-injection frameworks.</p><p>The Configuration system itself will handle all
the details with interfacing with reading and writing the configuration.
-The normal UnitOfWork management is used, but handled internally by the
configuration system.</p><p>In Zest, Configuration are strongly typed and
refactoring-friendly. Configuration is read from the entity store, but if
-it can not be found, then it will try to bootstrap it from a properties file,
with the same name as the
-ServiceDescriptor.identifiedBy(), which is set during <a class="xref"
href="core-bootstrap-assembly.html" title="Core Bootstrap">Assembly</a> and
defaults to the fully qualified
-classname of the <a class="xref" href="core-api.html#core-api-service"
title="Service Composite">ServiceComposite</a> type.</p><div class="section"
title="Defining a Configuration Type"><div class="titlepage"><div><div><h5
class="title"><a id="_defining_a_configuration_type"></a>Defining a
Configuration Type</h5></div></div></div><p>The Configuration type is simply
listing the properties that are available. The standard rules on @UseDefaults
and
-@Optional applies.
-Example;</p><pre class="programlisting brush: java">public interface
MailServiceConfiguration extends ConfigurationComposite
-{
- Property<String> hostName();
-
- Property<Integer> port();
-}
-</pre></div><div class="section" title="Using a Configuration Type"><div
class="titlepage"><div><div><h5 class="title"><a
id="_using_a_configuration_type"></a>Using a Configuration
Type</h5></div></div></div><p>It is important to remember that Configuration is
not static values that are set prior to application start-up and
-therefor applications should not cache the values retrieved forever, but
consciously know when the configuration should
-be re-read.</p><p>Configuration is injected via the @This injection scope. One
reasonable strategy is to read the configuration on service
-activation, so by deactivating/reactivating a service, the user have a
well-defined behavior to know how configuration
-changes take effect. Example;</p><pre class="programlisting brush: java">@This
-private Configuration<MailServiceConfiguration> config;
-
-@Override
-public void sendMail( @Email String to, @MinLength( 8 ) String subject, String
body )
-{
- config.refresh();
- MailServiceConfiguration conf = config.get();
- String hostName = conf.hostName().get();
- int port = conf.port().get();
- [...snip...]
-
-}
-</pre></div><div class="section" title="Modifying Configuration"><div
class="titlepage"><div><div><h5 class="title"><a
id="_modifying_configuration"></a>Modifying
Configuration</h5></div></div></div><p>Configuration is modifiable, and after
the modifications have been made, the save() method on the Configuration type
-must be called. Example;</p><pre class="programlisting brush: java"> void
changeExternalMailService( String hostName, int port );
- [...snip...]
-
- @Override
- public void changeExternalMailService( String hostName, int port )
- {
- MailServiceConfiguration conf = config.get();
- conf.hostName().set( hostName );
- conf.port().set( port );
- config.save();
- }
- [...snip...]
-
- }
-}
-</pre></div></div><div class="section" title="EntityComposite"><div
class="titlepage"><div><div><h4 class="title"><a
id="core-api-entity"></a>EntityComposite</h4></div></div></div><p>Entities are
common in the object oriented programming world, but has never reached the
stardom of Class and Object.
-Instead we have seen many attempts at creating Entities on top of Java, such
as EJB (3 incompatible versions), Java
-Data Objects (JDO, 2 somewhat compatible versions), Java Persistence
Architecture (JPA, 2 somewhat compatible versions),
-Hibernate (4+ somewhat incompatible versions) and many other less known. This
seems to suggest that the topic of
-creating objects that survives over long periods of time is a difficult
one.</p><p>Eric Evans points out in his book that Entities is a very definite
and distinct concept that needs to be handled
-explicitly. Composite Oriented Programming in general, and Zest⢠in
particular, takes this point very seriously and
-makes Entities a central part of the whole system. And likewise, we are
convinced that it is not possible to develop
-domain-knowledge-rich applications without a conscious and well-defined
strategy on Entities. So, instead of spending
-endless hours trying to get Hibernate mapping to do the right thing, we
introduce a Composite meta type called
-EntityComposite, which all entities must derive from, and by doing so
automatically become persistable, searchable,
-have a lifecycle and support nested undoable modifications.</p><p>The
characteristics of an EntityComposite compared to other Composite meta types
are;</p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem">
-It has an Identity.
-</li><li class="listitem">
-It has a LifeCycle.
-</li><li class="listitem">
-It is typically persisted.
-</li><li class="listitem">
-It can only be referenced by an Association or ManyAssociation.
-</li><li class="listitem">
-Its CRUD operations are bound by a UnitOfWork.
-</li></ul></div></div><div class="section" title="Unit Of Work"><div
class="titlepage"><div><div><h4 class="title"><a
id="core-api-unitofwork"></a>Unit Of Work</h4></div></div></div><p>A UnitOfWork
is a bounded group of operations performed, typically on entities, where these
operations are not visible
-to other threads until the UnitOfWork is completed. It is also possible to
discard these operations, as if they were
-never executed.</p><div class="note" title="Note" style="margin-left: 0.5in;
margin-right: 0.5in;"><h3 class="title">Note</h3><p>UnitOfWork has many
similarities with the Transaction concept used with RDBMSes. But since Zestâ¢
introduced several deviations to the common definitions of Transactions, we
chose to use a different term.</p></div><p>There are several key
characteristics of UnitOfWork;</p><div class="itemizedlist"><ul
class="itemizedlist"><li class="listitem">
-They are limited to a single thread.
-</li><li class="listitem">
-They have an associated use-case.
-</li><li class="listitem">
-They can be paused and resumed.
-</li><li class="listitem">
-They have a notification mechanism (used to trigger Indexing for instance).
-</li><li class="listitem">
-They can be long-running, as they donât tie up underlying transactions or
other expensive resources.
-</li></ul></div><p>At the moment, they are exclusively used to manipulate <a
class="xref" href="core-api.html#core-api-entity"
title="EntityComposite">EntityComposite</a> composites. All entity operations
MUST be
-done via UnitOfWork, and in fact it is not possible to get this wrong.</p><div
class="section" title="UnitOfWork Propagation"><div
class="titlepage"><div><div><h5 class="title"><a
id="_unitofwork_propagation"></a>UnitOfWork
Propagation</h5></div></div></div><p>UnitOfWork is associated with a thread,
and can only be transferred to another thread by a relatively complex operation
-of pausing a UnitOfWork in one thread, then hand over the UnitOfWork to the
other thread and resume it there. Donât do it!</p><p>UnitOfWork is available
from the <span class="emphasis"><em><a class="xref"
href="core-api.html#core-api-module" title="Module">Module</a>, and from the
Module you request either a new UnitOfWork or asking
-for the _current</em></span> one. <span class="emphasis"><em>Current
UnitOfWork</em></span> means the UnitOfWork that was created earlier within the
same thread. So,
-typically most entity manipulation code only request the current UnitOfWork
and the management of creating, completing
-and aborting the UnitOfWork is handled by the transaction boundary, often in
the so called application layer (see
-<a class="xref" href="core-api.html#core-api-layer"
title="Layer">Layer</a>)</p><p>Since it is very common to have all, or nearly
all, methods in the <span class="emphasis"><em>transaction boundary</em></span>
to handle the creation and
-completion, possibly with retry, in the same class, module or even layer,
Zest⢠provides annotations to easily declare
-UnitOfWork concern: @UnitOfWorkPropagation, @UnitOfWorkDiscardOn and
@UnitOfWorkRetry</p></div></div><div class="section"
title="TransientComposite"><div class="titlepage"><div><div><h4
class="title"><a
id="core-api-transient"></a>TransientComposite</h4></div></div></div><p>TransientComposite
is a Composite meta type for all other cases. The main characteristics
are;</p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem">
-It can not be serialized nor persisted.
-</li><li class="listitem">
-hashcode/equals are not treated specially and will be delegated to fragment(s)
implementing those methods.
-</li><li class="listitem">
-It can not be used as a Property type.
-</li></ul></div></div><div class="section" title="Mixin"><div
class="titlepage"><div><div><h4 class="title"><a
id="core-api-mixin"></a>Mixin</h4></div></div></div><p>Mixins are the
state-carrying part of a Composite instance. The other Fragments can not retain
state between method
-invocations as they are shared across Composite instances.</p><div
class="section" title="Mixin Type"><div class="titlepage"><div><div><h5
class="title"><a id="_mixin_type"></a>Mixin Type</h5></div></div></div><p>The
Mixin Type is the interface that declares the Mixin methods. Each Mixin
implementation (the classes defined in
-the @Mixins annotation of a Composite declaration) implements one or more
methods from one or more Mixin Types.</p><p>Mixin Type can be very simple,
like;</p><pre class="programlisting brush: java">public interface BankAccount
-{
- Money checkBalance();
-}
-</pre><p>Or contain hundreds of methods, subclassed from dozens of super
interfaces.</p><p>The Mixin Types of a Composite are ;</p><div
class="itemizedlist"><ul class="itemizedlist"><li class="listitem">
-all the aggregated interfaces of the Composite Type, minus Composite meta-type
interfaces, and
-</li><li class="listitem">
-all private mixin referenced types.
-</li></ul></div><p>There is not a 1:1 correlation between Mixin Type and Mixin
implementation. One canât even know if there are more or
-less of one over the other. That is because a Mixin implementation can
implement less than one, one, or more than one
-Mixin Type.</p><p>It is also entirely possible that multiple implementation
methods exists for a Mixin Type method. The mixin method
-resolution algorithm will provide a deterministic behavior of which
implementation of a method is chosen. The algorithm
-is as follows;</p><p>For each declared method of all Mixin Types of a
Composite;</p><div class="itemizedlist"><ul class="itemizedlist"><li
class="listitem">
-Iterate all Mixin types declared from left to right in the declaration,
-</li><li class="listitem">
-Iterate all Mixin types of super-interfaces from left to right in the <span
class="emphasis"><em>extends</em></span> clause,
-</li><li class="listitem">
-Iterate all Mixin types within one interface before succeeding to the next
interface,
-</li><li class="listitem">
-Iterate all super-interface Mixin types before proceeding to the
super-interfaces of those,
-</li><li class="listitem">
-Iterate all Typed Mixin implementations of all super-interfaces, before
repeating the algorithm for Generic Mixin
- implementations,
-</li></ul></div><p>This means that one Mixin implementation can <span
class="emphasis"><em>override</em></span> a single method that a larger mixin
implementation implements
-together with many other methods. So, just because a mixin implements
MixinTypeA.method1() and has an implementation
-of MixinTypeA.method2(), doesnât mean that method2() is mapped to that
mixin. This is very important to remember. The
-Envisage tool is capable of visualizing how Mixin Type methods are mapped to
implementations.</p></div><div class="section" title="Public Mixins"><div
class="titlepage"><div><div><h5 class="title"><a id="_public_mixins"></a>Public
Mixins</h5></div></div></div><p>Mixins are the state holders of the composite
instance. Public Mixins are the mixins that are exposed to the outside
-world via the CompositeType interface.</p><p><span class="strong"><strong>Each
method in the CompositeType interface MUST be backed by a mixin
class.</strong></span></p><p>Mixins are declared as annotations on the
composite interface.</p><pre class="programlisting brush: java">@Mixins(
SomethingMixin.class )
-public interface Something
-{}
-</pre><pre class="programlisting brush: java">public class SomethingMixin
- implements Something
-{
- // State is allowed.
-
- public void doSomething()
- {
- // do stuff...
- }
-}
-</pre><p>In the above sample, the SomethingMixin will be made part of the
Something composite.</p><p>If we have many interfaces defining many methods,
that all must be backed by a mixin implementation, we simply list all
-the mixins required.</p><pre class="programlisting brush: java">@Mixins( {
StartMixin.class, VehicleMixin.class } )
-public interface Car extends Startable, Vehicle
-{}
-</pre><pre class="programlisting brush: java">public interface Startable
-{
- boolean start();
- void stop();
-}
-
-</pre><pre class="programlisting brush: java">public interface Vehicle
-{
- void turn(float angle);
-
- void accelerate(float acceleration);
-
- // more methods
-}
-
-</pre><p>In the example above, the VehicleMixin would need to deal with all
methods defined in the Vehicle interface. That
-interface could be very large, and could be totally independent concerns. So,
instead we should use abstract mixins,
-which are ordinary mixins but are lacking some methods. This is simply done by
declaring the class abstract.</p><pre class="programlisting brush:
java">@Mixins( { StartMixin.class, SpeedMixin.class, CrashResultMixin.class } )
-public interface Car extends Startable, Vehicle
-{}
-
-</pre><pre class="programlisting brush: java">public interface Vehicle extends
SpeedLocation, Crashable
-{
-}
-
-</pre><pre class="programlisting brush: java">public interface SpeedLocation
-{
- void turn(float angle);
-
- void accelerate(float acceleration);
-}
-</pre><pre class="programlisting brush: java">public abstract class SpeedMixin
- implements SpeedLocation
-{
- // state for speed
-
- public void accelerate( float acceleration )
- {
- // logic
- }
-}
-
-</pre><p>Above the SpeedMixin only implements the accelerate() method, and
Zest⢠will only map that method to this mixin. The
-other method of the SpeedLocation interface is not satisfied as the example is
written and will generate a runtime
-exception.</p></div><div class="section" title="Private Mixins"><div
class="titlepage"><div><div><h5 class="title"><a
id="_private_mixins"></a>Private Mixins</h5></div></div></div><p>Public mixins
expose their methods in the composite interface, and this is not always
desirable. Zest⢠supports
-<span class="emphasis"><em>Private Mixins</em></span>, which are only visible
within the composite itself. That means that other fragments in the composite
-can see/use it, but it is not visible to the clients of the
composite.</p><p>Private Mixins are handled automatically. When Zest⢠detects
a <code class="literal">@This</code> annotation referring to a type that is not
defined
-in the Composite interface, then that is a Private Mixin. The Mixin
implementation class, however, must exist in the
-list of Mixins in the @Mixins annotation. But often, the Private Mixin only
list internal Property methods in the Mixin
-Type, which will be satisfied by the standard PropertyMixin and hence always
available.</p><p>This is particularly useful in Domain Driven Design, where you
only want to expose domain methods, which are defined by
-the context where they are used. But the state of the Mixin should not be
exposed out at all. For instance, if we have
-the Cargo interface like;</p><pre class="programlisting brush: java">@Mixins(
CargoMixin.class )
-public interface Cargo extends EntityComposite
-{
- String origin();
-
- String destination();
-
- void changeDestination( String newDestination );
-
-}
-
-</pre><p>The interface is defined by its context, and not really exposing the
internal state. So in the implementation we
-probably do something like;</p><pre class="programlisting brush: java">public
abstract class CargoMixin
- implements Cargo
-{
- @This
- private CargoState state;
-
- public String origin()
- {
- return state.origin().get();
- }
-
- public String destination()
- {
- return state.destination().get();
- }
-
- public void changeDestination( String newDestination )
- {
- state.destination().set( newDestination );
- }
-}
-
-</pre><pre class="programlisting brush: java">public interface CargoState
-{
- Property<String> origin();
- Property<String> destination();
-}
-
-</pre><p>So, in this typical case, we donât need to declare the Mixin for
the CargoState, as it only defines Property methods,
-which are handled by the standard PropertyMixin always present.</p></div><div
class="section" title="Typed Mixin vs Generic Mixin implementations"><div
class="titlepage"><div><div><h5 class="title"><a
id="_typed_mixin_vs_generic_mixin_implementations"></a>Typed Mixin vs Generic
Mixin implementations</h5></div></div></div><p>Mixins, Concerns and SideEffects
can either be "typed" or "generic". A Typed Mixin implementation implements one
or
-more Mixin Type interfaces, and one or more of the methods of those
interfaces. A Generic Mixin implementation
-implements java.lang.reflect.InvocationHandler, and can therefor be matched to
any method of any interface.
-Typically, AppliesTo annotation is used to filter the methods that such
Generic Mixin implementation is mapped against,
-and sometimes Generic Mixin implementations are "last
resort".</p><p>Experience shows that Generic Mixin implementations are rare,
and should only be used in extreme cases. They are
-less frequent than Generic Concern or Generic SideEffect implementations, but
inside the Zest⢠API are a couple of
-Generic Mixin implementations that are always present to make the life of the
developer easier, such as PropertyMixin,
-AssociationMixin, ManyAssociationMixin, NoopMixin. The first 3 are declared on
the Composite and EntityComposite
-interfaces and automatically included if needed. They also serve as excellent
example of what they can be used for.</p><pre class="programlisting brush:
java">@AppliesTo( { PropertyMixin.PropertyFilter.class } )
-public final class PropertyMixin
- implements InvocationHandler
-{
- @State
- private StateHolder state;
-
- @Override
- public Object invoke( Object proxy, Method method, Object[] args )
- throws Throwable
- {
- return state.propertyFor( method );
- }
-
- /**
- * Filter Property methods to apply generic Property Mixin.
- */
- public static class PropertyFilter
- implements AppliesToFilter
- {
- @Override
- public boolean appliesTo( Method method, Class<?> mixin,
Class<?> compositeType, Class<?> modifierClass )
- {
- return Property.class.isAssignableFrom( method.getReturnType() );
- }
- }
-}
-</pre><p>Other examples that we have come across;</p><div
class="itemizedlist"><ul class="itemizedlist"><li class="listitem">
-Mapping from Property<type> to POJO style "properties".
-</li><li class="listitem">
-Remote Service delegation.
-</li><li class="listitem">
-Scripting delegation, where a script will implement the Mixin Type.
-</li></ul></div><p>which seems to indicate that Generic Mixin implementations
are likely to be used in integration of other technologies.</p><p>Typed Mixin
implementations are much preferred in general business logic, as they will be
first-class citizens of
-the IDE as well, for navigation, find usage, refactoring and many other common
tasks. This is one of the main
-advantages of the Zest⢠way of doing AOP compared to AspectJ et al, where
"weaving" is something bolted onto an
-applicationâs classes via regular expressions and known naming conventions,
which can change in an instance by a
-developer being unaware of which PointCuts applies to his
code.</p></div></div><div class="section" title="Concern"><div
class="titlepage"><div><div><h4 class="title"><a
id="core-api-concern"></a>Concern</h4></div></div></div><p>Concerns are the
equivalent of "around advice" in Aspect Oriented Programming. They are chained
into an invocation
-stack for each Mixin Type method and invoked after the Constraints have been
executed. Since they are sitting "around"
-the Mixin implementation method, they also have a chance to modify the
returned result, and even skip calling the
-underlying Mixin method implementation altogether.</p><p>To create a concern,
you need to create a class that,</p><div class="itemizedlist"><ul
class="itemizedlist"><li class="listitem">
-implements the Mixin Type (Typed Concerns) or
java.lang.reflect.InvocationHandler (Generic Concerns),
-</li><li class="listitem">
-extend ConcernOf (Typed Concerns) or GenericConcern (Generic Concerns) [1]
-</li></ul></div><p>You are allowed to modify both the in-arguments as well as
the returned value, including throw exceptions if that is
-suitable, perhaps for post condition checks.</p><div class="section"
title="Typed Concern"><div class="titlepage"><div><div><h5 class="title"><a
id="_typed_concern_2"></a>Typed Concern</h5></div></div></div><p>As mentioned
above, concerns that implements the <span class="emphasis"><em>Mixin
Type</em></span> are called <span class="strong"><strong>Typed
Mixins</strong></span>. They are more common in the
-business domain, and can be used for many important things in the domain
model, such as checking post conditions (i.e.
-ensure that the state in the entire composite is valid), coordinating
services, handling events and much more.</p><p>Typed Concerns doesnât have to
implement all the methods in the Mixin Type. By making the class abstract and
only
-implementing the methods of interest, Zest⢠runtime will subclass the
concern (otherwise not valid for the JVM), but the
-generated methods will never be invoked.</p></div><div class="section"
title="Generic Concern"><div class="titlepage"><div><div><h5 class="title"><a
id="_generic_concern_2"></a>Generic Concern</h5></div></div></div><p>In classic
AOP, all advice are effectively <span class="emphasis"><em>generic</em></span>.
There is no type information in the advice implementation and the
-pointcut can be defined anywhere in the code, and the implementation uses
proxy InvocationHandlers. Zest⢠supports this
-construct as well, and we call it <span class="strong"><strong>Generic
Concern</strong></span>.</p><p>Generic Concerns will be added to all methods
that the AppliesToFilter evaluates to true. By default, that is all
methods.</p><p>AppliesToFilters is a mechanism to limit, or direct, which
methods that the concern should be added to. You have full
-control over this selection process, via several mechanisms.</p><div
class="itemizedlist"><ul class="itemizedlist"><li class="listitem">
-@AppliesTo annotation can be put on the concern, with either;
-</li><li class="listitem">
-an interface for which the methods should be wrapped, or
-</li><li class="listitem">
-an AppliesToFilter implementation that is consulted during building the
invocation stack, or
-</li><li class="listitem">
-an annotation type that must be given on the method.
-</li><li class="listitem">
-Concerns are added only to composites that declares the Concern, either in
-</li><li class="listitem">
-the Composite Type, or
-</li><li class="listitem">
-during assembly in the withConcerns() method.
-</li></ul></div><p>This means that we can make the following three samples of
concerns. First the generic concern that is added to the methods
-of the JDBC Connection class;</p><pre class="programlisting brush:
java">@AppliesTo( java.sql.Connection.class )
-public class CacheConcern extends GenericConcern
- implements InvocationHandler
-{
-</pre><p>We can also use an AppliesToFilter to define which methods should be
wrapped with the concern, like this;</p><pre class="programlisting brush:
java">@AppliesTo( BusinessAppliesToFilter.class )
-public class BusinessConcern extends GenericConcern
- implements InvocationHandler
-{
- [...snip...]
-
-public class BusinessAppliesToFilter
- implements AppliesToFilter
-{
-
- @Override
- public boolean appliesTo( Method method, Class<?> mixin,
Class<?> compositeType, Class<?> fragmentClass
- )
- {
- return true; // Some criteria for when a method is wrapped with the
concern.
- }
-}
-</pre><p>And finally an example of how to use annotations to mark indvidual
methods for being wrapped by the concern.</p><pre class="programlisting brush:
java">@AppliesTo( Audited.class )
-public class AuditConcern extends GenericConcern
- implements InvocationHandler
-{
- [...snip...]
-
- @Override
- public Object invoke( Object proxy, Method method, Object[] args )
- throws Throwable
- {
- return null;
- }
-}
-
- [...snip...]
-
-@Retention( RetentionPolicy.RUNTIME )
-@Target( { ElementType.METHOD } )
-@Documented
-@InjectionScope
-public @interface Audited
-{
-}
-</pre><div class="note" title="Note" style="margin-left: 0.5in; margin-right:
0.5in;"><h3 class="title">Note</h3><p>Even if a method fulfills the requirement
for the concern, if the concern is not declared for the Composite then the
concern will NOT be applied.</p></div></div><div class="section"
title="Invocation Order"><div class="titlepage"><div><div><h5 class="title"><a
id="_invocation_order"></a>Invocation Order</h5></div></div></div><p>The
concerns are invoked AFTER all <a class="xref"
href="core-api.html#core-api-constraint" title="Constraint">Constraint</a> have
been checked. The concerns are executed before the
-<a class="xref" href="core-api.html#core-api-sideeffect"
title="SideEffect">SideEffect</a> are executed in the return path.</p><p>The
order of execution is defined by the declaration order, interface hierarchy,
whether the concern is generic or typed
-and if they are declared in the interface or declared in the <a class="xref"
href="core-bootstrap-assembly.html" title="Core
Bootstrap">Assembly</a>.</p><p>From the perspective of incoming call, i.e.
after the <core-api-constraint>> have been checked, the following rules
-are in place;</p><div class="itemizedlist"><ul class="itemizedlist"><li
class="listitem">
-Typed concerns are invoked AFTER Generic concerns.
-</li><li class="listitem">
-Concern declared to the LEFT are executed BEFORE concerns to the RIGHT.
-</li><li class="listitem">
-Concerns in subclasses are executed BEFORE concerns in super-interfaces.
-</li><li class="listitem">
-Concerns in super-interfaces are executed breadth BEFORE depth.
-</li><li class="listitem">
-Concerns in different super-interfaces at the same "level" are executed with
the concerns declared in super-interfaces left of other super-interfaces first.
(TODO: Strange explanation)
-</li><li class="listitem">
-Concerns declared in interfaces are executed AFTER concerns declared in <a
class="xref" href="core-bootstrap-assembly.html" title="Core
Bootstrap">Assembly</a>.
-</li></ul></div></div></div><div class="section" title="Constraint"><div
class="titlepage"><div><div><h4 class="title"><a
id="core-api-constraint"></a>Constraint</h4></div></div></div></div><div
class="section" title="SideEffect"><div class="titlepage"><div><div><h4
class="title"><a
id="core-api-sideeffect"></a>SideEffect</h4></div></div></div></div><div
class="section" title="DecoratorMixin"><div class="titlepage"><div><div><h4
class="title"><a
id="core-api-decoratormixin"></a>DecoratorMixin</h4></div></div></div><p>A
little known feature is the DecoratorMixin, which allows any object to become a
Mixin. This is useful when for instance
-the initialization of the object to act as a Mixin is complex, or maybe an
instance is shared across many Composites.
-This functionality is only relevant in Transients, and therefor not available
in other Composite meta types.</p><p>This is done by declaring the
DecoratorMixin on the interface, and add the object to be used via the use()
method on
-the TransientBuilder.</p><p>The DecoratorMixin will optimize the invocation
for generic mixins, to avoid additional cost of reflection. But otherwise
-the DecoratorMixin is fairly simple</p><div class="section"
title="Example"><div class="titlepage"><div><div><h5 class="title"><a
id="_example"></a>Example</h5></div></div></div><p>Letâs say that we have a
model, FooModel, whose implementation is simply a POJO. Several different views
shares this
-the same model instance, so any changes to the model will notify the
views.</p><p>We start with the FooModel interface;</p><pre
class="programlisting brush: java">public interface FooModel
-{
- String getBar();
- void setBar(String value);
- [...snip...]
-
-}
-</pre><p>and its implementation is not really relevant for this
discussion.</p><p>Each of the views looks like this;</p><pre
class="programlisting brush: java">@Mixins(View1.Mixin.class)
-public interface View1
-{
- String bar();
-
- public class Mixin
- implements View1
- {
- @This
- FooModel model;
-
- @Override
- public String bar()
- {
- return model.getBar();
- }
- }
-}
-</pre><p>Note that the mixin is expecting to have the FooModel as being part
of the view. This also simplies the mixin, which
-can for instance add and remove listeners to model updates in lifecycle
methods.</p><p>But we need an implementation of the FooModel that uses the
actual implementation of the FooModel. So we decorate the
-FooModel with the DecoratorMixin.</p><pre class="programlisting brush:
java">@Mixins(DecoratorMixin.class)
-public interface FooModel
-</pre><p>The DecoratorMixin expects that the implementation is found among the
"@Uses" objects, so to create a view we simply
-do;</p><pre class="programlisting brush: java">public View1 createView1(
FooModel model )
-{
- TransientBuilder<View1> builder = module.newTransientBuilder(
View1.class );
- builder.use( model );
- return builder.newInstance();
-}
-</pre><p>And there is nothing special in the assembly of this simple
example;</p><pre class="programlisting brush: java">@Override
-public void assemble( ModuleAssembly module )
- throws AssemblyException
-{
- module.transients( View1.class );
- module.transients( View2.class );
- module.transients( FooModel.class );
-}
-</pre><p>This can now be validated in a small test;</p><pre
class="programlisting brush: java">
-@Test
-public void testDecoration()
-{
- FooModelImpl model = new FooModelImpl( "Init" );
- View1 view1 = createView1( model );
- View2 view2 = createView2( model );
- assertThat( view1.bar(), equalTo( "Init" ) );
- assertThat( view2.bar(), equalTo( "Init" ) );
- model.setBar( "New Value" );
- assertThat( view1.bar(), equalTo( "New Value" ) );
- assertThat( view2.bar(), equalTo( "New Value" ) );
-}
-</pre></div></div><div class="section" title="Composite Types Lookup"><div
class="titlepage"><div><div><h4 class="title"><a
id="core-api-type-lookup"></a>Composite Types
Lookup</h4></div></div></div><p>Composite Types Lookup can occurs when you
explicitely lookup for a Composite by Type
-(ex. ServiceFinder.findService(..) methods), when you ask for an injection or
when you create a new composite instance.</p><p>All theses type lookup start
from a Module, are lazy, cached and obey the Zest⢠Visibility rules. Type
Lookup works
-equally accross Composite Types with some subtle differences when it comes to
Services and Entities.</p><div class="section" title="Object, Transient and
Value Types Lookup"><div class="titlepage"><div><div><h5 class="title"><a
id="_object_transient_and_value_types_lookup"></a>Object, Transient and Value
Types Lookup</h5></div></div></div><p>When creating or injecting Objects,
Transients or Values the Type Lookup does the following:</p><p>First, if
Object/Transient/Value Models exactly match the given type, the closest one
(Visibility then Assembly order)
-is returned. Multiple <span class="strong"><strong>exact</strong></span>
matches with the same Visibility are <span
class="strong"><strong>forbidden</strong></span> and result in an
-AmbiguousTypeException.</p><p>Second, if Object/Transient/Value Models match a
type assignable to the given type, the closest one (Visibility then
-Assembly order) is returned. Multiple <span
class="strong"><strong>assignable</strong></span> matches with the same
Visibility are <span class="strong"><strong>forbidden</strong></span> and
result in an
-AmbiguousTypeException.</p></div><div class="section" title="Entity Types
Lookup"><div class="titlepage"><div><div><h5 class="title"><a
id="_entity_types_lookup"></a>Entity Types
Lookup</h5></div></div></div><p>Entity Types Lookup is splitted in two use
cases famillies: Creational usecases and Non-Creational usecases.</p><p><span
class="strong"><strong>Creational Entity Types
Lookup</strong></span></p><p>This Type Lookup takes place when creating new
Entity instances from a UnitOfWork and behave exactly like
-Object/Transient/Value Types Lookups.</p><p><span
class="strong"><strong>Non-Creational Entity Types
Lookup</strong></span></p><p>This Type Lookup takes place when fetching
Entities from an EntityStore or writing queries using the Query API. The Type
-Lookup is different here to allow polymorphic use of Entities and
Queries.</p><p>First difference is that this Type Lookup returns an ordered
collection instead of a single match.</p><p>Returned collection contains, in
order, Entity Models that:</p><div class="itemizedlist"><ul
class="itemizedlist"><li class="listitem">
-exactly match the given type, in Visibility then Assembly order ;
-</li><li class="listitem">
-match a type assignable to the given type, in Visibility then Assembly order.
-</li></ul></div><p>Multiple <span class="strong"><strong>exact</strong></span>
matches with the same Visibility are <span
class="strong"><strong>forbidden</strong></span> and result in an
AmbiguousTypeException.</p><p>Multiple <span
class="strong"><strong>assignable</strong></span> matches are <span
class="strong"><strong>allowed</strong></span> to enable polymorphic fetches
and queries.</p></div><div class="section" title="Service Types Lookup"><div
class="titlepage"><div><div><h5 class="title"><a
id="_service_types_lookup"></a>Service Types
Lookup</h5></div></div></div><p>Service Types Lookup works as
follow:</p><p>Returned collection contains, in order, ServiceReferences
that:</p><div class="itemizedlist"><ul class="itemizedlist"><li
class="listitem">
-exactly match the given type, in Visibility then Assembly order ;
-</li><li class="listitem">
-match a type assignable to the given type, in Visibility then Assembly order.
-</li></ul></div><p>Multiple <span class="strong"><strong>exact</strong></span>
matches with the same Visibility are <span
class="strong"><strong>allowed</strong></span> to enable polymorphic
lookup/injection.</p><p>Multiple <span
class="strong"><strong>assignable</strong></span> matches with the same
Visibility are <span class="strong"><strong>allowed</strong></span> for the
very same reason.</p></div></div><div class="section" title="Metrics API"><div
class="titlepage"><div><div><h4 class="title"><a
id="core-api-metrics"></a>Metrics API</h4></div></div></div><p>The Zestâ¢
platform defines an advanced Metrics SPI to capture runtime metrics of Zestâs
internals as well be used by
-application code (via this API) to provide production metrics for operations
personnel, ensuring healthy state of
-the applications.</p><div class="section" title="MetricsProvider"><div
class="titlepage"><div><div><h5 class="title"><a
id="_metricsprovider"></a>MetricsProvider</h5></div></div></div><p>There are
quite a lot of different Metrics components available, which are instantiated
via factories. There is one
-factory for each component type, to allow for additional components to be
created in the future without breaking
-compatibility in the existing implementations.</p><p>The MetricsProvider is a
standard Zest⢠Service and simply acquired via the @Service annotation on a
field or
-constructor argument.</p><pre class="programlisting brush: java">@Service
-private MetricsProvider provider;
-</pre></div><div class="section" title="Gauge"><div
class="titlepage"><div><div><h5 class="title"><a
id="_gauge"></a>Gauge</h5></div></div></div><p>A Gauge is the simplest form of
Metric. It is a value that the application sets, which is polled upon request.
The
-application need to provide the implementation of the <span
class="emphasis"><em>value()</em></span> method. Gauges are genericized for
type-safe value
-handling.</p><p>A Gauge can represent anything, for instance, thread pool
levels, queue sizes and other resource allocations. It is
-useful to have separate gauges for percentage (%) and absolute numbers of the
same resource. Operations are mainly
-interested in being alerted when threshold are reach as a percentage, as it is
otherwise too many numbers to keep
-track of.</p><p>To create a Gauge, you do something like;</p><pre
class="programlisting brush: java">final BlockingQueue queue = new
LinkedBlockingQueue( 20 );
- [...snip...]
-
-MetricsGaugeFactory gaugeFactory = provider.createFactory(
MetricsGaugeFactory.class );
-MetricsGauge<Integer> gauge = gaugeFactory.registerGauge( getClass(),
"Sample Gauge", new MetricsGauge<Integer>()
-{
- @Override
- public Integer value()
- {
- return queue.size();
- }
-} );
-</pre></div><div class="section" title="Counter"><div
class="titlepage"><div><div><h5 class="title"><a
id="_counter"></a>Counter</h5></div></div></div><pre class="programlisting
brush: java">MetricsCounterFactory counterFactory = provider.createFactory(
MetricsCounterFactory.class );
-MetricsCounter counter = counterFactory.createCounter( getClass(), "Sample
Counter" );
-</pre></div><div class="section" title="Histogram"><div
class="titlepage"><div><div><h5 class="title"><a
id="_histogram"></a>Histogram</h5></div></div></div><pre class="programlisting
brush: java">MetricsHistogramFactory histoFactory = provider.createFactory(
MetricsHistogramFactory.class );
-MetricsHistogram histogram = histoFactory.createHistogram( getClass(), "Sample
Histogram" );
-</pre></div><div class="section" title="Meter"><div
class="titlepage"><div><div><h5 class="title"><a
id="_meter"></a>Meter</h5></div></div></div><pre class="programlisting brush:
java">MetricsMeterFactory meterFactory = provider.createFactory(
MetricsMeterFactory.class );
-MetricsMeter meter = meterFactory.createMeter( getClass(), "Sample Meter",
"requests", TimeUnit.MINUTES );
-</pre></div><div class="section" title="Timer"><div
class="titlepage"><div><div><h5 class="title"><a
id="_timer"></a>Timer</h5></div></div></div><p>Timers capture both the length
of some execution as well as rate of calls. They can be used to time method
calls, or
-critical sections, or even HTTP requests duration and similar.</p><pre
class="programlisting brush: java">MetricsTimerFactory timerFactory =
provider.createFactory( MetricsTimerFactory.class );
-MetricsTimer timer = timerFactory.createTimer( getClass(), "Sample Timer",
TimeUnit.SECONDS, TimeUnit.HOURS );
-</pre></div><div class="section" title="HealthCheck"><div
class="titlepage"><div><div><h5 class="title"><a
id="_healthcheck"></a>HealthCheck</h5></div></div></div><pre
class="programlisting brush: java">MetricsHealthCheckFactory healthFactory =
provider.createFactory( MetricsHealthCheckFactory.class );
-MetricsHealthCheck healthCheck = healthFactory.registerHealthCheck(
- getClass(),
- "Sample Healthcheck",
- new MetricsHealthCheck()
- {
- @Override
- public Result check()
- throws Exception
- {
- ServiceStatus status = pingMyService();
- return new Result( status.isOk(), status.getErrorMessage(),
status.getException() );
- }
- } );
-</pre></div></div></div><div xmlns="" xmlns:exsl="http://exslt.org/common";
class="footer"><p>
- Copyright © 2015 The Apache Software Foundation, Licensed under the
<a href="http://www.apache.org/licenses/"; target="_blank">Apache License,
Version 2.0</a>.
- <br /><small>
- Apache Zest, Zest, Apache, the Apache feather logo, and the Apache
Zest project logo are trademarks of The Apache Software Foundation.<br />
- All other marks mentioned may be trademarks or registered
trademarks of their respective owners.
- </small></p></div></body></html>
\ No newline at end of file
