Composite Oriented Programming builds on some principles that are not addressed by Object Oriented Programming at all.

Qi4j addresses the programming problems from the top-down, starting with the Domain Model and Business Rules needs, and let those requirements flow downwards in the software stack and dictate the requirements for underlying layers such as persistence, messaging, querying and more. This means that the business value developer is left to concentrate on the domain models and the actual application bringing the value, instead of creating massive amounts of glue code to tie underlying technologies together.

Qi4j didn’t appear out of the blue, when the founders of the project had nothing better to do. It is the result of observation of problems in real applications, and the experience from previous attempts to address or correct these problems, that has led to the Qi4j vision.

How can OOP be a problem? We and others have observed that there is a fundamental flaw in the OOP model. In fact, we would like to even state that OOP as it is commonly practiced today is not object oriented at all. The object is not the primary citizen, instead the class is the primary artifact. In most mainstream OOP languages, Objects are derived from classes, not that classes are assigned to created objects. Therefore, we think it should have been called Class Oriented Programming. We can also see this class focus in many of the technologies in Java today: in Spring you declare class names in application contexts, JSP uses class names to declare beans and so forth.

This in turn leads to that there is no good OOP solution for the problem we describe below.

Once you start thinking of "Behavior depends on Context", you have a hard time understanding how people for the last 20 years or so of Object Oriented Programming (OOP) has ignored this fact.

The OOP proponents once proclaimed that classes can be re-used, since the code is encapsulated with the class, so the class is an independent unit which lends itself well to re-use. In reality, however, we have found that classes becomes tightly coupled with many other classes in their neighborhood, leading to impossibilities of single class re-use. Many tricks are introduced to minimize the "Coupling Hell", such as Inversion of Control and Dependency Injection. Although those tools are good, the underlying problem remains.

Why do we end up with large coupled class network graphs?

Essentially, it boils down to "scope". Classes are too large, their scope is too large, and for each small functional unit within the class, there will be additional coupling to other classes. And this often progresses to the full boundary of the entire domain the class remains in.

Almost all technologies used in modern software development, starts by looking at an infrastructural problem and try to solve that the best way. This is often done in a vacuum and layers on top will be struggling to map or translate the solution into the higher abstraction, and the higher up we get, the harder it becomes to ignore the assumptions, problems and limitations of the underlying technologies. It is also common that the underlying technologies "bleeds" through the layers all the way into the domain models. The "bleed" combined with the problem of using independently developed technologies, puts a large burden on the application developer, whose job it is to bring business value. And often, the most skilled developers end up doing the bottom layers, leaving the hardest job to the least suitable. Another interesting consequence is that each layer needs to anticipate every single use-case - real, potential or perceived - and deal with it in a specifiable and useful manner. This leads to overly complex solutions, compared to if the system is built from the top layer down, where each layer beneath knows exactly what is expected from it, and only needs to handle those use-cases.

To paraphrase a famous proverb about a hammer: "If all you have are objects, everything looks like a dependency." We think that increasing abstraction often also increases complexity, and that the abstraction benefits are somewhat linear whereas the complexity negatives are exponential. So, our conclusion is that by making no distinction between different kinds of objects, many sound technologies run into incredibly difficult problems. The implementation of the programming platform (e.g. Java) is of course easier to implement with a hefty amount of scope reduction into as few as possible abstractions. But that is not the situation for the user. The abstraction is then required to be reversed when the rubber hits the road, e.g. ORM mapping must be declared explicitly by the programmer, often using separate tools and languages.

We think the solution was expressed more than 2500 years ago, first by Indian scholars and slightly later by Leucippus and Democritus. We are of course talking about atoms, and by using really small building blocks, we can express arbitrarily complex structures. By reducing the classes into what we in Composite Oriented Programming call Fragments, we limit the coupling network graph substantially. Re-use of Fragments becomes a reality, and by combination of Fragments, we compose larger structures, the Composites.

Composite Oriented Programming also view the object, we call it the Composite instance, as the first class citizen. The Composite instance can be cast to any context, meaning a different behavior can be applied to the Composite instance, without affecting its underlying state. And back. This in turn means that we can for instance create a ServerContextualInvoiceEntity, transport that across to a client, cast it to a GuiContextualInvoiceEntity do the modifications to the underlying state, possibly using extra interfaces and methods for interacting with the GUI environment, and then transport the modified object back to the server, cast it back to the ServerContextualInvoiceEntity, and then persist the changes.

Composite Oriented Programming is heavily influenced by the book "Domain Driven Design" by Eric Evans. And we are trying to use his analysis of the problem to provide the mechanisms needed to get the job done quicker and more reliably. Mr Evans talks about Applications, Layers, Modules, Specifications, SideEffects and so forth, and all of these should be present in a Composite Oriented Programming implementation, and to a large extent it is in Qi4j.

I’ve written a series of post on AOP lately (here, here and here), and in the last part I promised to tackle mixins and introductions in a future post. When I was doing my research for just that, I came cross a Java framework (just humor me :p) called Qi4j (that’s chee for jay), written by Swedish Richard Öberg, pioneering the idea of Composite Oriented Programming, which instantly put a spell on me. Essentially, it takes the concepts from Aspect Oriented Programming to the extreme, and for the past week I’ve dug into it with a passion. This post is the first fruits of my labor.

public class Division
{
    public Int64 Dividend { get; set; }
    private long _divisor = 1;

    public Int64 Divisor
    {
        get { return _divisor; }
        set
        {
            if(value == 0)
            {
                throw new ArgumentException("Cannot set the divisor to 0; division by 0 is not allowed.");
            }
            _divisor = value;
        }
    }

    public Int64 Calculate()
    {
        Trace.WriteLine("Calculating the division of " + this.Dividend + " by " + this.Divisor);
        Int64 result = this.Dividend/this.Divisor;
        Trace.WriteLine("Returning result: " + result);
        return result;
    }
}

public interface ICalculationDataAspect // aspect contract
{
    long Number1 { get; set; }
    long Number2 { get; set; }
}

public class CalculationDataAspect : ICalculationDataAspect // aspect implementation
{
    public long Number1 { get; set; }
    public long Number2 { get; set; }
}

public interface ICalculationLogicAspect
{
    long Calculate();
}

public class DivisionLogicAspect : ICalculationLogicAspect
{
    [AspectRef] ICalculationDataAspect _data;

    public long Calculate()
    {
        return _data.Number1 / _data.Number2;
    }
}

public abstract class DivisionValidationConcern : ICalculationDataAspect
{
    [ConcernFor] protected ICalculationDataAspect _proceed;

    public abstract long Number1 { get; set; }

    public long Number2
    {
        get { return _proceed.Number2; }
        set
        {
            if (value == 0)
            {
                throw new ArgumentException("Cannot set the Divisor to 0 - division by zero not allowed.");
            }
            _proceed.Number2 = value; // here, we tell the framework to proceed with the call to the *real* Number2 property
        }
    }
}

public class LoggingAdvice : IAdvice
{
    public object Execute(AdviceTarget target)
    {
        Trace.WriteLine("Invoking method " + target.TargetInfo.Name + " on " + target.TargetInfo.DeclaringType.FullName);

        object retValue;

        try
        {
            retValue = target.Proceed();
        }
        catch(Exception ex)
        {
            Trace.WriteLine("Method threw exception: " + ex.Message);
            throw;
        }
        Trace.WriteLine("Method returned " + retValue);
        return retValue;
    }
}

[Mixin(typeof(ICalculationDataAspect), typeof(CalculationDataAspect))]
[Mixin(typeof(ICalculationLogicAspect), typeof(DivisionLogicAspect))]
[Concern(typeof(DivisionValidationConcern))]
[Concern(typeof(LoggingAdvice))]
public interface IDivision : ICalculationDataAspect, ICalculationLogicAspect
{ }

IDivision division = Composer.Compose<IDivision>().Instantiate();
division.Number1 = 10;
division.Number2 = 2;

Int64 sum = division.Calculate();

public class SubtractionLogicAspect : ICalculationLogicAspect
{
    [AspectRef] ICalculationDataAspect _data;

    public long Calculate()
    {
        return _data.Number1 - _data.Number2;
    }
}

[Mixin(typeof(ICalculationDataAspect), typeof(CalculationDataAspect))]
[Mixin(typeof(ICalculationLogicAspect), typeof(SubtractionLogicAspect))]
[Pointcut(typeof(LoggingAdvice))]
public interface ISubtraction : ICalculationDataAspect, ICalculationLogicAspect
{ }

public class AbsoluteNumberConcern : ICalculationLogicAspect
{
    [ConcernFor] protected ICalculationLogicAspect _proceed;

    public long Calculate()
    {
        long result = _proceed.Calculate();

        return Math.Abs(result);
    }
}

[Mixin(typeof(ICalculationDataAspect), typeof(CalculationDataAspect))]
[Mixin(typeof(ICalculationLogicAspect), typeof(SubtractionLogicAspect))]
[Concern(typeof(AbsoluteNumberConcern))]
[Pointcut(typeof(LoggingAdvice))]
public interface ISubtraction : ICalculationDataAspect, ICalculationLogicAspect
{ }

Here’s an example of how you could define an EntityComposite:

interface PersonEntity
        extends EntityComposite
{
    Property<String> givenName();
    Property<String> surName();
}

With these few lines you have done what would have taken a whole lot more effort using POJOs, and what you want to express is very explicit. To define a property you would have had to write a field and two accessors, and if you use interfaces then those accessors would have to be duplicated.

The EntityComposite base interface also includes an identity property for you, as that’s an intrinsic feature of Entities, so that’s all taken care of. So if you speak about Entities in your domain discussions, each having Properties, then you can put that down in code pretty much as-is. This is, to me, a huge advantage over other ways of doing it, including POJO modeling (which lose clarity), UML modeling (which has roundtrip problems), DSL modeling (which lose tools support), and whatnot.

If you want to get picky about it, the above example is probably not how you would model Person. Having a name is just one role that a Person has to play, and since Composite Oriented Programming is all about using roles and context instead of classes you would probably do something like this instead:

interface Nameable
{
    @UseDefaults Property<String> givenName();
    @UseDefaults @Optional Property<String> surName();
}

interface PersonEntity
        extends Nameable, EntityComposite
{}

I’ve extracted the ability to be Named to its own interface, and let my domain Entity extend it. This way client code can check for "x instanceof Nameable" rather than "x instanceof PersonEntity", and then do something intelligent with it. By doing this, not only has Nameable become a reusable interface, but the client code that understands it has also become reusable for all domain objects in your model that uses it!

I’ve also marked both properties as @UseDefaults. What does this do? Well, if you have string properties they have the annoying property of being null to begin with, compared to ints and longs which default to 0. We figured that this was such a useful thing that we wanted to be able to mark our properties as being able to have their initial values be set to a default, for the type. For Strings this is the empty string, for primitives they are what you would expect. For Collections they are set to empty collections of the type indicated. "@UseDefaults Property<List<String>> addresses();" would be initialized to an empty ArrayList, for example.

In addition I have set surName() to be @Optional. In Qi4j we have defined all properties to be not-null as the default, and the same goes for all parameters in method invocations. If you explicitly want to allow properties to be null, so that for example "Madonna" would be an acceptable name, then you can mark it as @Optional. We prefer @Optional to @Nullable since it better expresses the intent from a domain perspective. Avoiding technical terms as much as possible is a another goal (which is damn hard to reach!).

If you want to get really picky about it, not even the above would be a real example. You may want to encapsulate the two properties into one value instead, so that you can more easily perform validation checks when they are updated. What you want are ValueComposites:

interface NameValue
        extends ValueComposite
{
    @UseDefaults Property<String> givenName();
    @UseDefaults @Optional Property<String> surName();
}

interface Nameable
{
    Property<NameValue> name();
}

Normally if you want a property to be immutable, meaning, you can set an initial value but not change it later, you would have to mark the Property as @Immutable. But since NameValue extends ValueComposite, which itself is marked with @Immutable, this is implicit for all subtypes of ValueComposite, and there’s no way to "opt out" of it.

By introducing one more level in the state model you have created an easy way to access the name as a whole and hand it around the system, instead of as two separate properties. Since it is immutable you are also ensured that noone can change it without going through the Entity, and you can also share instances of the name without having to worry about thread-safety.

The above is already a great step ahead in terms of how you can model your state more easily than having to use POJOs to sort of "fake" the features I’m describing above, and there’s also a ton of cool features and consequences of the whole thing I’m skipping here, for brevity. One of the problems with POJO models that usually come up is that your getters and setters get exposed to clients, and so functionality tend to not be put in the Entities, but rather in services and helper code, thereby scattering the Entity into a bunch of places. What should have been a neat and tidy little package is instead a anorectic little thing whose guts lay splashed around your code, looking all soggy and unappetizing.

What to do about this? One of the great inventions of Qi4j, I believe, is the notion of private mixins. That we can have mixins in an object which are explicitly HIDDEN from usage outside of it. How can we use this for state modeling? What you’d want to do is to model the state of an Entity as a private mixin, which is hidden from clients, and then you write role mixins which map domain methods to that internal state. Here’s an example:

@Mixins(ListablePersonMixin.class)
interface PersonEntity
        extends Listable, EntityComposite {}

interface PersonState
        extends Nameable {}

public class ListablePersonMixin
        implements Listable
{
    @This PersonState person;

    @Override
    public String listName()
    {
        String fullName = person.name().get().givenName().get();
        String sn = person.name().get().surName().get();
        if (sn != null) fullName += " "+sn;
        return fullName;
    }
}

interface Listable
{
    public String listName();
}

Neat huh? @This is a dependency injection annotation, but rather than the usual generic annotations like "@Inject" and friends, this one actually has a meaningful scope, that is, it requires that "this Entity" implements PersonState. The reference, as it is not extended by PersonEntity, is not visible to clients of the Entity and is hence a private mixin. Furthermore, all of a sudden your client code doesn’t even care if your domain object is Nameable, but rather if it is Listable. Cool! So you can make a UI widget for listing "stuff" that only requires that your thingie is Listable, rather than being a PersonEntity or Nameable.

For extra credit you could move the construction of "fullName" into a method on the NameValue, so that the value is not only a dumb data container, but can also perform useful operations on itself. And for the performance aware, don’t worry, the mixin is lazy-loaded, so if the particular usecase handling the Entity doesn’t need the "Listable" interface the mixin will never be instantiated.

And so much more…

The above is just a small taste of what you can do with state modeling in Qi4j. There is also support for associations and many-associations, the notion of aggregates, and a complete pluggable system for persistence and indexing/querying of data. To end with, here’s a sample of how some other state modeling concepts can be expressed in Qi4j:

interface PersonEntity
        extends EntityComposite
{
    Association<PersonEntity> father();
    @Optional Association<PersonEntity> spouse();
    ManyAssociation<PersonEntity> children();
    @Aggregated ManyAssociation<BookNoteEntity> favouriteBooks();
}

interface BookNoteEntity
        extends EntityComposite
{
    Property<String> note();
    Association<BookEntity> book();
}

I hope they are self-explanatory.

My hope is that with Composite Oriented Programming and Qi4j we can come one step closer to being able to express our domain as clearly as possible in code.

In chronological order, related publications:

Pêle-mêle, inspiring, inspired, alternatives or simply related:

This quite long introduction to Qi4j will start by brushing up an overview of the problems Qi4j solve, teach you what Composite Oriented Programming is and guide you through the process of writing a complete Application around an adapted Hello World example.

Throughout this set of tutorials it will be shown how to depend on Qi4j in your build, how to assemble a complete application, how to create and work with Composites and Services, how to use contextual fragments and leverage properties.

In this other set of tutorials it will be shown how to achieve tasks that frequently arise during the development of a typical application.

This last set of tutorials you’ll learn how to build the Qi4j SDK from sources including this very documentation website , the Qi4j manual, binaries and sources distributions.

In this short introduction, we have covered the essence of Qi4j. We have looked at what is a Composite, seen some of the Fragments in action, and how simple it is to turn a Composite into a persisted Composite, known as an EntityComposite.

We have now explored a couple more intricate features of Qi4j, hopefully without being overwhelmed with details on how to create applications from scratch, how to structure applications, and how the entire Qi4j Extension system works. We have looked at how to add a Concern that uses a private Mixin, we have touched a bit on Generic Concerns, and finally a short introduction to the Query API.

If you don’t rely on your build scripts dependency resolution mechanism you should download the SDK distribution.

First you need to register the Qi4j repositories:

<!-- ... -->
<repositories>
    <!-- ... -->
    <repository>
        <id>qi4j-releases</id>
        <url>https://repository-qi4j.forge.cloudbees.com/release/</url>
    </repository>
    <repository>
        <id>qi4j-snapshots</id>
        <url>https://repository-qi4j.forge.cloudbees.com/snapshot/</url>
        <releases><enabled>false</enabled></releases>
        <snapshots><enabled>true</enabled></snapshots>
    </repository>
    <!-- ... -->
</repositories>
<!-- ... -->

After that you can declare dependencies on Qi4j artifacts:

<!-- ... -->
<dependencies>
    <!-- ... -->
    <dependency>
        <groupId>org.qi4j.core</groupId>
        <artifactId>org.qi4j.core.bootstrap</artifactId>
        <version>QI4J_VERSION</version>
    </dependency>
    <dependency>
        <groupId>org.qi4j.core</groupId>
        <artifactId>org.qi4j.core.runtime</artifactId>
        <version>QI4J_VERSION</version>
        <scope>runtime</scope>
    </dependency>
    <dependency>
        <groupId>org.qi4j.core</groupId>
        <artifactId>org.qi4j.core.testsupport</artifactId>
        <version>QI4J_VERSION</version>
        <scope>test</scope>
    </dependency>
    <!-- ... -->
</dependencies>
<!-- ... -->

Where QI4J_VERSION is the Qi4j version you want to use.

First you need to register the Qi4j repositories:

// ...
repositories {
    // ...
    mavenRepo name: 'qi4j-releases', url: "https://repository-qi4j.forge.cloudbees.com/release/"
    mavenRepo name: 'qi4j-snapshots', url: "https://repository-qi4j.forge.cloudbees.com/snapshot/"
    // ...
}
// ...

After that you can declare dependencies on Qi4j artifacts:

// ...
dependencies {
    // ...
    compile "org.qi4j.core:org.qi4j.core.bootstrap:QI4J_VERSION"
    runtime "org.qi4j.core:org.qi4j.core.runtime:QI4J_VERSION"
    test    "org.qi4j.core:org.qi4j.core.testsupport:QI4J_VERSION"
    // ...
}
// ...

Where QI4J_VERSION is the Qi4j version you want to use.

First you need to register the Qi4j repositories:

# ...
repositories.remote << 'https://repository-qi4j.forge.cloudbees.com/release/'
repositories.remote << 'https://repository-qi4j.forge.cloudbees.com/snapshot/'
# ...

After that you can declare dependencies on Qi4j artifacts:

# ...
compile.with 'org.qi4j.core:org.qi4j.core.bootstrap:QI4J_VERSION'
package(:war).with :libs => 'org.qi4j.core:org.qi4j.core.runtime:QI4J_VERSION'
test.with 'org.qi4j.core:org.qi4j.core.testsupport:QI4J_VERSION'
# ...

Where QI4J_VERSION is the Qi4j version you want to use.

First you need to register the Qi4j repositories:

// ...
resolvers += "qi4j-releases" at "https://repository-qi4j.forge.cloudbees.com/release/"
resolvers += "qi4j-snapshots" at "https://repository-qi4j.forge.cloudbees.com/snapshot/"
// ...

After that you can declare dependencies on Qi4j artifacts:

// ...
libraryDependencies += \
    "org.qi4j.core" % "org.qi4j.core.bootstrap" % "QI4J_VERSION" \
    withSources() withJavadoc()
libraryDependencies += \
    "org.qi4j.core" % "org.qi4j.core.runtime" % "QI4J_VERSION" % "runtime" \
    withSources() withJavadoc()
libraryDependencies += \
    "org.qi4j.core" % "org.qi4j.core.testsupport" % "QI4J_VERSION" % "test" \
    withSources() withJavadoc()
// ...

Where QI4J_VERSION is the Qi4j version you want to use.

First you need to register the Qi4j repositories in a ivysettings.xml file:

<ivysettings>
    <settings defaultResolver="chain"/>
    <resolvers>
        <chain name="chain">
            <!-- ... -->
            <ibiblio name="qi4j-releases"  m2compatible="true"
                     root="https://repository-qi4j.forge.cloudbees.com/release/"/>
            <ibiblio name="qi4j-snapshots" m2compatible="true"
                     root="https://repository-qi4j.forge.cloudbees.com/snapshot/"/>
            <!-- ... -->
        </chain>
    </resolvers>
</ivysettings>

After that you can declare dependencies on Qi4j artifacts:

<ivy-module>
    <!-- ... -->
    <dependencies>
        <!-- ... -->
        <dependency org="org.qi4j.core" name="org.qi4j.core.bootstrap"
                    rev="QI4J_VERSION"  conf="default" />
        <dependency org="org.qi4j.core" name="org.qi4j.core.runtime"
                    rev="QI4J_VERSION"  conf="runtime" />
        <dependency org="org.qi4j.core" name="org.qi4j.core.testsupport"
                    rev="QI4J_VERSION"  conf="test" />
        <!-- ... -->
    </dependencies>
    <!-- ... -->
</ivy-module>

Where QI4J_VERSION is the Qi4j version you want to use.

First let’s recap the structural requirements of Qi4j;

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

The first one means that for each Qi4j Runtime you start, there will be exactly one application. As far as we know, Qi4j 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 Qi4j, 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 Qi4j 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;

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.

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 Qi4j 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 qi4j;
    private static Application application;

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

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

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

                return assembly;
            }
        } );

        // We need to handle shutdown.
        installShutdownHook();

        // Activate the Application Runtime.
        application.activate();
    }

      [...snip...]

}

The above is the basic setup on how to structure a real-world applicaton, unless you intend to mess with the implementations of various Qi4j 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);

    module.addServices(
            AccountRepositoryService.class,
            AccountFactoryService.class,
            EntryFactoryService.class,
            EntryRepositoryService.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 )
            {
                try
                {
                    application.passivate();
                }
                catch( Exception e )
                {
                    e.printStackTrace();
                }
            }
        }
    }) );
}

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

Previous step was Step 1 - Interface Refactoring.

In this step we will create a TransientComposite interface that ties all pieces together. The TransientComposite interface is a regular Java interface which extends the interfaces you want to expose from your domain model, and which uses various annotations to declare what Fragments to include. Fragments include Mixins, Concerns, SideEffects and Constraints. In this tutorial we will only use Mixins. When a TransientComposite is instantiated at runtime the framework will inspect the interface to determine what the TransientComposite instance should look like in terms of used Fragments.

In Qi4j all method parameters are considered mandatory unless marked as @Optional. Therefore you can remove the null checks in the Mixin. If a null value is passed in an exception will be thrown by Qi4j.

Steps for this tutorial:

/**
 * This Composite interface declares all the Fragments
 * of the HelloWorld composite.
 * <p/>
 * Currently it only declares one Mixin.
 */
@Mixins( HelloWorldMixin.class )
public interface HelloWorldComposite
    extends HelloWorld, TransientComposite
{
}

/**
 * This is the implementation of the HelloWorld
 * interface. The behaviour and state is mixed.
 */
public class HelloWorldMixin
    implements HelloWorld
{
    String phrase;
    String name;

    @Override
    public String say()
    {
        return getPhrase() + " " + getName();
    }

    @Override
    public void setPhrase( String phrase )
        throws IllegalArgumentException
    {
        if( phrase == null )
        {
            throw new IllegalArgumentException( "Phrase may not be null" );
        }

        this.phrase = phrase;
    }

    @Override
    public String getPhrase()
    {
        return phrase;
    }

    @Override
    public void setName( String name )
        throws IllegalArgumentException
    {
        if( name == null )
        {
            throw new IllegalArgumentException( "Name may not be null" );
        }

        this.name = name;
    }

    @Override
    public String getName()
    {
        return name;
    }
}

Previous step was Step 2 - Creating a Transient Composite.

In this step we refactor the Mixin from the previous steps into two, one which serves the behaviour interface and one which serves the state interface. This makes it possible to reuse the interfaces independently and also makes it easier to exchange one interface implementation with another. This also allows us to specify the new Mixins as default implementations of the interfaces by adding @Mixins annotations on them.

Steps for this tutorial:

/**
 * This Composite interface declares all the Fragments
 * of the HelloWorld composite.
 * <p/>
 * The Mixins annotation has been moved to the respective sub-interfaces.
 * The sub-interfaces therefore declare themselves what mixin implementation
 * is preferred. This interface could still have its own Mixins annotation
 * with overrides of those defaults however.
 */
public interface HelloWorldComposite
    extends HelloWorld, TransientComposite
{
}

/**
 * This interface contains only the behaviour
 * of the HelloWorld object.
 * <p/>
 * It declares what Mixin to use as default implementation.
 */
@Mixins( HelloWorldBehaviourMixin.class )
public interface HelloWorldBehaviour
{
    String say();
}

/**
 * This is the implementation of the HelloWorld
 * behaviour interface.
 * <p/>
 * It uses a @This Dependency Injection
 * annotation to access the state of the Composite. The field
 * will be automatically injected when the Composite
 * is instantiated. Injections of resources or references
 * can be provided either to fields, constructor parameters or method parameters.
 */
public class HelloWorldBehaviourMixin
    implements HelloWorldBehaviour
{
    @This
    HelloWorldState state;

    @Override
    public String say()
    {
        return state.getPhrase() + " " + state.getName();
    }
}

/**
 * This interface contains only the state
 * of the HelloWorld object.
 * The exceptions will be thrown by Qi4j automatically if
 * null is sent in as values. The parameters would have to be declared
 * as @Optional if null is allowed.
 */
@Mixins( HelloWorldStateMixin.class )
public interface HelloWorldState
{
    void setPhrase( String phrase )
        throws IllegalArgumentException;

    String getPhrase();

    void setName( String name )
        throws IllegalArgumentException;

    String getName();
}

/**
 * This is the implementation of the HelloWorld
 * state interface.
 */
public class HelloWorldStateMixin
    implements HelloWorldState
{
    String phrase;
    String name;

    @Override
    public String getPhrase()
    {
        return phrase;
    }

    @Override
    public void setPhrase( String phrase )
    {
        this.phrase = phrase;
    }

    @Override
    public String getName()
    {
        return name;
    }

    @Override
    public void setName( String name )
    {
        this.name = name;
    }
}

Previous step was Step 3 - Mixins.

In this step we refactor the mixin from the previous steps so that the result of the say() method is modified to be prefixed with "Simon says:". To do this we need to implement a Concern for the say() method. Concerns are a type of Modifier which modify the behaviour of the methods in Mixins. They do this by intercepting the invocation of the TransientComposite. This allows them to change the invocation parameters, return their own values or throw their own exceptions, and do other things which directly affect the invocation of the method.

Concerns should not perform any side-effects, such as updating state in another TransientComposite, Mixin or similar. Any side-effects are done in SideEffects, which is another type of Modifier, which are allowed to perform side-effects but, in contrast to Concerns, cannot change the parameters or in any other way change the result of the invocation.

Concerns are implemented in one of two ways: either create a class which directly implements the interface whose methods should be modified, or create a generic Modifier by implementing the InvocationHandler interface (or subclass GenericConcern which does this for you). Add an @ConcernFor dependency injection, as a field, constructor parameter or method parameter, which has the same type as the interface the Concern implements. When the TransientComposite is invoked the Concern will be called, allowing it to perform it’s work. If the call should proceed, then invoke the method again on the injected object. The preferred way to do all of this is to subclass ConcernOf which does all of this for you.

Concerns are applied by adding an @Concerns annotation on the TransientComposite, the domain interface, or the Mixin implementation. Any of these works, and where to put it is a matter of design choice.

Steps for this tutorial:

/**
 * This is the implementation of the HelloWorld
 * behaviour interface.
 * <p/>
 * It uses a @This Dependency Injection
 * annotation to access the state of the Composite. The field
 * will be automatically injected when the Composite
 * is instantiated. Injections of resources or references
 * can be provided either to fields, constructor parameters or method parameters.
 */
@Concerns( HelloWorldBehaviourConcern.class )
public class HelloWorldBehaviourMixin
    implements HelloWorldBehaviour
{
    @This
    HelloWorldState state;

    @Override
    public String say()
    {
        return state.getPhrase() + " " + state.getName();
    }
}

/**
 * This is a concern that modifies the mixin behaviour.
 */
public class HelloWorldBehaviourConcern
    extends ConcernOf<HelloWorldBehaviour>
    implements HelloWorldBehaviour
{
    @Override
    public String say()
    {
        return "Simon says:" + next.say();
    }
}

Previous step was Step 4 - Concerns.

In this step we will look at how to use Constraints. When we pass parameters to methods in regular Java code the only restriction we can make is to denote a type. Any other constraints on the input value, such as whether the parameter is optional, integer ranges, string regular expressions, and so on, cannot be expressed, and so we have to put this into Javadoc, and then manually add these checks in the implementation class.

In Qi4j there is the option to use Constraints, which are further restrictions on the parameters. This is implemented by having an annotation that describes what the Constraint does, and then an implementation class that checks whether a specific value fulfills the Constraint or not.

	Note
	The previous steps had a dependency to the Core API only. The constraints you’ve used in this step, introduce a new dependency to the Constraints Library, where all the constraint related classes reside. So update your classpath settings accordingly.

There are a number of pre-written constraints in Qi4j which you can use. The null check of the original HelloWorld version is already handled by default since Qi4j considers method parameters to be mandatory if not explicitly marked with the @Optional annotation. So, instead of doing that check we will add other checks that are useful to make, such as ensuring that the passed in string is not empty.

The only thing you have to do is add the annotation @NotEmpty to the method parameters you want to constrain in this way. The annotation has a default implementation declared in it by using the @Constraints annotation. You can either just use this, which is the common case, or override it by declaring your own @Constraints annotation in the TransientComposite type.

You can add as many Constraint annotations you want to a parameter. All of them will be checked whenever a method is called.

Steps for this tutorial:

/**
 * This interface contains only the behaviour
 * of the HelloWorld object.
 * <p/>
 * It declares what Mixin to use as default implementation, and also the extra
 * concern to be applied.
 */
@Concerns( HelloWorldBehaviourConcern.class )
@Mixins( HelloWorldBehaviourMixin.class )
public interface HelloWorldBehaviour
{
    String say();
}

/**
 * This is the implementation of the HelloWorld
 * behaviour interface.
 * <p/>
 * It uses a @This DependencyModel Injection
 * annotation to access the state of the Composite. The field
 * will be automatically injected when the Composite
 * is instantiated. Injections of resources or references
 * can be provided either to fields, constructor parameters or method parameters.
 */
public class HelloWorldBehaviourMixin
    implements HelloWorldBehaviour
{
    @This
    HelloWorldState state;

    @Override
    public String say()
    {
        return state.getPhrase() + " " + state.getName();
    }
}

/**
 * This Concern validates the parameters
 * to the HelloWorldState interface.
 */
public class HelloWorldBehaviourConcern
    extends ConcernOf<HelloWorldBehaviour>
    implements HelloWorldBehaviour
{
    @Override
    public String say()
    {
        return "Simon says:" + next.say();
    }
}

/**
 * This interface contains only the state
 * of the HelloWorld object.
 * <p/>
 * The parameters are declared as @NotEmpty, so the client cannot pass in empty strings
 * as values.
 */
@Mixins( HelloWorldStateMixin.class )
public interface HelloWorldState
{
    void setPhrase( @NotEmpty String phrase )
        throws IllegalArgumentException;

    String getPhrase();

    void setName( @NotEmpty String name )
        throws IllegalArgumentException;

    String getName();
}

Previous step was Step 5 - Constraints.

The current say() method has a Concern that modifies its value. What if we instead want the value to be intact, but log that value to System.out? That would be considered a side-effect of the say() method, and should hence not be done in a Concern. It would be better to implement this in a SideEffect. SideEffects are executed after the Mixin and all Concerns for a method are done, which means that the final result has been computed. A SideEffect can access this result value, and then use that for further computation, but it should not change the value or throw an exception.

SideEffects can be either typed or generic, just like Concerns. In the typed case we are interested in specifying SideEffects for one or more particular methods, whereas in the generic case the SideEffect is not really relying on what method is being invoked. Both are useful in different scenarios.

The easiest way to implement a typed SideEffect is to subclass the SideEffectOf class. This gives you access to the result of the real method invocation by using the "next" field, which has the same type as the interface of the method you want the code to be a side-effect of. Note that calling "next" does not actually do anything, it only returns the value (or throws the exception, if one was thrown from the original method) that has already been computed. Similarly, since the method is already done, you can return anything from the SideEffect method. The framework will simply throw it away, and also ignore any exceptions that you throw in your code.

To declare that the SideEffect should be used you add the @SideEffects annotation to either the TransientComposite type, the Mixin type, or the Mixin implementation. Either works.

Steps for this tutorial:

/**
 * This interface contains only the behaviour
 * of the HelloWorld object.
 */
public interface HelloWorldBehaviour
{
    String say();
}

/**
 * As a side-effect of calling say, output the result.
 */
public class HelloWorldBehaviourSideEffect
    extends SideEffectOf<HelloWorldBehaviour>
    implements HelloWorldBehaviour
{
    @Override
    public String say()
    {
        System.out.println( result.say() );
        return null;
    }
}

/**
 * This Composite interface declares transitively
 * all the Fragments of the HelloWorld composite.
 * <p/>
 * It declares that the HelloWorldBehaviourSideEffect should be applied.
 */
@Mixins( { HelloWorldBehaviourMixin.class, HelloWorldStateMixin.class } )
@SideEffects( HelloWorldBehaviourSideEffect.class )
public interface HelloWorldComposite
    extends HelloWorld, TransientComposite
{
}

/**
 * This interface contains only the state
 * of the HelloWorld object.
 * <p/>
 * The parameters are declared as @NotEmpty, so the client cannot pass in empty strings
 * as values.
 */
public interface HelloWorldState
{
    void setPhrase( @NotEmpty String phrase )
        throws IllegalArgumentException;

    String getPhrase();

    void setName( @NotEmpty String name )
        throws IllegalArgumentException;

    String getName();
}

Previous step was Step 6 - SideEffects.

One of the goals of Qi4j is to give you domain modeling tools that allow you to more concisely use domain concepts in code. One of the things we do rather often is model Properties of objects as getters and setters. But this is a very weak model, and does not give you any access to metadata about the property, and also makes common tasks like UI binding non-trivial. There is also a lot of repetition of code, which is unnecessary. Using JavaBeans conventions one typically have to have code in five places for one property, whereas in Qi4j the same thing can be achieved with one line of code.

But lets start out easy. To declare a property you have to make a method in a mixin type that returns a value of the type Property, and which does not take any parameters. Here’s a simple example:

Property<String> name();

This declares a Property of type String with the name "name". The Property interface has methods "get" and "set" to access and mutate the value, respectively.

For now you will be responsible for implementing these methods, but later on these will be handled automatically, thus reducing Properties to one-liners!

In the Mixin implementation of the interface with the Property declaration you should have an injection of the Property, which is created for you by Qi4j. The injection can be done in a field like this:

@State Property<String> name;

The State dependency injection annotation means that Qi4j will inject the Property for you. The field has the name "name", which matches the name in the interface, and therefore that Property is injected. You can then implement the method trivially by just returning the "name" field.

Properties can have Constraints just like method parameters. Simply set them on the Property method instead, and they will be applied just as before when you call "set".

Steps for this tutorial:

/**
 * This is the implementation of the HelloWorld
 * behaviour interface.
 * <p/>
 * This version access the state using Qi4j Properties.
 */
public class HelloWorldBehaviourMixin
    implements HelloWorldBehaviour
{
    @This
    HelloWorldState state;

    @Override
    public String say()
    {
        return state.phrase().get() + " " + state.name().get();
    }
}

/**
 * This Composite interface declares transitively
 * all the Fragments of the HelloWorld composite.
 */
@Mixins( { HelloWorldBehaviourMixin.class, HelloWorldStateMixin.class } )
public interface HelloWorldComposite
    extends HelloWorldBehaviour, HelloWorldState, TransientComposite
{
}

/**
 * This interface contains only the state
 * of the HelloWorld object.
 * <p/>
 * The state is now declared using Properties. The @NotEmpty annotation is applied to the
 * method instead, and has the same meaning as before.
 */
public interface HelloWorldState
{
    @NotEmpty
    Property<String> phrase();

    @NotEmpty
    Property<String> name();
}

/**
 * This is the implementation of the HelloWorld
 * state interface.
 */
public class HelloWorldStateMixin
    implements HelloWorldState
{
    @State
    private Property<String> phrase;
    @State
    private Property<String> name;

    @Override
    public Property<String> phrase()
    {
        return phrase;
    }

    @Override
    public Property<String> name()
    {
        return name;
    }
}

Previous step was Step 7 - Properties.

In this step we will look at how to use generic Fragments. So far all Fragments, i.e. the Concerns, SideEffects, and Mixins, have directly implemented the domain interface. But sometimes it is useful to be able to provide a generic implementation of an interface. An example of this is the HelloWorldState interface. Since it only handles properties, and the old version used the JavaBean rules for naming getters and setters we could create a mixin that handles invocations of such methods automatically for us by storing the properties in a map and use the methods to look them up.

Implementing a generic Fragment is done by creating a class that implements the interface java.lang.proxy.InvocationHandler. This has a single "invoke" method which is passed the object that was invoked (the TransientComposite in this case), the method, and the arguments. The Fragment is then allowed to implement the method any way it wants.

Since interfaces with only Properties is such a common case Qi4j already has a generic Mixin that implements the Properties management described above, but for the builtin Property type instead of the getter/setter variant. The class is aptly named PropertyMixin.

While we could use it, for now we will implement it ourselves to get a feel for how generic Mixins work.

Steps for this tutorial:

@AppliesTo( { GenericPropertyMixin.PropertyFilter.class } )
public class GenericPropertyMixin
    implements InvocationHandler
{
    @State
    private StateHolder state;

    @Override
    public Object invoke( Object proxy, Method method, Object[] args )
        throws Throwable
    {
        return state.propertyFor( method );
    }

    public static class PropertyFilter
        implements AppliesToFilter
    {
        @Override
        public boolean appliesTo( Method method, Class<?> mixin, Class<?> compositeType, Class<?> modifierClass )
        {
            return Property.class.isAssignableFrom( method.getReturnType() );
        }
    }
}

/**
 * This is the implementation of the HelloWorld
 * behaviour interface.
 */
public class HelloWorldBehaviourMixin
    implements HelloWorldBehaviour
{
    @This
    HelloWorldState state;

    @Override
    public String say()
    {
        return state.phrase().get() + " " + state.name().get();
    }
}

/**
 * This Composite interface declares transitively
 * all the Fragments of the HelloWorld composite.
 * <p/>
 * All standard declarations have been moved to
 * the StandardAbstractEntityComposite so we don't have to repeat
 * them in all Composites.
 */
@Mixins( { HelloWorldBehaviourMixin.class, GenericPropertyMixin.class } )
public interface HelloWorldComposite
    extends HelloWorldBehaviour, HelloWorldState, TransientComposite
{
}

Previous step was Step 8 - Generic Mixins.

Now we’re going to turn around and see how we can reduce the code needed to implement the HelloWorld example. We will also look at how to hide the Properties from the client code, since Properties are often considered to be implementation details that should not be exposed to clients.

The first thing we will do is remove the behaviour interface, and move the say() method to the TransientComposite type. This forces the mixin to implement the TransientComposite type, which would normally mean that it would have to implement all methods, including those found in the TransientComposite interface. However, since we are only really interested in implementing the say() method we will mark this by declaring that the Mixin "implements" the TransientComposite type, but is also "abstract". This, using pure Java semantics, makes it possible to avoid having to implement all methods. Qi4j will during the initialization phase detect that the Mixin only handles the say() method, and therefore only map it to that specific method. In order to instantiate the Mixin it will generate a subclass which implements the remaining methods in the TransientComposite type, as no-ops. These will never be called however, and is there purely for the purpose of being able to instantiate the Mixin. The Mixin is considered to be an Abstract Fragment.

To hide the state from the client we need to use what is called Private Mixins. A Private Mixin is any mixin that is referenced by another Mixin by using the @This injection, but which is not included in the TransientComposite type. As long as there is a Mixin implementation declared for the interface specified by the @This injection it will work, since Qi4j can know how to implement the interface. But since it is not extended by the TransientComposite type there is no way for a user of the TransientComposite to access it. That Mixin becomes an implementation detail. This can be used either for encapsulation purposes, or for referencing utility mixins that help the rest of the code implement some interface, but which itself should not be exposed.

Since the state is now hidden the initialization of the TransientComposite is a bit more tricky. Instead of just instantiating it you have to create a TransientBuilder first, then set the state using .prototypeFor(), and then call newInstance(). This ensures that the state can be set during construction, but not at any later point, other than through publicly exposed methods.

Steps for this tutorial:

/**
 * This Composite interface declares transitively
 * all the Fragments of the HelloWorld composite.
 * <p/>
 * The Fragments are all abstract, so it's ok to
 * put the domain methods here. Otherwise the Fragments
 * would have to implement all methods, including those in Composite.
 */
@Mixins( { HelloWorldMixin.class } )
public interface HelloWorldComposite
    extends TransientComposite
{
    String say();
}

/**
 * This is the implementation of the say() method. The mixin
 * is abstract so it doesn't have to implement all methods
 * from the Composite interface.
 */
public abstract class HelloWorldMixin
    implements HelloWorldComposite
{
    @This
    HelloWorldState state;

    @Override
    public String say()
    {
        return state.phrase().get() + " " + state.name().get();
    }
}

/**
 * This interface contains only the state
 * of the HelloWorld object.
 */
public interface HelloWorldState
{
    @NotEmpty
    Property<String> phrase();

    @NotEmpty
    Property<String> name();
}

In this tutorial we start with basic Java classes, to simulate a very simple Library where you can borrow and return books.

Qi4j relies heavily on the use of interfaces. This makes it possible for an object to externally implement a number of interfaces which internally is backed by a number of Mixins, some of which you may have written yourself, and some of which may have been reused. This is also true for services, which we are to cover in this tutorial.

The first task is therefore to refactor the code so that the methods are implemented from an interface instead, and to essentially make the identical "application" into a Qi4j application. We also want the Book to be a ValueComposite.

Steps for this tutorial:

Services can be "activated" and "passivated". Applications can be notified of this occurring by Qi4j runtime by assembling them with an Activator.

Activators methods are called around "activation" and "passivation": beforeActivation, afterActivation, beforeActivation, afterPassivation. The ActivatorAdapter class help you keeping your code short when you only need one or two hooks.

To showcase how this works, we refactor the code to create a number of copies of the books, to be lend out upon call to the borrowBook method, which will return null if no copy is available. The book copies are created in the activate method.

Steps to do:

Services typically have configuration. Configurations are directly supported in Qi4j. A ConfigurationComposite is a subtype of EntityComposite. That is because configurations are stored in EntityStores, can be modified in runtime by client code and has the same semantics as regular entities.

Qi4j also handles the bootstrapping of configuration for the services. If the ConfigurationComposite is not found in the configured entity store, then Qi4j will automatically locate a properties file for each service instance, read those properties into a ConfigurationComposite instance, save that to the entity store and provide the values to the service. The properties file must be with the same name as the service instance with the extension "properties" in the same package as the service.

For this exercise, create a LibraryConfiguration that contains "titles", "authors" and "copies". The first two are a string with a comma separated list, and the "copies" is just an Integer with how many copies are made of each title.

Steps to do.

The Property concept also allows a much better defined persistence model. In Qi4j, only Property and Association instances are persisted, and that makes the semantics around the persistence system very clear.

Properties reference values only, and these values must be Serializable, which means that Properties can not contain Entities, since Entities are not Serializable. Associations are the opposite, as they must only reference Entities and nothing else.

Properties can also have typed, custom meta information associated with them. Meta information is declared once per Property per Module. A Property is identified by its method name and the interface it is declared in.

Let’s say we want to create a generic Swing client that can show and navigate the domain model, without knowing the actual domain model. Such Swing client will utilize a SwingInfo property info if it is available.

public interface SwingInfo
{
    Icon icon( Rectangle size );

    String displayName( Locale locale );
}

Our generic Swing UI will be mainly reflective in nature, but when it gets hold of a Property, it can simply do;

    @Structure
    private Qi4j api;
      [...snip...]

    private void addProperty( JPanel panel, Property<?> property )
    {
        SwingInfo info = api.propertyDescriptorFor( property ).metaInfo( SwingInfo.class );
        Icon icon = info.icon( SIZE_32_32 );
        panel.add(  new JLabel(info.displayName( this.locale ), icon, JLabel.CENTER) );
    }
      [...snip...]

}

Method Constraints are declared with annotations on the method argument. The annotation itself is custom, and it is possible to make your own.

public interface Dialer
{
    void callPhoneNumber(@PhoneNumber String phoneNo);

}

In the code above we say that we want the argument to the callPhoneNumber() method to be a valid phone number. This annotation is not built-in, so we need to declare it.

@ConstraintDeclaration
@Retention( RetentionPolicy.RUNTIME )
@Target( { ElementType.PARAMETER, ElementType.ANNOTATION_TYPE, ElementType.METHOD } )
public @interface PhoneNumber
{
}

We then need to provide the Constraint implementation.

public class PhoneNumberConstraint
        implements Constraint<PhoneNumber, String>
{
    public boolean isValid( PhoneNumber annotation, String number )
    {
        boolean validPhoneNumber = true; // check phone number format...
        return validPhoneNumber;  // return true if valid phone number.
    }
}

We also need to include the Constraint on the Composites we want to have them present.

@Constraints( PhoneNumberConstraint.class )
public interface DialerComposite extends ServiceComposite, Dialer
{
}

If a Constraint is violated, then a ConstraintViolationException is thrown. The Exception contains ALL violations found in the method invocation. Concerns can be used to catch and report these violations.

public class ParameterViolationConcern extends ConcernOf<InvocationHandler>
    implements InvocationHandler
{
    public Object invoke( Object proxy, Method method, Object[] args )
        throws Throwable
    {
        try
        {
            return next.invoke( proxy, method, args );
        }
        catch( ConstraintViolationException e )
        {
            for( ConstraintViolation violation : e.constraintViolations() )
            {
                String name = violation.name();
                Object value = violation.value();
                Annotation constraint = violation.constraint();
                report( name, value, constraint );
            }
            throw new IllegalArgumentException("Invalid argument(s)", e);
        }
    }

      [...snip...]

    private void report( String name, Object value, Annotation constraint )
    {
    }
}

Property Constraints are declared on the Property method.

public interface HasPhoneNumber
{
    @PhoneNumber
    Property<String> phoneNumber();
}

In this case, the Constraint associated with the phoneNumber() method, will be called before the set() method on that Property is called. If there is a constraint violation, the Exception thrown will be part of the caller, and not the composite containing the Property, so a reporting constraint on the containing Composite will not see it. If you want the containing Composite to handle the Constraint Violation, then you need to add a Concern on the Property itself, which can be done like this;

public abstract class PhoneNumberParameterViolationConcern extends ConcernOf<HasPhoneNumber>
    implements HasPhoneNumber
{
    @Concerns( CheckViolation.class )
    public abstract Property<String> phoneNumber();

    private abstract class CheckViolation extends ConcernOf<Property<String>>
        implements Property<String>
    {
        public void set( String number )
        {
            try
            {
                next.set( number );
            }
            catch( ConstraintViolationException e )
            {
                Collection<ConstraintViolation> violations = e.constraintViolations();
                report( violations );
            }
        }

          [...snip...]

        private void report( Collection<ConstraintViolation> violations )
        {
        }
    }
}

A typed Concern is a Java class that implements the MixinType it can be used on:

public class InventoryConcern extends ConcernOf<Order>
    implements Order
{
    @Service
    private InventoryService inventory;

    @Override
    public void addLineItem( LineItem item )
    {
        String productCode = item.productCode().get();
        int quantity = item.quantity().get();
        inventory.remove( productCode, quantity );
        next.addLineItem( item );
    }

    @Override
    public void removeLineItem( LineItem item )
    {
        String productCode = item.productCode().get();
        int quantity = item.quantity().get();
        inventory.add( productCode, quantity );
        next.removeLineItem( item );
    }
}

The InventoryConcern is implemented as an abstract class, since we are not interested in the many other methods in the Order interface. Extending the ConcernOf is a convenience mechanism, instead of an explicit @ConcernFor annotation on a private field, which can be used in rare occasions when you are not able to extend. This base class defines the next field, which is set up by the Qi4j runtime and points to the next fragment in the call stack. We can also see that the InventoryService is provided to the concern, which is done with dependency injection. Qi4j also supports dependency injection via constructors and methods.

It can be used as follows;

@Concerns( InventoryConcern.class )
public interface Order
{
    void addLineItem( LineItem item );
    void removeLineItem( LineItem item );

      [...snip...]

Methods of the Concern Fragment will be called before the Mixin invocation.

A generic Concern is a Java class that implements java.lang.reflect.InvocationHandler which allows it to be used on any arbitrary MixinType.

public class MyGenericConcern extends GenericConcern
{
    @Override
    public Object invoke( Object proxy, Method method, Object[] args )
        throws Throwable
    {
        // Do whatever you want

          [...snip...]

It can be used as follows;

@Concerns( MyGenericConcern.class )
public interface AnyMixinType
{

  [...snip...]

    @MyAnnotation
    void doSomething();

    void doSomethingElse();

Methods of the Concern Fragment will be called before the Mixin invocation.

@AppliesTo( { MyAnnotation.class, MyAppliesToFilter.class } )
public class MyGenericConcern extends GenericConcern
{

@Concerns( MyGenericConcern.class )
public interface AnyMixinType
{

    @MyAnnotation
    void doSomething();

    void doSomethingElse();

}

public class MyAppliesToFilter implements AppliesToFilter
{
    public boolean appliesTo( Method method, Class<?> mixin, Class<?> compositeType, Class<?> modifierClass )
    {
        boolean appliesTo = evaluate(method); // Do whatever you want
        return appliesTo;
    }

      [...snip...]

    private boolean evaluate( Method method )
    {
        return true;
    }

A typed SideEffect is a Java class that implements the MixinType it can be used on:

public abstract class MailNotifySideEffect extends SideEffectOf<Confirmable>
    implements Confirmable
{
    @Service
    private MailService mailer;

    @This
    private HasLineItems hasItems;

    @This
    private HasCustomer hasCustomer;

    @Override
    public void confirm()
    {
        StringBuilder builder = new StringBuilder();
        builder.append( "An Order has been made.\n\n\n" );
        builder.append( "Customer:" );
        builder.append( hasCustomer.name().get() );
        builder.append( "\n\nItems ordered:\n" );
        for( LineItem item : hasItems.lineItems().get() )
        {
            builder.append( item.name().get() );
            builder.append( " : " );
            builder.append( item.quantity().get() );
            builder.append( "\n" );
        }
        mailer.send( "sales@mycompany.com", builder.toString() );
    }
}

The MailNotifySideEffect is implemented as an abstract class, since we are not interested in the many other methods in the Confirmable interface. Extending the SideEffectOf is a convenience mechanism, instead of an explicit @SideEffectFor annotation on a private field, which can be used in rare occasions when you are not able to extend. This base class defines the next field, which is set up by the Qi4j runtime and points to the next fragment in the call stack. We can also see that the MailService, HasLineItems and HasCustomer are provided to the side-effect, which is done with dependency injection. Qi4j also supports dependency injection via constructors and methods.

It can be used as follows;

@SideEffects( MailNotifySideEffect.class )
public interface OrderEntity
    extends Order, HasSequenceNumber, HasCustomer,
            HasLineItems, Confirmable, EntityComposite
{
}

Methods of the SideEffect Fragment will be called after the Mixin invocation.

A generic SideEffect is a Java class that implements java.lang.reflect.InvocationHandler which allows it to be used on any arbitrary MixinType.

public class MyGenericSideEffect extends GenericSideEffect
{
    @Override
    public Object invoke( Object proxy, Method method, Object[] args )
        throws Throwable
    {
        // Do whatever you need...

        try
        {
            // It is possible to obtain the returned values by using 'result' member;
            Object returnedValue = result.invoke( proxy, method, args );
        } catch( NumberFormatException e )
        {
            // And Exception will be thrown accordingly, in case you need to know.
            throw new IllegalArgumentException(); // But any thrown exceptions are ignored.
        }
        return 23; // Return values will also be ignored.
    }
}

It can be used as follows;

@Concerns( MyGenericSideEffect.class )
public interface AnyMixinType
{
  [...snip...]

}

Methods of the SideEffect Fragment will be called before the Mixin invocation.

@AppliesTo( { MyAnnotation.class, MyAppliesToFilter.class } )
public class MyGenericSideEffect extends GenericSideEffect
{
  [...snip...]

}

@Concerns( MyGenericSideEffect.class )
public interface AnyMixinType
{

    @MyAnnotation
    void doSomething();

    void doSomethingElse();

}
  [...snip...]

public class MyAppliesToFilter implements AppliesToFilter
{
    public boolean appliesTo( Method method, Class<?> mixin, Class<?> compositeType, Class<?> modifierClass )
    {
        boolean appliesTo = evaluate(method); // Do whatever you want
        return appliesTo;
    }

      [...snip...]

    private boolean evaluate( Method method )
    {
        return true;
    }

All Entity operations MUST be done within a UnitOfWork. UnitOfWorks can be nested and if underlying UnitOfWorks are not completed (method complete()), then none of the operations will be persisted permanently.

Entity composites are subtypes of the EntityComposite interface.

Domain code typically don’t need to know of the EntityComposite types directly, and is instead using the domain specific interface. The Visibility rules will be applied to associate the right EntityComposite when a domain type is requested. Ambiguities are not accepted and will result in runtime exceptions.

Qi4j supports that each entity instance can have more than one entity type, and it is managed per instance. This feature is beyond the scope of this HowTO and will be covered subsequently.

We have made the observation that it is good practice to separate the internal state from the observable behavior. By this we mean that it is not a good practice to allow client code to manipulate or even view the internal states of objects, which is such a common (bad) practice in the so called POJO world.

Instead, we recommend that the programmer defines the client requirement of what each participant within the client context needs to conform to, and then create composites accordingly and hide all the state internal to the composite in private mixins. By doing so, the same entity can participate in multiple contexts with different behavioral requirements but using the same internal state.

We recommend limited use of primitive types for Properties and instead subtype the Property.

And try to use ValueComposites instead of Entities.

We need an entity to illustrate how we recommend to separate internal state from public behavior and observable state. We will for the sake of simplicity use a trivial example. Please refer to other (possibly future) HowTos on patterns on Entity management.

public interface Car
{
    @Immutable
    Association<Manufacturer> manufacturer();

    @Immutable
    Property<String> model();

    ManyAssociation<Accident> accidents();
}

public interface Manufacturer
{
    Property<String> name();
    Property<String> country();

    @UseDefaults
    Property<Long> carsProduced();
}

public interface Accident
{
    Property<String> description();
    Property<Date> occured();
    Property<Date> repaired();
}

Above we define a Car domain object, which is of a particular Manufacturer (also an Entity), a model and a record of Accidents.

We will also need to define the composites for the above domain structure;

public interface CarEntity extends Car, EntityComposite
{}

public interface ManufacturerEntity extends Manufacturer, EntityComposite
{}

public interface AccidentValue extends Accident, ValueComposite
{}

For this case, we define both the Car and the Manufacturer as Entities, whereas the Accident is a Value, since it is an immutable event that can not be modified.

All of the above must also be declared in the assembly. We MUST associate the EntityComposites with a relevant Module. We must also assemble an EntityStore for the entire application, but that is outside the scope of this HowTo.

public class MyAssembler
        implements Assembler
{
    public void assemble( ModuleAssembly module )
    {
        module.entities( CarEntity.class,
                ManufacturerEntity.class );

        module.values( AccidentValue.class );
          [...snip...]

    }
}

We have no other Composites involved yet, so we can proceed to look at the usage code.

We recommend that the life cycle management of entities is placed inside domain factories, one for each type and made available as services.

The entity factory is something you need to write yourself, but as with most things in Qi4j it will end up being a fairly small implementation. So how is that done?

public interface CarEntityFactory
{
    Car create(Manufacturer manufacturer, String model);
}

That is just the domain interface. We now need to make the service interface, which Qi4j needs to identify services and make it possible for the service injection later.

@Mixins( { CarEntityFactoryMixin.class } )
public interface CarEntityFactoryService
        extends CarEntityFactory, ServiceComposite
{}

Then we need an implementation of the mixin.

public class CarEntityFactoryMixin
        implements CarEntityFactory
{

And doing that, first of all we need to request Qi4j runtime to give us the UnitOfWorkFactory associated with the Module that our code belongs to, and the UnitOfWork current context the execution is happening in.

Injections that are related to the Visibility rules are handled by the @Structure annotation. And the easiest way for us to obtain a UnitOfWorkFactory is simply to;

public class CarEntityFactoryMixin
        implements CarEntityFactory
{

    @Structure
    UnitOfWorkFactory uowf;

Here Qi4j will inject the member uowf with the correct UnitOfWorkFactory. In case we only need the UnitOfWorkFactory during the construction, we can also request it in the same manner as constructor argument.

public CarEntityFactoryMixin( @Structure UnitOfWorkFactory uowf )
{
}

This is important to know, since the injected member will not be available until AFTER the constructor has been completed.

We then need to provide the implementation for the create() method.

public Car create(Manufacturer manufacturer, String model)
{
    UnitOfWork uow = uowf.currentUnitOfWork();
    EntityBuilder<Car> builder = uow.newEntityBuilder( Car.class );

    Car prototype = builder.instance();
    prototype.manufacturer().set( manufacturer );
    prototype.model().set( model );

    return builder.newInstance();
}

So far so good. But how about the Manufacturer input into the create() method?

DDD promotes the use of Repositories. They are the type-safe domain interfaces into locating entities without getting bogged down with querying infrastructure details. And one Repository per Entity type, so we keep it nice, tidy and re-usable. So let’s create one for the Manufacturer type.

public interface ManufacturerRepository
{
    Manufacturer findByIdentity(String identity);

    Manufacturer findByName(String name);
}

And then we repeat the process for creating a Service…

@Mixins( ManufacturerRepositoryMixin.class  )
public interface ManufacturerRepositoryService
        extends ManufacturerRepository, ServiceComposite
{}

and a Mixin that implements it…

public class ManufacturerRepositoryMixin
        implements ManufacturerRepository
{
    @Structure
    private UnitOfWorkFactory uowf;

    @Structure
    private Module module;

    public Manufacturer findByIdentity( String identity )
    {
        UnitOfWork uow = uowf.currentUnitOfWork();
        return uow.get(Manufacturer.class, identity);
    }

    public Manufacturer findByName( String name )
    {
        UnitOfWork uow = uowf.currentUnitOfWork();
        QueryBuilder<Manufacturer> builder =
                module.newQueryBuilder( Manufacturer.class );

        Manufacturer template = templateFor( Manufacturer.class );
        builder.where( eq( template.name(), name ) );

        Query<Manufacturer> query = uow.newQuery( builder);
        return query.find();
    }
}

But now we have introduced 2 services that also are required to be declared in the assembly. In this case, we want the Services to be available to the application layer above, and not restricted to within this domain model.

public class MyAssembler
        implements Assembler
{
    public void assemble( ModuleAssembly module )
    {
        module.entities( CarEntity.class,
                ManufacturerEntity.class );

        module.values( AccidentValue.class );
        module.addServices(
                ManufacturerRepositoryService.class,
                CarEntityFactoryService.class
        ).visibleIn( Visibility.application );
    }
}

If you notice, there is a couple of calls to UnitOfWorkFactory.currentUnitOfWork(), but what is current UnitOfWork, and who is setting that up?

Well, the domain layer should not worry about UoW, it is probably the responsibility of the application/service layer sitting on top. That could be a web application creating and completing a UoW per request, or some other co-ordinator doing long-running UnitOfWorks.

There are of course a lot more details to get all this completed, but that is beyond the scope of this HowTo.

To illustrate these features we create an TravelPlan service, which allows clients to find and make Reservations to Destinations. For the sake of simplicity, we are leaving out the domain details…

public interface TravelPlan
{
    // Domain methods, which are beyond the discussion at hand.
}

So, then there is the ServiceComposite…

// The package is relevant to the Initial Values discussed later.
package org.qi4j.manual.travel;
  [...snip...]

@Mixins( { TravelPlanMixin.class } )
public interface TravelPlanService extends TravelPlan, ServiceComposite
{}

And then in the Mixin we actually need to connect to a foreign system to obtain the various details that the service can provide to the clients. For instance, it needs a host name and port and a protocol to use. We put these into a configuration interface.

public interface TravelPlanConfiguration
{
    Property<String> hostName();

    @Range( min=0, max=65535 )
    Property<Integer> portNumber();

    @Matches( "(ssh|rlogin|telnet)" )
    Property<String> protocol();
}

We used the recommended type-safe Property subtype pattern, and for each PortNumber and Protocol we have defined a Constraint required.

Now we can access this configuration in the TravelPlanMixin like this;

import org.qi4j.api.configuration.Configuration;

public class TravelPlanMixin implements TravelPlan
{
    @This
    Configuration<TravelPlanConfiguration> config;

    private void foo()
    {
        TravelPlanConfiguration tpConf = config.get();
        String hostName = tpConf.hostName().get();
        // ...
    }
      [...snip...]

}

And from the Service point of view, it doesn’t need to worry about where the configuration really comes from. But it may want to control when the Configuration should be refreshed, to ensure that atomic changes are happening. This is done with the refresh() method in the Configuration interface;

public void doSomething()
{
    // Refresh Configuration before reading it.
    config.refresh();

    TravelPlanConfiguration tpConf = config.get();
    // ...
}

This ensures that any updates to the Configuration that has occurred will be retrieved and available to the Service. Since Configuration instance is an Entity, the UnitOfWork system will ensure that the Configuration is consistent and not in the middle of value changes.

# Hostname to the TravelPlan service
hostName=niclas.hedhman.org

# Port number to use for the connection
portNumber=5439

# Protocol to use; Valid options "ssh", "rlogin", "telnet"
protocol=ssh

public void assemble(ModuleAssembly module) throws AssemblyException
{
    module.addServices(TravelPlanService.class).instantiateOnStartup();
}

If you need to use multiple instances of the same service, or that the service has a non-default Identity, then you need to name the properties file according to the Identity of the service declaration, but the file will still need to be in the same package as the ServiceComposite sub type, the TravelPlanService in the above example. For instance;

public void assemble(ModuleAssembly module) throws AssemblyException
{
    module.addServices(TravelPlanService.class)
            .instantiateOnStartup()
            .identifiedBy("ExpediaService");

    module.addServices(TravelPlanService.class)
            .instantiateOnStartup()
            .identifiedBy("OrbitzService");
}

And the two files for configuration,

# Hostname to the TravelPlan service
hostName=expedia.hedhman.org

# Port number to use for the connection
portNumber=9251

# Protocol to use; Valid options "ssh", "rlogin", "telnet"
protocol=ssh

File: org/qi4j/manual/travel/ExpediaService.properties

# Hostname to the TravelPlan service
hostName=orbitz.hedhman.org

# Port number to use for the connection
portNumber=7412

# Protocol to use; Valid options "ssh", "rlogin", "telnet"
protocol=rlogin

File: org/qi4j/manual/travel/OrbitzService.properties

Unlike most frameworks, the Configuration in Qi4j is an active Entity, and once the properties file has been read once at the first(!) startup, it no longer serves any purpose. The Configuration will always be retrieved from the EntityStore. Changes to the properties file are not taken into consideration if the Configuration entity is found in the entity store.

But that also means that applications should not cache the configuration values, and instead read them from the Configuration instance every time needed, and do a refresh() method call when it is safe to update the Configuration Entity with new values.

If you want to reproduce what’s explained in this tutorial, remember to depend on the Core Runtime artifact that depends on Core API, Core SPI, Core Bootstrap and Core Functional & I/O APIs:

See the Depend on Qi4j in your build tutorial for details.

Once theses parts were identified it was mostly just a matter of putting interfaces on these pieces, and making sure they can be easily used in many different situations. The result is as follows.

To start with we have Input:

public interface Input<T, SenderThrowableType extends Throwable>
{
    <ReceiverThrowableType extends Throwable> void transferTo( Output<? super T, ReceiverThrowableType> output )
        throws SenderThrowableType, ReceiverThrowableType;
}

Inputs, like Iterables, can be used over and over again to initiate transfers of data from one place to another, in this case an Output. Since I want this to be generic the type of things that is sent is T, so can be anything (byte[], String, EntityState, MyDomainObject). I also want the sender and receiver of data to be able to throw their own exceptions, and this is marked by declaring these as generic exception types. For example, the input may want to throw SQLException and the output IOException, if anything goes wrong. This should be strongly typed, and both sender and receiver must know when either side screws up, so that they can recover properly and close any resources they have opened.

On the receiving side we then have Output:

public interface Output<T, ReceiverThrowableType extends Throwable>
{
  [...snip...]

    <SenderThrowableType extends Throwable> void receiveFrom( Sender<? extends T, SenderThrowableType> sender )
        throws ReceiverThrowableType, SenderThrowableType;
}

When receiveFrom is invoked by an Input, as a result of invoking transferTo on the Input, the Output should open whatever resources it needs to write to, and then expect data to come from a Sender. Both the Input and Output must have the same type T, so that they agree on what is being sent. We will see later how this can be handled if this is not the case.

Next we have Sender:

public interface Sender<T, SenderThrowableType extends Throwable>
{
  [...snip...]

    <ReceiverThrowableType extends Throwable> void sendTo( Receiver<? super T, ReceiverThrowableType> receiver )
        throws ReceiverThrowableType, SenderThrowableType;
}

The Output invokes sendTo and passes in a Receiver that the Sender will use to send individual items. The sender at this point can start transferring data of type T to the receiver, one at a time. The Receiver looks like this:

public interface Receiver<T, ReceiverThrowableType extends Throwable>
{
  [...snip...]

    void receive( T item )
        throws ReceiverThrowableType;
}

When the receiver gets the individual items from the sender it can either immediately write them to its underlying resource, or batch them up. Since the receiver will know when the transfer is done (sendTo returns) it can write the remaining batches properly and close any resource it holds.

This simple pattern, with two interfaces on the sending side and two on the receiving side, gives us the potential to do scalable, performant and fault-tolerant transfers of data.

So now that the above API defines the contract of sending and receiving data, I can then create a couple of standard inputs and outputs. Let’s say, reading lines of text from a file, and writing lines of text to a file. These implementations I can then put in static methods so they are easy to use. In the end, to make a copy of a text file looks like this:

File source = new File("source.txt");
File destination = new File("destination.txt");
Inputs.text( source ).transferTo( Outputs.text( destination ) );

One line of code that handles the reading, the writing, the cleaning up, buffering, and whatnot. Pretty nifty! The transferTo method will throw IOException, which I can catch if I want to present any errors to the user. But actually dealing with those errors, i.e. closing the files and potentially deleting the destination if the transfer failed, is already handled by the Input and Output. I will never have to deal with the details of reading text from a file ever again!

While the above handles the basic input/output of a transfer, there are usually other things that I want to do as well. I may want to count how many items were transferred, do some filtering, or log every 1000 items or so to see what’s going on. Since input and output are now separated this becomes simply a matter of inserting something in the middle that mediates the input and output. Since many of these mediations have a similar character I can put these into standard utility methods to make them easier to use.

The first standard decorator is a filter. I will implement this by means of supplying a Specification:

public static <T,ReceiverThrowableType extends Throwable> Output<T, ReceiverThrowableType> filter( final Specification<T> specification, final Output<T, ReceiverThrowableType> output)
{
   ... create an Output that filters items based on the Specification<T> ...
}

Where Specification is:

interface Specification<T>
{
     boolean test(T item);
}

With this simple construct I can now perform transfers and easily filter out items I don’t want on the receiving side. This example removes empty lines from a text file.

File source = ...
File destination = ...
Inputs.text( source ).transferTo( Transforms.filter(new Specification<String>()
{
   public boolean test(String string)
   {
      return string.length() != 0;
   }
}, Outputs.text(destination) );

The second common operation is mapping from one type to the other. This deals with the case that one Input you have may not match the Output you want to send to, but there’s a way to map from the input type to the output type. An example would be to map from String to JSONObject, for example. The operation itself looks like this:

public static <From,To,ReceiverThrowableType extends Throwable> Output<From, ReceiverThrowableType> map( Function<From,To> function, Output<To, ReceiverThrowableType> output)

Where Function is defined as:

interface Function<From, To>
{
    To map(From from);
}

With this I can then connect an Input of Strings to an Output of JSONObject like so:

Input<String,IOException> input = ...;
Output<JSONObject,RuntimeException> output = ...;
input.transferTo(Transforms.map(new String2JSON(), output);

Where String2JSON implements Function and it’s map method converts the String into a JSONObject.

At this point we can now deal with the last part of the initial example, the counting of items. This can be implemented as a generic Map that has the same input and output type, and just maintains a count internally that updates on every call to map(). The example can then be written as:

File source = ...
File destination = ...
Counter<String> counter = new Counter<String>();
Inputs.text( source ).transferTo( Transforms.map(counter, Outputs.text(destination) ));
System.out.println("Nr of lines:"+counter.getCount())

Now I can finally get back to my initial problem that led me to look into this: how to implement a good way to access EntityStates in a Qi4j EntityStore, and perform restores of backups. The current version of accessing EntityStates look like this:

<ThrowableType extends Throwable> void visitEntityStates( EntityStateVisitor<ThrowableType> visitor, ModuleSPI module )
     throws ThrowableType;

interface EntityStateVisitor<ThrowableType extends Throwable>
{
  void visitEntityState( EntityState entityState )
     throws ThrowableType;
}

This can now be replaced with:

Input<EntityState, EntityStoreException> entityStates(ModuleSPI module);

Because of the pattern outlined above, users of this will get more information about what’s happening in the traversal, such as if the EntityStore raised an EntityStoreException during the traversal, which they can then handle gracefully. It also becomes easy to add decorators such as maps and filters to users of this. Let’s say you only are interested in EntityState’s of a given type. Then add a filter for this, without changing the consumer.

For importing backup data into an EntityStore, the interface used to look like this:

interface ImportSupport
{
    ImportResult importFrom( Reader in )
            throws IOException;
}

This ties the EntityStore to only being able to read JSON lines from Reader’s, the client will not know if the IOException raised is due to errors in the Reader or writing in the store, and the ImportResult, which contains a list of exceptions and count of stuff, is quite ugly to create and use. With the I/O API at hand this can now be replaced with:

interface ImportSupport
{
   Output<String,EntityStoreException> importJSON();
}

To use this, given the helpers outlined above, is as simple as:

File backup = ...
ImportSupport entityStore = ...
Inputs.text(backup).transferTo(entityStore.importJSON());

If the client wants any "extras", such as counting how many objects were imported, this can be done by adding filters as previously shown. If you only want to, say, import entities modified before a particular date (let’s say you know some junk was introduced after a given time), then add a specification filter that performs this check. And so on.

It is quite common while developing software that you have to shuffle data or objects from one input to another output, possible with some transformations in the middle. Usually these things have to be done from scratch, which opens up for errors and badly applied patterns. By introducing a generic Input/Output API that encapsulates and separates these things properly it becomes easier to perform these tasks in a scalable, performant and error-free way, and while still allowing these tasks to be decorated with extra features when needed.

This article has outlined one way to do this, and the API and helpers that I’ve described are available in the current Qi4j Core 1.3-SNAPSHOT in Git (see Qi4j homepage for access details). The idea is to start using it throughout Qi4j wherever we need to do I/O of the type described here.

By default, the build system produces a "zero build". It means that there is no version assigned to the build, and a "0" is used in the produced artifacts. This is due to our disagreement (with Maven community) that the "next" version name/number is known prior to the release. This is in our opinion a delayed decision. To build a particular version, you specify a "version" property on the command-line, like

./gradlew -Dversion=2.0-FLAVOUR install

If a "version" property is not defined, the build system will refuse to make a release and upload.

Gradle is very flexible, and we have defined (or in the process of defining) the following tasks (same as Ant’s targets).

Build System configuration is done through Gradle properties.

This can be done in many ways, see Gradle properties and system properties.

signing.keyId=FB751943
signing.password=foobar
signing.secretKeyRingFile=/home/foo/.gnupg/secring.gpg

./gradlew uploadArchives -Dversion=2.0-SNAPSHOT -PuploadReleaseSpec=false \
    -PuploadWagon=what:ever:wagon -PuploadRepository=http://what.ever.repository/url \
    -PuploadUsername=foo -PuploadPassword=bar

./gradlew uploadArchives -Dversion=2.0 -PuploadRepository=file:///path/to/local/repository

	Tip
	To generate the website locally use ./gradlew -p manual website. Output is in ~/manual/build/docs/website.

Each (sub)project has its own documentation, in src/docs/ and all the Asciidoc documents have the .txt file extension.

The documents can use code snippets which will extract code from the project. This is preferred way to include source code in the documentation, since any refactoring will be reflected in the documentation.

The above files are all consumed by the build of the manual (by adding them as dependencies). To get content included in the manual, it has to be explicitly included by a document in the manual as well.

The whole documentation set is generated from the *manual* module in the qi4j-sdk, and we are currently only creating the website. The User Guide and Reference Manual are future projects.

Each document starts over with headings from level zero (the document title). Each document should have an id. In some cases sections in the document need to have id’s as well, this depends on where they fit in the overall structure. To be able to link to content, it has to have an id. Missing id’s in mandatory places will produce warnings, or even fail (depending on severity), the build.

This is how a document should start:

[[unique-id-verbose-is-ok,Remember This Caption]]
= The Document Title =

To push the headings down to the right level in the output, the leveloffset attribute is used when including the document inside of another document.

Subsequent headings in a document should use the following syntax:

== Subheading ==

... content here ...

=== Subsubheading ===

content here ...

Asciidoc comes with one more syntax for headings, but in this project it’s not used.

Try to put one sentence on each line. Lines without empty lines between them still belongs to the same paragraph. This makes it easy to move content around, and also easy to spot (too) long sentences.

To link to other parts of the manual the id of the target is used. This is how such a reference looks:

<<community-docs-overall-flow>>

Which will render like: Documentation Flow

	Note
	Just write "see <<target-id>>" and similar, that’s enough in most cases.

If you need to link to another document with your own link text, this is what to do:

<<target-id, link text that fits in the context>>

	Note
	Having lots of linked text may work well in a web context but is a pain in print, and we aim for both!

External links are added like this:

http://www.qi4j.org/[Link text here]

Which renders like: Link text here

For short links it may be better not to add a link text, just do:

http://www.qi4j.org/

Which renders like: http://www.qi4j.org/

It’s ok to have a dot right after the URL, it won’t be part of the link.

http://www.qi4j.org/.

Which renders like: http://www.qi4j.org/.

These are very useful and should be used where appropriate. Choose from the following (write all caps and no, we can’t easily add new ones):

	Note
	Note.

	Tip
	Tip.

	Important
	Important

	Caution
	Caution

	Warning
	Warning

Here’s how it’s done:

NOTE: Note.

A multiline variation:

[TIP]
Tiptext.
Line 2.

Which is rendered as:

	Tip
	Tiptext. Line 2.

Common attributes you can use in documents:

These can substitute part of URLs that point to for example APIdocs or source code.

Useful links when configuring the docbook toolchain:

The Qi4j Core API is the primary interface for client application code during the main execution phase, i.e. after the application has been activated.

Learn more

Qi4j 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 Qi4j, where types "belongs" to a module and visibility rules define default behaviors, enforcement of architectural integrity and much more.

Learn more

Qi4j comes with classes to help with testing. There is also some mocking support, to allow some of Qi4j’s unique aspects to be mocked, but since Qi4j is so flexible at a fine-granular level, we have found that mocking is seldom, if ever, needed.

Learn more

The Qi4j Core Functional API is a generic package to work with Iterables in a "functional programming language" style.

This package is completely independent of everything else in Qi4j and may be used on its own in any kind of environment such as Spring or Java EE applications.

Learn more

The Qi4j 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.

Learn more

The Qi4j Core Runtime has a number of extension points, which we call the Qi4j 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.

Learn more

Your code should never, ever, have a dependency on Qi4j 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 Extension SPI is needed.

Learn more

Composition is at the heart of COP, and refers to two different levels of constructs;

In Qi4j, we use the term Assembly for the second case of composition. See separate chapter.

Composition will allow library authors a new level of flexibility in how functionality is provided to client code. More on that later.

@Mixins( { BalanceCheckMixin.class } )
public interface BankAccount
{
    Money checkBalance();
      [...snip...]

}

public void assemble( ModuleAssembly module )
{
    module.entities( BankAccount.class );
}

Qi4j promotes a conventional view of application structure, that computer science has been using for decades.

The definition is as follows;

The principle of this Structure is to assist the programmer to create well modularized applications, that are easily extended and maintained. Qi4j will restrict access between Modules, so that code can only reach Composites and Objects in Modules (including itself) of the same or lower Layers.

Each Layer has to be declared which lower Layer(s) it uses, and it is not allowed that a lower Layer uses a higher Layer, i.e. cyclic references.

Every Qi4j runtime has one and only one Application in it. It is possible to run multiple Qi4j runtimes in the same JVM, and it is even possible to embed a Qi4j runtime within a Qi4j Application, but there can only be one Application in a Qi4j runtime.

An Application is then broken into layers and modules are placed within those layers. Composites are placed within modules. This forms the Application Structure and is enforced by the Qi4j runtime.

A Qi4j Application must consist of at least one layer. More layers are common, often dividing the application along the common architectural diagrams used on whiteboards, perhaps with a UI layer at the top, followed by a service or application layer, then with a domain layer and finally some persistence layer at the bottom.

Qi4j enforces this layering by requiring the Assembly to declare which layer uses which other layer. And Visibility rules define that layers below can not locate composites in layers above. Also, defining that "Layer1 uses Layer2" and "Layer2 uses Layer3" does NOT imply that Layer1 has Visibility to Layer3. If that is wanted, then it must be declared explicitly.

Modules are logical compartments to assist developers in creating and maintaining well modularized code. A Module only belongs to a single Layer, but many Modules can exist in the same Layer. Composite access is limited to;

Modules contains a lot of the Qi4j infrastructure, which are the enforcers of these wise modularization principles.

It is not possible to modify the Modules, their resolution nor binding in any way after the application starts.

Usage of value objects is one of the most ignored and best return-on-investment the programmer can do. Values are immutable and can be compared by value instead of memory reference. Concurrency is suddenly not an issue, since either the value exists or it doesn’t, no need for synchronization. Values are typically very easy to test and very robust to refactoring.

Qi4j defines values as a primary meta type through the ValueComposite, as we think the benefits of values are great. The ValueComposite is very light-weight compared to the EntityComposite, and its value can still be persisted as part of an EntityComposite via a Property.

The characteristics of a ValueComposite compared to other Composite meta types are;

Return to top

Value Serialization

Value objects can be serialized and deserialized using the ValueSerialization API which is a Service API implemented by SPI and extensions.

	Tip
	ValueSerialization extends ValueSerializer, ValueDeserializer. See the JavaDocs for interfaces detail.

The ValueSerialization mechanism apply to the following object types :

• ValueComposite,
• EntityReference,
• Iterable,
• Map,
• Plain Value.

Nested Plain Values, EntityReferences, Iterables, Maps, ValueComposites are supported. EntityComposites and EntityReferences are serialized as their identity string.

Plain Values can be one of :

• String,
• Character or char,
• Boolean or boolean,
• Integer or int,
• Long or long,
• Short or short,
• Byte or byte,
• Float or float,
• Double or double,
• BigInteger,
• BigDecimal,
• Date,
• DateTime (JodaTime),
• LocalDateTime (JodaTime),
• LocalDate (JodaTime).

Values of unknown types and all arrays are considered as java.io.Serializable and by so are (de)serialized to (from) base64 encoded bytes using pure Java serialization. If it happens that the value is not Serializable or the input to deserialize is invalid, a ValueSerializationException is thrown.

Methods of ValueSerializer allow to specify if the serialized state should contain extra type information about the serialized value. Having type information in the serialized payload allows to keep actual ValueComposite types and by so circumvent AmbiguousTypeException when deserializing.

Core Runtime provides a default ValueSerialization system based on the org.json Java library producing and consuming JSON.

Let’s see how it works in practice.

public interface SomeValue // (1)
{

    Property<String> foo();
}

@Override
public void assemble( ModuleAssembly module )
    throws AssemblyException
{
    module.values( SomeValue.class ); // (2)
      [...snip...]

}
  [...snip...]

public void defaultValueSerialization()
{
    SomeValue someValue = someNewValueInstance( module ); // (3)
    String json = someValue.toString(); // (4)
    SomeValue someNewValue = module.newValueFromSerializedState( SomeValue.class, json ); // (5)
      [...snip...]

}

Reading this first example step by step we ;

1. declare a ValueComposite,
2. assemble it,
3. create a new Value instance,
4. use the ValueComposite#toString() method to get a JSON representation of the Value,
5. and finally, use the Module#newValueFromSerializedState() method to create a new Value instance from the JSON state.

ValueComposite#toString() method leverage Value Serialization and by so provide JSON based representation. The Module API allows to create new Value instances from serialized state.

On top of that, Application assemblies can register different implementation of ValueSerialization as Services to support more formats, see the Extensions section. Note that the default behaviour described above is overriden if a ValueSerialization Service is visible.

Let’s see how to use the ValueSerialization Services.

public interface SomeValue // (1)
{

    Property<String> foo();
}

@Override
public void assemble( ModuleAssembly module )
    throws AssemblyException
{
    module.values( SomeValue.class ); // (2)
    new OrgJsonValueSerializationAssembler().assemble( module ); // (3)
}
  [...snip...]

@Service
private ValueSerializer valueSerializer; // (4)
@Service
private ValueDeserializer valueDeserializer; // (4)

  [...snip...]

public void assembledDefaultServiceSerialization()
{
    SomeValue someValue = someNewValueInstance( module ); // (5)
    String json = valueSerializer.serialize( someValue ); // (6)
    SomeValue someNewValue = valueDeserializer.deserialize( SomeValue.class, json ); // (7)
      [...snip...]

}

In this second example, we ;

1. declare a ValueComposite,
2. assemble it,
3. assemble a ValueSerialization Service backed by the org.json package,
4. get the ValueSerializer and ValueDeserializer Services injected,
5. create a new Value instance,
6. use the ValueSerializer#serialize() method to get a JSON representation of the Value,
7. and finally, use the ValueDeserializer#eserialize() method to create a new Value instance from the JSON state.

Many applications need to stream data. The ValueSerialization API support such use cases in two ways.

The first one use classic streams.

public void assembledServiceStreamingSerialization()
{
  [...snip...]

    // (1)
    Iterable<AcmeValue> data = dataSource; // Eg. Entities converted to Values
    OutputStream output = targetStream; // Eg. streaming JSON over HTTP

    // (2)
    valueSerializer.serialize( data, output );
      [...snip...]

    // (3)
    InputStream input = sourceStream; // Eg. reading incoming JSON

    // (4)
    List<AcmeValue> values = valueDeserializer.deserialize( CollectionType.listOf( AcmeValue.class ), input );
      [...snip...]

}

1. get a handle on a source of values and an OutputStream,
2. serialize data into the OutputStream,
3. get a handle on an InputStream,
4. deserialize data from the InputStream.

The second one use the I/O API:

public void assembledServiceIOSerialization()
    throws IOException
{
  [...snip...]

    // (1)
    Iterable<AcmeValue> queryResult = dataSource; // Eg. Entities converted to Values
    Writer writer = outputWriter; // Eg. to pipe data to another process or to a file

    // (2)
    Function<AcmeValue, String> serialize = valueSerializer.serialize();

    // (3)
    Inputs.iterable( queryResult ).transferTo( Transforms.map( serialize, Outputs.text( writer ) ) );
      [...snip...]

    // (4)
    Reader reader = inputReader;
    List<AcmeValue> values = new ArrayList<AcmeValue>();

    // (5)
    Function<String, AcmeValue> deserialize = valueDeserializer.deserialize( AcmeValue.class );

    // Deserialization of a collection of AcmeValue from a String.
    // One serialized AcmeValue per line.
    // (6)
    Inputs.text( reader ).transferTo( Transforms.map( deserialize, Outputs.collection( values ) ) );
      [...snip...]

}

1. get a handle on a source of values and a Writer,
2. prepare the serialization Function,
3. serialize a collection of values, one serialized value per line,
4. get a handle on a serialized values Reader and create a new empty List of values,
5. prepare the deserialization Function,
6. deserialize a collection of values from read lines.

Any service added, via the ModuleAssembly.addServices(), ModuleAssembly.services() and ModuleAssembly.importServices() methods, will have the ServiceComposite meta type added to it. In Qi4j, when we speak of Services we mean instances of ServiceComposite.

Most programmers are familiar with the term "Service", and after the failure of Object Oriented Programming’s promise to encapsulate all the behavior together with the object’s state, programmers learned that the only way to deal with decoupling and re-use was to make the objects into data containers and deploy services that acted upon those data containers. Very much what functions did on structs back in the C and Pascal days.

Qi4j will bring a lot of the behavior back to the Composite itself, but we still need Services for cross-composite functionality. The Qi4j Service model is fairly simple, yet powerful and flexible enough to accommodate most service-oriented patterns and ability to integrate well with external systems whether they are in-JVM or remote, such as Spring, OSGi, WS-*, Rest and others.

The characteristics of a ServiceComposite compared to other Composite meta types are;

Services in Qi4j are singletons, one instance per definition. That means that there may exist multiple instances of the same service type, but they can not be created on the fly in runtime, but has to be explicitly defined during Assembly.

By default, Services are not instantiated until they are used. This means that the ServiceComposite instance itself will not exist until someone calls a method. If a Service needs to be instantiated when the Module is activated, one need to declare/call the instantiateOnStartup() method on the ServiceDescriptor during the bootstrap.

@Override
public void assemble( ModuleAssembly module )
    throws AssemblyException
{
    ServiceDeclaration service = module.addServices( MyDemoService.class );
    service.instantiateOnStartup();

@Override
public void assemble( ModuleAssembly module )
    throws AssemblyException
{
    ServiceDeclaration service = module.addServices( MyDemoService.class );
      [...snip...]

    service.taggedWith( "Important", "Drain" );

@Service
private List<ServiceReference<MyDemoService>> services;

public MyDemoService locateImportantService()
{
    for( ServiceReference<MyDemoService> ref : services )
    {
        ServiceTags serviceTags = ref.metaInfo( ServiceTags.class );
        if( serviceTags.hasTag( "Important" ) )
        {
            return ref.get();
        }
    }
    return null;
}

Configuration in Qi4j is for Qi4j ServiceComposite only. The Configuration is stored in a visible Entity Store and is therefor runtime modifiable and not static in properties or XML files as in most other dependency injection frameworks.

The Configuration system itself will handle all the details with interfacing with reading and writing the configuration. The normal UnitOfWork management is used, but handled internally by the configuration system.

In Qi4j, Configuration are strongly typed and refactoring-friendly. Configuration is read from the entity store, but if it can not be found, then it will try to bootstrap it from a properties file, with the same name as the ServiceDescriptor.identifiedBy(), which is set during Assembly and defaults to the fully qualified classname of the ServiceComposite type.

public interface MailServiceConfiguration extends ConfigurationComposite
{
    Property<String> hostName();

    Property<Integer> port();
}

@This
private Configuration<MailServiceConfiguration> config;

@Override
public void sendMail( @Email String to, @MinLength( 8 ) String subject, String body )
{
    config.refresh();
    MailServiceConfiguration conf = config.get();
    String hostName = conf.hostName().get();
    int port = conf.port().get();
      [...snip...]

}

    void changeExternalMailService( String hostName, int port );
      [...snip...]

        @Override
        public void changeExternalMailService( String hostName, int port )
        {
            MailServiceConfiguration conf = config.get();
            conf.hostName().set( hostName );
            conf.port().set( port );
            config.save();
        }
          [...snip...]

    }
}

Entities are common in the object oriented programming world, but has never reached the stardom of Class and Object. Instead we have seen many attempts at creating Entities on top of Java, such as EJB (3 incompatible versions), Java Data Objects (JDO, 2 somewhat compatible versions), Java Persistence Architecture (JPA, 2 somewhat compatible versions), Hibernate (4+ somewhat incompatible versions) and many other less known. This seems to suggest that the topic of creating objects that survives over long periods of time is a difficult one.

Eric Evans points out in his book that Entities is a very definite and distinct concept that needs to be handled explicitly. Composite Oriented Programming in general, and Qi4j in particular, takes this point very seriously and makes Entities a central part of the whole system. And likewise, we are convinced that it is not possible to develop domain-knowledge-rich applications without a conscious and well-defined strategy on Entities. So, instead of spending endless hours trying to get Hibernate mapping to do the right thing, we introduce a Composite meta type called EntityComposite, which all entities must derive from, and by doing so automatically become persistable, searchable, have a lifecycle and support nested undoable modifications.

The characteristics of an EntityComposite compared to other Composite meta types are;

A UnitOfWork is a bounded group of operations performed, typically on entities, where these operations are not visible to other threads until the UnitOfWork is completed. It is also possible to discard these operations, as if they were never executed.

	Note
	UnitOfWork has many similarities with the Transaction concept used with RDBMSes. But since Qi4j introduced several deviations to the common definitions of Transactions, we chose to use a different term.

There are several key characteristics of UnitOfWork;

At the moment, they are exclusively used to manipulate EntityComposite composites. All entity operations MUST be done via UnitOfWork, and in fact it is not possible to get this wrong.

TransientComposite is a Composite meta type for all other cases. The main characteristics are;

Mixins are the state-carrying part of a Composite instance. The other Fragments can not retain state between method invocations as they are shared across Composite instances.

public interface BankAccount
{
    Money checkBalance();
}

@Mixins( SomethingMixin.class )
public interface Something
{}

public class SomethingMixin
        implements Something
{
    // State is allowed.

    public void doSomething()
    {
        // do stuff...
    }
}

@Mixins( { StartMixin.class, VehicleMixin.class } )
public interface Car extends Startable, Vehicle
{}

public interface Startable
{
    boolean start();
    void stop();
}

public interface Vehicle
{
    void turn(float angle);

    void accelerate(float acceleration);

    // more methods
}

@Mixins( { StartMixin.class, SpeedMixin.class, CrashResultMixin.class } )
public interface Car extends Startable, Vehicle
{}

public interface Vehicle extends SpeedLocation, Crashable
{
}

public interface SpeedLocation
{
    void turn(float angle);

    void accelerate(float acceleration);
}

public abstract class SpeedMixin
        implements SpeedLocation
{
    // state for speed

    public void accelerate( float acceleration )
    {
        // logic
    }
}

@Mixins( CargoMixin.class )
public interface Cargo extends EntityComposite
{
    String origin();

    String destination();

    void changeDestination( String newDestination );

}

public abstract class CargoMixin
        implements Cargo
{
    @This
    private CargoState state;

    public String origin()
    {
        return state.origin().get();
    }

    public String destination()
    {
        return state.destination().get();
    }

    public void changeDestination( String newDestination )
    {
        state.destination().set( newDestination );
    }
}

public interface CargoState
{
    Property<String> origin();
    Property<String> destination();
}

@AppliesTo( { PropertyMixin.PropertyFilter.class } )
public final class PropertyMixin
    implements InvocationHandler
{
    @State
    private StateHolder state;

    @Override
    public Object invoke( Object proxy, Method method, Object[] args )
        throws Throwable
    {
        return state.propertyFor( method );
    }

    /**
     * Filter Property methods to apply generic Property Mixin.
     */
    public static class PropertyFilter
        implements AppliesToFilter
    {
        @Override
        public boolean appliesTo( Method method, Class<?> mixin, Class<?> compositeType, Class<?> modifierClass )
        {
            return Property.class.isAssignableFrom( method.getReturnType() );
        }
    }
}

Concerns are the equivalent of "around advice" in Aspect Oriented Programming. They are chained into an invocation stack for each Mixin Type method and invoked after the Constraints have been executed. Since they are sitting "around" the Mixin implementation method, they also have a chance to modify the returned result, and even skip calling the underlying Mixin method implementation altogether.

To create a concern, you need to create a class that,

You are allowed to modify both the in-arguments as well as the returned value, including throw exceptions if that is suitable, perhaps for post condition checks.

Return to top

Generic Concern

In classic AOP, all advice are effectively generic. There is no type information in the advice implementation and the pointcut can be defined anywhere in the code, and the implementation uses proxy InvocationHandlers. Qi4j supports this construct as well, and we call it Generic Concern.

Generic Concerns will be added to all methods that the AppliesToFilter evaluates to true. By default, that is all methods.

AppliesToFilters is a mechanism to limit, or direct, which methods that the concern should be added to. You have full control over this selection process, via several mechanisms.

• @AppliesTo annotation can be put on the concern, with either;
• an interface for which the methods should be wrapped, or
• an AppliesToFilter implementation that is consulted during building the invocation stack, or
• an annotation type that must be given on the method.
• Concerns are added only to composites that declares the Concern, either in
• the Composite Type, or
• during assembly in the withConcerns() method.

This means that we can make the following three samples of concerns. First the generic concern that is added to the methods of the JDBC Connection class;

@AppliesTo( java.sql.Connection.class )
public class CacheConcern extends GenericConcern
    implements InvocationHandler
{

We can also use an AppliesToFilter to define which methods should be wrapped with the concern, like this;

@AppliesTo( BusinessAppliesToFilter.class )
public class BusinessConcern extends GenericConcern
    implements InvocationHandler
{
  [...snip...]

public class BusinessAppliesToFilter
    implements AppliesToFilter
{

    @Override
    public boolean appliesTo( Method method, Class<?> mixin, Class<?> compositeType, Class<?> fragmentClass
    )
    {
        return true; // Some criteria for when a method is wrapped with the concern.
    }
}

And finally an example of how to use annotations to mark indvidual methods for being wrapped by the concern.

@AppliesTo( Audited.class )
public class AuditConcern extends GenericConcern
    implements InvocationHandler
{
  [...snip...]

    @Override
    public Object invoke( Object proxy, Method method, Object[] args )
        throws Throwable
    {
        return null;
    }
}

  [...snip...]

@Retention( RetentionPolicy.RUNTIME )
@Target( { ElementType.METHOD } )
@Documented
@InjectionScope
public @interface Audited
{
}

	Note
	Even if a method fulfills the requirement for the concern, if the concern is not declared for the Composite then the concern will NOT be applied.

A little known feature is the DecoratorMixin, which allows any object to become a Mixin. This is useful when for instance the initialization of the object to act as a Mixin is complex, or maybe an instance is shared across many Composites. This functionality is only relevant in Transients, and therefor not available in other Composite meta types.

This is done by declaring the DecoratorMixin on the interface, and add the object to be used via the use() method on the TransientBuilder.

The DecoratorMixin will optimize the invocation for generic mixins, to avoid additional cost of reflection. But otherwise the DecoratorMixin is fairly simple

public interface FooModel
{
    String getBar();
    void setBar(String value);
      [...snip...]

}

@Mixins(View1.Mixin.class)
public interface View1
{
    String bar();

    public class Mixin
        implements View1
    {
        @This
        FooModel model;

        @Override
        public String bar()
        {
            return model.getBar();
        }
    }
}

@Mixins(DecoratorMixin.class)
public interface FooModel

public View1 createView1( FooModel model )
{
    TransientBuilder<View1> builder = module.newTransientBuilder( View1.class );
    builder.use( model );
    return builder.newInstance();
}

@Override
public void assemble( ModuleAssembly module )
    throws AssemblyException
{
    module.transients( View1.class );
    module.transients( View2.class );
    module.transients( FooModel.class );
}

@Test
public void testDecoration()
{
    FooModelImpl model = new FooModelImpl( "Init" );
    View1 view1 = createView1( model );
    View2 view2 = createView2( model );
    assertThat( view1.bar(), equalTo( "Init" ) );
    assertThat( view2.bar(), equalTo( "Init" ) );
    model.setBar( "New Value" );
    assertThat( view1.bar(), equalTo( "New Value" ) );
    assertThat( view2.bar(), equalTo( "New Value" ) );
}

Composite Types Lookup can occurs when you explicitely lookup for a Composite by Type (ex. ServiceFinder.findService(..) methods), when you ask for an injection or when you create a new composite instance.

All theses type lookup start from a Module, are lazy, cached and obey the Qi4j Visibility rules. Type Lookup works equally accross Composite Types with some subtle differences when it comes to Services and Entities.

The Qi4j platform defines an advanced Metrics SPI to capture runtime metrics of Qi4j’s internals as well be used by application code (via this API) to provide production metrics for operations personnel, ensuring healthy state of the applications.

@Service
private MetricsProvider provider;

final BlockingQueue queue = new LinkedBlockingQueue( 20 );
  [...snip...]

MetricsGaugeFactory gaugeFactory = provider.createFactory( MetricsGaugeFactory.class );
MetricsGauge<Integer> gauge = gaugeFactory.registerGauge( getClass(), "Sample Gauge", new MetricsGauge<Integer>()
{
    @Override
    public Integer value()
    {
        return queue.size();
    }
} );

MetricsCounterFactory counterFactory = provider.createFactory( MetricsCounterFactory.class );
MetricsCounter counter = counterFactory.createCounter( getClass(), "Sample Counter" );

MetricsHistogramFactory histoFactory = provider.createFactory( MetricsHistogramFactory.class );
MetricsHistogram histogram = histoFactory.createHistogram( getClass(), "Sample Histogram" );

MetricsMeterFactory meterFactory = provider.createFactory( MetricsMeterFactory.class );
MetricsMeter meter = meterFactory.createMeter( getClass(), "Sample Meter", "requests", TimeUnit.MINUTES );

MetricsTimerFactory timerFactory = provider.createFactory( MetricsTimerFactory.class );
MetricsTimer timer = timerFactory.createTimer( getClass(), "Sample Timer", TimeUnit.SECONDS, TimeUnit.HOURS );

MetricsHealthCheckFactory healthFactory = provider.createFactory( MetricsHealthCheckFactory.class );
MetricsHealthCheck healthCheck = healthFactory.registerHealthCheck(
    getClass(),
    "Sample Healthcheck",
    new MetricsHealthCheck()
    {
        @Override
        public Result check()
            throws Exception
        {
            ServiceStatus status = pingMyService();
            return new Result( status.isOk(), status.getErrorMessage(), status.getException() );
        }
    } );

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

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

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

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

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

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

@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 );
}

@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" );
}

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
public void assemble( ModuleAssembly module )
    throws AssemblyException
{
    RestServerAssembler assembler = new RestServerAssembler();
    assembler.assemble( module );
}

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 effectively leaves the configuration in the properties file where Service Configuration 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).

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 easiest to put a Memory Entity Store in the same module, with Visibility set to module. Sometimes it makes sense to have an additional Configuration layer below the infrastructure layer, which has this setup.

As mentioned above, most entity stores defines a reasonable default Assembler, possibly with some constructor arguments to define certain aspects. An example is the popular JdbmEntityStore, which Assembler can be used like;

@Override
public void assemble( ModuleAssembly module )
    throws AssemblyException
{
    JdbmEntityStoreAssembler assembler = new JdbmEntityStoreAssembler( Visibility.application );
    assembler.assemble( module );
}

Every Qi4j 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
    {
        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 Qi4j 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.

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
{
    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 );
        }

    } );
}

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

private static Energy4Java qi4j;

private static Application application;

public static void main( String[] args )
        throws Exception
{
    // Create a Qi4j 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 );
}

In most cases, you will probably use the AbstractQi4jTest class to simplify starting a Qi4j test instance.

public class HelloTest extends AbstractQi4jTest
{
  [...snip...]

}

This will do all the initialization of a Qi4j runtime instance and create a single layer with a single module in it. What goes into that module is declared in the assembly() method;

@Override
public void assemble( ModuleAssembly module )
    throws AssemblyException
{
    module.values( Hello.class );
}

In this case we declare that we have a ValueComposite of type org.qi4j.tutorials.hello.Hello which looks like

/**
 * This Composite interface declares a simple "Hello World" interface with a single say() method. What is being
 * said is defined in the HelloWorldState interface, which is a private mixin.
 * <p/>
 */
@Mixins( { Hello.HelloWorldMixin.class } )
public interface Hello
{
    String say();

    /**
     * This is the implementation of the say() method.
     */
    public abstract class HelloWorldMixin
        implements Hello
    {
        // @This reference the composite itself, and since HelloWorldState is not part of the public interface,
        // it is a private mixin.
        @This
        private State state;

        @Override
        public String say()
        {
            return state.phrase().get() + " " + state.name().get();
        }
    }

    /**
     * This interface contains only the state of the HelloWorld object.
     */
    public interface State
    {
        @NotEmpty
        @UseDefaults
        Property<String> phrase();

        @NotEmpty
        @UseDefaults
        Property<String> name();
    }
}

The say() method will get the phrase and name from its internal state (the State interface is not magical, it could be named anything).

And then we create the actual test;

@Test
public void givenHelloValueInitializedToHelloWorldWhenCallingSayExpectHelloWorld()
{
    ValueBuilder<Hello> builder = module.newValueBuilder( Hello.class );
    builder.prototypeFor( Hello.State.class ).phrase().set( "Hello" );
    builder.prototypeFor( Hello.State.class ).name().set( "World" );
    Hello underTest = builder.newInstance();
    String result = underTest.say();
    assertThat( result, equalTo( "Hello World" ) );
}

By using the prototypeFor() we can access the hidden, internal and very private state of the ValueComposite. Once the value is created we can reach this directly.

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;

Iterable<Long> data = new ArrayList<Long>();
  [...snip...]


long sum = 0;
for( Long point : data )
{
    sum = sum + point;
}
System.out.println( "The sum is " + sum );

With the Qi4j Core Functional API, you go about it in a different way. The code ends up looking like this;

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 );

And this is just the tip of the iceberg.

The Qi4j Core Functional API are divided a handful of powerful concepts, especially when used together;

TODO

TODO

TODO

TODO

Why does I/O operations in Java have to be so complicated, with nested try/catch/finally and loops? Don’t you wish that the operations could be expressed in a more natural way, such as;

File source = ...
File destination = ...
source.copyTo( destination );

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 Qi4j 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?

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).

So, we want to read a text file and write the content into another text file, right? This is how it is done;

File source = new File( "source.txt" );
File destination = new File( "destination.txt" );
Inputs.text( source ).transferTo( Outputs.text( destination ) );

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 Qi4j Core I/O API. There is nothing you can forget to do.

Another simple example, where we want to count the number of lines in the text;

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() );

The Counter is a Function which gets injected into the transfer.

Ok, so we have seen that the end result can become pretty compelling. How does it work?

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.

This interface simply has a transferTo() method, which takes an Output. The formal definition is;

public interface Input<T, SenderThrowableType extends Throwable>
{
    <ReceiverThrowableType extends Throwable> void transferTo( Output<? super T, ReceiverThrowableType> output )
        throws SenderThrowableType, ReceiverThrowableType;
}

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.

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".

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).

The output interface is likewise fairly simple;

public interface Output<T, ReceiverThrowableType extends Throwable>
{
  [...snip...]

    <SenderThrowableType extends Throwable> void receiveFrom( Sender<? extends T, SenderThrowableType> sender )
        throws ReceiverThrowableType, SenderThrowableType;
}

It can simply receive data from a org.qi4j.io.Sender.

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.

Complicated? Perhaps not trivial to get your head around it at first, but the chain is;

Input passes a Sender to the Output which tells the Sender which Receiver the data should be sent to.

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.

The 3 component in the Qi4j 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.

The current transformations available are;

There are also a couple of handy map functions available, such as

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.

The implementation is very straight forward.

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;
    }
}

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.

Speaking of "progress", so how is the ProgressLog implemented? Glad you asked;

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<String>( logger, format );
        }
        counter = new Counter<T>();
    }

    public ProgressLog( long interval )
    {
        this.interval = interval;
        counter = new Counter<T>();
    }

    @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 + "" );
        }
    }
}

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 Qi4j Core API package.

The filter transform takes a specification implementation which has a very simple method, isSatisfiedBy() (read more about that in Function.

public interface Specification<T>
{
  [...snip...]

    boolean satisfiedBy( T item );
}

The only thing that the implementation need to do is return true or false 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

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;
    }
}

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.

The current set of ready-to-use Input implementations are;

/**
 * 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
 * @param bufferSize
 *
 * @return
 */
public static Input<ByteBuffer, IOException> byteBuffer( final File source, final int bufferSize )
  [...snip...]


/**
 * Read an inputstream using ByteBuffer of a given size.
 *
 * @param source
 * @param bufferSize
 *
 * @return
 */
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
 * @param <T>
 * @param <SenderThrowableType>
 *
 * @return
 */
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
 * @param <T>
 *
 * @return
 */
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
 * @param bufferSize
 *
 * @return
 */
public static Input<ByteBuffer, IOException> output( final Visitor<OutputStream, IOException> outputVisitor,
                                                     final int bufferSize
)

The current set of ready-to-use Input implementations are;

/**
 * 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.
 *
 * @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.
 *
 * @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
 * @param <T>
 *
 * @return
 */
public static <T> Output<ByteBuffer, IOException> byteBuffer( final File file )
  [...snip...]


/**
 * Write ByteBuffer data to an OutputStream.
 *
 * @param stream
 * @param <T>
 *
 * @return
 */
public static <T> 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
 * @param bufferSize
 * @param <T>
 *
 * @return
 */
public static <T> 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>
 *
 * @return
 */
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>
 * @param receiver receiver for this Output
 *
 * @return
 */
public static <T, ReceiverThrowableType extends Throwable> Output<T, ReceiverThrowableType> withReceiver( final Receiver<T, ReceiverThrowableType> receiver )
  [...snip...]


/**
 * Write objects to System.out.println.
 *
 * @return
 */
public static Output<Object, RuntimeException> systemOut()
  [...snip...]


/**
 * Write objects to System.err.println.
 */
public static Output<Object, RuntimeException> systemErr()
  [...snip...]


/**
 * Add items to a collection
 */
public static <T> Output<T, RuntimeException> collection( final Collection<T> collection )

It is very easy to create an extension for the Metrics SPI, simply by implementing the MetricsProvider. If only a subset of the factories/types are supported, there is a convenience adapter call MetricsProviderAdapter in the Metrics SPI package.

An Alarm Point is of an Alarm Class and of an Alarm Category. The Alarm Class defines the severity of the Alarm Point and the Alarm Category defines which part of the system it belongs to. Alarm Category can be extended by the developer, and the package contains the SimpleAlarmCategory as an example, where a Description property has been added.

An Alarm Point also has a System Name, which should be the subsystem or application name.

Alarm Points are triggered and an Alarm Trigger may cause the Alarm Status to change. IF, and only if, the Alarm Status changes, and Alarm Event is generated. The Alarm Model used for an Alarm Point defines which Alarm Status, Alarm Trigger and Alarm Event that are possible.

Alarm Points may also have user-defined properties. These are primarily used for reporting and auditing.

The Alarm Point is the central API for applications. Alarm Points are entities and normally dormant on in the Entity Store. The Alarm Point is a small workflow state-machine, and the Alarm Model associated with the Alarm Point defines the workflow.

Sometimes it is much more convenient to hold on to Alarm Points all the time, instead of reviving them from the Entity Store every time they are to be modified. Therefor, there is a convenience class available who does all the grunt work, called the Alarm Proxy. By creating an Alarm Proxy, all the UnitOfWork handling is done for you. You still need to provide an Identity of the Alarm, which must survive restarts. The code could look something like this;

@Service
private AlarmProxy.Factory factory;

private AlarmProxy myAlarmPoint;
  [...snip...]

@Override
public void assemble( ModuleAssembly module )
    throws AssemblyException
{
    new AlarmSystemAssembler().assemble( module );
      [...snip...]

        myAlarmPoint = factory.create( "This Alarm Identity", "ProActiveCRM", "Sales", AlarmClass.B );
        myAlarmPoint.history().maxSize().set( 20 );
          [...snip...]

        myAlarmPoint.activate();

The Qi4j Alarm library comes with 3 Alarm Models which should be sufficient for most uses. These are based on decades of experience from the industrial automation industry and user feedback.

The Simple Alarm Model is the most basic one, with only two Alarm Status, Normal and Activated. The only Alarm Triggers are activate and deactivate, where activate on a Normal status will bring it to Activated status and an Activated Alarm Event is generated.

The CircuitBreaker can be used directly, even without using anything else from the Qi4j SDK.

Here is a code snippet that demonstrate how to create a CircuitBreaker and how it behave:

// Create a CircuitBreaker with a threshold of 3, a 250ms timeout, allowing IllegalArgumentExceptions
CircuitBreaker cb = new CircuitBreaker( 3, 250, CircuitBreakers.in( IllegalArgumentException.class ) );

  [...snip...]

// Service levels goes down but does not cause a trip
cb.throwable( new IOException() );

  [...snip...]

// Service level goes down and causes a trip
cb.throwable( new IOException() );
cb.throwable( new IOException() );

  [...snip...]

// Turn on the CB again
cb.turnOn();

  [...snip...]

// Service levels goes down and causes a trip
cb.throwable( new IOException() );
cb.throwable( new IOException() );
cb.throwable( new IOException() );

  [...snip...]

// Wait until timeout

  [...snip...]

// CircuitBreaker is back on

As a facility you can make your Services extends AbstractBreakOnThrowable, set them a CircuitBreaker as MetaInfo during assembly and annotate methods with @BreaksCircuitOnThrowable. Doing this will :

Here is how to declare such a Service:

public void assemble( ModuleAssembly module )
        throws AssemblyException
{
    module.services( TestService.class ).setMetaInfo( new CircuitBreaker() );
}
  [...snip...]

public interface TestService
        extends AbstractBreakOnThrowable, ServiceComposite
{

    @BreaksCircuitOnThrowable
    int successfulMethod();

    @BreaksCircuitOnThrowable
    void throwingMethod();

      [...snip...]

}

Remember to annotate methods which when they throw throwables should cause circuit breakers to trip and go back on invocation success with the @BreaksCircuitOnThrowable annotation.

Traceback (most recent call last):
  File "/home/eskatos/.asciidoc/filters/snippet/snippet.py", line 86, in <module>
    for line in snippet(**configuration(indata)):
  File "/home/eskatos/.asciidoc/filters/snippet/snippet.py", line 37, in snippet
    sourceFile = open(PATH_PATTERN % locals())
IOError: [Errno 2] No such file or directory: 'libraries/circuitbreaker/src/test/java/org/qi4j/library/circuitbreaker/jmx/CircuitBreakerManagementTest.java'

A gradle task runSample is defined in this library as a shortcut to run a simple interactive example. You’ll need a MBean client to connect to the sample, VisualVM with its MBean plugin does the job. See Build System if you need some guidance.

You can use theses constraints on Properties or on method arguments. Here are some examples:

@Contains( "foo" ) Property<String> containsString();

@Email Property<String> email();

@URL Property<String> url();

@URI Property<String> uri();

@GreaterThan( 10 ) Property<Integer> greaterThan();

@InstanceOf( List.class ) Property<Collection> instanceOf();

@LessThan( 10 ) Property<Integer> lessThan();

@Matches( "a*b*c*" ) Property<String> matches();

@MaxLength( 3 ) Property<String> maxLength();

@MinLength( 3 ) Property<String> minLength();

@NotEmpty Property<String> notEmptyString();

@NotEmpty Property<Collection> notEmptyCollection();

@NotEmpty Property<List> notEmptyList();

@Range( min = 0, max = 100 ) Property<Integer> range();

@OneOf( { "Bar", "Xyzzy" } ) Property<String> oneOf();

void testParameters(@GreaterThan(10) Integer greaterThan);

To convert Entities to Values, use the EntityToValueService. It is easily assembled:

module.services( EntityToValueService.class );

Let’s say we have an interface defining state:

public interface PersonState
{

    Property<String> firstName();

    Property<String> lastName();

    Property<Date> dateOfBirth();

}

An EntityComposite using the state as a Private Mixin:

@Mixins( PersonMixin.class )
public interface PersonEntity
    extends EntityComposite
{

    String firstName();

    String lastName();

    Integer age();

    @Optional
    Association<PersonEntity> spouse();

    ManyAssociation<PersonEntity> children();

}
  [...snip...]

public static abstract class PersonMixin
    implements PersonEntity
{

    @This
    private PersonState state;
      [...snip...]

}

And a ValueComposite extending this very same state;

public interface PersonValue
    extends PersonState, ValueComposite
{

    @Optional
    Property<String> spouse();

    @Optional
    Property<List<String>> children();

}

Here is how to convert an EntityComposite to a ValueComposite:

EntityToValueService conversion = module.findService( EntityToValueService.class ).get();
PersonValue value = conversion.convert( PersonValue.class, entity );

Associations are converted to Identity strings.

If your Entities and Values cannot use the same state type, you can annotate the Value that is the target of the conversion with the @Unqualified annotation. Then, the lookup of the Value Property will be performed using the unqualified name only, and not via the default of the full qualified name. In other words, this means that the Property may be declared in the different interfaces and still be matched.

Here is an example:

@Unqualified
public interface PersonValue2
    extends ValueComposite
{

    Property<String> firstName();

    Property<String> lastName();

    Property<Date> dateOfBirth();

    @Optional
    Property<String> spouse();

    @Optional
    Property<List<String>> children();

}

public interface FileConfiguration
{
  [...snip...]

    File configurationDirectory();

    File dataDirectory();

    File temporaryDirectory();

    File cacheDirectory();

    File logDirectory();

}

To use it you simply need to declare the FileConfiguration Service in your application assembly:

module.services( FileConfigurationService.class );

These will default to the platform settings, but can be overridden manually, either one-by-one or as a whole.

You can override defaults by adding org.qi4j.library.fileconfig.FileConfiguration_OS.properties files to your classpath where OS is one of win, mac or unix.

You can also override all properties definitions at assembly time by setting a FileConfigurationOverride object as meta info of this service:

FileConfigurationOverride override = new FileConfigurationOverride().
        withConfiguration( confDir ).
        withData( dataDir ).
        withTemporary( tempDir ).
        withCache( cacheDir ).
        withLog( logDir );
module.services( FileConfigurationService.class ).setMetaInfo( override );

And finally, to get the FileConfiguration Service in your application code, simply use the following:

@Service FileConfiguration fileconfig;

EventListeners in HttpService are assembled as Services, so one have to declare a ServiceComposite like this:

@Mixins( FooServletContextListener.class )
public interface FooServletContextListenerService
        extends ServletContextListener, ServiceComposite
{
}

Servlets in HttpService are assembled as Services, so one have to declare a ServiceComposite like this:

@Mixins( HelloWorldServlet.class )
public interface HelloWorldServletService
        extends Servlet, ServiceComposite
{
}

It’s the same for Filters. As an example here is the bundled UnitOfWorkFilterService declaration:

@Mixins( UnitOfWorkFilter.class )
public interface UnitOfWorkFilterService extends Filter, ServiceComposite
{
}

The HTTP library provides a second HttpService that brings SSL support.

new SecureJettyServiceAssembler().assemble( module );
  [...snip...]

addServlets( serve( "/hello" ).with( HelloWorldServletService.class ) ).to( module );
addFilters( filter( "/*" ).through( UnitOfWorkFilterService.class ).on( REQUEST ) ).to( module );

SecureJettyConfiguration config = module.forMixin( SecureJettyConfiguration.class ).declareDefaults();
config.hostName().set( "127.0.0.1" );
config.port().set( HTTPS_PORT );

config.keystorePath().set( SERVER_KEYSTORE_PATH );
config.keystoreType().set( "JCEKS" );
config.keystorePassword().set( KS_PASSWORD );

config.truststorePath().set( TRUSTSTORE_PATH );
config.truststoreType().set( "JCEKS" );
config.truststorePassword().set( KS_PASSWORD );

config.wantClientAuth().set( Boolean.TRUE );

The SLF4J logger used by this library is named "org.qi4j.library.http".

public void assemble( ModuleAssembly module )
        throws AssemblyException
{
  [...snip...]

    new JMXAssembler().assemble( module );

    module.services( JMXConnectorService.class ).instantiateOnStartup();
    module.entities( JMXConnectorConfiguration.class );
    module.forMixin( JMXConnectorConfiguration.class ).declareDefaults().port().set( 1099 );
}

Note that you need to run it with -Dcom.sun.management.jmxremote so that the JVM starts the MBeanServer.

Logging is still not finalized and will need a lot more thought before considered done.

To produce debugging output in your code you just need to add the field

@Optional @This Debug debug;

and then check for null at each usage

if( debug != null )
{
    debug.debug( Debug.NORMAL, "Debugging is made easier." );
}

The Debug mixin can be either added to the composite declaration, or it can be added as a contextual fragment during bootstrap.

You will also need to declare a DebugService to be visible to the composite where the debug output is coming from. And the DebugService in turn will use the default UnitOfWork and associated entity store, which must also be configured and visible.

Tracing is the process of tracking all the methods that has been called. There are two levels of tracing available in Qi4j. Either Trace All or trace where a annotation has been given.

If the TraceAllConcern is added to a composite, and there is a TraceService visible, then all method calls into that composite is traced.

If a subset of the methods want to be traced, you can annotate those methods with @Trace in either the Composite Type interface or the mixin implementation. You will also need to add the TraceConcern to the composite.

public interface ImportantRepository
{
    @Trace
    void addImportantStuff( ImportantStuff stuff );

    @Trace
    void removeImportantStuff( ImportantStuff stuff );

    ImportantStuff findImportantStuff( String searchKey );
}

In the above sample code, the findImportantStuff() method is not traced, whereas the other two will be traced if there is a TraceConcern declared on the composite, and a TraceService visible from that composite.

The fact that each TraceConcern (and TraceAllConcern) will use the TraceService that is visible, allows you to enable or disable tracing per module, simply by adding or removing a TraceService with Visibility.module in each module you want it, or expose Visibility.layer and turn on/off tracing by layers. The TraceConcern has the TraceService as optional.

The recommended way to enable tracing is to use contexual fragments, a feature that allows you to add concerns, sideeffects and mixins to composites during the bootstrap phase instead of hard-coded into the composite declaration.

public void assemble( ModuleAssembly module )
        throws AssemblyException
{
    module.addServices(ImportantRepository.class)
            .withConcerns( TraceAllConcern.class )
            .withMixins( Debug.class );
}

Simply assemble the Service:

public void assemble( ModuleAssembly module )
        throws AssemblyException
{
    module.services( EmbeddedDatabaseService.class );
}

The embedded Neo4J database files are stored in the data directory defined using the FileConfig Library.

@Service EmbeddedDatabaseService neo4jService;

public void doSomething()
{
    GraphDatabaseService db = neo4jService.database();
      [...snip...]

}

interface MyQi4jService
    extends OSGiEnabledService
{
    // ...
}
  [...snip...]

public void assemble( ModuleAssembly module )
    throws AssemblyException
{
    BundleContext bundleContext = // ...
      [...snip...]

    module.services( OSGiServiceExporter.class ).
        setMetaInfo( bundleContext );
    module.services( MyQi4jService.class );
}

public void assemble( ModuleAssembly module )
    throws AssemblyException
{
  [...snip...]

    module.services( OSGiServiceImporter.class ).
        setMetaInfo( new OSGiImportInfo( bundleContext,
                                         MyOSGiService.class,
                                         MyOtherOSGiService.class ) ).
        setMetaInfo( new MyFallbackStrategy() );
}

The fallback strategy is invoked when the OSGi service is not available and a method call is invoked.

This library leverages the Restlet library, so keep its documentation nearby as well.

This library expects the client code to build up handlers on how to react to resources and errors. It is a more declarative approach than a typical ReST client application, which often isn’t HATEOAS at all, and Roy Fielding is upset that ReST now means something else than it was originally intended. We try to be true to Dr. Fielding’s intentions.

Client client =   new Client( Protocol.HTTP );

ContextResourceClientFactory contextResourceClientFactory = module.newObject( ContextResourceClientFactory.class, client );
contextResourceClientFactory.setAcceptedMediaTypes( MediaType.APPLICATION_JSON );

contextResourceClientFactory.setErrorHandler( new ErrorHandler().onError( ErrorHandler.AUTHENTICATION_REQUIRED, new ResponseHandler()
{
    boolean tried = false;

    @Override
    public HandlerCommand handleResponse( Response response, ContextResourceClient client )
    {
            if (tried)
                throw new ResourceException( response.getStatus() );

            tried = true;
            client.getContextResourceClientFactory().getInfo().setUser( new User("rickard", "secret") );

            // Try again
            return refresh();
    }
} ).onError( ErrorHandler.RECOVERABLE_ERROR, new ResponseHandler()
{
    @Override
    public HandlerCommand handleResponse( Response response, ContextResourceClient client )
    {
        // Try to restart
        return refresh();
    }
} ) );

Reference ref = new Reference( "http://localhost:8888/" );
crc = contextResourceClientFactory.newClient( ref );

crc.onResource( new ResultHandler<Resource>()
{
    @Override
    public HandlerCommand handleResult( Resource result, ContextResourceClient client )
    {
        return query( "querywithoutvalue" );
    }
} ).
onQuery( "querywithoutvalue", new ResultHandler<TestResult>()
{
    @Override
    public HandlerCommand handleResult( TestResult result, ContextResourceClient client )
    {
        Assert.assertThat( result.xyz().get(), CoreMatchers.equalTo( "bar" ) );
        return null;
    }
} );

crc.start();

crc.onResource( new ResultHandler<Resource>()
{
    @Override
    public HandlerCommand handleResult( Resource result, ContextResourceClient client )
    {
        return query( "querywithvalue", null );
    }
} ).onProcessingError( "querywithvalue", new ResultHandler<TestQuery>()
{
    @Override
    public HandlerCommand handleResult( TestQuery result, ContextResourceClient client )
    {
        ValueBuilder<TestQuery> builder = module.newValueBuilderWithPrototype( result );

        builder.prototype().abc().set( "abc" + builder.prototype().abc().get() );

        return query( "querywithvalue", builder.newInstance() );
    }
} ).onQuery( "querywithvalue", new ResultHandler<TestResult>()
{
    @Override
    public HandlerCommand handleResult( TestResult result, ContextResourceClient client )
    {
        return command( "commandwithvalue", null );
    }
} ).onProcessingError( "commandwithvalue", new ResultHandler<Form>()
{
    @Override
    public HandlerCommand handleResult( Form result, ContextResourceClient client )
    {
        result.set( "abc", "right" );

        return command( "commandwithvalue", result );
    }
} );

crc.start();

crc.onResource( new ResultHandler<Resource>()
{
    @Override
    public HandlerCommand handleResult( Resource result, ContextResourceClient client )
    {
        return query( "commandwithvalue" );
    }
} ).onQuery( "commandwithvalue", new ResultHandler<Links>()
{
    @Override
    public HandlerCommand handleResult( Links result, ContextResourceClient client )
    {
        Link link = LinksUtil.withId( "right", result );

        return command( link );
    }
} ).onCommand( "commandwithvalue", new ResponseHandler()
{
    @Override
    public HandlerCommand handleResponse( Response response, ContextResourceClient client )
    {
        System.out.println( "Done" );
        return null;
    }
} );

crc.start();
  [...snip...]

crc.onResource( new ResultHandler<Resource>()
{
    @Override
    public HandlerCommand handleResult( Resource result, ContextResourceClient client )
    {
        return query( "commandwithvalue" ).onSuccess( new ResultHandler<Links>()
        {
            @Override
            public HandlerCommand handleResult( Links result, ContextResourceClient client )
            {
                Link link = LinksUtil.withId( "right", result );

                return command( link ).onSuccess( new ResponseHandler()
                {
                    @Override
                    public HandlerCommand handleResponse( Response response, ContextResourceClient client )
                    {
                        System.out.println( "Done" );
                        return null;
                    }
                } );
            }
        } );
    }
} );

crc.start();

crc.onResource( new ResultHandler<Resource>()
{
    @Override
    public HandlerCommand handleResult( Resource result, ContextResourceClient client )
    {
        return query( "commandwithvalue" ).onSuccess( new ResultHandler<Links>()
        {
            @Override
            public HandlerCommand handleResult( Links result, ContextResourceClient client )
            {
                Link link = LinksUtil.withId( "right", result );

                return command( link ).onSuccess( new ResponseHandler()
                {
                    @Override
                    public HandlerCommand handleResponse( Response response, ContextResourceClient client )
                    {
                        System.out.println( "Done" );
                        return null;
                    }
                } );
            }
        } );
    }
} );

crc.start();

The SLF4J Logger used by this library is named "org.qi4j.library.scheduler".

Use SchedulerAssembler to add the Scheduler service to your Application. This Assembler provide a fluent api to programmatically configure configuration defaults and activate the Timeline service assembly that allow to browse in past and future Task runs.

Here is a full example:

new SchedulerAssembler().visibleIn( Visibility.layer )
    .withConfigAssembly( configModuleAssembly )
    .withTimeline()
    .assemble( moduleAssembly );

SchedulerConfiguration defines configuration properties details:

/**
 * @return Number of worker threads, optional and defaults to the number of available cores.
 */
@Optional
Property<Integer> workersCount();

/**
 * @return Size of the queue to use for holding tasks before they are run, optional and defaults to 10.
 */
@Optional
Property<Integer> workQueueSize();

/**
 * @return If the scheduler must stop without waiting for running tasks, optional and defaults to false.
 */
@UseDefaults
Property<Boolean> stopViolently();

To write a schedulable Task, compose an EntityComposite using Task to be able to schedule it.

The Task contract is quite simple:

public interface Task
        extends Runnable
{

    Property<String> name();

    @UseDefaults
    Property<List<String>> tags();

}

Tasks have a mandatory name property and an optional tags property. Theses properties get copied in each TimelineRecord created when the Timeline feature is activated.

The run() method of Tasks is wrapped in a UnitOfWork when called by the Scheduler. Thanks to the UnitOfWork handling in Qi4j, you can split the work done in your Tasks in several UnitOfWorks, the one around the Task#run() invocation will then be paused.

Here is a simple example:

interface MyTaskEntity extends Task, EntityComposite
{

    Property<String> myTaskState();

    Association<AnotherEntity> anotherEntity();
}

abstract class MyTaskMixin implements Runnable
{
    @This MyTaskEntity me;

    public void run()
    {
        me.myTaskState().set(me.anotherEntity().get().doSomeStuff(me.myTaskState().get()));
    }
}

Tasks are scheduled using the Scheduler service. This creates a Schedule associated to the Task that allows you to know if it is running, to change it’s cron expression and set it’s durability.

By default, a Schedule is not durable. In other words, it do not survive an Application restart. To make a Schedule durable, set it’s durable property to true once its scheduled.

There are two ways to schedule a Task using the Scheduler service: once or with a cron expression.

@Service Scheduler scheduler;

public void method()
{
    MyTaskEntity myTask = todo();
    Schedule schedule = scheduler.scheduleOnce( myTask, 10, false ); // myTask will be run in 10 seconds from now
}

Timeline allow to browse in past and future Task runs. This feature is available only if you activate the Timeline assembly in the SchedulerAssembler}, see above.

Once activated, Task success and failures are recorded. Then, the Timeline service allow to browse in past (recorded) and in anticipated (future) Task runs.

Use the following in your code to get a Timeline Service injected:

@Service Timeline timeline;

Here is the actual Timeline contract:

public interface Timeline
{
  [...snip...]

    Iterable<TimelineRecord> getLastRecords( int maxResults );
      [...snip...]

    Iterable<TimelineRecord> getNextRecords( int maxResults );
      [...snip...]

    Iterable<TimelineRecord> getRecords( DateTime from, DateTime to );
      [...snip...]

    Iterable<TimelineRecord> getRecords( long from, long to );
}