Additions to the SLF4J fluent API

[ceki]

There has been a request to add support for primitive types in addArgument and addKeyValue methods in LoggingEventBuilder.

Moreover, it might be reasonable to add shorter synonyms for addArgument() and addKeyValue() methods, such as arg() and kvp().

For more details see LoggingEventBuilder javadocs

See also issues/375

[ceki]

Additional methods were added to support primitive adding primitive types as arguments.

See the changes to LoggingEventBuilder in commit 154b4e4 for details.

[sabroe]

I have a proposition of another nature. For how to augment the existing SLF4J. Which I would like to show.

I can enhance and augment the existing LoggingEventBuilder. Without any control of the inner workings of the SLF4J API, which I very much prefer as a basis for my coding projects, and without interferring with its functionality.

Things that are easy to use often have a more complex definition. A definition may open up for enhancing and expanding, which may lead to something simpler in its usage, given that you control its point-of-origin.

A straightforward usage of the existing SLF4J API may look like this:

@Slf4j
class A {
    void run() {
        log.atDebug().setMessage("Hello, {}!").addArgument("World").log();
    }
}

An augmented usage can appear like this:

@Slf4j
class B {
    void execute() {
        Scribers.of(log.atInfo()).setMessage("Hello, {}!").addArgument("World").log();
        Scribers.of(log.atInfo()).message("Hello, {}!").arg("World").log();
        Scribers.of(log.atInfo()).m("Hello, {}!").a("World").l();
    }
}

I like the original LoggingEventBuilder -- but to do what I do I need an application of the self-referential generics pattern to method return types. This I cannot introduce since I cannot make changes to the SLF4J API. But I can do something else - I can replicate the interface into my private instance:

public interface LoggingEventBuilderEx<S extends LoggingEventBuilderEx<S>> {
    S setCause(Throwable throwable);
    S addMarker(Marker marker);
    S addArgument(Object o);
    S addArgument(Supplier<?> supplier);
    S addKeyValue(String s, Object o);
    S addKeyValue(String s, Supplier<Object> supplier);
    S setMessage(String s);
    S setMessage(Supplier<String> supplier);
    void log();
    void log(String s);
    void log(String s, Object o);
    void log(String s, Object o, Object o1);
    void log(String s, Object... objects);
    void log(Supplier<String> supplier);
}

Then I proceed and say that I want some basic aliases, making log-lines shorter:

public interface LoggingEventBuilderExAlias<S extends LoggingEventBuilderExAlias<S>> extends LoggingEventBuilderEx<S>{
    default S cause(Throwable throwable) {
        return setCause(throwable);
    }
    default S mark(Marker marker) {
        return addMarker(marker);
    }
    default S arg(Object o) {
        return addArgument(o);
    }
    default S arg(Supplier<?> supplier) {
        return addArgument(supplier);
    }
    default S key(String s, Object o) {
        return addKeyValue(s,o);
    }
    default S key(String s, Supplier<Object> supplier) {
        return addKeyValue(s,supplier);
    }
    default S message(String s) {
        return setMessage(s);
    }
    default S message(Supplier<String> supplier) {
        return setMessage(supplier);
    }
}

In parallel with this, I add methods with a much more aggressive, short naming -- not to the liking of everyone, possibly myself included --:

public interface LoggingEventBuilderExAliasAggressive<S extends LoggingEventBuilderExAliasAggressive<S>> extends LoggingEventBuilderEx<S>{
    default S c(Throwable throwable) {
        return setCause(throwable);
    }
    default S x(Marker marker) {
        return addMarker(marker);
    }
    default S a(Object o) {
        return addArgument(o);
    }
    default S a(Supplier<?> supplier) {
        return addArgument(supplier);
    }
    default S k(String s, Object o) {
        return addKeyValue(s,o);
    }
    default S k(String s, Supplier<Object> supplier) {
        return addKeyValue(s,supplier);
    }
    default S m(String s) {
        return setMessage(s);
    }
    default S m(Supplier<String> supplier) {
        return setMessage(supplier);
    }
    default void l() {
        log();
    }
}

The two alias-objects know nothing about each other, nor does the root interface LoggingEventBuilderEx with the self-referential return types know about any of the two alias-objects.

The return type can be used to tie these interfaces together so they can be used as one, which may be defined like this:

public interface Scriber<B extends LoggingEventBuilder> extends LoggingEventBuilderEx<Scriber<B>>,LoggingEventBuilderExAlias<Scriber<B>>,LoggingEventBuilderExAliasAggressive<Scriber<B>> {
    ...
}

What is left is to control the point-of-origin. In comes the Scribers object, an utility object for Scriber instances, as shown in the previous B example.

Now, if I become sad about my two sets of aliases then it is within reach to dump them again. The root interface LoggingEventBuilderEx continues to exist. But I need to replace Scriber and Scribers to get a new point-of-origin for my sub-types of LoggingEventBuilderEx.

References:

1. ScribersTest
2. LoggingEventBuilderEx
3. LoggingEventBuilderExAlias
4. LoggingEventBuilderExAliasAggressive
5. Scriber
6. JavaDoc//Topp Standard Logging Assistance For SLF4J
7. pkg:maven/com.yelstream.topp.standard/topp-standard-log-assist-slf4j@0.2.0

Please note that while I am trying to show an example of a different path, which I am sure may trigger additional thoughts, I am not really commenting upon the 2.1.x-alpha version (besides, it may be around 12 months too late). What I am saying is that a complex definition can lead to a simple usage.

The definition of LoggingEventBuilderEx has a lot of benefit to it. The reason that it is possible to succeed with a somewhat complex definition using the self-referential generics pattern, is that usages do not refer directly to this, but the simpler sub-type Scriber -- it could have avoided using any generics, the reference to the native LoggingEventBuilder.

As one last thing, beyond adding new methods for convenience, in which case controlling the point-of-origin appears as an ill-advised burden, I can see other types of integration with a logging API like SLF4J, like what I so far have called "rate-limited logging", which makes a new point-of-origin a much welcome point-of-integration -- possibly allowing for the chaining of different actions, responsiblities implemented and uphold by different libraries, into one. While keeping log-statements within one line of source code.

Who says that all our interfaces should be equal, or dictate if I am supposed to use Lombok @Slf4j or not, or put obstacles in the way of doing nice things with SLF4J, let alone having it as a preference for all Java libraries, even though that some application frameworks of newer date tends to try to promote some really poor log frameworks, no names mentioned, with which we do not want to be associated ?

There is quite a lot to be said about this.