http://git-wip-us.apache.org/repos/asf/polygene-website/blob/ea4d77b0/content/java/latest/core-bootstrap-assembly.html ---------------------------------------------------------------------- diff --git a/content/java/latest/core-bootstrap-assembly.html b/content/java/latest/core-bootstrap-assembly.html deleted file mode 100644 index 90668ce..0000000 --- a/content/java/latest/core-bootstrap-assembly.html +++ /dev/null @@ -1,405 +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 Bootstrap</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-api.html" title="Core API" /><link rel="next" href="core-testsupport.html" title="Core Test Support" /> - - -<!-- 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"><a href="core-api.html">Core API</a></span></dt><dt><span class="section"><span xmlns="" href="core-bootstrap-assembly.html">Core Bootstrap</span></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 Bootstrap"><div class="titlepage"><div><div><h3 class="title"><a id="core-bootstrap-ass embly"></a>Core Bootstrap</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-brief">docs</p><p class="devstatus-tests-good">tests</p><p>Zest⢠has a distinct bootstrap phase, also known as the <span class="emphasis"><em>Assembly</em></span> of an application, where the applications structure -is defined programmatically. Once all the layers, modules and all the composite types in each module have been defined -the model is instantiated into an application. This enables the entire <span class="emphasis"><em>structure</em></span> system in Zest, where types "belongs" -to a module and visibility rules define default behaviors, enforcement of architectural integrity and much more.</p><p>The <span class="emphasis"><em>assembly</em></span> is preceeded by the creation of the <span class="emphasis"><em>Qi4j Runtime</em></span>. The <span class="emphasis"><em>assembly</em></span> can be declared fully by defining -all modules and layers, and how the layers are sitting on top of each other, OR one can utilize one of the two -convenience assemblies, one for a <span class="emphasis"><em>pancake</em></span> pattern, where all layers are top on each other, or one with a single module -in a single layer, useful for small applications, spikes and tests. The <code class="literal">bootstrap</code> system has several ways to acheive -this, and they are listed below in <a class="xref" href="core-bootstrap-assembly.html#core-bootstrap-assembly-layered" title="Layered Application Assembler (RECOMMENDED!)">Layered Application Assembler</a>.</p><p>During <span class="emphasis"><em>assembly</em></span>, the application (JVM level) architecture and the application model is defined. You define which -layers exist and how they relate to each other. For each layer, you define which modules it contains. And for each -module, you define which composites are in it, and what are the visibility rules for each of these composites.</p><p>You can also;</p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"> -Define default values for properties. -</li><li class="listitem"> -Add additional interfaces to composites dynamically. -</li><li class="listitem"> -Add concerns, mixins, constraints and side effects dynamically. -</li><li class="listitem"> -Set <span class="emphasis"><em>meta information</em></span> on defined types. -</li><li class="listitem"> -Import external services to be available as Zest⢠services. -</li><li class="listitem"> -Tag services with markers -</li></ul></div><div class="table"><a id="idm371058808416"></a><p class="title"><strong>Table 16. 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.bootstrap</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="Defining Objects"><div class="titlepage"><div><div><h4 class="title"><a id="_defining_objects"></a>Defining Objects</h4></div></div></div><pre class="programlisting brush: java">@Override -public void assemble( ModuleAssembly module ) - throws AssemblyException -{ - module.objects( MyObject.class ).visibleIn( Visibility.layer ); -} -</pre></div><div class="section" title="Defining Transients"><div class="titlepage"><div><div><h4 class="title"><a id="_defining_transients"></a>Defining Transients</h4></div></div></div><pre class="programlisting brush: java">@Override -public void assemble( ModuleAssembly module ) - throws AssemblyException -{ - module.transients( MyTransient.class ).visibleIn( Visibility.layer ); -} -</pre></div><div class="section" title="Defining Values"><div class="titlepage"><div><div><h4 class="title"><a id="_defining_values"></a>Defining Values</h4></div></div></div><pre class="programlisting brush: java">@Override -public void assemble( ModuleAssembly module ) - throws AssemblyException -{ - module.values( MyValue.class ).visibleIn( Visibility.layer ); -} -</pre></div><div class="section" title="Defining Entities"><div class="titlepage"><div><div><h4 class="title"><a id="_defining_entities"></a>Defining Entities</h4></div></div></div><pre class="programlisting brush: java">@Override -public void assemble( ModuleAssembly module ) - throws AssemblyException -{ - module.entities( MyEntity.class ).visibleIn( Visibility.layer ); -} -</pre></div><div class="section" title="Defining Services"><div class="titlepage"><div><div><h4 class="title"><a id="_defining_services"></a>Defining Services</h4></div></div></div><pre class="programlisting brush: java">@Override -public void assemble( ModuleAssembly module ) - throws AssemblyException -{ - module.services( MyService.class ).visibleIn( Visibility.layer ); -} -</pre><div class="section" title="Tagging Services"><div class="titlepage"><div><div><h5 class="title"><a id="_tagging_services"></a>Tagging Services</h5></div></div></div><pre class="programlisting brush: java">@Override -public void assemble( ModuleAssembly module ) - throws AssemblyException -{ - module.services( MyService.class ).taggedWith( "foo", "bar" ); -} -</pre></div><div class="section" title="Importing external Services"><div class="titlepage"><div><div><h5 class="title"><a id="_importing_external_services"></a>Importing external Services</h5></div></div></div><pre class="programlisting brush: java">@Override -public void assemble( ModuleAssembly module ) - throws AssemblyException -{ - module.importedServices( MyService.class ). - importedBy( InstanceImporter.class ). - setMetaInfo( new MyService() ); - - // OR - - module.objects( MyService.class ); - module.importedServices( MyService.class ). - importedBy( NewObjectImporter.class ); -} -</pre></div></div><div class="section" title="Defining default values for Properties"><div class="titlepage"><div><div><h4 class="title"><a id="_defining_default_values_for_properties"></a>Defining default values for Properties</h4></div></div></div><pre class="programlisting brush: java">@Override -public void assemble( ModuleAssembly module ) - throws AssemblyException -{ - module.values( MyValue.class ); - MyValue myValueDefaults = module.forMixin( MyValue.class ).declareDefaults(); - myValueDefaults.foo().set( "bar" ); - - module.entities( MyEntity.class ); - MyEntity myEntityDefaults = module.forMixin( MyEntity.class ).declareDefaults(); - myEntityDefaults.cathedral().set( "bazar" ); -} -</pre></div><div class="section" title="Adding additional interfaces to composites"><div class="titlepage"><div><div><h4 class="title"><a id="_adding_additional_interfaces_to_composites"></a>Adding additional interfaces to composites</h4></div></div></div></div><div class="section" title="Adding concerns, mixins, constraints and side effects"><div class="titlepage"><div><div><h4 class="title"><a id="_adding_concerns_mixins_constraints_and_side_effects"></a>Adding concerns, mixins, constraints and side effects</h4></div></div></div></div><div class="section" title="Setting meta information on assembled types"><div class="titlepage"><div><div><h4 class="title"><a id="_setting_meta_information_on_assembled_types"></a>Setting meta information on assembled types</h4></div></div></div></div><div class="section" title="Using Assemblers"><div class="titlepage"><div><div><h4 class="title"><a id="_using_assemblers"></a>Using Assemblers</h4></div></div></div><p>Many <a class="link" href="libra ries.html" title="Libraries">libraries</a> and <a class="link" href="extensions.html" title="Extensions">extensions</a> provides a cookie-cutter <span class="emphasis"><em>Assembler</em></span>, to simplify the set up -of such component. Often these are suitable, but sometimes they wonât fit the application in hand, in which case the -source code at least provides information of what is needed for the component to be used.</p><p>Assemblers are typically just instantiated and then call the assemble() method with the ModuleAssembly instance, -such as;</p><pre class="programlisting brush: java">@Override -public void assemble( ModuleAssembly module ) - throws AssemblyException -{ - RestServerAssembler assembler = new RestServerAssembler(); - assembler.assemble( module ); -} -</pre></div><div class="section" title="Defining an Entity Store"><div class="titlepage"><div><div><h4 class="title"><a id="_defining_an_entity_store"></a>Defining an Entity Store</h4></div></div></div><p>Defining an <span class="emphasis"><em>Entity Store</em></span> is in principle as simple as defining a ServiceComposite implementing the EntityStore -interface. The problem is that most Entity Stores require <a class="xref" href="core-api.html#core-api-service-configuration" title="Service Configuration">Service Configuration</a>, and configuration requires an -Entity Store. This chicken-and-egg problem is resolved by having an entity store available that does not require any -<a class="xref" href="core-api.html#core-api-service-configuration" title="Service Configuration">Service Configuration</a>. Many <span class="emphasis"><em>Assemblers</em></span> for entity store implementations uses the MemoryEntityStore, and -effectively leaves the configuration in the properties file where <a class="xref" href="core-api.html#core-api-service-configuration" title="Service Configuration">Service Configuration</a> bootstraps from. It is -possible to chain this, so that for instance the Neo4J Entity Store uses the Preferences Entity Store for its -configuration, and the Preferences Entity Store uses the Memory Entity Store (i.e. the properties file).</p><p>The point is that the entity store used for the configuration of the primary entity store used in the application is -that it must not be visible to the application itself. Sometimes it is easier to put a Memory Entity Store in the -same module, with Visibility set to <span class="emphasis"><em>module</em></span>. Sometimes it makes sense to have an additional Configuration layer below -the infrastructure layer, which has this setup.</p><p>As mentioned above, most entity stores defines a reasonable default <span class="emphasis"><em>Assembler</em></span>, possibly with some constructor -arguments or methods to define certain aspects. An example is the popular JdbmEntityStore, which <span class="emphasis"><em>Assembler</em></span> can be -used like;</p><pre class="programlisting brush: java">@Override -public void assemble( ModuleAssembly module ) - throws AssemblyException -{ - new JdbmEntityStoreAssembler().assemble( module ); -} -</pre></div><div class="section" title="Layered Application Assembler (RECOMMENDED!)"><div class="titlepage"><div><div><h4 class="title"><a id="core-bootstrap-assembly-layered"></a>Layered Application Assembler (RECOMMENDED!)</h4></div></div></div><p>In 2.1, a new way to instantiate Zest⢠applications was introduced. It starts with subclassing the -<code class="literal">LayeredApplicationAssembler</code>, and implementing the <code class="literal">assembleLayers()</code> method.</p><p>In the <code class="literal">assembleLayers()</code> method, one is epected to either call the <code class="literal">createLayer()</code> method in the super class -with the Class of the LayerAssembler,</p><pre class="programlisting brush: java"> LayerAssembly domainLayer = createLayer( DomainLayer.class );</pre><p>OR manually instantiate and call the LayerAssembler.</p><pre class="programlisting brush: java"> LayerAssembly infraLayer = new InfrastructureLayer( configModule ).assemble( assembly.layer( InfrastructureLayer.NAME ));</pre><p>This is to make the normal case as simple as possible, yet allow the special needs that occssionally surfaces.</p><p>Each LayerAssembler implementation may optionally extend the <code class="literal">LayeredLayerAssembler</code>, to get access to the -<code class="literal">createModule()</code> method, which again simplifies the creation of modules in the <code class="literal">assemble()</code> method.</p><pre class="programlisting brush: java"> createModule( layer, InvoicingModule.class );</pre><p><code class="literal">ModuleAssembler</code> implementations typically use <code class="literal">Assembler</code> classes to put together, or call the <code class="literal">entities()</code>, -<code class="literal">values()</code> methods described elsewhere on this page. There is no superclass to use.</p><p><code class="literal">ModuleAssembler</code> implementations should have a name ending with "Module" and the naming will insert a human-readable -space within the module name, e.g. <code class="literal">InvoicingModule</code> will be named "Invoicing Module".</p><p>For example code, see the tutorial <a class="xref" href="howto-assemble-application.html" title="Assemble an Application">Assemble an Application</a>.</p></div><div class="section" title="Singleton Assembler"><div class="titlepage"><div><div><h4 class="title"><a id="_singleton_assembler"></a>Singleton Assembler</h4></div></div></div><p>Every Zest⢠runtime instance consist of One Application, with one or more Layers and one or more Modules in each Layer. -So the minimal application is still one layer with one module. This is not recommended other than for testing purposes -and really trivial applications.</p><p>Letâs take a closer look at how it is put together.</p><pre class="programlisting brush: java">SingletonAssembler assembler = new SingletonAssembler() -{ - - @Override - public void assemble( ModuleAssembly module ) - throws AssemblyException - { - module.services( MyService.class ).identifiedBy( "Foo" ); - module.services( MyService.class ).identifiedBy( "Bar" ); - module.objects( Stuff.class ); - } - -}; -Module module = assembler.module(); -Stuff stuff = module.newObject( Stuff.class ); -</pre><p>Once the SingletonAssembler constructor returns, the Zest⢠application is up and running.</p><p>The SingletonAssembler also makes common system resources available from the bootstrap code, such as -Module, UnitOfWorkFactory and others. This is possible since there is only one Module.</p></div><div class="section" title="Application Builder"><div class="titlepage"><div><div><h4 class="title"><a id="_application_builder"></a>Application Builder</h4></div></div></div><p>Some applications has no need for runtime determination of the exact application structure, and no need for -advanced alterations to a staright-forward layered application structure. By using the <code class="literal">ApplicationBuilder</code> -it is possible to define the application structure from a JSON document, AND call the provided <code class="literal">main()</code> class, -taking the JSON document as input on <code class="literal">System.in</code>.</p><p>The format of the JSON document, directly reflects the application structure, such as</p><pre class="programlisting brush: json">{ - "name": "Build from JSON test.", - "layers": [ - { "name": "service", "uses": [ "domain", "config"] }, - { "name": "donfig" }, - { - "name": "domain", - "modules" : [ - { - "name" : "Invoicing", - "assemblers" : [ - "org.hedhman.niclas.bootstrap.InvoicingAssembler" - ] - } - ] - } - ] -}</pre><p>At the moment, the JSON format only support <code class="literal">Assembler</code> classes to do the work.</p><p>Another way to use the <code class="literal">ApplicationBuilder</code> is to subclass it, optionally use the <code class="literal">configureFromJSON()</code> method, -and then programmatically enhance the structure before calling <code class="literal">newApplication()</code>.</p></div><div class="section" title="Pancake Assembly"><div class="titlepage"><div><div><h4 class="title"><a id="_pancake_assembly"></a>Pancake Assembly</h4></div></div></div><p>There is one case that stands out as a common case, and forms a reasonable middle-ground. It is where each layer sits -exactly on top of each other layer, like pancakes. Each layer will only use the layer directly below and only that -layer. For this case we have a convenience setup. You create an Assembler[][][], where the outer-most array is each -layer, the middle array is the modules in each layer, and the last array is a set of assemblers needed to put the -things togather.</p><p>Letâs look at an example;</p><pre class="programlisting brush: java">public static void main( String[] args ) - throws Exception -{ - qi4j = new Energy4Java(); - Assembler[][][] assemblers = new Assembler[][][]{ - { // View Layer - { // Login Module - new LoginAssembler() - // : - }, - { // Main Workbench Module - new MenuAssembler(), - new PerspectivesAssembler(), - new ViewsAssembler() - // : - }, - { // Printing Module - new ReportingAssembler(), - new PdfAssembler() - // : - } - }, - { // Application Layer - { // Accounting Module - new BookkeepingAssembler(), - new CashFlowAssembler(), - new BalanceSheetAssembler() - // : - }, - { // Inventory Module - new PricingAssembler(), - new ProductAssembler() - // : - } - }, - { // Domain Layer - // : - }, - { // Infrastructure Layer - // : - } - }; - ApplicationDescriptor model = newApplication( assemblers ); - Application runtime = model.newInstance( qi4j.spi() ); - runtime.activate(); -} - -private static ApplicationDescriptor newApplication( final Assembler[][][] assemblers ) - throws AssemblyException -{ - return qi4j.newApplicationModel( new ApplicationAssembler() - { - - @Override - public ApplicationAssembly assemble( ApplicationAssemblyFactory appFactory ) - throws AssemblyException - { - return appFactory.newApplicationAssembly( assemblers ); - } - - } ); -} -</pre></div><div class="section" title="Full Assembly"><div class="titlepage"><div><div><h4 class="title"><a id="_full_assembly"></a>Full Assembly</h4></div></div></div><p>Full Assembly means that you have the opportunity to create any layer/module hierarchy that are within the rules of the -Zest⢠runtime. It requires more support in your code to be useful, and the example below is by no means a recommended way -to organize large application assemblies.</p><p>In principle, you first start the Zest⢠runtime, call newApplication with an ApplicationAssembler instance and call -activate() on the returned application. The ApplicationAssembler instance will be called with an -ApplicationAssemblyFactory, which is used to create an ApplicationAssembly describing the application structure.</p><pre class="programlisting brush: java">private static Energy4Java qi4j; - -private static Application application; - -public static void main( String[] args ) - throws Exception -{ - // Create a Zest Runtime - qi4j = new Energy4Java(); - application = qi4j.newApplication( new ApplicationAssembler() - { - - @Override - public ApplicationAssembly assemble( ApplicationAssemblyFactory appFactory ) - throws AssemblyException - { - ApplicationAssembly assembly = appFactory.newApplicationAssembly(); - buildAssembly( assembly ); - return assembly; - } - - } ); - // activate the application - application.activate(); -} - -static void buildAssembly( ApplicationAssembly app ) throws AssemblyException -{ - LayerAssembly webLayer = createWebLayer( app ); - LayerAssembly domainLayer = createDomainLayer( app ); - LayerAssembly persistenceLayer = createInfrastructureLayer( app ); - LayerAssembly authLayer = createAuth2Layer( app ); - LayerAssembly messagingLayer = createMessagingLayer( app ); - - webLayer.uses( domainLayer ); - domainLayer.uses( authLayer ); - domainLayer.uses( persistenceLayer ); - domainLayer.uses( messagingLayer ); -} - -static LayerAssembly createWebLayer( ApplicationAssembly app ) throws AssemblyException -{ - LayerAssembly layer = app.layer( "web-layer" ); - createCustomerWebModule( layer ); - return layer; -} - -static LayerAssembly createDomainLayer( ApplicationAssembly app ) throws AssemblyException -{ - LayerAssembly layer = app.layer( "domain-layer" ); - createCustomerDomainModule( layer ); - // : - // : - return layer; -} - -static LayerAssembly createInfrastructureLayer( ApplicationAssembly app ) throws AssemblyException -{ - LayerAssembly layer = app.layer( "infrastructure-layer" ); - createPersistenceModule( layer ); - return layer; -} - -static LayerAssembly createMessagingLayer( ApplicationAssembly app ) throws AssemblyException -{ - LayerAssembly layer = app.layer( "messaging-layer" ); - createWebServiceModule( layer ); - createMessagingPersistenceModule( layer ); - return layer; -} - -static LayerAssembly createAuth2Layer( ApplicationAssembly application ) throws AssemblyException -{ - LayerAssembly layer = application.layer( "auth2-layer" ); - createAuthModule( layer ); - return layer; -} - -static void createCustomerWebModule( LayerAssembly layer ) throws AssemblyException -{ - ModuleAssembly assembly = layer.module( "customer-web-module" ); - assembly.transients( CustomerViewComposite.class, CustomerEditComposite.class, - CustomerListViewComposite.class, CustomerSearchComposite.class ); -} - -static void createCustomerDomainModule( LayerAssembly layer ) throws AssemblyException -{ - ModuleAssembly assembly = layer.module( "customer-domain-module" ); - assembly.entities( CustomerEntity.class, CountryEntity.class ); - assembly.values( AddressValue.class ); -} - -static void createAuthModule( LayerAssembly layer ) throws AssemblyException -{ - ModuleAssembly assembly = layer.module( "auth-module" ); - new LdapAuthenticationAssembler().assemble( assembly ); - new ThrinkAuthorizationAssembler().assemble( assembly ); - new UserTrackingAuditAssembler().assemble( assembly ); -} - -static void createPersistenceModule( LayerAssembly layer ) throws AssemblyException -{ - ModuleAssembly assembly = layer.module( "persistence-module" ); - // Someone has created an assembler for the Neo EntityStore - new NeoAssembler( "./neostore" ).assemble( assembly ); -} - -</pre></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
http://git-wip-us.apache.org/repos/asf/polygene-website/blob/ea4d77b0/content/java/latest/core-functional.html ---------------------------------------------------------------------- diff --git a/content/java/latest/core-functional.html b/content/java/latest/core-functional.html deleted file mode 100644 index 87f162b..0000000 --- a/content/java/latest/core-functional.html +++ /dev/null @@ -1,106 +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 Functional 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-testsupport.html" title="Core Test Support" /><link rel="next" href="core-io.html" title="Core I/O API" /> - - -<!-- 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"><a href="core-api.html">Core API</a></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"><span xmlns="" href="core-functional.html">Core Functional API</span></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 Functional API"><div class="titlepage"><div><div><h3 class="title"><a id="core-function al"></a>Core Functional API</h3></div></div></div><p class="remark"><em><span class="comment"></span></em></p><p class="devstatus-code-beta">code</p><p class="devstatus-docs-good">docs</p><p class="devstatus-tests-good">tests</p><p>The Zest⢠Core Functional API is a generic package to work with Iterables in a "functional programming language" style.</p><p>This package is completely independent of everything else in Zest⢠and may be used on its own in any kind of environment -such as Spring or Java EE applications.</p><div class="table"><a id="idm371092057360"></a><p class="title"><strong>Table 18. 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.functional</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="First Example"><div class="titlepage"><div><div><h4 class="title"><a id="_first_example"></a>First Example</h4></div></div></div><p>Letâs say that you have an Iterable of Integers and you want to sum them all up. Most people would create a loop and -sum it all up in something like this;</p><pre class="programlisting brush: java">Iterable<Long> data = new ArrayList<Long>(); - [...snip...] - - -long sum = 0; -for( Long point : data ) -{ - sum = sum + point; -} -System.out.println( "The sum is " + sum ); -</pre><p>With the Zest⢠Core Functional API, you go about it in a different way. The code ends up looking like this;</p><pre class="programlisting brush: java">import static org.qi4j.functional.ForEach.forEach; -import static org.qi4j.functional.Functions.longSum; - [...snip...] - - Iterable<Number> data = new ArrayList<Number>(); - Long sum = forEach( data ).map( longSum() ).last(); - System.out.println( "The sum is " + sum ); - -</pre><p>And this is just the tip of the iceberg.</p></div><div class="section" title="The Big Picture"><div class="titlepage"><div><div><h4 class="title"><a id="_the_big_picture"></a>The Big Picture</h4></div></div></div><p>The Zest⢠Core Functional API are divided a handful of powerful concepts, especially when used together;</p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"> -<span class="strong"><strong>Iterables</strong></span> - many methods to deal with Iterable data, so that the loops in your programs can largely be removed. -</li><li class="listitem"> -<span class="strong"><strong>Functions</strong></span> - f(x) and f(x,y) are well-know from mathematics and used in functional programming languages. Zest⢠is - not capable of introducing lambda calculus due to limitations in Java itself, but we can simulate a lot to allow - people to create more readable code. -</li><li class="listitem"> -<span class="strong"><strong>Specification</strong></span> - A simple concept to define the bounds of data. This is used for filtering, query and many other - higher level abstractions. -</li><li class="listitem"> -<span class="strong"><strong>Visitor</strong></span> pattern - A way to be handed the items in a collection, without having the loops. This could be for - end result handling, distribution of intermediary values, and many other things. -</li></ul></div></div><div class="section" title="Specification"><div class="titlepage"><div><div><h4 class="title"><a id="_specification"></a>Specification</h4></div></div></div><p>TODO</p></div><div class="section" title="Function"><div class="titlepage"><div><div><h4 class="title"><a id="_function"></a>Function</h4></div></div></div><p>TODO</p></div><div class="section" title="Visitor Pattern"><div class="titlepage"><div><div><h4 class="title"><a id="_visitor_pattern"></a>Visitor Pattern</h4></div></div></div><p>TODO</p></div><div class="section" title="Iterables"><div class="titlepage"><div><div><h4 class="title"><a id="_iterables"></a>Iterables</h4></div></div></div><p>TODO</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 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 http://git-wip-us.apache.org/repos/asf/polygene-website/blob/ea4d77b0/content/java/latest/core-io.html ---------------------------------------------------------------------- diff --git a/content/java/latest/core-io.html b/content/java/latest/core-io.html deleted file mode 100644 index 134a857..0000000 --- a/content/java/latest/core-io.html +++ /dev/null @@ -1,503 +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 I/O 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-functional.html" title="Core Functional API" /><link rel="next" href="core-spi.html" title="Core Extension SPI" /> - - -<!-- 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"><a href="core-api.html">Core API</a></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"><span xmlns="" href="core-io.html">Core I/O API</span></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 I/O API"><div class="titlepage"><div><div><h3 class="title"><a id="core-io"></a>Core I/ O API</h3></div></div></div><p class="remark"><em><span class="comment"></span></em></p><p class="devstatus-code-beta">code</p><p class="devstatus-docs-good">docs</p><p class="devstatus-tests-good">tests</p><p>The Zest⢠Core I/O API is completely generic and not tied to the Zest⢠programming model as a whole. It can be used -independently of Zest, together with the Zest⢠Core Functional API, which the Core I/O API depends on.</p><p>The Zest⢠Core I/O API tries to address the problem around shuffling data around from various I/O inputs and outputs, -possibly with transformations and filtering along the way. It was identified that there is a general mix-up of concerns -in the stereotypical I/O handling codebases that people deal with all the time. The reasoning around this, can be found -in the <a class="xref" href="howto-use-io.html" title="Use I/O API">Use I/O API</a>, and is recommended reading.</p><div class="table"><a id="idm371116472912"></a><p class="title"><strong>Table 19. 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.io</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="The Problem"><div class="titlepage"><div><div><h4 class="title"><a id="_the_problem"></a>The Problem</h4></div></div></div><p>Why does I/O operations in Java have to be so complicated, with nested try/catch/finally a nd loops? Donât you wish -that the operations could be expressed in a more natural way, such as;</p><pre class="programlisting brush: java">File source = ... -File destination = ... -source.copyTo( destination );</pre><p>It seems natural to do, yet it is not present for us. We need to involve FileInputStream/FileOutputStream, wrap them -in Buffered versions of it, do our own looping, close the streams afterwards and what not. So, the java.io.File does -not have this simple feature and in the Zest⢠Core API, we need to work around this limitation. We also want to -make the abstraction a little bit more encompassing than "just" files. So how does that look like then?</p></div><div class="section" title="First Examples"><div class="titlepage"><div><div><h4 class="title"><a id="_first_examples"></a>First Examples</h4></div></div></div><p>The most common inputs and outputs are collected in the org.qi4j.io.Inputs and org.qi4j.io.Outputs classes as static -factory methods, but you can create your (more about that later).</p><p>So, we want to read a text file and write the content into another text file, right? This is how it is done;</p><pre class="programlisting brush: java">File source = new File( "source.txt" ); -File destination = new File( "destination.txt" ); -Inputs.text( source ).transferTo( Outputs.text( destination ) ); -</pre><p>Pretty much self-explanatory, wouldnât you say? But what happened to the handling of exceptions and closing of -resources? It is all handled inside the Zest⢠Core I/O API. There is nothing you can forget to do.</p><p>Another simple example, where we want to count the number of lines in the text;</p><pre class="programlisting brush: java">import org.qi4j.io.Transforms.Counter; -import static org.qi4j.io.Transforms.map; - [...snip...] - - File source = new File( "source.txt" ); - File destination = new File( "destination.txt" ); - Counter<String> counter = new Counter<String>(); - Inputs.text( source ).transferTo( map(counter, Outputs.text(destination) )); - System.out.println( "Lines: " + counter.count() ); -</pre><p>The Counter is a <a class="xref" href="core-functional.html" title="Core Functional API">Function</a> which gets injected into the transfer.</p></div><div class="section" title="The 3 Parts"><div class="titlepage"><div><div><h4 class="title"><a id="_the_3_parts"></a>The 3 Parts</h4></div></div></div><p>Ok, so we have seen that the end result can become pretty compelling. How does it work?</p><p>I/O is defined as a process of moving data from an Input, via one or more Transforms to an Output. The Input could -be a File or a String, the transformation could be a filter, conversion or a function and finally the Output -destination could be a File, String or an OutputStream. It is important to note that there is a strong separation of -concern between them. Letâs look at the on at a time.</p></div><div class="section" title="org.qi4j.io.Input"><div class="titlepage"><div><div><h4 class="title"><a id="_org_qi4j_io_input"></a>org.qi4j.io.Input</h4></div></div></div><p>This interface simply has a transferTo() method, which takes an Output. The formal definition is;</p><pre class="programlisting brush: java">public interface Input<T, SenderThrowableType extends Throwable> -{ - <ReceiverThrowableType extends Throwable> void transferTo( Output<? super T, ReceiverThrowableType> output ) - throws SenderThrowableType, ReceiverThrowableType; -} -</pre><p>What on earth is all this genericized Exceptions? Well, it abstracts away the explicit Exception that implementations -may throw (or not). So instead of demanding that all I/O must throw the java.io.IOException, as is the case in the -JDK classes, it is up to the implementation to declare what it may throw. That is found in the SenderThrowable generic -of the interface.</p><p>But hold on a second. Why is an Input throwing a "sender" exception? Well, think again. The Input is feeding "something" -with data. It takes it from some source and "sends it" to the downstream chain, eventually reaching an Output, which -likewise is the ultimate "receiver".</p><p>So, then, the method transferTo() contains the declaration of the downstream receiverâs possible Exception -(ReceiverThrowable) which the transferTo() method may also throw as the data may not be accepted and such exception -will bubble up to the transferTo() method (the clientâs view of the transfer).</p></div><div class="section" title="org.qi4j.io.Output"><div class="titlepage"><div><div><h4 class="title"><a id="_org_qi4j_io_output"></a>org.qi4j.io.Output</h4></div></div></div><p>The output interface is likewise fairly simple;</p><pre class="programlisting brush: java">public interface Output<T, ReceiverThrowableType extends Throwable> -{ - [...snip...] - - <SenderThrowableType extends Throwable> void receiveFrom( Sender<? extends T, SenderThrowableType> sender ) - throws ReceiverThrowableType, SenderThrowableType; -} -</pre><p>It can simply receive data from a org.qi4j.io.Sender.</p><p>Hey, hold on! Why is it not receiving from an Input? Because the Input is the clientâs entry point and of no use to -the Output as such. Instead, the Output will tell the Sender (which is handed to from the Input or an transformation) -to which Receiver the content should be sent to.</p><p>Complicated? Perhaps not trivial to get your head around it at first, but the chain is;</p><p>Input passes a Sender to the Output which tells the Sender which Receiver the data should be sent to.</p><p>The reason for this is that we need to separate the concerns properly. Input is a starting point, but it emits something -which is represented by the Sender. Likewise the destination is an Output, but it receives the data via its Receiver -interface. For O/S resources, they are handled purely inside the Input and Output implementations, where are the -Sender/Receiver are effectively dealing with the data itself.</p></div><div class="section" title="org.qi4j.io.Transforms"><div class="titlepage"><div><div><h4 class="title"><a id="_org_qi4j_io_transforms"></a>org.qi4j.io.Transforms</h4></div></div></div><p>The 3 component in the Zest⢠Core I/O API is the transformations that are possible. Interestingly enough, with the -above separation of concerns, we donât need an InputOutput type that can both receive and send data. Instead, we -simply need to prepare easy to use static factory methods, which are found in the org.qi4j.io.Transforms class. Again, -it is fairly straight forward to create your own Transforms if you need something not provided here.</p><p>The current transformations available are;</p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"> -filter - takes a Specification and only forwards data items conforming to the Specification. -</li><li class="listitem"> -map - takes a org.qi4j.functional.Function to convert an item from one type to (potentially) another, and any - possible change along the way. -</li><li class="listitem"> -filteredMap - is a combination of a filter and a map. If the Specification is satisfied, the map function is - applied, otherwise the item is passed through unaffected. -</li><li class="listitem"> -lock - A wrapper which protects the Input or Output from simultaneous access. Not a transformation by itself, - but implemented in the same fashion. -</li></ul></div><p>There are also a couple of handy map functions available, such as</p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"> -Log -</li><li class="listitem"> -ProgressLog -</li><li class="listitem"> -Counter -</li><li class="listitem"> -ByteBuffer2String -</li><li class="listitem"> -Object2String -</li><li class="listitem"> -String2Bytes -</li></ul></div></div><div class="section" title="Writing a Map Function?"><div class="titlepage"><div><div><h4 class="title"><a id="_writing_a_map_function"></a>Writing a Map Function?</h4></div></div></div><p>Let us take a closer look at the implementation of a map function, namely Counter mentioned above and also used in -the section First Example above.</p><p>The implementation is very straight forward.</p><pre class="programlisting brush: java">public static class Counter<T> - implements Function<T, T> -{ - private volatile long count = 0; - - public long count() - { - return count; - } - - @Override - public T map( T t ) - { - count++; - return t; - } -} -</pre><p>On each call to the map() method, increment the counter field. The client can then retrieve that value after the -transfer is complete, or in a separate thread to show progress.</p><p>Speaking of "progress", so how is the ProgressLog implemented? Glad you asked;</p><pre class="programlisting brush: java">public static class ProgressLog<T> - implements Function<T, T> -{ - private Counter<T> counter; - private Log<String> log; - private final long interval; - - public ProgressLog( Logger logger, String format, long interval ) - { - this.interval = interval; - if( logger != null && format != null ) - { - log = new Log<>( logger, format ); - } - counter = new Counter<>(); - } - - public ProgressLog( long interval ) - { - this.interval = interval; - counter = new Counter<>(); - } - - @Override - public T map( T t ) - { - counter.map( t ); - if( counter.count % interval == 0 ) - { - logProgress(); - } - return t; - } - - // Override this to do something other than logging the progress - protected void logProgress() - { - if( log != null ) - { - log.map( counter.count + "" ); - } - } -} -</pre><p>It combines the Counter and the Log implementations, so that the count is forwarded to the Log at a given interval, such -as every 1000 items. This may not be what you think a ProgressLog should look like, but it serves as a good example on -how you can combine the general principles found in the Zest⢠Core API package.</p></div><div class="section" title="How to write a filter specification?"><div class="titlepage"><div><div><h4 class="title"><a id="_how_to_write_a_filter_specification"></a>How to write a filter specification?</h4></div></div></div><p>The filter transform takes a specification implementation which has a very simple method, isSatisfiedBy() (read more -about that in <a class="xref" href="core-functional.html" title="Core Functional API">Function</a>.</p><pre class="programlisting brush: java">public interface Specification<T> -{ - [...snip...] - - boolean satisfiedBy( T item ); -} -</pre><p>The only thing that the implementation need to do is return <span class="strong"><strong>true</strong></span> or <span class="strong"><strong>false</strong></span> for whether the item passed in is within -the limits of the Specification. Letâs say that you have a IntegerRangeSpecification, which could then be implemented -as</p><pre class="programlisting brush: java">public static class IntegerRangeSpecification - implements Specification<Integer> -{ - - private int lower; - private int higher; - - public IntegerRangeSpecification( int lower, int higher ) - { - this.lower = lower; - this.higher = higher; - } - - @Override - public boolean satisfiedBy( Integer item ) - { - return item >= lower && item <= higher; - } -} -</pre></div><div class="section" title="Ready-to-use components"><div class="titlepage"><div><div><h4 class="title"><a id="_ready_to_use_components"></a>Ready-to-use components</h4></div></div></div><p>Input and Output implementations at first glance look quite scary. Taking a closer look and it can be followed. But to -simplify for users, the org.qi4j.io.Inputs and org.qi4h.io.Outputs contains static factory methods for many useful -sources and destinations.</p></div><div class="section" title="org.qi4j.io.Inputs"><div class="titlepage"><div><div><h4 class="title"><a id="_org_qi4j_io_inputs"></a>org.qi4j.io.Inputs</h4></div></div></div><p>The current set of ready-to-use Input implementations are;</p><pre class="programlisting brush: java"> -/** - * Read lines from a String. - * - * @param source lines - * - * @return Input that provides lines from the string as strings - */ -public static Input<String, RuntimeException> text( final String source ) - [...snip...] - - -/** - * Read lines from a Reader. - * - * @param source lines - * - * @return Input that provides lines from the string as strings - */ -public static Input<String, RuntimeException> text( final Reader source ) - [...snip...] - - -/** - * Read lines from a UTF-8 encoded textfile. - * - * If the filename ends with .gz, then the data is automatically unzipped when read. - * - * @param source textfile with lines separated by \n character - * - * @return Input that provides lines from the textfiles as strings - */ -public static Input<String, IOException> text( final File source ) - [...snip...] - - -/** - * Read lines from a textfile with the given encoding. - * - * If the filename ends with .gz, then the data is automatically unzipped when read. - * - * @param source textfile with lines separated by \n character - * @param encoding encoding of file, e.g. "UTF-8" - * - * @return Input that provides lines from the textfiles as strings - */ -public static Input<String, IOException> text( final File source, final String encoding ) - [...snip...] - - -/** - * Read lines from a textfile at a given URL. - * - * If the content support gzip encoding, then the data is automatically unzipped when read. - * - * The charset in the content-type of the URL will be used for parsing. Default is UTF-8. - * - * @param source textfile with lines separated by \n character - * - * @return Input that provides lines from the textfiles as strings - */ -public static Input<String, IOException> text( final URL source ) - [...snip...] - - -/** - * Read a file using ByteBuffer of a given size. Useful for transferring raw data. - * - * @param source The file to be read. - * @param bufferSize The size of the byte array. - * - * @return An Input instance to be applied to streaming operations. - */ -public static Input<ByteBuffer, IOException> byteBuffer( final File source, final int bufferSize ) - [...snip...] - - -/** - * Read an inputstream using ByteBuffer of a given size. - * - * @param source The InputStream to be read. - * @param bufferSize The size of the byte array. - * - * @return An Input instance to be applied to streaming operations. - */ -public static Input<ByteBuffer, IOException> byteBuffer( final InputStream source, final int bufferSize ) - [...snip...] - - -/** - * Combine many Input into one single Input. When a transfer is initiated from it all items from all inputs will be transferred - * to the given Output. - * - * @param inputs An Iterable of Input instances to be combined. - * @param <T> The item type of the Input - * @param <SenderThrowableType> The Throwable that might be thrown by the Inputs. - * - * @return A combined Input, allowing for easy aggregation of many Input sources. - */ -public static <T, SenderThrowableType extends Throwable> Input<T, SenderThrowableType> combine( final Iterable<Input<T, SenderThrowableType>> inputs ) - [...snip...] - - -/** - * Create an Input that takes its items from the given Iterable. - * - * @param iterable The Iterable to be used as an Input. - * @param <T> The item type of the Input - * - * @return An Input instance that is backed by the Iterable. - */ -public static <T> Input<T, RuntimeException> iterable( final Iterable<T> iterable ) - [...snip...] - - -/** - * Create an Input that allows a Visitor to write to an OutputStream. The stream is a BufferedOutputStream, so when enough - * data has been gathered it will send this in chunks of the given size to the Output it is transferred to. The Visitor does not have to call - * close() on the OutputStream, but should ensure that any wrapper streams or writers are flushed so that all data is sent. - * - * @param outputVisitor The OutputStream Visitor that will be backing the Input ByteBuffer. - * @param bufferSize The buffering size. - * - * @return An Input instance of ByteBuffer, that is backed by an Visitor to an OutputStream. - */ -public static Input<ByteBuffer, IOException> output( final Visitor<OutputStream, IOException> outputVisitor, - final int bufferSize -) -</pre></div><div class="section" title="org.qi4j.io.Outputs"><div class="titlepage"><div><div><h4 class="title"><a id="_org_qi4j_io_outputs"></a>org.qi4j.io.Outputs</h4></div></div></div><p>The current set of ready-to-use Input implementations are;</p><pre class="programlisting brush: java"> -/** - * Write lines to a text file with UTF-8 encoding. Separate each line with a newline ("\n" character). If the writing or sending fails, - * the file is deleted. - * <p> - * If the filename ends with .gz, then the data is automatically GZipped. - * </p> - * @param file the file to save the text to - * - * @return an Output for storing text in a file - */ -public static Output<String, IOException> text( final File file ) - [...snip...] - - -/** - * Write lines to a text file. Separate each line with a newline ("\n" character). If the writing or sending fails, - * the file is deleted. - * <p> - * If the filename ends with .gz, then the data is automatically GZipped. - * </p> - * @param file the file to save the text to - * - * @return an Output for storing text in a file - */ -public static Output<String, IOException> text( final File file, final String encoding ) - [...snip...] - - -/** - * Write lines to a Writer. Separate each line with a newline ("\n" character). - * - * @param writer the Writer to write the text to - * @return an Output for storing text in a Writer - */ -public static Output<String, IOException> text( final Writer writer ) - [...snip...] - - -/** - * Write lines to a StringBuilder. Separate each line with a newline ("\n" character). - * - * @param builder the StringBuilder to append the text to - * @return an Output for storing text in a StringBuilder - */ -public static Output<String, IOException> text( final StringBuilder builder ) - [...snip...] - - -/** - * Write ByteBuffer data to a file. If the writing or sending of data fails the file will be deleted. - * - * @param file The destination file. - * - * @return The Output ByteBuffer instance backed by a File. - */ -public static Output<ByteBuffer, IOException> byteBuffer( final File file ) - [...snip...] - - -/** - * Write ByteBuffer data to an OutputStream. - * - * @param stream Destination OutputStream - * - * @return The Output of ByteBuffer that will be backed by the OutputStream. - */ -public static Output<ByteBuffer, IOException> byteBuffer( final OutputStream stream ) - [...snip...] - - -/** - * Write byte array data to a file. If the writing or sending of data fails the file will be deleted. - * - * @param file The File to be written to. - * @param bufferSize The size of the ByteBuffer. - * - * @return An Output instance that will write to the given File. - */ -public static Output<byte[], IOException> bytes( final File file, final int bufferSize ) - [...snip...] - - -/** - * Do nothing. Use this if you have all logic in filters and/or specifications - * - * @param <T> The item type. - * - * @return An Output instance that ignores all data. - */ -public static <T> Output<T, RuntimeException> noop() - [...snip...] - - -/** - * Use given receiver as Output. Use this if there is no need to create a "transaction" for each transfer, and no need - * to do batch writes or similar. - * - * @param <T> The item type - * @param receiver receiver for this Output - * - * @return An Output instance backed by a Receiver of items. - */ -public static <T, ReceiverThrowableType extends Throwable> Output<T, ReceiverThrowableType> withReceiver( final Receiver<T, ReceiverThrowableType> receiver ) - [...snip...] - - -/** - * Write objects to System.out.println. - * - * @return An Output instance that is backed by System.out - */ -public static Output<Object, RuntimeException> systemOut() - [...snip...] - - -/** - * Write objects to System.err.println. - * - * @return An Output instance backed by System.in - */ -@SuppressWarnings( "UnusedDeclaration" ) -public static Output<Object, RuntimeException> systemErr() - [...snip...] - - -/** - * Add items to a collection - */ -public static <T> Output<T, RuntimeException> collection( final Collection<T> collection ) -</pre></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 http://git-wip-us.apache.org/repos/asf/polygene-website/blob/ea4d77b0/content/java/latest/core-runtime.html ---------------------------------------------------------------------- diff --git a/content/java/latest/core-runtime.html b/content/java/latest/core-runtime.html deleted file mode 100644 index 77d3d88..0000000 --- a/content/java/latest/core-runtime.html +++ /dev/null @@ -1,77 +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 Runtime</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-spi.html" title="Core Extension SPI" /><link rel="next" href="libraries.html" title="Libraries" /> - - -<!-- 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"><a href="core-api.html">Core API</a></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"><span xmlns="" href="core-runtime.html">Core Runtime</span></span></dt></dl></div></div><div class="section" title="Core Runtime"><div class="titlepage"><div><div><h3 class="title"><a id="core-runtime"></a>Co re Runtime</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-brief">docs</p><p class="devstatus-tests-good">tests</p><p>First of all, your code should never, ever, have a dependency on Core Runtime. If you think you need this, you should -probably contact qi4j-dev forum at Google Groups and see if your usecase can either be solved in a existing way or perhaps -that a new Core SPI Extension is needed.</p><div class="table"><a id="idm371116328624"></a><p class="title"><strong>Table 21. 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.runtime</p></td><td align="left" valign="top"><p>2.1</p></td></tr></tbody></table></div></div><br class="table-break" /><p>Letâs repeat that; <span class="strong"><strong>Never, never, ever depend on Core Runtime</strong></span>. Make sure that the compile dependency does NOT include -the <code class="literal">org.qi4j.core.runtime</code> jar.</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 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
