Custom log site and new black box API

[dmdashenkov]

Log site

Flogger library provides API for changing the header of log messages via LogSite instances. In this PR we add new logging API for all the entities. In a handler method, a user may obtain a preconfigured logger as follows:

class TaskAggregate extends Aggregate<...> implements LoggingEntity {

    @React
    AssigneeRemoved on(UserDeleted event, EventContext ctx) {
        _fine().log("Reacting to an event");
        // ...
    }
}

The resulting log would be similar to:

org.example.TaskAggregate on(UserDeleted, EventContext)
FINE: Reacting to an event

Implementation details

A new interface HandlerLifecycle is introduced. This is a set of callbacks regarding a message handler method invocation.

All the entities which extend AbstractEntity now implement this interface. The framework users may choose to implement it in other message handlers, namely AbstractEventReactor, AbstractEventSubscriber, AbstractCommander, and AbstractCommandHandler subclasses.

The framework users may employ the interface for their own needs, such as tracking the performance of the handler methods, adding extra logging, etc.

Custom actor ID for Black Box Bounded Context

With this PR, we add API for configuring the ID and time zone used to produce actor requests in the Black Box Bounded Context.

In some domains, entities and repositories may rely on the details from the ActorContext, such as the actor ID. One common use case for this is routing commands by the actor ID.

In order to simulate real-life actors in black-box tests, we add the API for changing the actor how posts commands via BlackBoxBoundedContext:

BlackBoxBoundedContext
        .from(builder)
        .withActor(actorId)
        .receivesCommand(..)
        ...

Also, users may change the time zone ID and offset via the in method:

BlackBoxBoundedContext
        .from(builder)
        .in(ZoneIds.of("Europe/Kyiv"), ZoneOffsets.ofHours(2))
        .receivesCommand(..)
        ...

Or do both at the same time via the withActorIn method:

BlackBoxBoundedContext
        .from(builder)
        .withActorIn(actorId, ZoneIds.of("Europe/Kyiv"), ZoneOffsets.ofHours(2))
        .receivesCommand(..)
        ...

Resolves #1226.

[codecov]

Codecov Report

Merging #1242 into master will not change coverage by %.
The diff coverage is n/a.

@@            Coverage Diff            @@
##             master    #1242   +/-   ##
=========================================
  Coverage     91.22%   91.22%           
  Complexity     4763     4763           
=========================================
  Files           620      620           
  Lines         14918    14918           
  Branches        838      838           
=========================================
  Hits          13609    13609           
  Misses         1054     1054           
  Partials        255      255           

[dmdashenkov]

@armiol, PTAL.

[alexander-yevsyukov]

@dmdashenkov, would log tracing improvements work for underscored methods like _debug()?

[dmdashenkov]

@alexander-yevsyukov, no, they wouldn't. These logging configurations only apply to the logs created via the log().at(...) construct. The method is deliberately named log() and not logger() to avoid a naming clash if a user wants to use Logging in their entity.

[armiol]

@dmdashenkov LGTM with some minor comments.

Also, as discussed vocally, we probably need to rename AbstractEntity.log() method into something, which would make it clear, why its invocation result differs from _debug(), _info() and others.

[armiol]

Please document this package.

[armiol]

Do we intend to validate LibraryCardId.reader? If so, then LibraryCardId should also say the reader is required.

[dmdashenkov]

@armiol, PTAL again.

[armiol]

@dmdashenkov as long as you change the PR description, feel free to merge.