http://git-wip-us.apache.org/repos/asf/polygene-website/blob/ea4d77b0/content/java/latest ---------------------------------------------------------------------- diff --git a/content/java/latest b/content/java/latest new file mode 120000 index 0000000..42f7d23 --- /dev/null +++ b/content/java/latest @@ -0,0 +1 @@ +2.1 \ No newline at end of file diff --git a/content/java/latest/build-system.html b/content/java/latest/build-system.html deleted file mode 100644 index b83a4c5..0000000 --- a/content/java/latest/build-system.html +++ /dev/null @@ -1,149 +0,0 @@ -<?xml version="1.0" encoding="UTF-8" standalone="no"?> -<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd";><html xmlns="http://www.w3.org/1999/xhtml";><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Zest⢠Build System</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-use-io.html" title="Use I/O API" /><link rel="next" href="community-docs.html" title="Writing Zest⢠Documentation" /> - - -<!-- favicon --> - -<link rel="shortcut icon" href="http://qi4j.org/favicon.ico"; type="image/vnd.microsoft.icon" /> -<link rel="icon" href="http://qi4j.org/favicon.ico"; type="image/x-icon" /> - -<!-- style --> - -<link href="css/shCore.css" rel="stylesheet" type="text/css" /> -<link href="css/shCoreEclipse.css" rel="stylesheet" type="text/css" /> -<link href="css/shThemeEclipse.css" rel="stylesheet" type="text/css" /> -<link href="css/qi4j.css" rel="stylesheet" type="text/css" /> - -<!-- Syntax Highlighter --> - -<script type="text/javascript" src="js/shCore.js"></script> -<script type="text/javascript" src="js/shBrushJava.js"></script> -<script type="text/javascript" src="js/shBrushScala.js"></script> -<script type="text/javascript" src="js/shBrushJScript.js"></script> -<script type="text/javascript" src="js/shBrushBash.js"></script> -<script type="text/javascript" src="js/shBrushPlain.js"></script> -<script type="text/javascript" src="js/shBrushXml.js"></script> -<script type="text/javascript" src="js/shBrushGroovy.js"></script> -<script type="text/javascript" src="js/shBrushPython.js"></script> -<script type="text/javascript" src="js/shBrushRuby.js"></script> -<script type="text/javascript" src="js/shBrushCSharp.js"></script> - -<script type="text/javascript"> - SyntaxHighlighter.defaults['tab-size'] = 4; - SyntaxHighlighter.defaults['gutter'] = false; - SyntaxHighlighter.defaults['toolbar'] = false; - SyntaxHighlighter.all() -</script> - -<!-- JQuery --> - -<script type="text/javascript" src="js/jquery-1.6.4.min.js"></script> - -<!-- Image Scaler --> - -<script type="text/javascript" src="js/imagescaler.js"></script> - -<!-- Table Styler --> - -<script type="text/javascript" src="js/tablestyler.js"></script> - -<!-- Qi4j WebSite Progressive Enhancement --> - -<link href="css/progressive-enhancement.css" rel="stylesheet" type="text/css" /> -<script type="text/javascript" src="js/jquery.scrollTo-1.4.2.js"></script> -<script type="text/javascript" src="js/progressive-enhancement.js"></script> - -<!-- Analytics --> - <script type="text/javascript"> - var _gaq = _gaq || []; - _gaq.push(['_setAccount', 'UA-89723617-1']); - _gaq.push(['_trackPageview']); - - (function() { - var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true; - ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js'; - var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s); - })(); - </script> - - </head><body><div xmlns="" xmlns:exsl="http://exslt.org/common"; class="logo"><a href="index.html"><img src="images/logo-standard.png" /></a></div><div xmlns="" xmlns:exsl="http://exslt.org/common"; class="top-nav"><div xmlns="http://www.w3.org/1999/xhtml"; class="toc"><dl><dt><span class="section"><a href="index.html#home">Zestâ¢</a></span></dt><dt><span class="section"><a href="intro.html">Introduction</a></span></dt><dt><span class="section"><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.html"> Glossary </a></span></dt></dl></div></div><div xmlns="" xmlns:exsl="http://exslt.org/common"; class="sub-nav"><div xmlns="http://www.w3.org/1999/xhtml"; class="toc"><dl><dt><span class="section"><a href="tutorials.html#_overview">Overview</a></span></dt><dt><span class="section"><a href="two-minutes-intro.html">Zest⢠in 2 minutes</a></span></dt><dt><span class="section"><a href="ten-minutes-intro.html">Zest⢠in 10 minutes</a></span></dt><dt><span class="section"><a href="thirty-minutes-intro.html">Zest⢠in 30 minutes</a></span></dt><dt><span class="section"><a href="howto-depend-on-zest.html">Depend on Zest⢠in your build</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="howt o-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="howto-use-io.html">Use I/O API</a></span></dt><dt><span class="section"><span xmlns="" href="build-system.html">Zest⢠Build System</span></span></dt><dt><span class="section"><a href="community-docs.htm l">Writing Zest⢠Documentation</a></span></dt><dt><span class="section"><a href="releasing-apache.html">Releasing Zestâ¢</a></span></dt></dl></div></div><div class="section" title="Zest⢠Build System"><div class="titlepage"><div><div><h3 class="title"><a id="build-system"></a>Zest⢠Build System</h3></div></div></div><p>This tutorial is intended for developpers who want to build the Zest⢠SDK themselves. -It describe the Zest⢠SDK Build System from compilation to publication of artifacts for consumption by other -applications.</p><p>If instead you want to setup your project build system to depend on modules of the Zest⢠SDK see the -<a class="link" href="howto-depend-on-zest.html" title="Depend on Zest⢠in your build">dedicated tutorial</a>.</p><div class="section" title="Gradle"><div class="titlepage"><div><div><h4 class="title"><a id="_gradle"></a>Gradle</h4></div></div></div><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>All major Java IDEs have great Gradle support. -Visit the <a class="ulink" href="http://www.gradle.org/tooling"; target="_top">Gradle Tooling</a> page to learn how to import the Zest⢠SDK build into your -favorite IDE.</p></div><p>Zest⢠community migrated away from Maven after several years of frustration, especially around release management, -versioning and cross-module dependency resolution issues, in Feb 2011. -The tool of choice is now Gradle, and it doesnât require any installation, there are <code class="literal">gradlew</code> and <code class="literal">gradlew.bat</code> in -the root folder of the Zest⢠SDK that will bootstrap Gradle if not done so already.</p><p>If you are new to Gradle, you should keep the <a class="ulink" href="http://www.gradle.org/documentation"; target="_top">documentation</a> at hands.</p><p>Build System configuration is done through Gradle properties. -This can be done in many ways, see -<a class="ulink" href="http://gradle.org/docs/current/userguide/tutorial_this_and_that.html#sec:gradle_properties_and_system_properties"; target="_top">Gradle properties and system properties</a>.</p></div><div class="section" title="Root project tasks"><div class="titlepage"><div><div><h4 class="title"><a id="_root_project_tasks"></a>Root project tasks</h4></div></div></div><p>The Zest⢠SDK root project has tasks that work with the whole SDK. -The default build, triggered when running gradle without any command line arguments, compiles the code and run the -tests, but nothing else. -A quick way to check that nothing broke.</p><p>Here are some of theses global tasks we defined:</p><div class="variablelist"><dl><dt><span class="term"> -goOffline -</span></dt><dd>Resolve, download and cache all needed dependencies. -Useful to go offline.</dd><dt><span class="term"> -clean -</span></dt><dd>Clean up of all build output and restore the code base to a fresh state.</dd><dt><span class="term"> -check -</span></dt><dd>Run the tests and other checks like checkstyle. -Reports are generated in <code class="literal">build/reports</code>.</dd><dt><span class="term"> -install -</span></dt><dd>Is roughly the same as Mavenâs install goal. -It produces the test reports, javadocs and installs all the Jars into the local disk repository, for consumption -by other applications.</dd><dt><span class="term"> -buildAll -</span></dt><dd>Produces all the archives, javadocs, manuals and website content. -The output is generated to <code class="literal">build</code>.</dd><dt><span class="term"> -release -</span></dt><dd>Uploads the release artifacts to the distribution servers and creates the release output into the -<code class="literal">build/distributions</code> directory.</dd></dl></div></div><div class="section" title="Submodules tasks"><div class="titlepage"><div><div><h4 class="title"><a id="_submodules_tasks"></a>Submodules tasks</h4></div></div></div><p>In addition to that, some submodules have specific tasks. -To see all available tasks on a submodule issue the following command:</p><pre class="programlisting brush: bash">./gradlew -p tests/performance tasks</pre><p>This example will output all gradle tasks available in the <code class="literal">tests/performance</code> module where you should find -the <code class="literal">testPerf</code> task that run the Zest⢠performance test suite.</p></div><div class="section" title="Versions"><div class="titlepage"><div><div><h4 class="title"><a id="_versions"></a>Versions</h4></div></div></div><p>By default, the build system produces a "zero build". -It means that there is no version assigned to the build, and a "0" is used in the produced artifacts. -This is due to our disagreement (with Maven community) that the "next" version name/number is known prior to -the release. -This is in our opinion a delayed decision. -To build a particular version, you specify a <code class="literal">version</code> property on the command-line, like</p><pre class="programlisting brush: bash">./gradlew -Dversion=2.0-FLAVOUR install</pre><p>If a <code class="literal">version</code> property is not defined, the build system will refuse to make a release and upload.</p></div><div class="section" title="Tests"><div class="titlepage"><div><div><h4 class="title"><a id="_tests"></a>Tests</h4></div></div></div><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>See the <a class="ulink" href="https://builds.apache.org/view/S-Z/view/Zest/"; target="_top">Zest⢠Continuous Integration</a> for current tests results</p></div><p>Unit and integration tests are located near the code under test. -Youâll find theses tests across the whole SDK.</p><div class="section" title="Unit tests requiring external services"><div class="titlepage"><div><div><h5 class="title"><a id="_unit_tests_requiring_external_services"></a>Unit tests requiring external services</h5></div></div></div><p>Among unit tests, some require an external service to be run. -For example, the MongoDB EntityStore extension requires an actual MongoDB server to run its tests.</p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>The HTML test reports generated by Gradle show skipped tests.</p></div><p>All thoses tests should be part of the default build and check if the service is available at its default location -on <code class="literal">localhost</code> and skip if not. -This is easily achieved using <a class="ulink" href="http://junit.sourceforge.net/javadoc/org/junit/Assume.html"; target="_top">JUnit assumptions</a>.</p><p>Weâll list here services that the unit tests will use if available.</p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"> -Memcached, ASCII protocol, no authentication on <code class="literal">localhost:4444</code> for <code class="literal">extensions/cache-memcache</code> -</li><li class="listitem"> -MongoDB without authentication on <code class="literal">localhost:27017</code> for <code class="literal">extensions/entitystore-mongodb</code> -</li><li class="listitem"> -Riak without authentication on <code class="literal">localhost:4444</code> for <code class="literal">extensions/entitystore-riak</code> -</li><li class="listitem"> -Redis without authentication on <code class="literal">localhost:4444</code> for <code class="literal">extensions/entitystore-redis</code> -</li><li class="listitem"> -PostgreSQL for <code class="literal">extensions/entitystore-sql</code> and <code class="literal">extensions/indexing-sql</code> (need setup, see test source) -</li><li class="listitem"> -MySQL for <code class="literal">extensions/entitystore-sql</code> (need setup, see test source) -</li></ul></div></div><div class="section" title="Performance tests"><div class="titlepage"><div><div><h5 class="title"><a id="_performance_tests"></a>Performance tests</h5></div></div></div><p>Performance tests provide performance mesurements for typical Zest⢠use cases. -They are not part of the default build and are located in the <code class="literal">tests/performance</code> directory of the SDK.</p><p>They can be run with the following Gradle command:</p><pre class="programlisting brush: bash">./gradlew :org.qi4j.tests:org.qi4j.test.performance:testPerf</pre><p>Results will then be available in the test reports.</p></div></div><div class="section" title="Documentation generation"><div class="titlepage"><div><div><h4 class="title"><a id="_documentation_generation"></a>Documentation generation</h4></div></div></div><p>The build generates a documentation minisite:</p><pre class="programlisting brush: bash">./gradlew -p manual website</pre><p>Output is in <code class="literal">~/manual/build/docs/website</code>.</p><p>Youâll need Asciidoc and docbook-xsl installed.</p></div><div class="section" title="Build for releases"><div class="titlepage"><div><div><h4 class="title"><a id="_build_for_releases"></a>Build for releases</h4></div></div></div><div class="important" title="Important" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Important</h3><p>Remember that if a <code class="literal">version</code> property is not defined, the build system will refuse to make a release and upload.</p></div><p>The Zest⢠SDK build system is setup for an easy release process. -This is very useful to the Zest⢠Core Team but can also be useful to third parties that want to cut a in-house release. -In this regard, we try to make every aspect of the release process usable for such cases.</p><p>The following sections describe various aspects of the release process. -By default you need to have a proper PGP setup, see below.</p><div class="section" title="Release Criteria"><div class="titlepage"><div><div><h5 class="title"><a id="_release_criteria"></a>Release Criteria</h5></div></div></div><p>The Zest⢠SDK modules are of varying maturity level and we try to maintain a STATUS (<code class="literal">dev-status.xml</code>) file indicating -how good the codebase, documentation and unit tests are for each of the modules. This is highly subjective and -potentially different individuals will judge this differently, but at least it gives a ballpark idea of the situation -for our users.</p><p>The Zest⢠SDK build system use the values from the <code class="literal">dev-status.xml</code> files to filter out non-releasable modules out for -the <code class="literal">javadocs</code> and <code class="literal">uploadArchives</code> root project tasks. -Moreover, the <code class="literal">release</code> task ensure that no releasable module depends on module(s) that donât fit the release criteria -and throw a detailed exception if need be.</p><p>This can be relaxed by adding <code class="literal">-x checkReleaseSpec</code> arguments to gradle invocation.</p></div><div class="section" title="Signing"><div class="titlepage"><div><div><h5 class="title"><a id="_signing"></a>Signing</h5></div></div></div><p>Artifact signing is done using PGP. -You need to provide Gradle the following properties, <code class="literal">~/.gradle/gradle.properties</code> is a good place:</p><pre class="literallayout">signing.keyId=FB751943 -signing.password=foobar -signing.secretKeyRingFile=/home/foo/.gnupg/secring.gpg</pre><p>You can skip the signing process by adding <code class="literal">-x signArchives</code> arguments to gradle invocation.</p></div><div class="section" title="Artifact Upload"><div class="titlepage"><div><div><h5 class="title"><a id="_artifact_upload"></a>Artifact Upload</h5></div></div></div><p>Artifact upload behavior depends on the version assigned to the build.</p><p>By default RELEASES are signed, SNAPSHOTS are not. -Signing can be turned on or off by setting the <code class="literal">uploadSigned</code> property to false.</p><p>By default RELEASES must satisfy ReleaseSpecification, SNAPSHOT donât. -ReleaseSpecification usage can be turned on or off by setting the <code class="literal">uploadReleaseSpec</code> property to false.</p><p>By default RELEASES and SNAPHOTS are uploaded using HTTP. -Used Wagon can be overriden by setting the <code class="literal">uploadWagon</code> property.</p><p>By default RELEASES and SNAPSHOTS are uploaded to the Apache Nexus. -Target repository can be overriden by setting the <code class="literal">uploadRepository</code> property.</p><p>No username/password is provided by default. -If needed set them using the <code class="literal">uploadUsername</code> and <code class="literal">uploadPassword</code> properties.</p><p>For example here is how to deploy all artifacts as unsigned SNAPSHOTs to a given repository:</p><pre class="programlisting brush: bash">./gradlew uploadArchives -Dversion=3.2.1-SNAPSHOT -PuploadReleaseSpec=false \ - -PuploadWagon=what:ever:wagon -PuploadRepository=http://what.ever.repository/url \ - -PuploadUsername=foo -PuploadPassword=bar</pre><p>And here is how to deploy a signed release to the local filesystem:</p><pre class="programlisting brush: bash">./gradlew uploadArchives -Dversion=3.2.1 -PuploadRepository=file:///path/to/local/repository</pre><p>See the <a class="ulink" href="http://www.gradle.org/docs/current/userguide/maven_plugin.html#wagonLibs"; target="_top">Gradle documentation</a> about -supported protocols.</p></div></div></div><div xmlns="" xmlns:exsl="http://exslt.org/common"; class="footer"><p> - Copyright © 2015 The Apache Software Foundation, Licensed under the <a href="http://www.apache.org/licenses/"; target="_blank">Apache License, Version 2.0</a>. - <br /><small> - Apache Zest, Zest, Apache, the Apache feather logo, and the Apache Zest project logo are trademarks of The Apache Software Foundation.<br /> - All other marks mentioned may be trademarks or registered trademarks of their respective owners. - </small></p></div></body></html> \ No newline at end of file diff --git a/content/java/latest/community-docs.html b/content/java/latest/community-docs.html deleted file mode 100644 index c9c4ba9..0000000 --- a/content/java/latest/community-docs.html +++ /dev/null @@ -1,203 +0,0 @@ -<?xml version="1.0" encoding="UTF-8" standalone="no"?> -<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd";><html xmlns="http://www.w3.org/1999/xhtml";><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Writing Zest⢠Documentation</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="build-system.html" title="Zest⢠Build System" /><link rel="next" href="releasing-apache.html" title="Releasing Zestâ¢" /> - - -<!-- favicon --> - -<link rel="shortcut icon" href="http://qi4j.org/favicon.ico"; type="image/vnd.microsoft.icon" /> -<link rel="icon" href="http://qi4j.org/favicon.ico"; type="image/x-icon" /> - -<!-- style --> - -<link href="css/shCore.css" rel="stylesheet" type="text/css" /> -<link href="css/shCoreEclipse.css" rel="stylesheet" type="text/css" /> -<link href="css/shThemeEclipse.css" rel="stylesheet" type="text/css" /> -<link href="css/qi4j.css" rel="stylesheet" type="text/css" /> - -<!-- Syntax Highlighter --> - -<script type="text/javascript" src="js/shCore.js"></script> -<script type="text/javascript" src="js/shBrushJava.js"></script> -<script type="text/javascript" src="js/shBrushScala.js"></script> -<script type="text/javascript" src="js/shBrushJScript.js"></script> -<script type="text/javascript" src="js/shBrushBash.js"></script> -<script type="text/javascript" src="js/shBrushPlain.js"></script> -<script type="text/javascript" src="js/shBrushXml.js"></script> -<script type="text/javascript" src="js/shBrushGroovy.js"></script> -<script type="text/javascript" src="js/shBrushPython.js"></script> -<script type="text/javascript" src="js/shBrushRuby.js"></script> -<script type="text/javascript" src="js/shBrushCSharp.js"></script> - -<script type="text/javascript"> - SyntaxHighlighter.defaults['tab-size'] = 4; - SyntaxHighlighter.defaults['gutter'] = false; - SyntaxHighlighter.defaults['toolbar'] = false; - SyntaxHighlighter.all() -</script> - -<!-- JQuery --> - -<script type="text/javascript" src="js/jquery-1.6.4.min.js"></script> - -<!-- Image Scaler --> - -<script type="text/javascript" src="js/imagescaler.js"></script> - -<!-- Table Styler --> - -<script type="text/javascript" src="js/tablestyler.js"></script> - -<!-- Qi4j WebSite Progressive Enhancement --> - -<link href="css/progressive-enhancement.css" rel="stylesheet" type="text/css" /> -<script type="text/javascript" src="js/jquery.scrollTo-1.4.2.js"></script> -<script type="text/javascript" src="js/progressive-enhancement.js"></script> - -<!-- Analytics --> - <script type="text/javascript"> - var _gaq = _gaq || []; - _gaq.push(['_setAccount', 'UA-89723617-1']); - _gaq.push(['_trackPageview']); - - (function() { - var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true; - ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js'; - var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s); - })(); - </script> - - </head><body><div xmlns="" xmlns:exsl="http://exslt.org/common"; class="logo"><a href="index.html"><img src="images/logo-standard.png" /></a></div><div xmlns="" xmlns:exsl="http://exslt.org/common"; class="top-nav"><div xmlns="http://www.w3.org/1999/xhtml"; class="toc"><dl><dt><span class="section"><a href="index.html#home">Zestâ¢</a></span></dt><dt><span class="section"><a href="intro.html">Introduction</a></span></dt><dt><span class="section"><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.html"> Glossary </a></span></dt></dl></div></div><div xmlns="" xmlns:exsl="http://exslt.org/common"; class="sub-nav"><div xmlns="http://www.w3.org/1999/xhtml"; class="toc"><dl><dt><span class="section"><a href="tutorials.html#_overview">Overview</a></span></dt><dt><span class="section"><a href="two-minutes-intro.html">Zest⢠in 2 minutes</a></span></dt><dt><span class="section"><a href="ten-minutes-intro.html">Zest⢠in 10 minutes</a></span></dt><dt><span class="section"><a href="thirty-minutes-intro.html">Zest⢠in 30 minutes</a></span></dt><dt><span class="section"><a href="howto-depend-on-zest.html">Depend on Zest⢠in your build</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="howt o-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="howto-use-io.html">Use I/O API</a></span></dt><dt><span class="section"><a href="build-system.html">Zest⢠Build System</a></span></dt><dt><span class="section"><span xmlns="" href="community-docs.html"> Writing Zest⢠Documentation</span></span></dt><dt><span class="section"><a href="releasing-apache.html">Releasing Zestâ¢</a></span></dt></dl></div></div><div class="section" title="Writing Zest⢠Documentation"><div class="titlepage"><div><div><h3 class="title"><a id="community-docs"></a>Writing Zest⢠Documentation</h3></div></div></div><p>The documents use the asciidoc format, see:</p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"> -<a class="ulink" href="http://www.methods.co.nz/asciidoc/"; target="_top">Aciidoc Reference</a> -</li><li class="listitem"> -<a class="ulink" href="http://powerman.name/doc/asciidoc"; target="_top">AsciiDoc cheatsheet</a> -</li></ul></div><p>The cheatsheet is really useful!</p><p>You need to install <code class="literal">asciidoc</code> and <code class="literal">docbook-xsl</code>.</p><div class="section" title="Overall Flow"><div class="titlepage"><div><div><h4 class="title"><a id="community-docs-overall-flow"></a>Overall Flow</h4></div></div></div><div class="tip" title="Tip" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Tip</h3><p>To generate the website locally use <code class="literal">./gradlew -p manual website</code>. Output is in <code class="literal">~/manual/build/docs/website</code>.</p></div><p>Each (sub)project has its own documentation, in <span class="emphasis"><em>src/docs/</em></span> and all the Asciidoc documents have the <code class="literal">.txt</code> file extension.</p><p>The documents can use code snippets which will extract code from the project. This is preferred way to include -source code in the documentation, since any refactoring will be reflected in the documentation.</p><p>The above files are all consumed by the build of the manual (by adding them as dependencies). -To get content included in the manual, it has to be explicitly included by a document in the manual as well.</p><p>The whole documentation set is generated from the <span class="emphasis"><em>*manual*</em></span> module in the SDK, and we are currently only creating the website. -The User Guide and Reference Manual are future projects.</p></div><div class="section" title="Headings and document structure"><div class="titlepage"><div><div><h4 class="title"><a id="_headings_and_document_structure"></a>Headings and document structure</h4></div></div></div><p>Each document starts over with headings from level zero (the document title). -Each document should have an id. -In some cases sections in the document need to have idâs as well, this depends on where they fit in the overall structure. -To be able to link to content, it has to have an id. -Missing idâs in mandatory places will produce warnings, or even fail (depending on severity), the build.</p><p>This is how a document should start:</p><pre class="programlisting brush: plain">[[unique-id-verbose-is-ok,Remember This Caption]] -= The Document Title =</pre><p>To push the headings down to the right level in the output, the <code class="literal">leveloffset</code> -attribute is used when including the document inside of another document.</p><p>Subsequent headings in a document should use the following syntax:</p><pre class="programlisting brush: plain">== Subheading == - -... content here ... - -=== Subsubheading === - -content here ...</pre><p>Asciidoc comes with one more syntax for headings, but in this project itâs not used.</p></div><div class="section" title="Writing"><div class="titlepage"><div><div><h4 class="title"><a id="_writing"></a>Writing</h4></div></div></div><p>Try to put one sentence on each line. -Lines without empty lines between them still belongs to the same paragraph. -This makes it easy to move content around, and also easy to spot (too) long sentences.</p></div><div class="section" title="Gotchas"><div class="titlepage"><div><div><h4 class="title"><a id="_gotchas"></a>Gotchas</h4></div></div></div><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"> -A chapter canât be empty. (the build will fail on the docbook xml validity check) -</li><li class="listitem"> -The document title should be "underlined" by the same - number of <code class="literal">=</code> as there are characters in the title. -</li><li class="listitem"> -Always leave a blank line at the end of documents - (or the title of the next document might end up in the last - paragraph of the document) -</li><li class="listitem"> -As <code class="literal">{}</code> are used for Asciidoc attributes, everything inside will be treated as an attribute. - What you have to do is to escape the opening brace: <code class="literal">\{</code>. - If you donât, the braces and the text inside them will be removed without any warning being issued! -</li></ul></div></div><div class="section" title="Links"><div class="titlepage"><div><div><h4 class="title"><a id="_links"></a>Links</h4></div></div></div><p>To link to other parts of the manual the id of the target is used. -This is how such a reference looks:</p><pre class="programlisting brush: plain"><<community-docs-overall-flow>></pre><p>Which will render like: <a class="xref" href="community-docs.html#community-docs-overall-flow" title="Overall Flow">Documentation Flow</a></p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>Just write "see <<target-id>>" and similar, thatâs enough in most cases.</p></div><p>If you need to link to another document with your own link text, this is what to do:</p><pre class="programlisting brush: plain"><<target-id, link text that fits in the context>></pre><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>Having lots of linked text may work well in a web context but is a pain in print, and we aim for both!</p></div><p>External links are added like this:</p><pre class="programlisting brush: plain">https://zest. apache.org/[Link text here]</pre><p>Which renders like: <a class="ulink" href="https://zest.apache.org/"; target="_top">Link text here</a></p><p>For short links it may be better not to add a link text, just do:</p><pre class="programlisting brush: plain">https://zest.apache.org/</pre><p>Which renders like: <a class="ulink" href="https://zest.apache.org/"; target="_top">https://zest.apache.org/</a></p><p>Itâs ok to have a dot right after the URL, it wonât be part of the link.</p><pre class="programlisting brush: plain">https://zest.apache.org/.</pre><p>Which renders like: <a class="ulink" href="https://zest.apache.org/"; target="_top">https://zest.apache.org/</a>.</p></div><div class="section" title="Text Formatting"><div class="titlepage"><div><div><h4 class="title"><a id="_text_formatting"></a>Text Formatting</h4></div></div></div><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"> -<span class="strong"><strong>Bold</strong></span> - just donât do it, the editor in charge is likely to remove it anyhow! -</li><li class="listitem"> -_Italics_ is rendered as <span class="emphasis"><em>Italics</em></span> -</li><li class="listitem"> -+methodName()+ is rendered as <code class="literal">methodName()</code> and is used for literals as well -</li><li class="listitem"> -`command` is rendered as <code class="literal">command</code> (typically used for command-line) -</li><li class="listitem"> -'my/path/' is rendered as <span class="emphasis"><em>my/path/</em></span> (used for file names and paths) -</li></ul></div></div><div class="section" title="Admonitions"><div class="titlepage"><div><div><h4 class="title"><a id="_admonitions"></a>Admonitions</h4></div></div></div><p>These are very useful and should be used where appropriate. -Choose from the following (write all caps and no, we canât easily add new ones):</p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>Note.</p></div><div class="tip" title="Tip" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Tip</h3><p>Tip.</p></div><div class="important" title="Important" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Important</h3><p>Important</p></div><div class="caution" title="Caution" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Caution</h3><p>Caution</p></div><div class="warning" title="Warning" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Warning</h3><p>Warning</p></div><p>Hereâs how itâs done:</p><pre class="programlisting brush: plain">NOTE: Note.</pre><p>A multiline variation:</p><pre class="programlisting brush: plain">[TIP] -Tiptext. -Line 2.</pre><p>Which is rendered as:</p><div class="tip" title="Tip" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Tip</h3><p>Tiptext. -Line 2.</p></div></div><div class="section" title="Images"><div class="titlepage"><div><div><h4 class="title"><a id="_images"></a>Images</h4></div></div></div><div class="important" title="Important" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Important</h3><p><span class="emphasis"><em>All images in the entire manual share the same namespace.</em></span></p></div><div class="section" title="Images Files"><div class="titlepage"><div><div><h5 class="title"><a id="_images_files"></a>Images Files</h5></div></div></div><p>To include an image file, make sure it resides in the <span class="emphasis"><em>images/</em></span> directory relative to the document youâre including it from. -Then go:</p><pre class="programlisting brush: plain">image::logo-standard.png[]</pre><p>Which is rendered as:</p><div class="informalfigure"><a class="ulink" href="images/logo-standard.png" target="_top"> -<span class="inlinemediaobject"><img src="images/logo-standard.png" alt="logo-standard.png" /></span> -</a></div><p>Please note that the <span class="emphasis"><em>images/</em></span> directory is added automatically and not part of the link.</p><p>There are also global resources, residing in <span class="emphasis"><em>manual/src/resources</em></span>, which will be copied to the root of the documentation.</p></div></div><div class="section" title="Code Snippets"><div class="titlepage"><div><div><h4 class="title"><a id="_code_snippets"></a>Code Snippets</h4></div></div></div><div class="section" title="Import from codebase"><div class="titlepage"><div><div><h5 class="title"><a id="_import_from_codebase"></a>Import from codebase</h5></div></div></div><p>Most source code that is included in the documentation should be extract via <code class="literal">SNIPPET</code> markers and then included in document with;</p><pre class="programlisting brush: plain"> [snippet,java] - ----------- - source=tutorials/introduction/tenminutes/src/main/java/org/qi4j/demo/tenminute/OrderEntity.java - tag=mainClass - -----------</pre><p>The source file is relative to the SDK root, and the <span class="emphasis"><em>tag</em></span> is defined in the source file. -The above could be bringing in content that looks like;</p><pre class="programlisting brush: plain">package org.qi4j.demo.tenminute; - -import org.qi4j.api.concern.Concerns; -import org.qi4j.api.entity.EntityComposite; -import org.qi4j.api.sideeffect.SideEffects; - -// START SNIPPET: sideEffect -@SideEffects( MailNotifySideEffect.class ) -// START SNIPPET: mainClass -@Concerns({PurchaseLimitConcern.class, InventoryConcern.class}) -public interface OrderEntity - extends Order, HasSequenceNumber, HasCustomer, - HasLineItems, Confirmable, EntityComposite -{ -// END SNIPPET: sideEffect -} -// END SNIPPET: mainClass</pre><p>which will be rendered as;</p><pre class="programlisting brush: java">@Concerns( { PurchaseLimitConcern.class, InventoryConcern.class } ) -public interface OrderEntity - extends Order, Confirmable, - HasSequenceNumber, HasCustomer, HasLineItems, - EntityComposite -{ -} -</pre><p>Note that -1. The START and END doesnât need to be matching. -1. The AsciiDoc plugin will remove the <span class="emphasis"><em>START SNIPPET</em></span> and <span class="emphasis"><em>END SNIPPET</em></span> lines. -1. If you have more than one START/END section with the same tag, the plugin will insert a "[â¦snipâ¦]" for the excluded lines.</p></div><div class="section" title="Explicitly defined in the document"><div class="titlepage"><div><div><h5 class="title"><a id="_explicitly_defined_in_the_document"></a>Explicitly defined in the document</h5></div></div></div><div class="warning" title="Warning" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Warning</h3><p>Use this kind of code snippets as little as possible. - They are well known to get out of sync with reality after a while.</p></div><p>This is how to do it:</p><pre class="programlisting brush: plain"> [source,java] - ---- - HashMap<String,String> result = new HashMap<String,String>(); - for( String name : names ) - { - if( !"".equals( name ) ) - result.put( name, value ); - } - ----</pre><p>Which is rendered as:</p><pre class="programlisting brush: java"> HashMap<String,String> result = new HashMap<String,String>(); - for( String name : names ) - { - if( !"".equals( name ) ) - result.put( name, value ); - }</pre></div><div class="section" title="Source code Highlighting"><div class="titlepage"><div><div><h5 class="title"><a id="_source_code_highlighting"></a>Source code Highlighting</h5></div></div></div><p>If thereâs no suitable syntax highlighter, just omit the language: <code class="literal">[source]</code>.</p><p>Currently the following syntax highlighters are enabled:</p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"> -Bash -</li><li class="listitem"> -Groovy -</li><li class="listitem"> -Java -</li><li class="listitem"> -JavaScript -</li><li class="listitem"> -Python -</li><li class="listitem"> -Ruby -</li><li class="listitem"> -Scala -</li><li class="listitem"> -XML -</li></ul></div><p>For other highlighters we could add see <a class="ulink" href="http://alexgorbatchev.com/SyntaxHighlighter/manual/brushes/"; target="_top">http://alexgorbatchev.com/SyntaxHighlighter/manual/brushes/</a>.</p></div></div><div class="section" title="Attributes"><div class="titlepage"><div><div><h4 class="title"><a id="_attributes"></a>Attributes</h4></div></div></div><p>Common attributes you can use in documents:</p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"> -</li><li class="listitem"> -</li></ul></div><p>These can substitute part of URLs that point to for example APIdocs or source code.</p></div><div class="section" title="Toolchain"><div class="titlepage"><div><div><h4 class="title"><a id="_toolchain"></a>Toolchain</h4></div></div></div><p>Useful links when configuring the docbook toolchain:</p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"> -<a class="ulink" href="http://www.methods.co.nz/asciidoc"; target="_top">http://www.methods.co.nz/asciidoc</a> -</li><li class="listitem"> -<a class="ulink" href="http://powerman.name/doc/asciidoc"; target="_top">http://powerman.name/doc/asciidoc</a> -</li><li class="listitem"> -alexgorbatchev.com/SyntaxHighlighter/manual/brushes/ -</li><li class="listitem"> -<a class="ulink" href="http://www.docbook.org/tdg/en/html/docbook.html"; target="_top">http://www.docbook.org/tdg/en/html/docbook.html</a> -</li><li class="listitem"> -<a class="ulink" href="http://www.sagehill.net/docbookxsl/index.html"; target="_top">http://www.sagehill.net/docbookxsl/index.html</a> -</li><li class="listitem"> -<a class="ulink" href="http://docbook.sourceforge.net/release/xsl/1.76.1/doc/html/index.html"; target="_top">http://docbook.sourceforge.net/release/xsl/1.76.1/doc/html/index.html</a> -</li><li class="listitem"> -<a class="ulink" href="http://docbook.sourceforge.net/release/xsl/1.76.1/doc/fo/index.html"; target="_top">http://docbook.sourceforge.net/release/xsl/1.76.1/doc/fo/index.html</a> -</li></ul></div></div></div><div xmlns="" xmlns:exsl="http://exslt.org/common"; class="footer"><p> - Copyright © 2015 The Apache Software Foundation, Licensed under the <a href="http://www.apache.org/licenses/"; target="_blank">Apache License, Version 2.0</a>. - <br /><small> - Apache Zest, Zest, Apache, the Apache feather logo, and the Apache Zest project logo are trademarks of The Apache Software Foundation.<br /> - All other marks mentioned may be trademarks or registered trademarks of their respective owners. - </small></p></div></body></html> \ No newline at end of file diff --git a/content/java/latest/core-api.html b/content/java/latest/core-api.html deleted file mode 100644 index d4c99e9..0000000 --- a/content/java/latest/core-api.html +++ /dev/null @@ -1,957 +0,0 @@ -<?xml version="1.0" encoding="UTF-8" standalone="no"?> -<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd";><html xmlns="http://www.w3.org/1999/xhtml";><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Core API</title><link rel="stylesheet" type="text/css" href="css/style.css" /><meta name="generator" content="DocBook XSL Stylesheets V1.76.1" /><link rel="home" href="index.html" title="" /><link rel="up" href="core.html" title="Core" /><link rel="prev" href="core.html" title="Core" /><link rel="next" href="core-bootstrap-assembly.html" title="Core Bootstrap" /> - - -<!-- favicon --> - -<link rel="shortcut icon" href="http://qi4j.org/favicon.ico"; type="image/vnd.microsoft.icon" /> -<link rel="icon" href="http://qi4j.org/favicon.ico"; type="image/x-icon" /> - -<!-- style --> - -<link href="css/shCore.css" rel="stylesheet" type="text/css" /> -<link href="css/shCoreEclipse.css" rel="stylesheet" type="text/css" /> -<link href="css/shThemeEclipse.css" rel="stylesheet" type="text/css" /> -<link href="css/qi4j.css" rel="stylesheet" type="text/css" /> - -<!-- Syntax Highlighter --> - -<script type="text/javascript" src="js/shCore.js"></script> -<script type="text/javascript" src="js/shBrushJava.js"></script> -<script type="text/javascript" src="js/shBrushScala.js"></script> -<script type="text/javascript" src="js/shBrushJScript.js"></script> -<script type="text/javascript" src="js/shBrushBash.js"></script> -<script type="text/javascript" src="js/shBrushPlain.js"></script> -<script type="text/javascript" src="js/shBrushXml.js"></script> -<script type="text/javascript" src="js/shBrushGroovy.js"></script> -<script type="text/javascript" src="js/shBrushPython.js"></script> -<script type="text/javascript" src="js/shBrushRuby.js"></script> -<script type="text/javascript" src="js/shBrushCSharp.js"></script> - -<script type="text/javascript"> - SyntaxHighlighter.defaults['tab-size'] = 4; - SyntaxHighlighter.defaults['gutter'] = false; - SyntaxHighlighter.defaults['toolbar'] = false; - SyntaxHighlighter.all() -</script> - -<!-- JQuery --> - -<script type="text/javascript" src="js/jquery-1.6.4.min.js"></script> - -<!-- Image Scaler --> - -<script type="text/javascript" src="js/imagescaler.js"></script> - -<!-- Table Styler --> - -<script type="text/javascript" src="js/tablestyler.js"></script> - -<!-- Qi4j WebSite Progressive Enhancement --> - -<link href="css/progressive-enhancement.css" rel="stylesheet" type="text/css" /> -<script type="text/javascript" src="js/jquery.scrollTo-1.4.2.js"></script> -<script type="text/javascript" src="js/progressive-enhancement.js"></script> - -<!-- Analytics --> - <script type="text/javascript"> - var _gaq = _gaq || []; - _gaq.push(['_setAccount', 'UA-89723617-1']); - _gaq.push(['_trackPageview']); - - (function() { - var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true; - ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js'; - var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s); - })(); - </script> - - </head><body><div xmlns="" xmlns:exsl="http://exslt.org/common"; class="logo"><a href="index.html"><img src="images/logo-standard.png" /></a></div><div xmlns="" xmlns:exsl="http://exslt.org/common"; class="top-nav"><div xmlns="http://www.w3.org/1999/xhtml"; class="toc"><dl><dt><span class="section"><a href="index.html#home">Zestâ¢</a></span></dt><dt><span class="section"><a href="intro.html">Introduction</a></span></dt><dt><span class="section"><a href="tutorials.html">Tutorials</a></span></dt><dt><span class="section"><a href="javadocs.html">Javadoc</a></span></dt><dt><span class="section"><a href="samples.html">Samples</a></span></dt><dt><span class="section"><span xmlns="" href="core.html">Core</span></span></dt><dt><span class="section"><a href="libraries.html">Libraries</a></span></dt><dt><span class="section"><a href="extensions.html">Extensions</a></span></dt><dt><span class="section"><a href="tools.html">Tools</a></span></dt><dt><span class="section"><a href="glossary.html"> Glossary </a></span></dt></dl></div></div><div xmlns="" xmlns:exsl="http://exslt.org/common"; class="sub-nav"><div xmlns="http://www.w3.org/1999/xhtml"; class="toc"><dl><dt><span class="section"><a href="core.html#_overview_3">Overview</a></span></dt><dt><span class="section"><span xmlns="" href="core-api.html">Core API</span></span></dt><dt><span class="section"><a href="core-bootstrap-assembly.html">Core Bootstrap</a></span></dt><dt><span class="section"><a href="core-testsupport.html">Core Test Support</a></span></dt><dt><span class="section"><a href="core-functional.html">Core Functional API</a></span></dt><dt><span class="section"><a href="core-io.html">Core I/O API</a></span></dt><dt><span class="section"><a href="core-spi.html">Core Extension SPI</a></span></dt><dt><span class="section"><a href="core-runtime.html">Core Runtime</a></span></dt></dl></div></div><div class="section" title="Core API"><div class="titlepage"><div><div><h3 class="title"><a id="core-api"></a>Core API</ h3></div></div></div><p class="remark"><em><span class="comment"></span></em></p><p class="devstatus-code-stable">code</p><p class="devstatus-docs-good">docs</p><p class="devstatus-tests-good">tests</p><p>The Zest⢠Core API is the primary interface for client application code during the main execution phase, i.e. after the -application has been activated.</p><div class="table"><a id="idm371059221680"></a><p class="title"><strong>Table 15. Artifact</strong></p><div class="table-contents"><table summary="Artifact" border="1"><colgroup><col class="col_1" /><col class="col_2" /><col class="col_3" /></colgroup><thead><tr><th align="left" valign="top">Group ID</th><th align="left" valign="top">Artifact ID</th><th align="left" valign="top">Version</th></tr></thead><tbody><tr><td align="left" valign="top"><p>org.qi4j.core</p></td><td align="left" valign="top"><p>org.qi4j.core.api</p></td><td align="left" valign="top"><p>2.1</p></td></tr></tbody></table></div></div><br class="table-break" /><div class="section" title="Composition"><div class="titlepage"><div><div><h4 class="title"><a id="core-api-composition"></a>Composition</h4></div></div></div><p>Composition is at the heart of COP, and refers to two different levels of constructs;</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="list item"> -the ability to assemble (compose) objects from smaller pieces, called Fragments. -</li><li class="listitem"> -the construction of applications by assembling Composites into Modules and Modules into Layers. -</li></ol></div><p>In Zest, we use the term Assembly for the second case of composition. See separate chapter.</p><p>Composition will allow library authors a new level of flexibility in how functionality is provided to client code. More -on that later.</p><div class="section" title="Fragments"><div class="titlepage"><div><div><h5 class="title"><a id="_fragments"></a>Fragments</h5></div></div></div><p>There are 4 types of Fragments in Zest;</p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"> -<a class="xref" href="core-api.html#core-api-mixin" title="Mixin">Mixin</a> - The state carrying part of a Composite. -</li><li class="listitem"> -<a class="xref" href="core-api.html#core-api-constraint" title="Constraint">Constraint</a> - Rules for in and out arguments, typically used for validation. -</li><li class="listitem"> -<a class="xref" href="core-api.html#core-api-concern" title="Concern">Concern</a> - Interceptor of method calls. General purpose use, often for cross-cutting behaviors. -</li><li class="listitem"> -<a class="xref" href="core-api.html#core-api-sideeffect" title="SideEffect">SideEffect</a> - Executed after the method call has been completed, and unable to influence the - outcome of the method call. -</li></ul></div></div><div class="section" title="Composites"><div class="titlepage"><div><div><h5 class="title"><a id="_composites"></a>Composites</h5></div></div></div><p>There are 4 Composite meta types. Each of these have very different characteristics and it is important to understand -these, so the right meta type is used for the right purpose.</p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"> -Entity - Classic meaning. Has an Identity. Is persistable and can be referenced by the Identity. Can act as - Aggregate. Entity supports Lifecycle interface. Equals is defined by the Identity. -</li><li class="listitem"> -Value - Values are persistable when used in a Property from an Entity. Values are immutable, and equals is - defined by the values of its fields. -</li><li class="listitem"> -Service - Service is injectable to other composites and java objects. They are not persistable, but if - referenced from an Entity or Value, a new reference to the Service will be injected when the Entity/Value is - deserialized. Services are singletons. There are <span class="emphasis"><em>hosted</em></span> and <span class="emphasis"><em>imported</em></span> Services. The <span class="emphasis"><em>hosted</em></span> Service has - Configuration and its life cycle controlled by the Zest⢠runtime, whereas the <span class="emphasis"><em>imported</em></span> Services are external - references. -</li><li class="listitem"> -Transient - Short-lived composites that are not persistable. Equals/hashCode/toString are forwarded to the - Mixin Type declaring those methods explicitly. -</li></ul></div><p>In versions of Zest⢠prior to 2.0 (then Qi4j), composite types had to extend one of these 4 meta types, but in 2.0 and later, the -meta type interface is added dynamically during <a class="xref" href="core-bootstrap-assembly.html" title="Core Bootstrap">Assembly</a>. -We can therefor get rid of a lot of additional types, and use Zest-free interfaces directly;</p><pre class="programlisting brush: java">@Mixins( { BalanceCheckMixin.class } ) -public interface BankAccount -{ - Money checkBalance(); - [...snip...] - -} -</pre><p>and declare it with;</p><pre class="programlisting brush: java">public void assemble( ModuleAssembly module ) -{ - module.entities( BankAccount.class ); -} -</pre></div></div><div class="section" title="Structure"><div class="titlepage"><div><div><h4 class="title"><a id="core-api-structure"></a>Structure</h4></div></div></div><p>Zest⢠promotes a conventional view of application structure, that computer science has been using for decades.</p><p>The definition is as follows;</p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"> -One Application per Zest⢠runtime instance. -</li><li class="listitem"> -One or more Layers per Application. -</li><li class="listitem"> -Zero, one or more Modules per Layer. -</li><li class="listitem"> -Zero, one or more Assemblies per Module. -</li></ul></div><p>The principle of this Structure is to assist the programmer to create well modularized applications, that are easily -extended and maintained. Zest⢠will restrict access between Modules, so that code can only reach Composites and Objects -in Modules (including itself) of the same or lower Layers.</p><p>Each Layer has to be declared which lower Layer(s) it uses, and it is not allowed that a lower Layer uses a higher -Layer, i.e. cyclic references.</p></div><div class="section" title="Application"><div class="titlepage"><div><div><h4 class="title"><a id="core-api-application"></a>Application</h4></div></div></div><p>Every Zest⢠runtime has <span class="emphasis"><em>one and only one</em></span> Application in it. It is possible to run multiple Zest⢠runtimes in the same -JVM, and it is even possible to embed a Zest⢠runtime within a Zest⢠Application, but there can only be one Application -in a Zest⢠runtime.</p><p>An Application is then broken into layers and modules are placed within those layers. Composites are placed within -modules. This forms the Application Structure and is enforced by the Zest⢠runtime.</p></div><div class="section" title="Layer"><div class="titlepage"><div><div><h4 class="title"><a id="core-api-layer"></a>Layer</h4></div></div></div><p>A Zest⢠Application must consist of at least one layer. More layers are common, often dividing the application along the -common architectural diagrams used on whiteboards, perhaps with a UI layer at the top, followed by a service or application -layer, then with a domain layer and finally some persistence layer at the bottom.</p><p>Zest⢠enforces this layering by requiring the <a class="xref" href="core-bootstrap-assembly.html" title="Core Bootstrap">Assembly</a> to declare which layer uses which other layer. And -<a class="xref" href="core-api.html#core-api-visibility" title="Visibility">Visibility</a> rules define that layers below can not locate composites in layers above. Also, defining that -"Layer1 uses Layer2" and "Layer2 uses Layer3" does NOT imply that Layer1 has <a class="xref" href="core-api.html#core-api-visibility" title="Visibility">Visibility</a> to Layer3. If that -is wanted, then it must be declared explicitly.</p></div><div class="section" title="Module"><div class="titlepage"><div><div><h4 class="title"><a id="core-api-module"></a>Module</h4></div></div></div><p>Modules are logical compartments to assist developers in creating and maintaining well modularized code. A Module only -belongs to a single Layer, but many Modules can exist in the same Layer. Composite access is limited to;</p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"> -Composites within the same Module, with Visibility set to Visibility.module (default). -</li><li class="listitem"> -Composites from Modules in the same Layer, with Visibility set to Visibility.layer -</li><li class="listitem"> -Composites from Modules in Layers below, with Visibility set to Visibility.application -</li></ul></div><p>Modules contains a lot of the Zest⢠infrastructure, which are the enforcers of these wise modularization principles.</p><p>It is not possible to modify the Modules, their resolution nor binding in any way after the application starts.</p></div><div class="section" title="Visibility"><div class="titlepage"><div><div><h4 class="title"><a id="core-api-visibility"></a>Visibility</h4></div></div></div></div><div class="section" title="ValueComposite"><div class="titlepage"><div><div><h4 class="title"><a id="core-api-value"></a>ValueComposite</h4></div></div></div><p>Usage of value objects is one of the most ignored and best return-on-investment the programmer can do. Values are -immutable and can be compared by value instead of memory reference. Concurrency is suddenly not an issue, since either -the value exists or it doesnât, no need for synchronization. Values are typically very easy to test and very robust to -refactoring.</p><p>Zest⢠defines values as a primary meta type through the ValueComposite, as we think the benefits of values are great. -The ValueComposite is very light-weight compared to the EntityComposite, and its value can still be persisted as part -of an EntityComposite via a Property.</p><p>The characteristics of a ValueComposite compared to other Composite meta types are;</p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"> -It is Immutable. -</li><li class="listitem"> -Its equals/hashCode works on both the descriptor and the values of the ValueComposite. -</li><li class="listitem"> -Can be used as Property types. -</li><li class="listitem"> -Can be serialized and deserialized. -</li></ul></div><div class="section" title="Value Serialization"><div class="titlepage"><div><div><h5 class="title"><a id="_value_serialization"></a>Value Serialization</h5></div></div></div><p>Value objects can be serialized and deserialized using the ValueSerialization API which is a Service API implemented -by SPI and extensions.</p><div class="tip" title="Tip" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Tip</h3><p><code class="literal">ValueSerialization extends ValueSerializer, ValueDeserializer</code>. See the <a class="xref" href="javadocs.html" title="Javadoc"> JavaDocs</a> for interfaces detail.</p></div><p>The ValueSerialization mechanism apply to the following object types :</p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"> -ValueComposite, -</li><li class="listitem"> -EntityReference, -</li><li class="listitem"> -Iterable, -</li><li class="listitem"> -Map, -</li><li class="listitem"> -Plain Value. -</li></ul></div><p>Nested Plain Values, EntityReferences, Iterables, Maps, ValueComposites are supported. -EntityComposites and EntityReferences are serialized as their identity string.</p><p>Plain Values can be one of :</p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"> -String, -</li><li class="listitem"> -Character or char, -</li><li class="listitem"> -Boolean or boolean, -</li><li class="listitem"> -Integer or int, -</li><li class="listitem"> -Long or long, -</li><li class="listitem"> -Short or short, -</li><li class="listitem"> -Byte or byte, -</li><li class="listitem"> -Float or float, -</li><li class="listitem"> -Double or double, -</li><li class="listitem"> -BigInteger, -</li><li class="listitem"> -BigDecimal, -</li><li class="listitem"> -Date, -</li><li class="listitem"> -DateTime (JodaTime), -</li><li class="listitem"> -LocalDateTime (JodaTime), -</li><li class="listitem"> -LocalDate (JodaTime). -</li></ul></div><div class="tip" title="Tip" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Tip</h3><p>Serialization behaviour can be tuned with options. -Every <code class="literal">ValueSerializer</code> methods can take a <code class="literal">ValueSerializer.Options</code> object that contains flags to change how some -values are serialized. See the <a class="xref" href="javadocs.html" title="Javadoc"> JavaDocs</a> for more details.</p></div><p>Values of unknown types and all arrays are considered as <code class="literal">java.io.Serializable</code> and by so are (de)serialized to (from) -base64 encoded bytes using pure Java serialization. If it happens that the value is not Serializable or the input to -deserialize is invalid, a <code class="literal">ValueSerializationException</code> is thrown.</p><p>Methods of <code class="literal">ValueSerializer</code> allow to specify if the serialized state should contain extra type information about the -serialized value. Having type information in the serialized payload allows to keep actual ValueComposite types and by so -circumvent <code class="literal">AmbiguousTypeException</code> when deserializing.</p><p>Core Runtime provides a default ValueSerialization system based on the -<a class="ulink" href="https://github.com/douglascrockford/JSON-java"; target="_top">org.json</a> Java library producing and consuming JSON.</p><p>Letâs see how it works in practice.</p><pre class="programlisting brush: java">public interface SomeValue // (1) -{ - - Property<String> foo(); -} - -@Override -public void assemble( ModuleAssembly module ) - throws AssemblyException -{ - module.values( SomeValue.class ); // (2) - [...snip...] - -} - [...snip...] - -public void defaultValueSerialization() -{ - SomeValue someValue = someNewValueInstance( module ); // (3) - String json = someValue.toString(); // (4) - SomeValue someNewValue = module.newValueFromSerializedState( SomeValue.class, json ); // (5) - [...snip...] - -} -</pre><p>Reading this first example step by step we ;</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"> -declare a ValueComposite, -</li><li class="listitem"> -assemble it, -</li><li class="listitem"> -create a new Value instance, -</li><li class="listitem"> -use the <code class="literal">ValueComposite#toString()</code> method to get a JSON representation of the Value, -</li><li class="listitem"> -and finally, use the <code class="literal">Module#newValueFromSerializedState()</code> method to create a new Value instance from the JSON - state. -</li></ol></div><p><code class="literal">ValueComposite#toString()</code> method leverage Value Serialization and by so provide JSON based representation. The Module -API allows to create new Value instances from serialized state.</p><p>On top of that, Application assemblies can register different implementation of ValueSerialization as Services to -support more formats, see the <a class="xref" href="extensions.html" title="Extensions">Extensions</a> section. Note that the default behaviour described above is overriden if a -ValueSerialization Service is visible.</p><p>Letâs see how to use the ValueSerialization Services.</p><pre class="programlisting brush: java">public interface SomeValue // (1) -{ - - Property<String> foo(); -} - -@Override -public void assemble( ModuleAssembly module ) - throws AssemblyException -{ - module.values( SomeValue.class ); // (2) - new OrgJsonValueSerializationAssembler().assemble( module ); // (3) -} - [...snip...] - -@Service -private ValueSerializer valueSerializer; // (4) -@Service -private ValueDeserializer valueDeserializer; // (4) - - [...snip...] - -public void assembledDefaultServiceSerialization() -{ - SomeValue someValue = someNewValueInstance( module ); // (5) - String json = valueSerializer.serialize( someValue ); // (6) - SomeValue someNewValue = valueDeserializer.deserialize( SomeValue.class, json ); // (7) - [...snip...] - -} -</pre><p>In this second example, we ;</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"> -declare a ValueComposite, -</li><li class="listitem"> -assemble it, -</li><li class="listitem"> -assemble a ValueSerialization Service backed by the <code class="literal">org.json</code> package, -</li><li class="listitem"> -get the <code class="literal">ValueSerializer</code> and <code class="literal">ValueDeserializer</code> Services injected, -</li><li class="listitem"> -create a new Value instance, -</li><li class="listitem"> -use the <code class="literal">ValueSerializer#serialize()</code> method to get a JSON representation of the Value, -</li><li class="listitem"> -and finally, use the <code class="literal">ValueDeserializer#eserialize()</code> method to create a new Value instance from the JSON state. -</li></ol></div><p>Many applications need to stream data. The ValueSerialization API support such use cases in two ways.</p><p>The first one use classic streams.</p><pre class="programlisting brush: java">public void assembledServiceStreamingSerialization() -{ - [...snip...] - - // (1) - Iterable<AcmeValue> data = dataSource; // Eg. Entities converted to Values - OutputStream output = targetStream; // Eg. streaming JSON over HTTP - - // (2) - valueSerializer.serialize( data, output ); - [...snip...] - - // (3) - InputStream input = sourceStream; // Eg. reading incoming JSON - - // (4) - List<AcmeValue> values = valueDeserializer.deserialize( CollectionType.listOf( AcmeValue.class ), input ); - [...snip...] - -} -</pre><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"> -get a handle on a source of values and an <code class="literal">OutputStream</code>, -</li><li class="listitem"> -serialize data into the <code class="literal">OutputStream</code>, -</li><li class="listitem"> -get a handle on an <code class="literal">InputStream</code>, -</li><li class="listitem"> -deserialize data from the <code class="literal">InputStream</code>. -</li></ol></div><p>The second one use the <a class="xref" href="core-io.html" title="Core I/O API">I/O API</a>:</p><pre class="programlisting brush: java">public void assembledServiceIOSerialization() - throws IOException -{ - [...snip...] - - // (1) - Iterable<AcmeValue> queryResult = dataSource; // Eg. Entities converted to Values - Writer writer = outputWriter; // Eg. to pipe data to another process or to a file - - // (2) - Function<AcmeValue, String> serialize = valueSerializer.serialize(); - - // (3) - Inputs.iterable( queryResult ).transferTo( Transforms.map( serialize, Outputs.text( writer ) ) ); - [...snip...] - - // (4) - Reader reader = inputReader; - List<AcmeValue> values = new ArrayList<AcmeValue>(); - - // (5) - Function<String, AcmeValue> deserialize = valueDeserializer.deserialize( AcmeValue.class ); - - // Deserialization of a collection of AcmeValue from a String. - // One serialized AcmeValue per line. - // (6) - Inputs.text( reader ).transferTo( Transforms.map( deserialize, Outputs.collection( values ) ) ); - [...snip...] - -} -</pre><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"> -get a handle on a source of values and a <code class="literal">Writer</code>, -</li><li class="listitem"> -prepare the serialization <code class="literal">Function</code>, -</li><li class="listitem"> -serialize a collection of values, one serialized value per line, -</li><li class="listitem"> -get a handle on a serialized values <code class="literal">Reader</code> and create a new empty <code class="literal">List</code> of values, -</li><li class="listitem"> -prepare the deserialization <code class="literal">Function</code>, -</li><li class="listitem"> -deserialize a collection of values from read lines. -</li></ol></div></div></div><div class="section" title="Service Composite"><div class="titlepage"><div><div><h4 class="title"><a id="core-api-service"></a>Service Composite</h4></div></div></div><p>Any service added, via the ModuleAssembly.addServices(), ModuleAssembly.services() and ModuleAssembly.importServices() -methods, will have the ServiceComposite meta type added to it. In Zest, when we speak of <span class="emphasis"><em>Services</em></span> we mean instances -of <span class="emphasis"><em>ServiceComposite</em></span>.</p><p>Most programmers are familiar with the term "Service", and after the failure of Object Oriented Programmingâs promise -to encapsulate all the behavior together with the objectâs state, programmers learned that the only way to deal with -decoupling and re-use was to make the objects into data containers and deploy services that acted upon those data -containers. Very much what functions did on structs back in the C and Pascal days.</p><p>Zest⢠will bring a lot of the behavior back to the Composite itself, but we still need Services for cross-composite -functionality. The Zest⢠Service model is fairly simple, yet powerful and flexible enough to accommodate most -service-oriented patterns and ability to integrate well with external systems whether they are in-JVM or remote, -such as Spring, OSGi, WS-*, Rest and others.</p><p>The characteristics of a ServiceComposite compared to other Composite meta types are;</p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"> -It is one singleton per declaration in bootstrap. -</li><li class="listitem"> -It has an identity defined in bootstrap. -</li><li class="listitem"> -It has an Activation life cycle into which Activators hook. -</li><li class="listitem"> -It has an optional Configuration. -</li></ul></div><p><span class="emphasis"><em>Services</em></span> in Zest⢠are <span class="emphasis"><em>singletons</em></span>, one instance per definition. That means that there may exist multiple instances -of the same service type, but they can not be created on the fly in runtime, but has to be explicitly defined during -<a class="xref" href="core-bootstrap-assembly.html" title="Core Bootstrap">Assembly</a>.</p><p>By default, <span class="emphasis"><em>Services</em></span> are not instantiated until they are used. This means that the <span class="emphasis"><em>ServiceComposite</em></span> instance itself -will not exist until someone calls a method. If a <span class="emphasis"><em>Service</em></span> needs to be instantiated when the <span class="emphasis"><em>Module</em></span> is activated, one -need to declare/call the instantiateOnStartup() method on the <span class="emphasis"><em>ServiceDescriptor</em></span> during the bootstrap.</p><div class="section" title="Service Configuration"><div class="titlepage"><div><div><h5 class="title"><a id="_service_configuration"></a>Service Configuration</h5></div></div></div><p>The configuration for a service is well supported in Zest. See the <a class="xref" href="core-api.html#core-api-service-configuration" title="Service Configuration">Service Configuration</a> chapter for details.</p></div><div class="section" title="Service Activation"><div class="titlepage"><div><div><h5 class="title"><a id="_service_activation"></a>Service Activation</h5></div></div></div><p>Services are activated (injected and instantiated) either on application start-up, or upon first use. This is controlled -by calling instantiateOnStartup(), this way;</p><pre class="programlisting brush: java">@Override -public void assemble( ModuleAssembly module ) - throws AssemblyException -{ - ServiceDeclaration service = module.addServices( MyDemoService.class ); - service.instantiateOnStartup(); -</pre><p>If this method is not called during assembly, the activation will occur on first service usage.</p><p>Passivation occurs when a <a class="xref" href="core-api.html#core-api-module" title="Module">Module</a> is deactivated, typically because the whole application is shutting down. -Passivation occurs in the reverse order of the activation, to ensure that dependent services are still available for a -passivating service.</p><p>Activators can be assembled with Services to manage their activation. -The easiest way is to implement the ServiceActivation interface directly in the ServiceComposite;</p><pre class="programlisting brush: java">@Mixins( MyActivationMixin.class ) -public static interface MyActivationDemoService - extends ServiceComposite, ServiceActivation -{ -} - -public static class MyActivationMixin - implements ServiceActivation -{ - @Override - public void activateService() - throws Exception - { - // Activation code - } - - @Override - public void passivateService() - throws Exception - { - // Passivation code - } -} -</pre><p>The activation code can also be moved outside the composite by using the ServiceActivatorAdapter;</p><pre class="programlisting brush: java">@Activators( MyActivator.class ) -public static interface MyOtherActivationDemoService - extends ServiceComposite -{ -} - -public static class MyActivator - extends ServiceActivatorAdapter<MyOtherActivationDemoService> -{ - @Override - public void afterActivation( ServiceReference<MyOtherActivationDemoService> activated ) - throws Exception - { - // Activation code - } - - @Override - public void beforePassivation( ServiceReference<MyOtherActivationDemoService> passivating ) - throws Exception - { - // Passivation code - } -} -</pre><p>Activators can be registered on Service assembly too, this way;</p><pre class="programlisting brush: java">@Override -public void assemble( ModuleAssembly module ) -{ - module.services( MyDemoService.class ).withActivators( MyActivator.class ); -} -</pre><p>Activators assembled with the service will get their <code class="literal">beforeActivation</code> and <code class="literal">afterActivation</code> methods called around the -ServiceComposite activation and their <code class="literal">beforePassivation</code> and <code class="literal">afterPassivation</code> around the ServiceComposite -passivation. -Member injection and constructor initialization occur during the activation. The ServiceComposite can be used from the -<code class="literal">afterActivation</code> to the <code class="literal">beforePassivation</code> method.</p></div><div class="section" title="Identity and Tags"><div class="titlepage"><div><div><h5 class="title"><a id="_identity_and_tags"></a>Identity and Tags</h5></div></div></div><p>Services has an Identity, which drives the <a class="xref" href="core-api.html#core-api-service-configuration" title="Service Configuration">Service Configuration</a> system and can be used to lookup a particular service -instance. Services can also be arbitrarily tagged, via the ServiceDescriptor. Example;</p><pre class="programlisting brush: java">@Override -public void assemble( ModuleAssembly module ) - throws AssemblyException -{ - ServiceDeclaration service = module.addServices( MyDemoService.class ); - [...snip...] - - service.taggedWith( "Important", "Drain" ); -</pre><p>Tags are useful inside the application code to locate a particular service instance, in case we have many. For instance;</p><pre class="programlisting brush: java">@Service -private List<ServiceReference<MyDemoService>> services; - -public MyDemoService locateImportantService() -{ - for( ServiceReference<MyDemoService> ref : services ) - { - ServiceTags serviceTags = ref.metaInfo( ServiceTags.class ); - if( serviceTags.hasTag( "Important" ) ) - { - return ref.get(); - } - } - return null; -} -</pre></div></div><div class="section" title="Service Configuration"><div class="titlepage"><div><div><h4 class="title"><a id="core-api-service-configuration"></a>Service Configuration</h4></div></div></div><p>Configuration in Zest⢠is for Zest⢠<a class="xref" href="core-api.html#core-api-service" title="Service Composite">ServiceComposite</a> only. The Configuration is stored in a visible Entity -Store and is therefor runtime modifiable and not static in properties or XML files as in most other dependency -injection frameworks.</p><p>The Configuration system itself will handle all the details with interfacing with reading and writing the configuration. -The normal UnitOfWork management is used, but handled internally by the configuration system.</p><p>In Zest, Configuration are strongly typed and refactoring-friendly. Configuration is read from the entity store, but if -it can not be found, then it will try to bootstrap it from a properties file, with the same name as the -ServiceDescriptor.identifiedBy(), which is set during <a class="xref" href="core-bootstrap-assembly.html" title="Core Bootstrap">Assembly</a> and defaults to the fully qualified -classname of the <a class="xref" href="core-api.html#core-api-service" title="Service Composite">ServiceComposite</a> type.</p><div class="section" title="Defining a Configuration Type"><div class="titlepage"><div><div><h5 class="title"><a id="_defining_a_configuration_type"></a>Defining a Configuration Type</h5></div></div></div><p>The Configuration type is simply listing the properties that are available. The standard rules on @UseDefaults and -@Optional applies. -Example;</p><pre class="programlisting brush: java">public interface MailServiceConfiguration extends ConfigurationComposite -{ - Property<String> hostName(); - - Property<Integer> port(); -} -</pre></div><div class="section" title="Using a Configuration Type"><div class="titlepage"><div><div><h5 class="title"><a id="_using_a_configuration_type"></a>Using a Configuration Type</h5></div></div></div><p>It is important to remember that Configuration is not static values that are set prior to application start-up and -therefor applications should not cache the values retrieved forever, but consciously know when the configuration should -be re-read.</p><p>Configuration is injected via the @This injection scope. One reasonable strategy is to read the configuration on service -activation, so by deactivating/reactivating a service, the user have a well-defined behavior to know how configuration -changes take effect. Example;</p><pre class="programlisting brush: java">@This -private Configuration<MailServiceConfiguration> config; - -@Override -public void sendMail( @Email String to, @MinLength( 8 ) String subject, String body ) -{ - config.refresh(); - MailServiceConfiguration conf = config.get(); - String hostName = conf.hostName().get(); - int port = conf.port().get(); - [...snip...] - -} -</pre></div><div class="section" title="Modifying Configuration"><div class="titlepage"><div><div><h5 class="title"><a id="_modifying_configuration"></a>Modifying Configuration</h5></div></div></div><p>Configuration is modifiable, and after the modifications have been made, the save() method on the Configuration type -must be called. Example;</p><pre class="programlisting brush: java"> void changeExternalMailService( String hostName, int port ); - [...snip...] - - @Override - public void changeExternalMailService( String hostName, int port ) - { - MailServiceConfiguration conf = config.get(); - conf.hostName().set( hostName ); - conf.port().set( port ); - config.save(); - } - [...snip...] - - } -} -</pre></div></div><div class="section" title="EntityComposite"><div class="titlepage"><div><div><h4 class="title"><a id="core-api-entity"></a>EntityComposite</h4></div></div></div><p>Entities are common in the object oriented programming world, but has never reached the stardom of Class and Object. -Instead we have seen many attempts at creating Entities on top of Java, such as EJB (3 incompatible versions), Java -Data Objects (JDO, 2 somewhat compatible versions), Java Persistence Architecture (JPA, 2 somewhat compatible versions), -Hibernate (4+ somewhat incompatible versions) and many other less known. This seems to suggest that the topic of -creating objects that survives over long periods of time is a difficult one.</p><p>Eric Evans points out in his book that Entities is a very definite and distinct concept that needs to be handled -explicitly. Composite Oriented Programming in general, and Zest⢠in particular, takes this point very seriously and -makes Entities a central part of the whole system. And likewise, we are convinced that it is not possible to develop -domain-knowledge-rich applications without a conscious and well-defined strategy on Entities. So, instead of spending -endless hours trying to get Hibernate mapping to do the right thing, we introduce a Composite meta type called -EntityComposite, which all entities must derive from, and by doing so automatically become persistable, searchable, -have a lifecycle and support nested undoable modifications.</p><p>The characteristics of an EntityComposite compared to other Composite meta types are;</p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"> -It has an Identity. -</li><li class="listitem"> -It has a LifeCycle. -</li><li class="listitem"> -It is typically persisted. -</li><li class="listitem"> -It can only be referenced by an Association or ManyAssociation. -</li><li class="listitem"> -Its CRUD operations are bound by a UnitOfWork. -</li></ul></div></div><div class="section" title="Unit Of Work"><div class="titlepage"><div><div><h4 class="title"><a id="core-api-unitofwork"></a>Unit Of Work</h4></div></div></div><p>A UnitOfWork is a bounded group of operations performed, typically on entities, where these operations are not visible -to other threads until the UnitOfWork is completed. It is also possible to discard these operations, as if they were -never executed.</p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>UnitOfWork has many similarities with the Transaction concept used with RDBMSes. But since Zest⢠introduced several deviations to the common definitions of Transactions, we chose to use a different term.</p></div><p>There are several key characteristics of UnitOfWork;</p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"> -They are limited to a single thread. -</li><li class="listitem"> -They have an associated use-case. -</li><li class="listitem"> -They can be paused and resumed. -</li><li class="listitem"> -They have a notification mechanism (used to trigger Indexing for instance). -</li><li class="listitem"> -They can be long-running, as they donât tie up underlying transactions or other expensive resources. -</li></ul></div><p>At the moment, they are exclusively used to manipulate <a class="xref" href="core-api.html#core-api-entity" title="EntityComposite">EntityComposite</a> composites. All entity operations MUST be -done via UnitOfWork, and in fact it is not possible to get this wrong.</p><div class="section" title="UnitOfWork Propagation"><div class="titlepage"><div><div><h5 class="title"><a id="_unitofwork_propagation"></a>UnitOfWork Propagation</h5></div></div></div><p>UnitOfWork is associated with a thread, and can only be transferred to another thread by a relatively complex operation -of pausing a UnitOfWork in one thread, then hand over the UnitOfWork to the other thread and resume it there. Donât do it!</p><p>UnitOfWork is available from the <span class="emphasis"><em><a class="xref" href="core-api.html#core-api-module" title="Module">Module</a>, and from the Module you request either a new UnitOfWork or asking -for the _current</em></span> one. <span class="emphasis"><em>Current UnitOfWork</em></span> means the UnitOfWork that was created earlier within the same thread. So, -typically most entity manipulation code only request the current UnitOfWork and the management of creating, completing -and aborting the UnitOfWork is handled by the transaction boundary, often in the so called application layer (see -<a class="xref" href="core-api.html#core-api-layer" title="Layer">Layer</a>)</p><p>Since it is very common to have all, or nearly all, methods in the <span class="emphasis"><em>transaction boundary</em></span> to handle the creation and -completion, possibly with retry, in the same class, module or even layer, Zest⢠provides annotations to easily declare -UnitOfWork concern: @UnitOfWorkPropagation, @UnitOfWorkDiscardOn and @UnitOfWorkRetry</p></div></div><div class="section" title="TransientComposite"><div class="titlepage"><div><div><h4 class="title"><a id="core-api-transient"></a>TransientComposite</h4></div></div></div><p>TransientComposite is a Composite meta type for all other cases. The main characteristics are;</p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"> -It can not be serialized nor persisted. -</li><li class="listitem"> -hashcode/equals are not treated specially and will be delegated to fragment(s) implementing those methods. -</li><li class="listitem"> -It can not be used as a Property type. -</li></ul></div></div><div class="section" title="Mixin"><div class="titlepage"><div><div><h4 class="title"><a id="core-api-mixin"></a>Mixin</h4></div></div></div><p>Mixins are the state-carrying part of a Composite instance. The other Fragments can not retain state between method -invocations as they are shared across Composite instances.</p><div class="section" title="Mixin Type"><div class="titlepage"><div><div><h5 class="title"><a id="_mixin_type"></a>Mixin Type</h5></div></div></div><p>The Mixin Type is the interface that declares the Mixin methods. Each Mixin implementation (the classes defined in -the @Mixins annotation of a Composite declaration) implements one or more methods from one or more Mixin Types.</p><p>Mixin Type can be very simple, like;</p><pre class="programlisting brush: java">public interface BankAccount -{ - Money checkBalance(); -} -</pre><p>Or contain hundreds of methods, subclassed from dozens of super interfaces.</p><p>The Mixin Types of a Composite are ;</p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"> -all the aggregated interfaces of the Composite Type, minus Composite meta-type interfaces, and -</li><li class="listitem"> -all private mixin referenced types. -</li></ul></div><p>There is not a 1:1 correlation between Mixin Type and Mixin implementation. One canât even know if there are more or -less of one over the other. That is because a Mixin implementation can implement less than one, one, or more than one -Mixin Type.</p><p>It is also entirely possible that multiple implementation methods exists for a Mixin Type method. The mixin method -resolution algorithm will provide a deterministic behavior of which implementation of a method is chosen. The algorithm -is as follows;</p><p>For each declared method of all Mixin Types of a Composite;</p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"> -Iterate all Mixin types declared from left to right in the declaration, -</li><li class="listitem"> -Iterate all Mixin types of super-interfaces from left to right in the <span class="emphasis"><em>extends</em></span> clause, -</li><li class="listitem"> -Iterate all Mixin types within one interface before succeeding to the next interface, -</li><li class="listitem"> -Iterate all super-interface Mixin types before proceeding to the super-interfaces of those, -</li><li class="listitem"> -Iterate all Typed Mixin implementations of all super-interfaces, before repeating the algorithm for Generic Mixin - implementations, -</li></ul></div><p>This means that one Mixin implementation can <span class="emphasis"><em>override</em></span> a single method tha
<TRUNCATED>
