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:24 UTC
[43/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/glossary.html
----------------------------------------------------------------------
diff --git a/content/java/develop/glossary.html b/content/java/develop/glossary.html
new file mode 100644
index 0000000..f11e7a1
--- /dev/null
+++ b/content/java/develop/glossary.html
@@ -0,0 +1,257 @@
+<?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>Glossary�</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="index.html" title="" /><link rel="prev" href="tools-envisage.html" title="Envisage" />
+
+
+<!-- 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"><a href="core.html">Core</a></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"><span xmlns="" href="glossary.html"
>Glossary�</span></span></dt></dl></div></div><div xmlns="" xmlns:exsl="http://exslt.org/common" class="sub-nav"></div><div class="section" title="Glossary�"><div class="titlepage"><div><div><h2 class="title"><a id="glossary"></a>Glossary�</h2></div></div></div><div class="glossary" title="Glossary"><div class="titlepage"><div><div><h3 class="title"><a id="_glossary"></a>Glossary</h3></div></div></div><p>There are a lot of concepts in Polygene\u2122 which may have different meanings in other contexts. So in true DDD-style
+ubiquitous language, we are here listing the definitions of the terms and concepts that are being used.</p><dl><dt>
+<a id="def-abstract-mixin"></a>Abstract Mixin
+</dt><dd><p>An Abstract Mixin is an implementation of the <a class="xref" href="glossary.html#def-mixin-type">MixinType</a> interface, but is an abstract class and has not
+implemented all the methods.</p><p>The Polygene\u2122 runtime can use multiple <a class="link" href="glossary.html#def-mixin">Mixins</a> for each <a class="xref" href="glossary.html#def-mixin-type">MixinType</a> interface. It is also possible to let
+a <a class="xref" href="glossary.html#def-generic-mixin">Generic Mixin</a> handle the remaining missing methods.</p></dd><dt>
+<a id="def-abstract-modifier"></a>Abstract Modifier
+</dt><dd><p>Abstract Modifiers are <a class="link" href="glossary.html#def-modifier">Modifiers</a> that do not implement all the methods of the <a class="xref" href="glossary.html#def-mixin-type">MixinType</a>
+interface.</p><p>This works essentially in the same manner as the <a class="xref" href="glossary.html#def-abstract-mixin">Abstract Mixin</a>. And the methods that are not implemented
+will not be part of the <a class="xref" href="glossary.html#def-invocation-stack">Invocation Stack</a> of those methods.</p></dd><dt>
+<a id="def-application"></a>Application
+</dt><dd><p>Application is the top level concept handled by the Polygene\u2122 runtime instance. It holds the information about the
+<a class="link" href="glossary.html#def-layer">Layers</a> in the application architecture. See <a class="xref" href="glossary.html#def-structure">Structure</a> for more information.</p><p>There is one and only one Application instance per Polygene\u2122 Runtime instance.</p></dd><dt>
+<a id="def-application-mode"></a>Application Mode
+</dt><dd><p>During the Bootstrap phase an <a class="xref" href="glossary.html#def-application">Application</a> is given a Mode that can be <span class="emphasis"><em>test</em></span>, <span class="emphasis"><em>development</em></span>, <span class="emphasis"><em>staging</em></span> or
+<span class="emphasis"><em>production</em></span>.</p><p>See <a class="xref" href="core-bootstrap-assembly.html" title="Core Bootstrap">Assembly</a>.</p></dd><dt>
+<a id="def-association"></a>Association
+</dt><dd><p>An Association is a reference to an <a class="xref" href="glossary.html#def-entitycomposite">Entity Composite</a>.</p><p>References to <a class="link" href="glossary.html#def-entitycomposite">Entities</a> must be maintained in <a class="link" href="glossary.html#def-association">Associations</a>. It is illegal to
+define a <a class="xref" href="glossary.html#def-property">Property</a> with an <a class="xref" href="glossary.html#def-entitycomposite">Entity Composite</a> as its type.</p></dd><dt>
+<a id="def-composite"></a>Composite
+</dt><dd><p>A Composite is an instance of a <a class="xref" href="glossary.html#def-composite-type">Composite Type</a>.</p><p>However, we often speak of Composites when we actually mean CompositeType, similarly as we often speak of objects
+when we really are talking of classes in OOP.</p></dd><dt>
+<a id="def-composite-context"></a>Composite Context
+</dt><dd><p>A Composite Context is a mechanism to separate the state of a <a class="xref" href="glossary.html#def-transientcomposite">TransientComposite</a> across two or more threads.
+If a thread modifies a value, only that thread will see the changes, another thread will have its values protected
+by the thread boundaries. Use-cases for this include user credentials on which behalf the thread is executing.</p></dd><dt>
+<a id="def-composite-metatype"></a>Composite Meta Type
+</dt><dd><p>There are 5 Composite Meta Types defined in Polygene, which each share the composition features but have distinct
+semantic differences.</p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem">
+<a class="xref" href="glossary.html#def-entitycomposite">Entity Composite</a>
+</li><li class="listitem">
+<a class="xref" href="glossary.html#def-valuecomposite">ValueComposite</a>
+</li><li class="listitem">
+<a class="xref" href="glossary.html#def-servicecomposite">Service composite</a>
+</li><li class="listitem">
+<a class="xref" href="glossary.html#def-configurationcomposite">Configuration Composite</a> (subtype of EntityComposite)
+</li><li class="listitem">
+<a class="xref" href="glossary.html#def-transientcomposite">TransientComposite</a>
+</li></ul></div></dd><dt>
+<a id="def-composite-type"></a>Composite Type
+</dt><dd><p>CompositeType is the Java interface that declares the composition, from which <a class="xref" href="glossary.html#def-composite">Composite</a> instances can be
+created.</p><p>Composite Type interfaces must be a sub-type of one of the 5 <a class="link" href="glossary.html#def-composite-metatype">Composite Meta Types</a> defined in
+Polygene\u2122 otherwise it can not be instantiated.</p></dd><dt>
+<a id="def-concern"></a>Concern
+</dt><dd><p>A concern is a stateless <a class="xref" href="glossary.html#def-fragment">Fragment</a>, shared between invocations, that acts as an interceptor of the call to
+the <a class="xref" href="glossary.html#def-mixin">Mixin</a>. The Concern is a Java class, that either implements the <a class="xref" href="glossary.html#def-mixin-type">MixinType</a> it can be used on, or
+java.lang.reflect.InvocationHandler which allows it to be used on any arbitrary <a class="xref" href="glossary.html#def-mixin-type">MixinType</a>.</p><p>Concerns have many purposes, but they are not intended to produce side effects (see <a class="xref" href="glossary.html#def-sideeffect">SideEffect</a>). Use-cases
+involves;</p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem">
+Transaction handling.
+</li><li class="listitem">
+Call Tracing.
+</li><li class="listitem">
+User security.
+</li></ul></div><p>Concerns are established by the use of the @Concerns annotation on composites.</p><p>Concern is one of the 3 kinds of <a class="link" href="glossary.html#def-modifier">Modifiers</a> defined in Polygene.</p></dd><dt>
+<a id="def-configurationcomposite"></a>Configuration Composite
+</dt><dd><p>Service Composites can have configuration associated to it and that is done via
+<a class="link" href="glossary.html#def-configurationcomposite">Configuration Composites</a>, which are a subtype of <a class="xref" href="glossary.html#def-entitycomposite">Entity Composite</a>, as they are
+stored permanently in configured Entity Stores. Configuration Composites are also initialized automatically from
+properties files first time. Note that on consequent start-ups the properties file is not read, as the configuration is
+read from the EntityStore.</p><p>ConfigurationComposite is one of the 5 <a class="link" href="glossary.html#def-composite-metatype">Composite Meta Types</a> defined in Polygene.</p><p>See <a class="xref" href="howto-configure-service.html" title="Configure a Service">Configure a Service</a> to learn how to use Configuration Composites.</p></dd><dt>
+<a id="def-constraint"></a>Constraint
+</dt><dd><p>Constraints are a kind of validators, which are consulted prior to invoking the method call. Polygene\u2122 currently only
+supports ParameterConstraints on methods and value constraints on <a class="link" href="glossary.html#def-property">Properties</a>, but future versions will
+include Constraint types for checking complete method calls and return values.</p><p>See <a class="xref" href="core-api.html#core-api-constraint" title="Constraint">Constraint</a> for better understanding of its details.</p><p>See <a class="xref" href="library-constraints.html" title="Constraints">Constraints Library</a> for ready to use Constraints.</p><p>See <a class="xref" href="howto-create-constraint.html" title="Create a Constraint">Create a Constraint</a> to learn how to write your own Constraints.</p><p>Constraint is one of the 3 kinds of <a class="link" href="glossary.html#def-modifier">Modifiers</a> defined in Polygene.</p></dd><dt>
+<a id="def-entitycomposite"></a>Entity Composite
+</dt><dd><p>An Entity Composite, or just Entity for short, is a persisted composite with an <a class="xref" href="glossary.html#def-identity">Identity</a>. An entity only has
+scope within an <a class="xref" href="glossary.html#def-unitofwork">UnitOfWork</a> and is therefor inherently thread-safe.</p><p>EntityComposite is one of the 5 <a class="link" href="glossary.html#def-composite-metatype">Composite Meta Types</a> defined in Polygene.</p></dd><dt>
+<a id="def-fragment"></a>Fragment
+</dt><dd><p>A part of the implementation of a <a class="xref" href="glossary.html#def-composite">Composite</a>. There are 4 fragment types:</p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem">
+<a class="xref" href="glossary.html#def-mixin">Mixin</a>
+</li><li class="listitem">
+<a class="xref" href="glossary.html#def-concern">Concern</a>
+</li><li class="listitem">
+<a class="xref" href="glossary.html#def-constraint">Constraint</a>
+</li><li class="listitem">
+<a class="xref" href="glossary.html#def-sideeffect">SideEffect</a>.
+</li></ul></div></dd><dt>
+<a id="def-generic-fragment"></a>Generic Fragment
+</dt><dd><p>Generic Fragments are <a class="link" href="glossary.html#def-fragment">Fragments</a> that implements java.lang.reflect.InvocationHandler and potentially
+capable of being used for all <a class="link" href="glossary.html#def-mixin-type">MixinTypes</a>. This is the direct opposite of the Typed Fragments, which
+implements the <a class="xref" href="glossary.html#def-mixin-type">MixinType</a> interface.</p></dd><dt>
+<a id="def-generic-mixin"></a>Generic Mixin
+</dt><dd><p>A Generic Mixin implements the java.lang.reflect.InvocationHandler. The invoke() method will be called for all
+<a class="xref" href="glossary.html#def-mixin-type">MixinType</a> methods that the <a class="xref" href="glossary.html#def-mixin">Mixin</a> has been matched with, through the matching rules.</p><p>It is potentially possible that the Generic Mixin also implements the <a class="xref" href="glossary.html#def-mixin-type">MixinType</a> interface. In that case, the
+concrete methods will be called, but if the <a class="xref" href="glossary.html#def-mixin">Mixin</a> is also an abstract class, then the invoke() method will be
+called for the methods that has been match but are not present.</p></dd><dt>
+<a id="def-identity"></a>Identity
+</dt><dd><p>TODO</p><p>This term has no definition yet. Learn how to contribute in <a class="xref" href="community-docs.html" title="Polygene\u2122 Documentation">Writing Documentation</a>.</p></dd><dt>
+<a id="def-invocation-stack"></a>Invocation Stack
+</dt><dd><p>For each method, Polygene\u2122 will create and re-use an Invocation Stack. It will be built with the sequence of
+<a class="link" href="glossary.html#def-modifier">Modifiers</a> and an end-point that will link into the stateful <a class="xref" href="glossary.html#def-mixin">Mixin</a>.</p><p>It is important to recognize that, for memory footprint reasons, Invocation Stacks are shared across
+<a class="link" href="glossary.html#def-composite">Composites</a> of the same <a class="xref" href="glossary.html#def-composite-type">Composite Type</a>. They are however thread-safe, in that Polygene\u2122 will never
+bind the same Invocation Stack to more than one <a class="xref" href="glossary.html#def-composite">Composite</a> instance during a method call, but that between method
+invocations the <a class="link" href="glossary.html#def-modifier">Modifiers</a> in the Invocation Stack can not assume that it is bound to the same
+<a class="xref" href="glossary.html#def-composite">Composite</a> instance. Therefor, <a class="link" href="glossary.html#def-modifier">Modifiers</a> are not expected to keep state between method
+invocations, and when it needs to do that, then it should reference a <a class="xref" href="glossary.html#def-mixin">Mixin</a> via the @This annotation. Polygene\u2122 will
+during the binding of the Invocation Stack to the <a class="xref" href="glossary.html#def-composite">Composite</a>, also ensure that all referenced
+<a class="link" href="glossary.html#def-mixin">Mixins</a> are correctly injected in the Invocation Stack.</p></dd><dt>
+<a id="def-layer"></a>Layer
+</dt><dd><p>Polygene\u2122 promotes a Layered application design, where Layers can only access lower Layers and not higher Layers or Layers at
+the same level.</p></dd><dt>
+<a id="def-manyassociation"></a>ManyAssociation
+</dt><dd><p>TODO</p><p>This term has no definition yet. Learn how to contribute in <a class="xref" href="community-docs.html" title="Polygene\u2122 Documentation">Writing Documentation</a>.</p></dd><dt>
+<a id="def-metainfo"></a>MetaInfo
+</dt><dd><p>TODO</p><p>This term has no definition yet. Learn how to contribute in <a class="xref" href="community-docs.html" title="Polygene\u2122 Documentation">Writing Documentation</a>.</p></dd><dt>
+<a id="def-mixin"></a>Mixin
+</dt><dd><p>The Mixin is the instance providing the stateful representation of the <a class="xref" href="glossary.html#def-mixin-type">MixinType</a>. This can either be a class
+implementing the <a class="xref" href="glossary.html#def-mixin-type">MixinType</a> or a java.lang.reflect.InvocationHandler that is generic to handle any or a subset
+of <a class="xref" href="glossary.html#def-mixin-type">MixinType</a>.</p></dd><dt>
+<a id="def-mixin-type"></a>MixinType
+</dt><dd><p>The MixinType is the static type of a part of the <a class="xref" href="glossary.html#def-composite">Composite</a>. The MixinType is an interface that defines the methods
+to be exposed in the <a class="xref" href="glossary.html#def-composite">Composite</a>.</p></dd><dt>
+<a id="def-modifier"></a>Modifier
+</dt><dd><p>Modifiers are stateless interceptors of method calls, that forms an <a class="xref" href="glossary.html#def-invocation-stack">Invocation Stack</a>. The top of the
+<a class="xref" href="glossary.html#def-invocation-stack">Invocation Stack</a> is linked to the <a class="xref" href="glossary.html#def-composite">Composite</a> invocation handler and the bottom of the
+<a class="xref" href="glossary.html#def-invocation-stack">Invocation Stack</a> is linked to the <a class="link" href="glossary.html#def-mixin">Mixins</a>. <a class="link" href="glossary.html#def-invocation-stack">Invocation Stacks</a> are shared,
+so Modifiers must assume that the member fields will only be valid within a single method invocation.</p><p>There are 3 kinds of Modifiers;</p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem">
+<a class="xref" href="glossary.html#def-constraint">Constraint</a>
+</li><li class="listitem">
+<a class="xref" href="glossary.html#def-concern">Concern</a>
+</li><li class="listitem">
+<a class="xref" href="glossary.html#def-sideeffect">SideEffect</a>
+</li></ul></div></dd><dt>
+<a id="def-module"></a>Module
+</dt><dd><p>Modules defines the scope of the <a class="link" href="glossary.html#def-composite">Composites</a>. Modules are wired with Assemblies, and can expose
+<a class="link" href="glossary.html#def-composite">Composites</a> as visible. Non-visible <a class="link" href="glossary.html#def-composite">Composites</a> are not reachable from other Modules.</p></dd><dt>
+<a id="def-namedassociation"></a>NamedAssociation
+</dt><dd><p>TODO</p><p>This term has no definition yet. Learn how to contribute in <a class="xref" href="community-docs.html" title="Polygene\u2122 Documentation">Writing Documentation</a>.</p></dd><dt>
+<a id="def-private-mixin"></a>Private Mixin
+</dt><dd><p>When a @This injection refers to a <a class="xref" href="glossary.html#def-mixin-type">MixinType</a> which is not extended by the <a class="xref" href="glossary.html#def-composite-type">Composite Type</a> the former
+becomes a private <a class="xref" href="glossary.html#def-mixin-type">MixinType</a>.</p></dd><dt>
+<a id="def-property"></a>Property
+</dt><dd><p>TODO</p><p>This term has no definition yet. Learn how to contribute in <a class="xref" href="community-docs.html" title="Polygene\u2122 Documentation">Writing Documentation</a>.</p><p>See the <a class="xref" href="howto-leverage-properties.html" title="Leverage Properties">Leverage Properties</a> how-to.</p></dd><dt>
+<a id="def-servicecomposite"></a>Service Composite
+</dt><dd><p>Service Composite is a subtype of <a class="xref" href="glossary.html#def-composite">Composite</a>, and has a range of features built into it.</p><p>ServiceComposite is one of the 5 <a class="link" href="glossary.html#def-composite-metatype">Composite Meta Types</a> defined in Polygene.</p><p>See the <a class="link" href="core-api.html#core-api-service" title="Service Composite">Service Composite chapter</a>.</p></dd><dt>
+<a id="def-sideeffect"></a>SideEffect
+</dt><dd><p>A side effect is a stateless <a class="xref" href="glossary.html#def-fragment">Fragment</a>, shared between invocations, that acts as an interceptor of the call to
+the <a class="xref" href="glossary.html#def-mixin">Mixin</a>. The SideEffect is a Java class, that either implements the <a class="xref" href="glossary.html#def-mixin-type">MixinType</a> it can be used on, or
+java.lang.reflect.InvocationHandler which allows it to be used on any arbitrary <a class="xref" href="glossary.html#def-mixin-type">MixinType</a>.</p><p>SideEffects are executed after the completion of the method invocation and therefore cannot change parameters nor
+eventually returned object.</p><p>SideEffects have many purposes. Use-cases
+involves;</p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem">
+Sending emails.
+</li><li class="listitem">
+Call Tracing.
+</li><li class="listitem">
+Domain side effects modeling.
+</li></ul></div><p>SideEffects are established by the use of the @SideEffects annotation on composites.</p><p>SideEffect is one of the 3 kinds of <a class="link" href="glossary.html#def-modifier">Modifiers</a> defined in Polygene.</p></dd><dt>
+<a id="def-structure"></a>Structure
+</dt><dd><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 <a class="xref" href="glossary.html#def-application">Application</a> per Polygene\u2122 runtime instance.
+</li><li class="listitem">
+One or more <a class="link" href="glossary.html#def-layer">Layers</a> per <a class="xref" href="glossary.html#def-application">Application</a>.
+</li><li class="listitem">
+Zero, one or more <a class="link" href="glossary.html#def-module">Modules</a> per <a class="xref" href="glossary.html#def-layer">Layer</a>.
+</li><li class="listitem">
+Zero, one or more Assemblies per <a class="xref" href="glossary.html#def-module">Module</a>.
+</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 <a class="link" href="glossary.html#def-module">Modules</a>, so that code can only reach
+<a class="link" href="glossary.html#def-composite">Composites</a> and Objects in <a class="link" href="glossary.html#def-module">Modules</a> (including itself) of the same or lower
+<a class="link" href="glossary.html#def-layer">Layers</a>.</p><p>Each <a class="xref" href="glossary.html#def-layer">Layer</a> has to be declared which lower <a class="link" href="glossary.html#def-layer">Layer(s)</a> it uses, and it is not allowed that a lower
+<a class="xref" href="glossary.html#def-layer">Layer</a> uses a higher <a class="xref" href="glossary.html#def-layer">Layer</a>, i.e. cyclic references.</p></dd><dt>
+<a id="def-transientcomposite"></a>TransientComposite
+</dt><dd><p>TransientComposite is a <a class="xref" href="glossary.html#def-composite-metatype">Composite Meta Type</a> 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 <a class="link" href="glossary.html#def-fragment">Fragment(s)</a> implementing those methods.
+</li><li class="listitem">
+It can not be used as a <a class="xref" href="glossary.html#def-property">Property</a> type.
+</li></ul></div></dd><dt>
+<a id="def-unitofwork"></a>UnitOfWork
+</dt><dd><p>TODO</p><p>This term has no definition yet. Learn how to contribute in <a class="xref" href="community-docs.html" title="Polygene\u2122 Documentation">Writing Documentation</a>.</p></dd><dt>
+<a id="def-valuecomposite"></a>ValueComposite
+</dt><dd><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 <a class="xref" href="glossary.html#def-entitycomposite">Entity Composite</a>, and its value can still be persisted as
+part of an <a class="xref" href="glossary.html#def-entitycomposite">Entity Composite</a> via a <a class="xref" href="glossary.html#def-property">Property</a>.</p><p>The characteristics of a ValueComposite compared to other <a class="link" href="glossary.html#def-composite-metatype">Composite Meta Types</a> are;</p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem">
+It is Immutable.
+</li><li class="listitem">
+Its equals/hashCode works on the values of the ValueComposite.
+</li><li class="listitem">
+Can be used as <a class="xref" href="glossary.html#def-property">Property</a> types, but will not be indexed and searchable.
+</li></ul></div></dd></dl></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
http://git-wip-us.apache.org/repos/asf/polygene-website/blob/ba3a0fac/content/java/develop/howto-assemble-application.html
----------------------------------------------------------------------
diff --git a/content/java/develop/howto-assemble-application.html b/content/java/develop/howto-assemble-application.html
new file mode 100644
index 0000000..5d515c1
--- /dev/null
+++ b/content/java/develop/howto-assemble-application.html
@@ -0,0 +1,228 @@
+<?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>Assemble an Application</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="tutorials.html" title="Tutorials" /><link rel="prev" href="howto-depend-on-polygene.html" title="Depend on Polygene\u2122" /><link rel="next" href="tut-composites.html" title="Transient Composites Tutorial" />
+
+
+<!-- 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"><span xmlns="" href="tutorials.html">Tutorials</span></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"><a href="core.html">Core</a></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="tutorials.html#_overview">Overview</a></span></dt><dt><span class="section"><a href="two-minutes-intro.html">Polygene\u2122 in 2 minutes</a></span></dt><dt><span class="section"><a href="ten-minutes-intro.html">Polygene\u2122 in 10 minutes</a></span></dt><dt><span class="section"><a href="thirty-minutes-intro.html">Polygene\u2122 in 30 minutes</a></span></dt><dt><span class="section"><a href="howto-depend-on-polygene.html">Depend on Polygene\u2122</a></span></dt><dt><span class="section"><span xmlns="" href="howto-assemble-application.html">Assemble an Application</span></span></dt><dt><span class="section"><a href="tut-composites.html">Transient Composites Tutorial</a></span></dt><dt><span class="section"><a href="tut-services.html">Services Composites Tutorial</a></span></dt><dt><span clas
s="section"><a href="howto-contextual-fragments.html">Use contextual fragments</a></span></dt><dt><span class="section"><a href="howto-leverage-properties.html">Leverage Properties</a></span></dt><dt><span class="section"><a href="howto-create-constraint.html">Create a Constraint</a></span></dt><dt><span class="section"><a href="howto-create-concern.html">Create a Concern</a></span></dt><dt><span class="section"><a href="howto-create-sideeffect.html">Create a SideEffect</a></span></dt><dt><span class="section"><a href="howto-create-entity.html">Create an Entity</a></span></dt><dt><span class="section"><a href="howto-configure-service.html">Configure a Service</a></span></dt><dt><span class="section"><a href="howto-invocation-annotation.html">Use @Invocation</a></span></dt><dt><span class="section"><a href="build-system.html">Polygene\u2122 Build System</a></span></dt><dt><span class="section"><a href="community-docs.html">Polygene\u2122 Documentation</a></span></dt><dt><span class="sectio
n"><a href="releasing-apache.html">Releasing Polygene\u2122</a></span></dt></dl></div></div><div class="section" title="Assemble an Application"><div class="titlepage"><div><div><h3 class="title"><a id="howto-assemble-application"></a>Assemble an Application</h3></div></div></div><p>We receive a lot of questions about how applications should be assembled, and since we don\u2019t have any XML to "fill in"
+and everything is to be done programmatically, it escalates the need to provide more hands-on explanation of how this is
+done.</p><p>If you want to reproduce what\u2019s explained in this tutorial, remember to depend on the Core Bootstrap artifact:</p><p>At runtime you will need the Core Runtime artifact too. See the <a class="xref" href="howto-depend-on-polygene.html" title="Depend on Polygene\u2122">Depend on Polygene\u2122</a> tutorial for details.</p><div class="section" title="Basics"><div class="titlepage"><div><div><h4 class="title"><a id="_basics"></a>Basics</h4></div></div></div><p>First let\u2019s recap the structural requirements of Polygene;</p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem">
+There is one and only one Application instance per Polygene\u2122 Runtime.
+</li><li class="listitem">
+Every Application must contain one or more Layers.
+</li><li class="listitem">
+All Composites must be declared in one or more Modules.
+</li><li class="listitem">
+Each Module belong to a Layer.
+</li><li class="listitem">
+Layers are ordered in hierarchies, from simple to complex.
+</li><li class="listitem">
+Access to Composites are limited by visibility rules.
+</li></ul></div><p>Ok, that was quite a handful. Let\u2019s look at them one by one.</p></div><div class="section" title="Application"><div class="titlepage"><div><div><h4 class="title"><a id="_application"></a>Application</h4></div></div></div><p>The first one means that for each Polygene\u2122 Runtime you start, there will be exactly one application. As far as we know, Polygene
+is fully isolated, meaning there are no static members being populated and such.</p></div><div class="section" title="Layers"><div class="titlepage"><div><div><h4 class="title"><a id="_layers"></a>Layers</h4></div></div></div><p>Layers are the super-structures of an application. We have been talking about them for decades, drawn them on paper and
+whiteboards (or even black boards for those old enough), and sometimes organized the codebases along such boundaries.
+But, there has been little effort to enforce the Layer mechanism in code, although it is an extremely powerful
+construct. First of all it implies directional dependency and a high degree of order, spagetti code is reduced if
+successfully implemented. For Polygene, it means that we can restrict access to Composite and Object declarations, so that
+higher layers can not reach them incidentally. You can enforce architecture to a high degree. You can require all
+creation of composites to go through an exposed Factory, which doesn\u2019t require the Composite to be public. And so on.
+Layers have hierarchy, i.e. one layer is top of one or more layers, and is below one or more layers, except for the
+layers at the top and bottom. You could have disjoint layers, which can\u2019t access each other, meaning a couple of layers
+that are both the top and bottom.</p></div><div class="section" title="Modules"><div class="titlepage"><div><div><h4 class="title"><a id="_modules"></a>Modules</h4></div></div></div><p>The Module concept has also been around forever. And in Polygene\u2122 we also makes the Modules explicit. Each Module belong to a
+Layer, and for each Module you declare the Composite and Object types for that Module, together with a Visibility rule,
+one of; application, layer, module.</p></div><div class="section" title="Visibility"><div class="titlepage"><div><div><h4 class="title"><a id="_visibility"></a>Visibility</h4></div></div></div><p>The Visibility rules are perhaps the most powerful aspect of the above. Visibility is a mechanism that kicks in whenever
+a Composite type need to be looked up. It defines both the scoping rules of the client as well as the provider. A lookup
+is either a direct reference, such as</p><pre class="programlisting brush: java">UnitOfWork unitOfWork = module.currentUnitOfWork();
+PersonEntity person = unitOfWork.newEntity( PersonEntity.class );
+</pre><p>or an indirect lookup, such as</p><pre class="programlisting brush: java">UnitOfWork unitOfWork = module.currentUnitOfWork();
+Person person = unitOfWork.newEntity( Person.class );
+</pre><p>where it will first map the Person to a reachable PersonEntity.
+The algorithm is as follows;</p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem">
+Look in the callers Module, if there is one and only one Composite type matching, use it. If there are two or more
+ Composite types matching, then throw an ambiguity exception. If there are zero, proceed to the next step.
+</li><li class="listitem">
+Look in all Modules in the callers Layer. If there is one and only one Composite type that matches and is either
+ Visibility.layer, then use it. If there are two or more Composite types matching, then throw an ambiguity
+ exception. If there are zero, proceed to the next step.
+</li><li class="listitem">
+Look in all Layers that caller\u2019s Layer uses. If there is one and only one Composite type that matches and is
+ either Visibility.application, then use it. If there are two or more Composite types matching, then throw an
+ ambiguity exception. If there are zero, proceed to the next step.
+</li><li class="listitem">
+Throw a CompositeNotFoundException.
+</li></ul></div><p>The underlying principle comes down to Rickard\u2019s "Speaker Analogy", you can hear him (and not the other speakers at the
+conference) because you are in the same room. I.e. if something is really close by, it is very likely that this is what
+we want to use, and then the search expands outwards.</p></div><div class="section" title="Combining The Above"><div class="titlepage"><div><div><h4 class="title"><a id="_combining_the_above"></a>Combining The Above</h4></div></div></div><p>Ok, that was a whole lot of theory and probably take you more than one read-through to fully get into your veins (slow
+acting addiction).
+How to structure your code is beyond the scope of this section. If you are an experienced designer, you will have done
+that before, and you may have started out with good intentions at times only to find yourself in a spaghetti swamp
+later, or perhaps in the also famous "Clear as Clay" or "Ball (bowl?) of Mud". Either way, you need to draw on your
+experience and come up with good structure that Polygene\u2122 lets you enforce.</p><p>So, for the sake of education, we are going to look at an application that consists of many layers, each with a few
+modules. See picture below.</p><p>Image of Example of Layers</p><p>Figure 1. Example of Layers</p><p>So, lets see how we code up this bit in the actual code first.</p><pre class="programlisting brush: java">public class Main
+{
+ private static Energy4Java polygene;
+ private static Application application;
+
+ public static void main( String[] args )
+ throws Exception
+ {
+ // Bootstrap Polygene Runtime
+ // Create a Polygene Runtime
+ polygene = new Energy4Java();
+
+ // Instantiate the Application Model.
+ application = polygene.newApplication( new ApplicationAssembler()
+ {
+ public ApplicationAssembly assemble(
+ ApplicationAssemblyFactory factory )
+ throws AssemblyException
+ {
+ ApplicationAssembly assembly =
+ factory.newApplicationAssembly();
+ LayerAssembly runtime = createRuntimeLayer( assembly );
+ LayerAssembly designer = createDesignerLayer( assembly );
+ LayerAssembly domain = createDomainLayer( assembly );
+ LayerAssembly messaging= createMessagingLayer( assembly );
+ LayerAssembly persistence = createPersistenceLayer( assembly );
+
+ // declare structure between layers
+ domain.uses( messaging );
+ domain.uses( persistence );
+ designer.uses( persistence );
+ designer.uses( domain );
+ runtime.uses( domain );
+
+ return assembly;
+ }
+ } );
+
+ // We need to handle shutdown.
+ installShutdownHook();
+
+ // Activate the Application Runtime.
+ application.activate();
+ }
+
+ [...snip...]
+
+}
+
+</pre><p>The above is the basic setup on how to structure a real-world applicaton, unless you intend to mess with the
+implementations of various Polygene\u2122 systems (yes there are hooks for that too), but that is definitely beyond the scope of
+this tutorial.</p><p>Now, the createXyzLayer() methods were excluded to keep the sample crisp and easy to follow. Let\u2019s take a look at what
+it could be to create the Domain Layer.</p><pre class="programlisting brush: java">private static LayerAssembly createDomainLayer( ApplicationAssembly app )
+{
+ LayerAssembly layer = app.layer("domain-layer");
+ createAccountModule( layer );
+ createInventoryModule( layer );
+ createReceivablesModule( layer );
+ createPayablesModule( layer );
+ return layer;
+}
+
+</pre><p>We just call the layerAssembly() method, which will return either an existing Layer with that name or create a new one
+if one doesn\u2019t already exist, and then delegate to methods for creating the ModuleAssembly instances. In those method
+we need to declare which Composites, Entities, Services and Objects that is in each Module.</p><pre class="programlisting brush: java">private static void createAccountModule( LayerAssembly layer )
+{
+ ModuleAssembly module = layer.module("account-module");
+
+ module.entities(AccountEntity.class, EntryEntity.class);
+
+ module.addServices(
+ AccountRepositoryService.class,
+ AccountFactoryService.class,
+ EntryFactoryService.class,
+ EntryRepositoryService.class
+ ).visibleIn( Visibility.layer );
+}
+
+</pre><p>We also need to handle the shutdown case, so in the main() method we have a installShutdownHook() method call. It is
+actually very, very simple;</p><pre class="programlisting brush: java">private static void installShutdownHook()
+{
+ Runtime.getRuntime().addShutdownHook( new Thread( new Runnable()
+ {
+ public void run()
+ {
+ if( application != null )
+ {
+ try
+ {
+ application.passivate();
+ }
+ catch( Exception e )
+ {
+ e.printStackTrace();
+ }
+ }
+ }
+ }) );
+}
+</pre><p>This concludes this tutorial. We have looked how to get the initial Polygene\u2122 runtime going, how to declare the assembly
+for application model creation and finally the activation of the model itself.</p></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
http://git-wip-us.apache.org/repos/asf/polygene-website/blob/ba3a0fac/content/java/develop/howto-configure-service.html
----------------------------------------------------------------------
diff --git a/content/java/develop/howto-configure-service.html b/content/java/develop/howto-configure-service.html
new file mode 100644
index 0000000..565bff8
--- /dev/null
+++ b/content/java/develop/howto-configure-service.html
@@ -0,0 +1,182 @@
+<?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>Configure a Service</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="tutorials.html" title="Tutorials" /><link rel="prev" href="howto-create-entity.html" title="Create an Entity" /><link rel="next" href="howto-invocation-annotation.html" title="Use @Invocation" />
+
+
+<!-- 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"><span xmlns="" href="tutorials.html">Tutorials</span></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"><a href="core.html">Core</a></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="tutorials.html#_overview">Overview</a></span></dt><dt><span class="section"><a href="two-minutes-intro.html">Polygene\u2122 in 2 minutes</a></span></dt><dt><span class="section"><a href="ten-minutes-intro.html">Polygene\u2122 in 10 minutes</a></span></dt><dt><span class="section"><a href="thirty-minutes-intro.html">Polygene\u2122 in 30 minutes</a></span></dt><dt><span class="section"><a href="howto-depend-on-polygene.html">Depend on Polygene\u2122</a></span></dt><dt><span class="section"><a href="howto-assemble-application.html">Assemble an Application</a></span></dt><dt><span class="section"><a href="tut-composites.html">Transient Composites Tutorial</a></span></dt><dt><span class="section"><a href="tut-services.html">Services Composites Tutorial</a></span></dt><dt><span class="section"><a
href="howto-contextual-fragments.html">Use contextual fragments</a></span></dt><dt><span class="section"><a href="howto-leverage-properties.html">Leverage Properties</a></span></dt><dt><span class="section"><a href="howto-create-constraint.html">Create a Constraint</a></span></dt><dt><span class="section"><a href="howto-create-concern.html">Create a Concern</a></span></dt><dt><span class="section"><a href="howto-create-sideeffect.html">Create a SideEffect</a></span></dt><dt><span class="section"><a href="howto-create-entity.html">Create an Entity</a></span></dt><dt><span class="section"><span xmlns="" href="howto-configure-service.html">Configure a Service</span></span></dt><dt><span class="section"><a href="howto-invocation-annotation.html">Use @Invocation</a></span></dt><dt><span class="section"><a href="build-system.html">Polygene\u2122 Build System</a></span></dt><dt><span class="section"><a href="community-docs.html">Polygene\u2122 Documentation</a></span></dt><dt><span class="sectio
n"><a href="releasing-apache.html">Releasing Polygene\u2122</a></span></dt></dl></div></div><div class="section" title="Configure a Service"><div class="titlepage"><div><div><h3 class="title"><a id="howto-configure-service"></a>Configure a Service</h3></div></div></div><p>Polygene\u2122 supports a Configuration system for services. The configuration instance itself is an Entity and is therefor
+readable, writeable and queryable, just like other Entities. This should make Configuration management much simpler,
+since you can easily build GUI tools to allow editing of these in runtime. However, to simplify the initial values of
+the Configuration instance, Polygene\u2122 also does the initial bootstrapping of the Configuration entity for you. This HowTo is
+going to show how.</p><p>If you want to reproduce what\u2019s explained in this tutorial, remember to depend on the Core Bootstrap artifact:</p><p>At runtime you will need the Core Runtime artifact too. See the <a class="xref" href="howto-depend-on-polygene.html" title="Depend on Polygene\u2122">Depend on Polygene\u2122</a> tutorial for details.</p><div class="section" title="We need a Service"><div class="titlepage"><div><div><h4 class="title"><a id="_we_need_a_service"></a>We need a Service</h4></div></div></div><p>To illustrate these features we create an TravelPlan service, which allows clients to find and make Reservations to
+Destinations. For the sake of simplicity, we are leaving out the domain details\u2026</p><pre class="programlisting brush: java">public interface TravelPlan
+{
+ // Domain methods, which are beyond the discussion at hand.
+}
+</pre><p>So, then there is the ServiceComposite\u2026</p><pre class="programlisting brush: java">// The package is relevant to the Initial Values discussed later.
+package org.apache.polygene.manual.travel;
+ [...snip...]
+
+@Mixins( { TravelPlanMixin.class } )
+public interface TravelPlanService extends TravelPlan, ServiceComposite
+{}
+</pre><p>And then in the Mixin we actually need to connect to a foreign system to obtain the various details that the service
+can provide to the clients. For instance, it needs a host name and port and a protocol to use. We put these into a
+configuration interface.</p><pre class="programlisting brush: java">public interface TravelPlanConfiguration
+{
+ Property<String> hostName();
+
+ @Range( min=0, max=65535 )
+ Property<Integer> portNumber();
+
+ @Matches( "(ssh|rlogin|telnet)" )
+ Property<String> protocol();
+}
+</pre><p>We used the recommended type-safe Property subtype pattern, and for each PortNumber and Protocol we have defined a
+Constraint required.</p><p>Now we can access this configuration in the TravelPlanMixin like this;</p><pre class="programlisting brush: java">import org.apache.polygene.api.configuration.Configuration;
+
+public class TravelPlanMixin implements TravelPlan
+{
+ @This
+ Configuration<TravelPlanConfiguration> config;
+
+ private void foo()
+ {
+ TravelPlanConfiguration tpConf = config.get();
+ String hostName = tpConf.hostName().get();
+ // ...
+ }
+ [...snip...]
+
+}
+</pre><p>And from the Service point of view, it doesn\u2019t need to worry about where the configuration really comes from. But it may
+want to control when the Configuration should be refreshed, to ensure that atomic changes are happening. This is done
+with the refresh() method in the Configuration interface;</p><pre class="programlisting brush: java">public void doSomething()
+{
+ // Refresh Configuration before reading it.
+ config.refresh();
+
+ TravelPlanConfiguration tpConf = config.get();
+ // ...
+}
+</pre><p>This ensures that any updates to the Configuration that has occurred will be retrieved and available to the Service.
+Since Configuration instance is an Entity, the UnitOfWork system will ensure that the Configuration is consistent and
+not in the middle of value changes.</p><div class="section" title="Initial Values"><div class="titlepage"><div><div><h5 class="title"><a id="_initial_values"></a>Initial Values</h5></div></div></div><p>The initial Configuration instance will be created automatically behind the scenes, by reading a properties file and
+create an Entity with the same identity as the identity of the service. That was a handful. Services are, as we know,
+singletons and have an identity specified at assembly. Even if it is not provided, one will automatically be assigned.
+The service\u2019s "identifiedBy" will be used as the identifier for the Configuration entity and stored in the visible
+EntityStore. This identity is also used to locate a properties file in the same package as the ServiceComposite belongs
+to.</p><p>So, we create a properties file, where the keys are the names of the properties in TravelPlanConfiguration.</p><pre class="programlisting brush: bash"># Hostname to the TravelPlan service
+hostName=niclas.hedhman.org
+
+# Port number to use for the connection
+portNumber=5439
+
+# Protocol to use; Valid options "ssh", "rlogin", "telnet"
+protocol=ssh
+
+</pre><p>File: org/hedhman/niclas/travel/TravelPlanService.properties</p><p>Note that the file resides in the directory equivalent to the package name of the TravelPlanService.</p><p>And this would work with the standard assembly.</p><pre class="programlisting brush: java">public void assemble(ModuleAssembly module) throws AssemblyException
+{
+ module.addServices(TravelPlanService.class).instantiateOnStartup();
+}
+</pre></div></div><div class="section" title="Non-default Identity"><div class="titlepage"><div><div><h4 class="title"><a id="_non_default_identity"></a>Non-default Identity</h4></div></div></div><p>If you need to use multiple instances of the same service, or that the service has a non-default Identity, then you need
+to name the properties file according to the Identity of the service declaration, but the file will still need to be in
+the same package as the ServiceComposite sub type, the TravelPlanService in the above example. For instance;</p><pre class="programlisting brush: java">public void assemble(ModuleAssembly module) throws AssemblyException
+{
+ module.addServices(TravelPlanService.class)
+ .instantiateOnStartup()
+ .identifiedBy("ExpediaService");
+
+ module.addServices(TravelPlanService.class)
+ .instantiateOnStartup()
+ .identifiedBy("OrbitzService");
+}
+</pre><p>And the two files for configuration,</p><pre class="programlisting brush: bash"># Hostname to the TravelPlan service
+hostName=expedia.hedhman.org
+
+# Port number to use for the connection
+portNumber=9251
+
+# Protocol to use; Valid options "ssh", "rlogin", "telnet"
+protocol=ssh
+</pre><p>File: org/apache/polygene/manual/travel/ExpediaService.properties</p><pre class="programlisting brush: bash"># Hostname to the TravelPlan service
+hostName=orbitz.hedhman.org
+
+# Port number to use for the connection
+portNumber=7412
+
+# Protocol to use; Valid options "ssh", "rlogin", "telnet"
+protocol=rlogin
+</pre><p>File: org/apache/polygene/manual/travel/OrbitzService.properties</p></div><div class="section" title="Changing Configuration in runtime"><div class="titlepage"><div><div><h4 class="title"><a id="_changing_configuration_in_runtime"></a>Changing Configuration in runtime</h4></div></div></div><p>Unlike most frameworks, the Configuration in Polygene\u2122 is an active Entity, and once the properties file has been read once
+at the first(!) startup, it no longer serves any purpose. The Configuration will always be retrieved from the
+EntityStore. Changes to the properties file are not taken into consideration if the Configuration entity is found in the
+entity store.</p><p>But that also means that applications should not cache the configuration values, and instead read them from the
+Configuration instance every time needed, and do a refresh() method call when it is safe to update the Configuration
+Entity with new values.</p></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
http://git-wip-us.apache.org/repos/asf/polygene-website/blob/ba3a0fac/content/java/develop/howto-contextual-fragments.html
----------------------------------------------------------------------
diff --git a/content/java/develop/howto-contextual-fragments.html b/content/java/develop/howto-contextual-fragments.html
new file mode 100644
index 0000000..1e1e10c
--- /dev/null
+++ b/content/java/develop/howto-contextual-fragments.html
@@ -0,0 +1,93 @@
+<?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>Use contextual fragments</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="tutorials.html" title="Tutorials" /><link rel="prev" href="tut-services.html" title="Services Composites Tutorial" /><link rel="next" href="howto-leverage-properties.html" title="Leverage Properties" />
+
+
+<!-- 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"><span xmlns="" href="tutorials.html">Tutorials</span></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"><a href="core.html">Core</a></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="tutorials.html#_overview">Overview</a></span></dt><dt><span class="section"><a href="two-minutes-intro.html">Polygene\u2122 in 2 minutes</a></span></dt><dt><span class="section"><a href="ten-minutes-intro.html">Polygene\u2122 in 10 minutes</a></span></dt><dt><span class="section"><a href="thirty-minutes-intro.html">Polygene\u2122 in 30 minutes</a></span></dt><dt><span class="section"><a href="howto-depend-on-polygene.html">Depend on Polygene\u2122</a></span></dt><dt><span class="section"><a href="howto-assemble-application.html">Assemble an Application</a></span></dt><dt><span class="section"><a href="tut-composites.html">Transient Composites Tutorial</a></span></dt><dt><span class="section"><a href="tut-services.html">Services Composites Tutorial</a></span></dt><dt><span class="section"><sp
an xmlns="" href="howto-contextual-fragments.html">Use contextual fragments</span></span></dt><dt><span class="section"><a href="howto-leverage-properties.html">Leverage Properties</a></span></dt><dt><span class="section"><a href="howto-create-constraint.html">Create a Constraint</a></span></dt><dt><span class="section"><a href="howto-create-concern.html">Create a Concern</a></span></dt><dt><span class="section"><a href="howto-create-sideeffect.html">Create a SideEffect</a></span></dt><dt><span class="section"><a href="howto-create-entity.html">Create an Entity</a></span></dt><dt><span class="section"><a href="howto-configure-service.html">Configure a Service</a></span></dt><dt><span class="section"><a href="howto-invocation-annotation.html">Use @Invocation</a></span></dt><dt><span class="section"><a href="build-system.html">Polygene\u2122 Build System</a></span></dt><dt><span class="section"><a href="community-docs.html">Polygene\u2122 Documentation</a></span></dt><dt><span class="sectio
n"><a href="releasing-apache.html">Releasing Polygene\u2122</a></span></dt></dl></div></div><div class="section" title="Use contextual fragments"><div class="titlepage"><div><div><h3 class="title"><a id="howto-contextual-fragments"></a>Use contextual fragments</h3></div></div></div><p>Contextual fragments are fragments that are added to the composites during assembly time. That means that they are not
+present in the composite declarations, but a start-up decision what should be added. Once the application instance is
+created, it is no longer possible to modify which fragments are attached.</p><p>Typical use-case is tracing and debugging. Other potential uses are additional security or context interfaces needing
+access to internal mixins not originally intended for, such as GUI frameworks doing reflection on certain composites.
+We strongly recommend against using this feature, as it is not needed as commonly as you may think.</p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>Constraints are not supported to be contextual at the moment.</p></div><p>If you want to reproduce what\u2019s explained in this tutorial, remember to depend on the Core Bootstrap artifact:</p><p>At runtime you will need the Core Runtime artifact too. See the <a class="xref" href="howto-depend-on-polygene.html" title="Depend on Polygene\u2122">Depend on Polygene\u2122</a> tutorial for details.</p><p>The mixins, sideeffects and concerns are added during the bootstrap phase. It is very straight-forward;</p><pre class="programlisting brush: java">public class TraceAll
+{
+ public void assemble( ModuleAssembly module )
+ throws AssemblyException
+ {
+ ServiceDeclaration decl = module.addServices( PinSearchService.class );
+ if( Boolean.getBoolean( "trace.all" ) )
+ {
+ decl.withConcerns( TraceAllConcern.class );
+ }
+ }
+}
+
+</pre><p>In the example above, we add the TraceAllConcern from the Logging Library if the system property "trace.all" is true.
+If the system property is not set to true, there will be no TraceAllConcern on the PinSearchService.</p><p>Concerns that are added in this way will be at the top of the method invocation stack, i.e. will be the first one to be
+called and last one to be completed.</p><p>SideEffects that are added in this way will be the last one\u2019s to be executed.</p></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
http://git-wip-us.apache.org/repos/asf/polygene-website/blob/ba3a0fac/content/java/develop/howto-create-concern.html
----------------------------------------------------------------------
diff --git a/content/java/develop/howto-create-concern.html b/content/java/develop/howto-create-concern.html
new file mode 100644
index 0000000..8b97878
--- /dev/null
+++ b/content/java/develop/howto-create-concern.html
@@ -0,0 +1,163 @@
+<?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>Create a Concern</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="tutorials.html" title="Tutorials" /><link rel="prev" href="howto-create-constraint.html" title="Create a Constraint" /><link rel="next" href="howto-create-sideeffect.html" title="Create a SideEffect" />
+
+
+<!-- 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"><span xmlns="" href="tutorials.html">Tutorials</span></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"><a href="core.html">Core</a></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="tutorials.html#_overview">Overview</a></span></dt><dt><span class="section"><a href="two-minutes-intro.html">Polygene\u2122 in 2 minutes</a></span></dt><dt><span class="section"><a href="ten-minutes-intro.html">Polygene\u2122 in 10 minutes</a></span></dt><dt><span class="section"><a href="thirty-minutes-intro.html">Polygene\u2122 in 30 minutes</a></span></dt><dt><span class="section"><a href="howto-depend-on-polygene.html">Depend on Polygene\u2122</a></span></dt><dt><span class="section"><a href="howto-assemble-application.html">Assemble an Application</a></span></dt><dt><span class="section"><a href="tut-composites.html">Transient Composites Tutorial</a></span></dt><dt><span class="section"><a href="tut-services.html">Services Composites Tutorial</a></span></dt><dt><span class="section"><a
href="howto-contextual-fragments.html">Use contextual fragments</a></span></dt><dt><span class="section"><a href="howto-leverage-properties.html">Leverage Properties</a></span></dt><dt><span class="section"><a href="howto-create-constraint.html">Create a Constraint</a></span></dt><dt><span class="section"><span xmlns="" href="howto-create-concern.html">Create a Concern</span></span></dt><dt><span class="section"><a href="howto-create-sideeffect.html">Create a SideEffect</a></span></dt><dt><span class="section"><a href="howto-create-entity.html">Create an Entity</a></span></dt><dt><span class="section"><a href="howto-configure-service.html">Configure a Service</a></span></dt><dt><span class="section"><a href="howto-invocation-annotation.html">Use @Invocation</a></span></dt><dt><span class="section"><a href="build-system.html">Polygene\u2122 Build System</a></span></dt><dt><span class="section"><a href="community-docs.html">Polygene\u2122 Documentation</a></span></dt><dt><span class="sectio
n"><a href="releasing-apache.html">Releasing Polygene\u2122</a></span></dt></dl></div></div><div class="section" title="Create a Concern"><div class="titlepage"><div><div><h3 class="title"><a id="howto-create-concern"></a>Create a Concern</h3></div></div></div><p>Concerns are defined in <a class="xref" href="glossary.html#def-concern">Concern</a>.</p><p>If you want to reproduce what\u2019s explained in this tutorial, remember to depend on the Core Bootstrap artifact:</p><p>At runtime you will need the Core Runtime artifact too. See the <a class="xref" href="howto-depend-on-polygene.html" title="Depend on Polygene\u2122">Depend on Polygene\u2122</a> tutorial for details.</p><div class="section" title="Typed Concern"><div class="titlepage"><div><div><h4 class="title"><a id="_typed_concern"></a>Typed Concern</h4></div></div></div><p>A typed Concern is a Java class that implements the MixinType it can be used on:</p><pre class="programlisting brush: java">public class InventoryConcern extends Conce
rnOf<Order>
+ implements Order
+{
+ @Service
+ private InventoryService inventory;
+
+ @Override
+ public void addLineItem( LineItem item )
+ {
+ String productCode = item.productCode().get();
+ int quantity = item.quantity().get();
+ inventory.remove( productCode, quantity );
+ next.addLineItem( item );
+ }
+
+ @Override
+ public void removeLineItem( LineItem item )
+ {
+ String productCode = item.productCode().get();
+ int quantity = item.quantity().get();
+ inventory.add( productCode, quantity );
+ next.removeLineItem( item );
+ }
+}
+</pre><p>Note that we could have implemented the InventoryConcern as an abstract class if we were not interested in <span class="emphasis"><em>all</em></span> the methods in the Order interface.
+Extending the ConcernOf is a convenience mechanism, instead of an explicit @ConcernFor annotation on
+a private field, which can be used in rare occasions when you are not able to extend. This base class defines the next
+field, which is set up by the Polygene\u2122 runtime and points to the next fragment in the call stack. We can also see that the
+InventoryService is provided to the concern, which is done with dependency injection. Polygene\u2122 also supports dependency
+injection via constructors and methods.</p><p>It can be used as follows;</p><pre class="programlisting brush: java">@Concerns( InventoryConcern.class )
+public interface Order
+{
+ void addLineItem( LineItem item );
+ void removeLineItem( LineItem item );
+
+ [...snip...]
+
+</pre><p>Methods of the Concern Fragment will be called before the Mixin invocation.</p></div><div class="section" title="Generic Concern"><div class="titlepage"><div><div><h4 class="title"><a id="_generic_concern"></a>Generic Concern</h4></div></div></div><p>A generic Concern is a Java class that implements java.lang.reflect.InvocationHandler which allows it to be used on any
+arbitrary MixinType.</p><pre class="programlisting brush: java">public class MyGenericConcern extends GenericConcern
+{
+ @Override
+ public Object invoke( Object proxy, Method method, Object[] args )
+ throws Throwable
+ {
+ // Do whatever you want
+
+ [...snip...]
+
+</pre><p>It can be used as follows;</p><pre class="programlisting brush: java">@Concerns( MyGenericConcern.class )
+public interface AnyMixinType
+{
+
+ [...snip...]
+
+ @MyAnnotation
+ void doSomething();
+
+ void doSomethingElse();
+
+</pre><p>Methods of the Concern Fragment will be called before the Mixin invocation.</p><div class="section" title="AppliesTo"><div class="titlepage"><div><div><h5 class="title"><a id="_appliesto"></a>AppliesTo</h5></div></div></div><p>For generic Concerns that should only trigger on methods with specific annotations or fulfilling some expression, add
+@AppliesTo annotation to the Concern class which points to either triggering annotation(s), or to AppliesToFilter
+implementation(s).</p><p>The Concern is invoked if one of the triggering annotations is found or one of the AppliesToFilter accepts the
+invocation. In other words the AppliesTo arguments are OR\u2019ed.</p><p>Here is how the declaration goes ;</p><pre class="programlisting brush: java">@AppliesTo( { MyAnnotation.class, MyAppliesToFilter.class } )
+public class MyGenericConcern extends GenericConcern
+{
+</pre><p>And how to use the annotation ;</p><pre class="programlisting brush: java">@Concerns( MyGenericConcern.class )
+public interface AnyMixinType
+{
+
+ @MyAnnotation
+ void doSomething();
+
+ void doSomethingElse();
+
+}
+</pre><p>Here only the doSomething() method will see the Concern applied whereas the doSomethingElse() method won\u2019t.</p><p>Finally here is how to implement an AppliesToFilter:</p><pre class="programlisting brush: java">public class MyAppliesToFilter implements AppliesToFilter
+{
+ public boolean appliesTo( Method method, Class<?> mixin, Class<?> compositeType, Class<?> modifierClass )
+ {
+ boolean appliesTo = evaluate(method); // Do whatever you want
+ return appliesTo;
+ }
+
+ [...snip...]
+
+ private boolean evaluate( Method method )
+ {
+ return true;
+ }
+</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