Core Bootstrap

code

docs

tests

Polygene™ has a distinct bootstrap phase, also known as the Assembly 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 structure system in Polygene, where types "belongs" to a module and visibility rules define default behaviors, enforcement of architectural integrity and much more.

The assembly is preceeded by the creation of the Polygene Runtime. The assembly can be declared fully by defining @@ -75,7 +75,7 @@ convenience assemblies, one for a pancake in a single layer, useful for small applications, spikes and tests. The bootstrap system has several ways to acheive this, and they are listed below in Layered Application Assembler.

During assembly, 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.

You can also;

+module, you define which composites are in it, and what are the visibility rules for each of these composites.

You can also;

Define default values for properties.
Add additional interfaces to composites dynamically. @@ -87,60 +87,23 @@ Set meta information on defined types. Import external services to be available as Polygene™ services.
Tag services with markers -

Table 15. Artifact

Group ID	Artifact ID	Version
org.apache.polygene.core	org.apache.polygene.core.bootstrap	3.0.0-SNAPSHOT

Defining Objects

@Override
-public void assemble( ModuleAssembly module )
-        throws AssemblyException
-{
-    module.objects( MyObject.class ).visibleIn( Visibility.layer );
-}
-

Defining Transients

@Override
-public void assemble( ModuleAssembly module )
-        throws AssemblyException
-{
-    module.transients( MyTransient.class ).visibleIn( Visibility.layer );
-}
-

Defining Values

@Override
-public void assemble( ModuleAssembly module )
-        throws AssemblyException
-{
-    module.values( MyValue.class ).visibleIn( Visibility.layer );
-}
-

Defining Entities

@Override
-public void assemble( ModuleAssembly module )
-        throws AssemblyException
-{
-    module.entities( MyEntity.class ).visibleIn( Visibility.layer );
-}
-

Defining Services

@Override
-public void assemble( ModuleAssembly module )
-        throws AssemblyException
-{
-    module.services( MyService.class ).visibleIn( Visibility.layer );
-}
-

Tagging Services

@Override
-public void assemble( ModuleAssembly module )
-    throws AssemblyException
-{
-    module.services( MyService.class ).taggedWith( "foo", "bar" );
-}
-

Importing external Services

@Override
-public void assemble( ModuleAssembly module )
-    throws AssemblyException
-{
-    module.importedServices( MyService.class ).
-        importedBy( InstanceImporter.class ).
-        setMetaInfo( new MyService() );
-
-    // OR
-
+

Table 15. Artifact

Group ID	Artifact ID	Version
org.apache.polygene.core	org.apache.polygene.core.bootstrap	3.1.0-SNAPSHOT

Defining Objects

( ModuleAssembly module ) -> module.objects( MyObject.class ).visibleIn( Visibility.layer )
+

Defining Transients

( ModuleAssembly module ) -> module.transients( MyTransient.class ).visibleIn( Visibility.layer )
+

Defining Values

( ModuleAssembly module ) -> module.values( MyValue.class ).visibleIn( Visibility.layer )
+

Defining Entities

( ModuleAssembly module ) -> module.entities( MyEntity.class ).visibleIn( Visibility.layer )
+

Defining Services

( ModuleAssembly module ) -> module.services( MyService.class ).visibleIn( Visibility.layer )
+

Tagging Services

( ModuleAssembly module ) -> module.services( MyService.class ).taggedWith( "foo", "bar" )
+

Importing external Services

( ModuleAssembly module ) -> module.importedServices( MyService.class )
+                                   .importedBy( InstanceImporter.class )
+                                   .setMetaInfo( new MyService() ),
+
+// OR
+
+( ModuleAssembly module ) -> {
     module.objects( MyService.class );
-    module.importedServices( MyService.class ).
-        importedBy( NewObjectImporter.class );
+    module.importedServices( MyService.class ).importedBy( NewObjectImporter.class );
 }
-

Defining default values for Properties

@Override
-public void assemble( ModuleAssembly module )
-    throws AssemblyException
-{
+

Defining default values for Properties

( ModuleAssembly module ) -> {
     module.values( MyValue.class );
     MyValue myValueDefaults = module.forMixin( MyValue.class ).declareDefaults();
     myValueDefaults.foo().set( "bar" );
@@ -149,7 +112,7 @@ public void assemble( ModuleAssembly module )
     MyEntity myEntityDefaults = module.forMixin( MyEntity.class ).declareDefaults();
     myEntityDefaults.cathedral().set( "bazar" );
 }
-

Adding additional interfaces to composites

Adding concerns, mixins, constraints and side effects

Setting meta information on assembled types

Using Assemblers

Many libraries and extensions provides a cookie-cutter Assembler, to simplify the set up +

Adding additional interfaces to composites

Adding concerns, mixins, constraints and side effects

Setting meta information on assembled types

Using Assemblers

Many libraries and extensions provides a cookie-cutter Assembler, 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.

Assemblers are typically just instantiated and then call the assemble() method with the ModuleAssembly instance, such as;

@Override
@@ -159,7 +122,7 @@ public void assemble( ModuleAssembly module )
     RestServerAssembler assembler = new RestServerAssembler();
     assembler.assemble( module );
 }
-

Defining an Entity Store

Defining an Entity Store is in principle as simple as defining a ServiceComposite implementing the EntityStore +

Defining an Entity Store

Defining an Entity Store is in principle as simple as defining a ServiceComposite implementing the EntityStore interface. The problem is that most Entity Stores require Service Configuration, and configuration requires an Entity Store. This chicken-and-egg problem is resolved by having an entity store available that does not require any Service Configuration. Many Assemblers for entity store implementations uses the MemoryEntityStore, and @@ -176,30 +139,24 @@ public void assemble( ModuleAssembly module ) { new JdbmEntityStoreAssembler().assemble( module ); } -

Layered Application Assembler (RECOMMENDED!)

In 2.1, a new way to instantiate Polygene™ applications was introduced. It starts with subclassing the +

Layered Application Assembler (RECOMMENDED!)

In 2.1, a new way to instantiate Polygene™ applications was introduced. It starts with subclassing the LayeredApplicationAssembler, and implementing the assembleLayers() method.

In the assembleLayers() method, one is epected to either call the createLayer() method in the super class with the Class of the LayerAssembler,

    LayerAssembly domainLayer = createLayer( DomainLayer.class );

OR manually instantiate and call the LayerAssembler.

    LayerAssembly infraLayer = new InfrastructureLayer( configModule ).assemble( assembly.layer( InfrastructureLayer.NAME  ));

This is to make the normal case as simple as possible, yet allow the special needs that occssionally surfaces.

Each LayerAssembler implementation may optionally extend the LayeredLayerAssembler, to get access to the createModule() method, which again simplifies the creation of modules in the assemble() method.

    createModule( layer, InvoicingModule.class );

ModuleAssembler implementations typically use Assembler classes to put together, or call the entities(), values() methods described elsewhere on this page. There is no superclass to use.

ModuleAssembler implementations should have a name ending with "Module" and the naming will insert a human-readable -space within the module name, e.g. InvoicingModule will be named "Invoicing Module".

For example code, see the tutorial Assemble an Application.

Singleton Assembler

Every Polygene™ runtime instance consist of One Application, with one or more Layers and one or more Modules in each Layer. +space within the module name, e.g. InvoicingModule will be named "Invoicing Module".

For example code, see the tutorial Assemble an Application.

Singleton Assembler

Every Polygene™ 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.

Let’s take a closer look at how it is put together.

SingletonAssembler assembler = new SingletonAssembler()
-{
-
-    @Override
-    public void assemble( ModuleAssembly module )
-            throws AssemblyException
-    {
+and really trivial applications.
Let’s take a closer look at how it is put together.
SingletonAssembler assembler = new SingletonAssembler(
+    module -> {
         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 );
 
Once the SingletonAssembler constructor returns, the Polygene™ application is up and running.
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.

Application Builder

Some applications has no need for runtime determination of the exact application structure, and no need for +Module, UnitOfWorkFactory and others. This is possible since there is only one Module.

Application Builder

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 ApplicationBuilder it is possible to define the application structure from a JSON document, AND call the provided main() class, taking the JSON document as input on System.in.

The format of the JSON document, directly reflects the application structure, such as

{
@@ -220,50 +177,50 @@ taking the JSON document as input on System.in.
         }
     ]
 }

At the moment, the JSON format only support Assembler classes to do the work.

Another way to use the ApplicationBuilder is to subclass it, optionally use the configureFromJSON() method, -and then programmatically enhance the structure before calling newApplication().

Pancake Assembly

There is one case that stands out as a common case, and forms a reasonable middle-ground. It is where each layer sits +and then programmatically enhance the structure before calling newApplication().

Pancake Assembly

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.

Let’s look at an example;

public static void main( String[] args )
-        throws Exception
+    throws Exception
 {
     polygene = new Energy4Java();
-    Assembler[][][] assemblers = new Assembler[][][]{
+    Assembler[][][] assemblers = new Assembler[][][] {
         { // View Layer
-            { // Login Module
-                new LoginAssembler()
+          { // Login Module
+            new LoginAssembler()
             // :
-            },
-            { // Main Workbench Module
-                new MenuAssembler(),
-                new PerspectivesAssembler(),
-                new ViewsAssembler()
+          },
+          { // Main Workbench Module
+            new MenuAssembler(),
+            new PerspectivesAssembler(),
+            new ViewsAssembler()
             // :
-            },
-            { // Printing Module
-                new ReportingAssembler(),
-                new PdfAssembler()
+          },
+          { // Printing Module
+            new ReportingAssembler(),
+            new PdfAssembler()
             // :
-            }
+          }
         },
         { // Application Layer
-            { // Accounting Module
-                new BookkeepingAssembler(),
-                new CashFlowAssembler(),
-                new BalanceSheetAssembler()
+          { // Accounting Module
+            new BookkeepingAssembler(),
+            new CashFlowAssembler(),
+            new BalanceSheetAssembler()
             // :
-            },
-            { // Inventory Module
-                new PricingAssembler(),
-                new ProductAssembler()
+          },
+          { // Inventory Module
+            new PricingAssembler(),
+            new ProductAssembler()
             // :
-            }
+          }
         },
         { // Domain Layer
-        // :
+          // :
         },
         { // Infrastructure Layer
-        // :
+          // :
         }
     };
     ApplicationDescriptor model = newApplication( assemblers );
@@ -272,21 +229,11 @@ things togather.
Let’s look at an example;
Full Assembly
Full Assembly means that you have the opportunity to create any layer/module hierarchy that are within the rules of the
+

Full Assembly

Full Assembly means that you have the opportunity to create any layer/module hierarchy that are within the rules of the Polygene™ 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.

In principle, you first start the Polygene™ runtime, call newApplication with an ApplicationAssembler instance and call activate() on the returned application. The ApplicationAssembler instance will be called with an @@ -295,28 +242,17 @@ ApplicationAssemblyFactory, which is used to create an ApplicationAssembly descr private static Application application; public static void main( String[] args ) - throws Exception + throws Exception { // Create a Polygene Runtime polygene = new Energy4Java(); - application = polygene.newApplication( new ApplicationAssembler() - { - - @Override - public ApplicationAssembly assemble( ApplicationAssemblyFactory appFactory ) - throws AssemblyException - { - ApplicationAssembly assembly = appFactory.newApplicationAssembly(); - buildAssembly( assembly ); - return assembly; - } - - } ); - // activate the application + // Create the application + application = polygene.newApplication( factory -> buildAssembly( factory.newApplicationAssembly() ) ); + // Activate the application application.activate(); } -static void buildAssembly( ApplicationAssembly app ) throws AssemblyException +static ApplicationAssembly buildAssembly( ApplicationAssembly app ) throws AssemblyException { LayerAssembly webLayer = createWebLayer( app ); LayerAssembly domainLayer = createDomainLayer( app ); @@ -328,6 +264,8 @@ static void buildAssembly( ApplicationAssembly app ) throws AssemblyException domainLayer.uses( authLayer ); domainLayer.uses( persistenceLayer ); domainLayer.uses( messagingLayer ); + + return app; } static LayerAssembly createWebLayer( ApplicationAssembly app ) throws AssemblyException http://git-wip-us.apache.org/repos/asf/polygene-website/blob/2d44da7d/content/java/develop/core-runtime.html ---------------------------------------------------------------------- diff --git a/content/java/develop/core-runtime.html b/content/java/develop/core-runtime.html index c280b17..1554475 100644 --- a/content/java/develop/core-runtime.html +++ b/content/java/develop/core-runtime.html @@ -1,5 +1,5 @@ -Core Runtime +Core Runtime @@ -66,15 +66,52 @@ })(); -

Polygene™
Introduction
Tutorials
Javadoc
Samples
Core
Libraries
Extensions
Tools
Glossary

Overview
Core API
Core Bootstrap
Core Test Support
Core Extension SPI
Core Runtime

Core Runtime

code

docs

tests

First of all, your code should never, ever, have a dependency on Core Runtime. If you think you need this, you should +

Polygene™
Introduction
Tutorials
Javadoc
Samples
Core
Libraries
Extensions
Tools
Glossary

Overview
Core API
Core Bootstrap
Core Test Support
Core Extension SPI
Core Runtime

Core Runtime

code

docs

tests

First of all, your code should never, ever, have a dependency on Core Runtime. If you think you need this, you should probably contact users@polygene.apache.org mailing list and see if your usecase can either be solved in a existing way or -perhaps that a new Core SPI Extension is needed.

Table 18. Artifact

Group ID	Artifact ID	Version
org.apache.polygene.core	org.apache.polygene.core.runtime	3.0.0-SNAPSHOT

Let’s repeat that; Never, never, ever depend on Core Runtime. Make sure that the compile dependency does NOT include -the org.apache.polygene.core.runtime jar.

Custom AssemblyHelper

BUT, there are super-rare cases, where a custom AssemblyHelper might be needed. One known use-case is to introduce +perhaps that a new Core SPI Extension is needed.

Table 18. Artifact

Group ID	Artifact ID	Version
org.apache.polygene.core	org.apache.polygene.core.runtime	3.1.0-SNAPSHOT

Let’s repeat that; Never, never, ever depend on Core Runtime. Make sure that the compile dependency does NOT include +the org.apache.polygene.core.runtime jar.

Custom AssemblyHelper

BUT, there are super-rare cases, where a custom AssemblyHelper might be needed. One known use-case is to introduce an alternative bytecode generation algorithm, either better than the one we have, or for a different system, such as Dalvik.

To do this, add the AssemblyHelper implementation instance as metaInfo to the ApplicationAssembly

We think this is so rare, that the AssemblyHelper class will remain in the core/runtime module and has not been promoted to the core/bootstrap module. If you plan to use this feature, please contact the Polygene development -team at dev@polygene.apache.org to ensure we can make this a better supported, backed by real usecases.

Fictitious example of using a hypothetical Dalvik capable classloader;

source=core/runtime/src/test/java/org/apache/polygene/runtime/bootstrap/docs/DocumentationSupport.java
-tag=customAssemblyHelper

+team at dev@polygene.apache.org to ensure we can make this a better supported, backed by real usecases.

Fictitious example of using a hypothetical Dalvik capable classloader;

private static Energy4Java polygene;
+
+private static Application application;
+
+public static void main( String[] args )
+    throws Exception
+{
+    // Create a Polygene Runtime
+    polygene = new Energy4Java();
+    // Create the application
+    application = polygene.newApplication( factory -> {
+        ApplicationAssembly assembly = factory.newApplicationAssembly();
+        assembly.setMetaInfo( new DalvikAssemblyHelper() );
+          [...snip...]
+
+        return assembly;
+    } );
+    // Activate the application
+    application.activate();
+}
+
+public static class DalvikAssemblyHelper extends AssemblyHelper
+{
+    @Override
+    protected FragmentClassLoader instantiateFragmentClassLoader( ClassLoader parent )
+    {
+        return new DalvikFragmentClassLoader( parent );
+    }
+}
+
+public static class DalvikFragmentClassLoader extends FragmentClassLoader
+{
+
+    public DalvikFragmentClassLoader( ClassLoader parent )
+    {
+        super( parent );
+    }
+}
+

Copyright © 2015 The Apache Software Foundation, Licensed under the Apache License, Version 2.0.
Apache Polygene, Polygene, Apache, the Apache feather logo, and the Apache Polygene project logo are trademarks of The Apache Software Foundation.
http://git-wip-us.apache.org/repos/asf/polygene-website/blob/2d44da7d/content/java/develop/core-spi.html ---------------------------------------------------------------------- diff --git a/content/java/develop/core-spi.html b/content/java/develop/core-spi.html index 5d0519d..af85b34 100644 --- a/content/java/develop/core-spi.html +++ b/content/java/develop/core-spi.html @@ -1,5 +1,5 @@ -Core Extension SPI +Core Extension SPI @@ -66,9 +66,9 @@ })(); -

Polygene™
Introduction
Tutorials
Javadoc
Samples
Core
Libraries
Extensions
Tools
Glossary

Overview
Core API
Core Bootstrap
Core Test Support
Core Extension SPI
Core Runtime

Core Extension SPI

code

docs

tests

The Polygene™ Core Runtime has a number of extension points, which we call the Polygene Core Extension SPI. These are defined +

Polygene™
Introduction
Tutorials
Javadoc
Samples
Core
Libraries
Extensions
Tools
Glossary

Overview
Core API
Core Bootstrap
Core Test Support
Core Extension SPI
Core Runtime

Core Extension SPI

code

docs

tests

The Polygene™ Core Runtime has a number of extension points, which we call the Polygene Core Extension SPI. These are defined interfaces used only by the Core Runtime and never directly by application code. Extensions are assembled in -applications during the bootstrap phase.

Table 17. Artifact

Group ID	Artifact ID	Version
org.apache.polygene.core	org.apache.polygene.core.spi	3.0.0-SNAPSHOT

There are currently 5 Core SPI extensions;

+applications during the bootstrap phase.

Table 17. Artifact

Group ID	Artifact ID	Version
org.apache.polygene.core	org.apache.polygene.core.spi	3.1.0-SNAPSHOT

There are currently 5 Core SPI extensions;

Serialization SPI

EntityStore SPI @@ -81,7 +81,7 @@ applications during the bootstrap phase.

users@dev.apache.org mailing list, to see if your usecase -can be solved in a support manner, or that we need to extend the Core API to support it.

Serialization SPI

Tip

Find Serialization extensions in the Extensions list.

Overview

The Polygene™ Core Runtime use Serialization to provide string representation of ValueComposites via their toString() +can be solved in a support manner, or that we need to extend the Core API to support it.

Serialization SPI

Tip

Find Serialization extensions in the Extensions list.

Overview

The Polygene™ Core Runtime use Serialization to provide string representation of ValueComposites via their toString() method, and, their instantiation from the very same representation via the newValueFromSerializedState(..) method of the ValueBuilderFactory API.

public interface SomeValue // (1)
 {
@@ -92,14 +92,19 @@ the ValueBuilderFactory API.
public i
 public void assemble( ModuleAssembly module )
 {
     module.values( SomeValue.class ); // (2)
+      [...snip...]
+
+    module.defaultServices(); // (3)
+      [...snip...]
+
 }
   [...snip...]
 
 public void defaultSerialization()
 {
-    SomeValue someValue = someNewValueInstance(); // (3)
-    String json = someValue.toString(); // (4)
-    SomeValue someNewValue = valueBuilderFactory.newValueFromSerializedState( SomeValue.class, json ); // (5)
+    SomeValue someValue = someNewValueInstance(); // (4)
+    String json = someValue.toString(); // (5)
+    SomeValue someNewValue = valueBuilderFactory.newValueFromSerializedState( SomeValue.class, json ); // (6)
       [...snip...]
 
 }
@@ -113,6 +118,11 @@ public void defaultSerialization()
 public void assemble( ModuleAssembly module )
 {
     module.values( SomeValue.class ); // (2)
+      [...snip...]
+
+    new JavaxJsonSerializationAssembler().assemble( module ); // (3)
+      [...snip...]
+
 }
   [...snip...]
 
@@ -131,7 +141,7 @@ public void assembledDefaultServiceSerialization()
       [...snip...]
 
 }
-

Text or Binary?

The Core SPI provides adapters for text or bytes based serialization, extends the following types to implement a custom +

Text or Binary?

The Core SPI provides adapters for text or bytes based serialization, extends the following types to implement a custom serialization.

For text based serialization:

/**
  * Base Text Serializer.
  *
@@ -164,7 +174,7 @@ public abstract class AbstractBinarySerializer extends AbstractSerializer
  * See {@link AbstractBinarySerializer}.
  */
 public abstract class AbstractBinaryDeserializer extends AbstractDeserializer
-

JSON or XML?

The Core SPI provides JSON and XML serialization respectively based on javax.json and javax.xml types and APIs to +

JSON or XML?

The Core SPI provides JSON and XML serialization respectively based on javax.json and javax.xml types and APIs to work directly with these types so you can work with the actual object representations without serializing to text or bytes. They both rely on the text serialization adapters shown above.

Here is an example using the JsonSerialization service:

@Service
 JsonSerialization jsonSerialization;
@@ -202,14 +212,14 @@ XmlSerialization xmlSerialization;
           [...snip...]
 
     }
-

Implementation notes

Simply implement Serialization to create an extension for the Serialization SPI. +

Implementation notes

Simply implement Serialization to create an extension for the Serialization SPI. The Core SPI module provides adapters to create Serializers and Deserializers.

The behaviour described here apply to all Serialization services implemented using the Core SPI adapters. Note that -nothing stops you from implementing an extension for the Serialization SPI without relying on theses adapters.

Theses adapters are tailored for serialization mechanisms that support the following two structures that can be nested:

+nothing stops you from implementing an extension for the Serialization SPI without relying on theses adapters.
Theses adapters are tailored for serialization mechanisms that support the following two structures that can be nested:
- a collection of name/value pairs. In various languages, this is realized as an object, record, struct, dictionary, hash table, keyed list, or associative array,
- an ordered list of values. In most languages, this is realized as an array, vector, list, or sequence ; -
in other words, a JSON-like structure.