There are 4 types of Fragments in Zest;

There are 4 Composite meta types. Each of these have very different characteristics and it is important to understand these, so the right meta type is used for the right purpose.

In versions of Zest™ prior to 2.0 (then Qi4j), composite types had to extend one of these 4 meta types, but in 2.0 and later, the meta type interface is added dynamically during Assembly. We can therefor get rid of a lot of additional types, and use Zest-free interfaces directly;

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

}

and declare it with;

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

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

The ValueSerialization mechanism apply to the following object types :

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

Plain Values can be one of :

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 ;

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 ;

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

}

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

}

The configuration for a service is well supported in Zest. See the Service Configuration chapter for details.

Services are activated (injected and instantiated) either on application start-up, or upon first use. This is controlled by calling instantiateOnStartup(), this way;

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

If this method is not called during assembly, the activation will occur on first service usage.

Passivation occurs when a Module is deactivated, typically because the whole application is shutting down. Passivation occurs in the reverse order of the activation, to ensure that dependent services are still available for a passivating service.

Activators can be assembled with Services to manage their activation. The easiest way is to implement the ServiceActivation interface directly in the ServiceComposite;

@Mixins( MyActivationMixin.class )
public static interface MyActivationDemoService
    extends ServiceComposite, ServiceActivation
{
}

public static class MyActivationMixin
    implements ServiceActivation
{
    @Override
    public void activateService()
        throws Exception
    {
        // Activation code
    }

    @Override
    public void passivateService()
        throws Exception
    {
        // Passivation code
    }
}

The activation code can also be moved outside the composite by using the ServiceActivatorAdapter;

@Activators( MyActivator.class )
public static interface MyOtherActivationDemoService
    extends ServiceComposite
{
}

public static class MyActivator
    extends ServiceActivatorAdapter<MyOtherActivationDemoService>
{
    @Override
    public void afterActivation( ServiceReference<MyOtherActivationDemoService> activated )
        throws Exception
    {
        // Activation code
    }

    @Override
    public void beforePassivation( ServiceReference<MyOtherActivationDemoService> passivating )
        throws Exception
    {
        // Passivation code
    }
}

Activators can be registered on Service assembly too, this way;

@Override
public void assemble( ModuleAssembly module )
{
    module.services( MyDemoService.class ).withActivators( MyActivator.class );
}

Activators assembled with the service will get their beforeActivation and afterActivation methods called around the ServiceComposite activation and their beforePassivation and afterPassivation around the ServiceComposite passivation. Member injection and constructor initialization occur during the activation. The ServiceComposite can be used from the afterActivation to the beforePassivation method.

Services has an Identity, which drives the Service Configuration system and can be used to lookup a particular service instance. Services can also be arbitrarily tagged, via the ServiceDescriptor. Example;

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

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

Tags are useful inside the application code to locate a particular service instance, in case we have many. For instance;

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

The Configuration type is simply listing the properties that are available. The standard rules on @UseDefaults and @Optional applies. Example;

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

    Property<Integer> port();
}

It is important to remember that Configuration is not static values that are set prior to application start-up and therefor applications should not cache the values retrieved forever, but consciously know when the configuration should be re-read.

Configuration is injected via the @This injection scope. One reasonable strategy is to read the configuration on service activation, so by deactivating/reactivating a service, the user have a well-defined behavior to know how configuration changes take effect. Example;

@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...]

}

Configuration is modifiable, and after the modifications have been made, the save() method on the Configuration type must be called. Example;

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

    }
}

UnitOfWork is associated with a thread, and can only be transferred to another thread by a relatively complex operation of pausing a UnitOfWork in one thread, then hand over the UnitOfWork to the other thread and resume it there. Don’t do it!

UnitOfWork is available from the Module, and from the Module you request either a new UnitOfWork or asking for the _current one. Current UnitOfWork means the UnitOfWork that was created earlier within the same thread. So, typically most entity manipulation code only request the current UnitOfWork and the management of creating, completing and aborting the UnitOfWork is handled by the transaction boundary, often in the so called application layer (see Layer)

Since it is very common to have all, or nearly all, methods in the transaction boundary to handle the creation and completion, possibly with retry, in the same class, module or even layer, Zest™ provides annotations to easily declare UnitOfWork concern: @UnitOfWorkPropagation, @UnitOfWorkDiscardOn and @UnitOfWorkRetry

The Mixin Type is the interface that declares the Mixin methods. Each Mixin implementation (the classes defined in the @Mixins annotation of a Composite declaration) implements one or more methods from one or more Mixin Types.

Mixin Type can be very simple, like;

public interface BankAccount
{
    Money checkBalance();
}

Or contain hundreds of methods, subclassed from dozens of super interfaces.

The Mixin Types of a Composite are ;

There is not a 1:1 correlation between Mixin Type and Mixin implementation. One can’t even know if there are more or less of one over the other. That is because a Mixin implementation can implement less than one, one, or more than one Mixin Type.

It is also entirely possible that multiple implementation methods exists for a Mixin Type method. The mixin method resolution algorithm will provide a deterministic behavior of which implementation of a method is chosen. The algorithm is as follows;

For each declared method of all Mixin Types of a Composite;

This means that one Mixin implementation can override a single method that a larger mixin implementation implements together with many other methods. So, just because a mixin implements MixinTypeA.method1() and has an implementation of MixinTypeA.method2(), doesn’t mean that method2() is mapped to that mixin. This is very important to remember. The Envisage tool is capable of visualizing how Mixin Type methods are mapped to implementations.

Mixins are the state holders of the composite instance. Public Mixins are the mixins that are exposed to the outside world via the CompositeType interface.

Each method in the CompositeType interface MUST be backed by a mixin class.

Mixins are declared as annotations on the composite interface.

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

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

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

In the above sample, the SomethingMixin will be made part of the Something composite.

If we have many interfaces defining many methods, that all must be backed by a mixin implementation, we simply list all the mixins required.

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

In the example above, the VehicleMixin would need to deal with all methods defined in the Vehicle interface. That interface could be very large, and could be totally independent concerns. So, instead we should use abstract mixins, which are ordinary mixins but are lacking some methods. This is simply done by declaring the class abstract.

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

Above the SpeedMixin only implements the accelerate() method, and Zest™ will only map that method to this mixin. The other method of the SpeedLocation interface is not satisfied as the example is written and will generate a runtime exception.

Public mixins expose their methods in the composite interface, and this is not always desirable. Zest™ supports Private Mixins, which are only visible within the composite itself. That means that other fragments in the composite can see/use it, but it is not visible to the clients of the composite.

Private Mixins are handled automatically. When Zest™ detects a @This annotation referring to a type that is not defined in the Composite interface, then that is a Private Mixin. The Mixin implementation class, however, must exist in the list of Mixins in the @Mixins annotation. But often, the Private Mixin only list internal Property methods in the Mixin Type, which will be satisfied by the standard PropertyMixin and hence always available.

This is particularly useful in Domain Driven Design, where you only want to expose domain methods, which are defined by the context where they are used. But the state of the Mixin should not be exposed out at all. For instance, if we have the Cargo interface like;

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

    String destination();

    void changeDestination( String newDestination );

}

The interface is defined by its context, and not really exposing the internal state. So in the implementation we probably do something like;

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

So, in this typical case, we don’t need to declare the Mixin for the CargoState, as it only defines Property methods, which are handled by the standard PropertyMixin always present.

Mixins, Concerns and SideEffects can either be "typed" or "generic". A Typed Mixin implementation implements one or more Mixin Type interfaces, and one or more of the methods of those interfaces. A Generic Mixin implementation implements java.lang.reflect.InvocationHandler, and can therefor be matched to any method of any interface. Typically, AppliesTo annotation is used to filter the methods that such Generic Mixin implementation is mapped against, and sometimes Generic Mixin implementations are "last resort".

Experience shows that Generic Mixin implementations are rare, and should only be used in extreme cases. They are less frequent than Generic Concern or Generic SideEffect implementations, but inside the Zest™ API are a couple of Generic Mixin implementations that are always present to make the life of the developer easier, such as PropertyMixin, AssociationMixin, ManyAssociationMixin, NoopMixin. The first 3 are declared on the Composite and EntityComposite interfaces and automatically included if needed. They also serve as excellent example of what they can be used for.

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

Other examples that we have come across;

which seems to indicate that Generic Mixin implementations are likely to be used in integration of other technologies.

Typed Mixin implementations are much preferred in general business logic, as they will be first-class citizens of the IDE as well, for navigation, find usage, refactoring and many other common tasks. This is one of the main advantages of the Zest™ way of doing AOP compared to AspectJ et al, where "weaving" is something bolted onto an application’s classes via regular expressions and known naming conventions, which can change in an instance by a developer being unaware of which PointCuts applies to his code.

As mentioned above, concerns that implements the Mixin Type are called Typed Mixins. They are more common in the business domain, and can be used for many important things in the domain model, such as checking post conditions (i.e. ensure that the state in the entire composite is valid), coordinating services, handling events and much more.

Typed Concerns doesn’t have to implement all the methods in the Mixin Type. By making the class abstract and only implementing the methods of interest, Zest™ runtime will subclass the concern (otherwise not valid for the JVM), but the generated methods will never be invoked.

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. Zest™ 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.

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

The concerns are invoked AFTER all Constraint have been checked. The concerns are executed before the SideEffect are executed in the return path.

The order of execution is defined by the declaration order, interface hierarchy, whether the concern is generic or typed and if they are declared in the interface or declared in the Assembly.

From the perspective of incoming call, i.e. after the <core-api-constraint>> have been checked, the following rules are in place;

Let’s say that we have a model, FooModel, whose implementation is simply a POJO. Several different views shares this the same model instance, so any changes to the model will notify the views.

We start with the FooModel interface;

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

}

and its implementation is not really relevant for this discussion.

Each of the views looks like this;

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

    public class Mixin
        implements View1
    {
        @This
        FooModel model;

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

Note that the mixin is expecting to have the FooModel as being part of the view. This also simplies the mixin, which can for instance add and remove listeners to model updates in lifecycle methods.

But we need an implementation of the FooModel that uses the actual implementation of the FooModel. So we decorate the FooModel with the DecoratorMixin.

@Mixins(DecoratorMixin.class)
public interface FooModel

The DecoratorMixin expects that the implementation is found among the "@Uses" objects, so to create a view we simply do;

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

And there is nothing special in the assembly of this simple example;

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

This can now be validated in a small test;

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

When creating or injecting Objects, Transients or Values the Type Lookup does the following:

First, if Object/Transient/Value Models exactly match the given type, the closest one (Visibility then Assembly order) is returned. Multiple exact matches with the same Visibility are forbidden and result in an AmbiguousTypeException.

Second, if Object/Transient/Value Models match a type assignable to the given type, the closest one (Visibility then Assembly order) is returned. Multiple assignable matches with the same Visibility are forbidden and result in an AmbiguousTypeException.

Entity Types Lookup is splitted in two use cases famillies: Creational usecases and Non-Creational usecases.

Creational Entity Types Lookup

This Type Lookup takes place when creating new Entity instances from a UnitOfWork and behave exactly like Object/Transient/Value Types Lookups.

Non-Creational Entity Types Lookup

This Type Lookup takes place when fetching Entities from an EntityStore or writing queries using the Query API. The Type Lookup is different here to allow polymorphic use of Entities and Queries.

First difference is that this Type Lookup returns an ordered collection instead of a single match.

Returned collection contains, in order, Entity Models that:

Multiple exact matches with the same Visibility are forbidden and result in an AmbiguousTypeException.

Multiple assignable matches are allowed to enable polymorphic fetches and queries.

Service Types Lookup works as follow:

Returned collection contains, in order, ServiceReferences that:

Multiple exact matches with the same Visibility are allowed to enable polymorphic lookup/injection.

Multiple assignable matches with the same Visibility are allowed for the very same reason.

There are quite a lot of different Metrics components available, which are instantiated via factories. There is one factory for each component type, to allow for additional components to be created in the future without breaking compatibility in the existing implementations.

The MetricsProvider is a standard Zest™ Service and simply acquired via the @Service annotation on a field or constructor argument.

@Service
private MetricsProvider provider;

A Gauge is the simplest form of Metric. It is a value that the application sets, which is polled upon request. The application need to provide the implementation of the value() method. Gauges are genericized for type-safe value handling.

A Gauge can represent anything, for instance, thread pool levels, queue sizes and other resource allocations. It is useful to have separate gauges for percentage (%) and absolute numbers of the same resource. Operations are mainly interested in being alerted when threshold are reach as a percentage, as it is otherwise too many numbers to keep track of.

To create a Gauge, you do something like;

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

Timers capture both the length of some execution as well as rate of calls. They can be used to time method calls, or critical sections, or even HTTP requests duration and similar.

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