Custom log site and new black box API

gradle/wrapper/gradle-wrapper.properties

@@ -1,5 +1,5 @@
 distributionBase=GRADLE_USER_HOME
 distributionPath=wrapper/dists
-distributionUrl=https\://services.gradle.org/distributions/gradle-6.1-bin.zip
+distributionUrl=https\://services.gradle.org/distributions/gradle-6.2.1-bin.zip
 zipStoreBase=GRADLE_USER_HOME
 zipStorePath=wrapper/dists

license-report.md

@@ -1,6 +1,6 @@
 
 
-# Dependencies of `io.spine:spine-client:1.4.9`
+# Dependencies of `io.spine:spine-client:1.4.10`
 
 ## Runtime
 1. **Group:** com.google.android **Name:** annotations **Version:** 4.1.1.4
@@ -415,12 +415,12 @@
  The dependencies distributed under several licenses, are used according their commercial-use-friendly license.
 
 
-This report was generated on **Thu Feb 27 18:05:32 EET 2020** using [Gradle-License-Report plugin](https://github.com/jk1/Gradle-License-Report) by Evgeny Naumenko, licensed under [Apache 2.0 License](https://github.com/jk1/Gradle-License-Report/blob/master/LICENSE).
+This report was generated on **Tue Mar 03 16:17:23 EET 2020** using [Gradle-License-Report plugin](https://github.com/jk1/Gradle-License-Report) by Evgeny Naumenko, licensed under [Apache 2.0 License](https://github.com/jk1/Gradle-License-Report/blob/master/LICENSE).
 
 
 
 
-# Dependencies of `io.spine:spine-core:1.4.9`
+# Dependencies of `io.spine:spine-core:1.4.10`
 
 ## Runtime
 1. **Group:** com.google.code.findbugs **Name:** jsr305 **Version:** 3.0.2
@@ -791,12 +791,12 @@ This report was generated on **Thu Feb 27 18:05:32 EET 2020** using [Gradle-Lice
  The dependencies distributed under several licenses, are used according their commercial-use-friendly license.
 
 
-This report was generated on **Thu Feb 27 18:05:33 EET 2020** using [Gradle-License-Report plugin](https://github.com/jk1/Gradle-License-Report) by Evgeny Naumenko, licensed under [Apache 2.0 License](https://github.com/jk1/Gradle-License-Report/blob/master/LICENSE).
+This report was generated on **Tue Mar 03 16:17:24 EET 2020** using [Gradle-License-Report plugin](https://github.com/jk1/Gradle-License-Report) by Evgeny Naumenko, licensed under [Apache 2.0 License](https://github.com/jk1/Gradle-License-Report/blob/master/LICENSE).
 
 
 
 
-# Dependencies of `io.spine.tools:spine-model-assembler:1.4.9`
+# Dependencies of `io.spine.tools:spine-model-assembler:1.4.10`
 
 ## Runtime
 1. **Group:** com.google.android **Name:** annotations **Version:** 4.1.1.4
@@ -1206,12 +1206,12 @@ This report was generated on **Thu Feb 27 18:05:33 EET 2020** using [Gradle-Lice
  The dependencies distributed under several licenses, are used according their commercial-use-friendly license.
 
 
-This report was generated on **Thu Feb 27 18:05:34 EET 2020** using [Gradle-License-Report plugin](https://github.com/jk1/Gradle-License-Report) by Evgeny Naumenko, licensed under [Apache 2.0 License](https://github.com/jk1/Gradle-License-Report/blob/master/LICENSE).
+This report was generated on **Tue Mar 03 16:17:24 EET 2020** using [Gradle-License-Report plugin](https://github.com/jk1/Gradle-License-Report) by Evgeny Naumenko, licensed under [Apache 2.0 License](https://github.com/jk1/Gradle-License-Report/blob/master/LICENSE).
 
 
 
 
-# Dependencies of `io.spine.tools:spine-model-verifier:1.4.9`
+# Dependencies of `io.spine.tools:spine-model-verifier:1.4.10`
 
 ## Runtime
 1. **Group:** com.google.android **Name:** annotations **Version:** 4.1.1.4
@@ -1681,12 +1681,12 @@ This report was generated on **Thu Feb 27 18:05:34 EET 2020** using [Gradle-Lice
  The dependencies distributed under several licenses, are used according their commercial-use-friendly license.
 
 
-This report was generated on **Thu Feb 27 18:05:35 EET 2020** using [Gradle-License-Report plugin](https://github.com/jk1/Gradle-License-Report) by Evgeny Naumenko, licensed under [Apache 2.0 License](https://github.com/jk1/Gradle-License-Report/blob/master/LICENSE).
+This report was generated on **Tue Mar 03 16:17:25 EET 2020** using [Gradle-License-Report plugin](https://github.com/jk1/Gradle-License-Report) by Evgeny Naumenko, licensed under [Apache 2.0 License](https://github.com/jk1/Gradle-License-Report/blob/master/LICENSE).
 
 
 
 
-# Dependencies of `io.spine:spine-server:1.4.9`
+# Dependencies of `io.spine:spine-server:1.4.10`
 
 ## Runtime
 1. **Group:** com.google.android **Name:** annotations **Version:** 4.1.1.4
@@ -2113,12 +2113,12 @@ This report was generated on **Thu Feb 27 18:05:35 EET 2020** using [Gradle-Lice
  The dependencies distributed under several licenses, are used according their commercial-use-friendly license.
 
 
-This report was generated on **Thu Feb 27 18:05:36 EET 2020** using [Gradle-License-Report plugin](https://github.com/jk1/Gradle-License-Report) by Evgeny Naumenko, licensed under [Apache 2.0 License](https://github.com/jk1/Gradle-License-Report/blob/master/LICENSE).
+This report was generated on **Tue Mar 03 16:17:25 EET 2020** using [Gradle-License-Report plugin](https://github.com/jk1/Gradle-License-Report) by Evgeny Naumenko, licensed under [Apache 2.0 License](https://github.com/jk1/Gradle-License-Report/blob/master/LICENSE).
 
 
 
 
-# Dependencies of `io.spine:spine-testutil-client:1.4.9`
+# Dependencies of `io.spine:spine-testutil-client:1.4.10`
 
 ## Runtime
 1. **Group:** com.google.android **Name:** annotations **Version:** 4.1.1.4
@@ -2586,12 +2586,12 @@ This report was generated on **Thu Feb 27 18:05:36 EET 2020** using [Gradle-Lice
  The dependencies distributed under several licenses, are used according their commercial-use-friendly license.
 
 
-This report was generated on **Thu Feb 27 18:05:38 EET 2020** using [Gradle-License-Report plugin](https://github.com/jk1/Gradle-License-Report) by Evgeny Naumenko, licensed under [Apache 2.0 License](https://github.com/jk1/Gradle-License-Report/blob/master/LICENSE).
+This report was generated on **Tue Mar 03 16:17:28 EET 2020** using [Gradle-License-Report plugin](https://github.com/jk1/Gradle-License-Report) by Evgeny Naumenko, licensed under [Apache 2.0 License](https://github.com/jk1/Gradle-License-Report/blob/master/LICENSE).
 
 
 
 
-# Dependencies of `io.spine:spine-testutil-core:1.4.9`
+# Dependencies of `io.spine:spine-testutil-core:1.4.10`
 
 ## Runtime
 1. **Group:** com.google.android **Name:** annotations **Version:** 4.1.1.4
@@ -3067,12 +3067,12 @@ This report was generated on **Thu Feb 27 18:05:38 EET 2020** using [Gradle-Lice
  The dependencies distributed under several licenses, are used according their commercial-use-friendly license.
 
 
-This report was generated on **Thu Feb 27 18:05:40 EET 2020** using [Gradle-License-Report plugin](https://github.com/jk1/Gradle-License-Report) by Evgeny Naumenko, licensed under [Apache 2.0 License](https://github.com/jk1/Gradle-License-Report/blob/master/LICENSE).
+This report was generated on **Tue Mar 03 16:17:29 EET 2020** using [Gradle-License-Report plugin](https://github.com/jk1/Gradle-License-Report) by Evgeny Naumenko, licensed under [Apache 2.0 License](https://github.com/jk1/Gradle-License-Report/blob/master/LICENSE).
 
 
 
 
-# Dependencies of `io.spine:spine-testutil-server:1.4.9`
+# Dependencies of `io.spine:spine-testutil-server:1.4.10`
 
 ## Runtime
 1. **Group:** com.google.android **Name:** annotations **Version:** 4.1.1.4
@@ -3584,4 +3584,4 @@ This report was generated on **Thu Feb 27 18:05:40 EET 2020** using [Gradle-Lice
  The dependencies distributed under several licenses, are used according their commercial-use-friendly license.
 
 
-This report was generated on **Thu Feb 27 18:05:49 EET 2020** using [Gradle-License-Report plugin](https://github.com/jk1/Gradle-License-Report) by Evgeny Naumenko, licensed under [Apache 2.0 License](https://github.com/jk1/Gradle-License-Report/blob/master/LICENSE).
+This report was generated on **Tue Mar 03 16:17:32 EET 2020** using [Gradle-License-Report plugin](https://github.com/jk1/Gradle-License-Report) by Evgeny Naumenko, licensed under [Apache 2.0 License](https://github.com/jk1/Gradle-License-Report/blob/master/LICENSE).

pom.xml

@@ -12,7 +12,7 @@ all modules and does not describe the project structure per-subproject.
 
 <groupId>io.spine</groupId>
 <artifactId>spine-core-java</artifactId>
-<version>1.4.9</version>
+<version>1.4.10</version>
 
 <inceptionYear>2015</inceptionYear>
 
@@ -70,7 +70,7 @@ all modules and does not describe the project structure per-subproject.
   <dependency>
     <groupId>io.spine</groupId>
     <artifactId>spine-base</artifactId>
-    <version>1.4.8</version>
+    <version>1.4.9</version>
     <scope>compile</scope>
   </dependency>
   <dependency>
@@ -82,13 +82,13 @@ all modules and does not describe the project structure per-subproject.
   <dependency>
     <groupId>io.spine.tools</groupId>
     <artifactId>spine-model-compiler</artifactId>
-    <version>1.4.8</version>
+    <version>1.4.9</version>
     <scope>compile</scope>
   </dependency>
   <dependency>
     <groupId>io.spine.tools</groupId>
     <artifactId>spine-plugin-base</artifactId>
-    <version>1.4.8</version>
+    <version>1.4.9</version>
     <scope>compile</scope>
   </dependency>
   <dependency>
@@ -130,7 +130,7 @@ all modules and does not describe the project structure per-subproject.
   <dependency>
     <groupId>io.spine</groupId>
     <artifactId>spine-testlib</artifactId>
-    <version>1.4.8</version>
+    <version>1.4.9</version>
     <scope>test</scope>
   </dependency>
   <dependency>
@@ -142,13 +142,13 @@ all modules and does not describe the project structure per-subproject.
   <dependency>
     <groupId>io.spine.tools</groupId>
     <artifactId>spine-mute-logging</artifactId>
-    <version>1.4.8</version>
+    <version>1.4.9</version>
     <scope>test</scope>
   </dependency>
   <dependency>
     <groupId>io.spine.tools</groupId>
     <artifactId>spine-plugin-testlib</artifactId>
-    <version>1.4.8</version>
+    <version>1.4.9</version>
     <scope>test</scope>
   </dependency>
   <dependency>
@@ -210,12 +210,12 @@ all modules and does not describe the project structure per-subproject.
   <dependency>
     <groupId>io.spine.tools</groupId>
     <artifactId>spine-javadoc-filter</artifactId>
-    <version>1.4.8</version>
+    <version>1.4.9</version>
   </dependency>
   <dependency>
     <groupId>io.spine.tools</groupId>
     <artifactId>spine-protoc-plugin</artifactId>
-    <version>1.4.8</version>
+    <version>1.4.9</version>
   </dependency>
   <dependency>
     <groupId>net.sourceforge.pmd</groupId>

server/src/main/java/io/spine/server/entity/AbstractEntity.java

@@ -22,6 +22,8 @@
 
 import com.google.common.annotations.VisibleForTesting;
 import com.google.common.base.MoreObjects;
+import com.google.common.flogger.FluentLogger;
+import com.google.errorprone.annotations.OverridingMethodsMustInvokeSuper;
 import com.google.errorprone.annotations.concurrent.LazyInit;
 import com.google.protobuf.Any;
 import com.google.protobuf.Message;
@@ -34,17 +36,23 @@
 import io.spine.server.entity.model.EntityClass;
 import io.spine.server.entity.rejection.CannotModifyArchivedEntity;
 import io.spine.server.entity.rejection.CannotModifyDeletedEntity;
+import io.spine.server.log.HandlerLifecycle;
+import io.spine.server.log.HandlerLog;
+import io.spine.server.model.HandlerMethod;
 import io.spine.string.Stringifiers;
 import io.spine.validate.ConstraintViolation;
 import io.spine.validate.Validate;
 import org.checkerframework.checker.nullness.qual.MonotonicNonNull;
+import org.checkerframework.checker.nullness.qual.Nullable;
 
 import java.util.List;
 import java.util.Objects;
 import java.util.function.Function;
+import java.util.logging.Level;
 
 import static com.google.common.base.Preconditions.checkNotNull;
 import static com.google.common.base.Preconditions.checkState;
+import static io.spine.logging.Logging.loggerFor;
 import static io.spine.util.Exceptions.newIllegalArgumentException;
 import static io.spine.validate.Validate.checkValid;
 
@@ -59,9 +67,9 @@
 @SuppressWarnings({
         "SynchronizeOnThis" /* This class uses double-check idiom for lazy init of some
             fields. See Effective Java 2nd Ed. Item #71. */,
-        "AbstractClassWithoutAbstractMethods",
         "ClassWithTooManyMethods"})
-public abstract class AbstractEntity<I, S extends EntityState> implements Entity<I, S> {
+public abstract class AbstractEntity<I, S extends EntityState>
+        implements Entity<I, S>, HandlerLifecycle {
 
     /**
      * Lazily initialized reference to the model class of this entity.
@@ -108,6 +116,8 @@ public abstract class AbstractEntity<I, S extends EntityState> implements Entity
      */
     private volatile boolean lifecycleFlagsChanged;
 
+    private @Nullable HandlerLog handlerLog;
+
     /**
      * Creates a new instance with the zero version and cleared lifecycle flags.
      *
@@ -508,6 +518,42 @@ public Timestamp whenModified() {
         return version.getTimestamp();
     }
 
+    @OverridingMethodsMustInvokeSuper
+    @Override
+    public void beforeInvoke(HandlerMethod<?, ?, ?, ?> method) {
+        checkNotNull(method);
+        FluentLogger logger = loggerFor(getClass());
+        this.handlerLog = new HandlerLog(logger, method);
+    }
+
+    @OverridingMethodsMustInvokeSuper
+    @Override
+    public void afterInvoke(HandlerMethod<?, ?, ?, ?> method) {
+        this.handlerLog = null;
+    }
+
+    /**
+     * Obtains a new fluent logging API at the given level.
+     *
+     * <p>If called from within a handler method, the resulting log will reference the handler
+     * method as the log site. Otherwise, equivalent to
+     * {@code Logging.loggerFor(getClass()).at(logLevel)}.
+     *
+     * @param logLevel
+     *         the log level
+     * @return new fluent logging API
+     * @apiNote This method mirrors the declaration of
+     *         {@link io.spine.server.log.LoggingEntity#at(Level)}. It is recommended to implement
+     *         the {@link io.spine.server.log.LoggingEntity} interface and use the underscore
+     *         logging methods instead of calling {@code at(..)} directly.
+     * @see io.spine.server.log.LoggingEntity
+     */
+    public final FluentLogger.Api at(Level logLevel) {
+        return handlerLog != null
+               ? handlerLog.at(logLevel)
+               : loggerFor(getClass()).at(logLevel);
+    }
+
     @Override
     public boolean equals(Object o) {
         if (this == o) {

server/src/main/java/io/spine/server/log/HandlerLifecycle.java

@@ -0,0 +1,74 @@
+/*
+ * Copyright 2020, TeamDev. All rights reserved.
+ *
+ * Redistribution and use in source and/or binary forms, with or without
+ * modification, must retain the above copyright notice and the following
+ * disclaimer.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+ * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+ * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+ * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+ * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+ * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+ * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+ * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+ * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ */
+
+package io.spine.server.log;
+
+import io.spine.server.model.HandlerMethod;
+
+/**
+ * Callbacks for a {@link HandlerMethod} invocation.
+ *
+ * <p>If the target of the method implements {@code HandlerLifecycle}, it is invoked alongside
+ * handler method. For example:
+ * <pre>
+ * class SignUpSubscriber extends AbstractEventSubscriber implements HandlerLifecycle {
+ *
+ *    {@literal @Subscribe}
+ *     void on(UserSignedUp event) {
+ *         // ...
+ *     }
+ *
+ *    {@literal @Override}
+ *     public void beforeInvoke(HandlerMethod<?, ?, ?, ?> method) {
+ *         // ...
+ *     }
+ *
+ *    {@literal @Override}
+ *     public void afterInvoke(HandlerMethod<?, ?, ?, ?> method) {
+ *         // ...
+ *     }
+ * }
+ * </pre>
+ *
+ * <p>When a {@code UserSignedUp} event is dispatched to the {@code SignUpSubscriber},
+ * the invocation order goes as follows:
+ * <ol>
+ *     <li>{@code beforeInvoke([instance representing on(UserSignedUp) method])}.
+ *     <li>{@code on(UserSignedUp)}.
+ *     <li>{@code afterInvoke([instance representing on(UserSignedUp) method])}.
+ * </ol>
+ */
+public interface HandlerLifecycle {
+
+    /**
+     * A callback for a handler method invocation start.
+     *
+     * <p>The handler method is invoked immediately after this method.
+     */
+    void beforeInvoke(HandlerMethod<?, ?, ?, ?> method);
+
+    /**
+     * A callback for a handler method invocation end.
+     *
+     * <p>This method is invoked immediately after the handler method, even if it has thrown
+     * an exception.
+     */
+    void afterInvoke(HandlerMethod<?, ?, ?, ?> method);
+}