You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@polygene.apache.org by pa...@apache.org on 2016/12/31 14:21:30 UTC
[49/53] [abbrv] [partial] polygene-website git commit: Import
content/java/develop
http://git-wip-us.apache.org/repos/asf/polygene-website/blob/ba3a0fac/content/java/develop/core-api.html
----------------------------------------------------------------------
diff --git a/content/java/develop/core-api.html b/content/java/develop/core-api.html
new file mode 100644
index 0000000..180eef3
--- /dev/null
+++ b/content/java/develop/core-api.html
@@ -0,0 +1,936 @@
+<?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://polygene.apache.org/favicon.ico" type="image/vnd.microsoft.icon" />
+<link rel="icon" href="http://polygene.apache.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/polygene.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>
+
+<!-- Apache Polygene 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-62007352-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">Polygene\u2122</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.ht
ml">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-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 c
lass="devstatus-tests-good">tests</p><p>The Polygene\u2122 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="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="listitem">
+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 Polygene, 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 Polygene;</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 Polygene\u2122 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 Polygene\u2122 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 Polygene-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>Polygene\u2122 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 Polygene\u2122 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. Polygene\u2122 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 Polygene\u2122 runtime has <span class="emphasis"><em>one and only one</em></span> Application in it. It is possible to run multiple Polygene\u2122 runtimes in the same
+JVM, and it is even possible to embed a Polygene\u2122 runtime within a Polygene\u2122 Application, but there can only be one Application
+in a Polygene\u2122 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 Polygene\u2122 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 Polygene\u2122 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>Polygene\u2122 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 Polygene\u2122 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\u2019t, no need for synchronization. Values are typically very easy to test and very robust to
+refactoring.</p><p>Polygene\u2122 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\u2019s 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(); // (3)
+ String json = someValue.toString(); // (4)
+ SomeValue someNewValue = valueBuilderFactory.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\u2019s 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)
+ new DefaultUnitOfWorkAssembler().assemble( module );
+}
+ [...snip...]
+
+@Service
+private ValueSerializer valueSerializer; // (4)
+@Service
+private ValueDeserializer valueDeserializer; // (4)
+
+ [...snip...]
+
+public void assembledDefaultServiceSerialization()
+{
+ SomeValue someValue = someNewValueInstance(); // (5)
+ String json = valueSerializer.serialize( someValue ); // (6)
+ SomeValue someNewValue = valueDeserializer.deserialize( module, 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 using 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( module, 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></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 Polygene, 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\u2019s promise
+to encapsulate all the behavior together with the object\u2019s 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>Polygene\u2122 will bring a lot of the behavior back to the Composite itself, but we still need Services for cross-composite
+functionality. The Polygene\u2122 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 Polygene\u2122 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 Polygene. 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 Polygene\u2122 is for Polygene\u2122 <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 Polygene, 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 Polygene\u2122 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 Polygene\u2122 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\u2019t 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\u2019t 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, Polygene\u2122 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="Objects"><div class="titlepage"><div><div><h4 class="title"><a id="core-api-object"></a>Objects</h4></div></div></div><p>There are times when Apache Polygene needs to interoperate with other systems, which
+does not have interfaces as their abstraction. Polygene has a notion of
+Objects, which are Polygene-managed classes and can still be injected with
+the Polygene runtime model, such as @Structure and @Service.</p><p>The characteristics of an Object compared to Composite meta types are;</p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem">
+It is a Class, not an interface.
+</li><li class="listitem">
+It can have injections applied to it after it has been created.
+</li><li class="listitem">
+No Mixins, Concerns or SideEffects.
+</li><li class="listitem">
+No Constraints.
+</li><li class="listitem">
+Can not have Property instances managed by the Polygene runtime.
+</li></ul></div><div class="section" title="Serialization"><div class="titlepage"><div><div><h5 class="title"><a id="_serialization"></a>Serialization</h5></div></div></div><p>Objects can be serialized and deserialized using the ValueSerialization API, if and only
+if they are used as types in Properties in Values or Entities. It depends on the
+ValueSerialization implementation on how the objects are serialized, and
+what the requirements are to allow for deserialization. In general, the Spring
+POJO setter/getter approach will always work, a default constructor is needed, and
+to be safe, make it into <code class="literal">java.io.Serializable</code>.</p></div><div class="section" title="Usage"><div class="titlepage"><div><div><h5 class="title"><a id="_usage"></a>Usage</h5></div></div></div><p>Objects are instantiated either by calling <code class="literal">ObjectFactory.newObject( type, \u2026 )</code> or
+instantiating it in some other fashion and then call <code class="literal">ObjectFactory.injectInto(\u2026)</code>
+to populate the fields.</p></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\u2019t 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\u2019t 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 Polygene\u2122 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. Polygene\u2122 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 Polygene\u2122 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\u2019t 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 Polygene\u2122 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 Polygene\u2122 way of doing AOP compared to AspectJ et al, where "weaving" is something bolted onto an
+application\u2019s 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\u2019t have to implement all the methods in the Mixin Type. By making the class abstract and only
+implementing the methods of interest, Polygene\u2122 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. Polygene\u2122 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\u2019s 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 = transientBuilderFactory.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 Polygene\u2122 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 Polygene\u2122 platform defines an advanced Metrics SPI to capture runtime metrics of Polygene\u2019s 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 Polygene\u2122 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( "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( "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( "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( "Sample Meter" );
+</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( "Sample Timer" );
+</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(
+ "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 Polygene, Polygene, Apache, the Apache feather logo, and the Apache Polygene 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