Assemble an Application

We receive a lot of questions about how applications should be assembled, and since we don’t have any XML to "fill in" and everything is to be done programmatically, it escalates the need to provide more hands-on explanation of how this is done.

If you want to reproduce what’s explained in this tutorial, remember to depend on the Core Bootstrap artifact:

At runtime you will need the Core Runtime artifact too. See the Depend on Polygene™ tutorial for details.


First let’s recap the structural requirements of Polygene;

  • There is one and only one Application instance per Polygene™ Runtime.
  • Every Application must contain one or more Layers.
  • All Composites must be declared in one or more Modules.
  • Each Module belong to a Layer.
  • Layers are ordered in hierarchies, from simple to complex.
  • Access to Composites are limited by visibility rules.

Ok, that was quite a handful. Let’s look at them one by one.


The first one means that for each Polygene™ Runtime you start, there will be exactly one application. As far as we know, Polygene is fully isolated, meaning there are no static members being populated and such.


Layers are the super-structures of an application. We have been talking about them for decades, drawn them on paper and whiteboards (or even black boards for those old enough), and sometimes organized the codebases along such boundaries. But, there has been little effort to enforce the Layer mechanism in code, although it is an extremely powerful construct. First of all it implies directional dependency and a high degree of order, spagetti code is reduced if successfully implemented. For Polygene, it means that we can restrict access to Composite and Object declarations, so that higher layers can not reach them incidentally. You can enforce architecture to a high degree. You can require all creation of composites to go through an exposed Factory, which doesn’t require the Composite to be public. And so on. Layers have hierarchy, i.e. one layer is top of one or more layers, and is below one or more layers, except for the layers at the top and bottom. You could have disjoint layers, which can’t access each other, meaning a couple of layers that are both the top and bottom.


The Module concept has also been around forever. And in Polygene™ we also makes the Modules explicit. Each Module belong to a Layer, and for each Module you declare the Composite and Object types for that Module, together with a Visibility rule, one of; application, layer, module.


The Visibility rules are perhaps the most powerful aspect of the above. Visibility is a mechanism that kicks in whenever a Composite type need to be looked up. It defines both the scoping rules of the client as well as the provider. A lookup is either a direct reference, such as

UnitOfWork unitOfWork = module.currentUnitOfWork();
PersonEntity person = unitOfWork.newEntity( PersonEntity.class );

or an indirect lookup, such as

UnitOfWork unitOfWork = module.currentUnitOfWork();
Person person = unitOfWork.newEntity( Person.class );

where it will first map the Person to a reachable PersonEntity. The algorithm is as follows;

  • Look in the callers Module, if there is one and only one Composite type matching, use it. If there are two or more Composite types matching, then throw an ambiguity exception. If there are zero, proceed to the next step.
  • Look in all Modules in the callers Layer. If there is one and only one Composite type that matches and is either Visibility.layer, then use it. If there are two or more Composite types matching, then throw an ambiguity exception. If there are zero, proceed to the next step.
  • Look in all Layers that caller’s Layer uses. If there is one and only one Composite type that matches and is either Visibility.application, then use it. If there are two or more Composite types matching, then throw an ambiguity exception. If there are zero, proceed to the next step.
  • Throw a CompositeNotFoundException.

The underlying principle comes down to Rickard’s "Speaker Analogy", you can hear him (and not the other speakers at the conference) because you are in the same room. I.e. if something is really close by, it is very likely that this is what we want to use, and then the search expands outwards.

Combining The Above

Ok, that was a whole lot of theory and probably take you more than one read-through to fully get into your veins (slow acting addiction). How to structure your code is beyond the scope of this section. If you are an experienced designer, you will have done that before, and you may have started out with good intentions at times only to find yourself in a spaghetti swamp later, or perhaps in the also famous "Clear as Clay" or "Ball (bowl?) of Mud". Either way, you need to draw on your experience and come up with good structure that Polygene™ lets you enforce.

So, for the sake of education, we are going to look at an application that consists of many layers, each with a few modules. See picture below.

Image of Example of Layers

Figure 1. Example of Layers

So, lets see how we code up this bit in the actual code first.

public class Main
    private static Energy4Java polygene;
    private static Application application;

    public static void main( String[] args )
            throws Exception
        // Bootstrap Polygene Runtime
        // Create a Polygene Runtime
        polygene = new Energy4Java();

        // Instantiate the Application Model.
        application = polygene.newApplication( new ApplicationAssembler()
            public ApplicationAssembly assemble(
                    ApplicationAssemblyFactory factory )
                    throws AssemblyException
                ApplicationAssembly assembly =
                LayerAssembly runtime = createRuntimeLayer( assembly );
                LayerAssembly designer = createDesignerLayer( assembly );
                LayerAssembly domain = createDomainLayer( assembly );
                LayerAssembly messaging= createMessagingLayer( assembly );
                LayerAssembly persistence = createPersistenceLayer( assembly );

                // declare structure between layers
                domain.uses( messaging );
                domain.uses( persistence );
                designer.uses( persistence );
                designer.uses( domain );
                runtime.uses( domain );

                return assembly;
        } );

        // We need to handle shutdown.

        // Activate the Application Runtime.



The above is the basic setup on how to structure a real-world applicaton, unless you intend to mess with the implementations of various Polygene™ systems (yes there are hooks for that too), but that is definitely beyond the scope of this tutorial.

Now, the createXyzLayer() methods were excluded to keep the sample crisp and easy to follow. Let’s take a look at what it could be to create the Domain Layer.

private static LayerAssembly createDomainLayer( ApplicationAssembly app )
    LayerAssembly layer = app.layer("domain-layer");
    createAccountModule( layer );
    createInventoryModule( layer );
    createReceivablesModule( layer );
    createPayablesModule( layer );
    return layer;

We just call the layerAssembly() method, which will return either an existing Layer with that name or create a new one if one doesn’t already exist, and then delegate to methods for creating the ModuleAssembly instances. In those method we need to declare which Composites, Entities, Services and Objects that is in each Module.

private static void createAccountModule( LayerAssembly layer )
    ModuleAssembly module = layer.module("account-module");

    module.entities(AccountEntity.class, EntryEntity.class);

    ).visibleIn( Visibility.layer );

We also need to handle the shutdown case, so in the main() method we have a installShutdownHook() method call. It is actually very, very simple;

private static void installShutdownHook()
    Runtime.getRuntime().addShutdownHook( new Thread( new Runnable()
        public void run()
            if( application != null )
                catch( Exception e )
    }) );

This concludes this tutorial. We have looked how to get the initial Polygene™ runtime going, how to declare the assembly for application model creation and finally the activation of the model itself.