Debugging

First of all, if you need logging output from your application to be able to find bugs and to make sure everything is working, you should use Debugging and not Logging in Qi4j.

Debugging is a way for a piece of code to record something. The Debug interface is fairly straight forward.

public interface Debug
{
    int OFF = Integer.MIN_VALUE;
    int LOWLOW = -100;
    int LOW = -50;
    int NORMAL = 0;
    int HIGH = 50;
    int HIGHHIGH = 100;

Property<Integer> debugLevel();

void debug( int level, String message );

void debug( int level, String message, Object param1 );

void debug( int level, String message,
Object param1, Object param2 );

void debug( int level, String message, Object... params );
}

The Debug interface is used as a Private Mixin, meaning you only need to add the Debug member variable with a @This annotation. Qi4j runtime will take care of the rest. Example;

public class SpeakerMixin
implements Speaker
{
@This private Debug dev;

    public void say( String message )
    {
        :
        dev.debug( "Some message: %s ", someArg  );
        :
    }
}

You can also declare a "level" for the Debug used, and only if the DebugService has its level set lower, the output will be generated.

dev.debugLevel().set( Debug.LOW );

This declares that the Debug instance should only forward to the DebugService if the DebugService has it level set to Debug.LOW or lower.

Optional Debugging

It is often the case that we want to disable the debugging code once we ship the product. If there is no DebuggingService visible, then the debugging is effectively disabled, but the calls are still being routed to the Debug mixin which is a small performance hit that we may want to avoid. Is there a simple pattern and mechanism to achieve this? Yes, in a matter of fact it is fairly straight forward.

Mark the Debug member with the @Optional annotation and check at each call that it is not null.

public class SpeakerMixin
implements Speaker
{
@Optional @This private Debug dev;

    public void say( String message )
    {
        :
        if( dev != null )
            dev.debug( "Some message: %s ", someArg  );
        :
    }
}

Then by combining this optionality with the use of context mixins, i.e. mixins that are declared at bootstrap and not directly in the composite type, you have a very flexible system, where each composite can either have debugging always enabled, enabled at bootstrap or not at all. The implementation can always assume the optionality by the pattern above, and leave the choice of debugging to the assembler of the code.

DebugService

Applications should typically not use the DebugService directly. But the DebugService must be declared in a module, like any other service. It is also a configurable service (see below).

The DebugService interface is fairly straight forward.

Qi4j and the Qi4j logo are trademarks of Richard Öberg, Niclas Hedhman and the members of the Qi4j Core Team. See Qi4j licensing for more information.