diff --git a/jvm/middleware/src/main/java/io/spine/logging/jvm/AbstractLogger.java b/jvm/middleware/src/main/java/io/spine/logging/jvm/AbstractLogger.java index 6c391fce7..5929dc541 100644 --- a/jvm/middleware/src/main/java/io/spine/logging/jvm/AbstractLogger.java +++ b/jvm/middleware/src/main/java/io/spine/logging/jvm/AbstractLogger.java @@ -46,6 +46,7 @@ * * @param * the logging API provided by this logger. + * * @see * Original Java code of Google Flogger */ @@ -81,10 +82,12 @@ protected AbstractLogger(LoggerBackend backend) { /** * Returns a fluent logging API appropriate for the specified log level. + * *

* If a logger implementation determines that logging is definitely disabled at this point then * this method is expected to return a "no-op" implementation of that logging API, which will * result in all further calls made for the log statement to being silently ignored. + * *

* A simple implementation of this method in a concrete subclass might look like: *

{@code
diff --git a/jvm/middleware/src/main/java/io/spine/logging/jvm/JvmApi.java b/jvm/middleware/src/main/java/io/spine/logging/jvm/JvmApi.java
index 474150e2c..fcae9d50e 100644
--- a/jvm/middleware/src/main/java/io/spine/logging/jvm/JvmApi.java
+++ b/jvm/middleware/src/main/java/io/spine/logging/jvm/JvmApi.java
@@ -35,6 +35,7 @@
 /**
  * The basic logging API. An implementation of this API (or an extension of it) will be
  * returned by any fluent logger and forms the basis of the fluent call chain.
+ *
  * 

* In typical usage each method in the API, with the exception of the terminal {@code log()} * statements, will carry out some simple task (which may involve modifying the context of the log @@ -82,9 +83,11 @@ public interface JvmApi> { * is emitted all the rate limiters are reset. In particular for {@code every(N)} this means that * logs need not always be emitted at multiples of {@code N} if other rate limiters are active, * though it will always be at least {@code N}. + * *

* When rate limiting is active, a {@code "skipped"} count is added to log statements to indicate * how many logs were disallowed since the last log statement was emitted. + * *

* If this method is called multiple times for a single log statement, the last invocation will * take precedence. @@ -107,9 +110,11 @@ public interface JvmApi> { * only be emitted once all rate limiters have reached their threshold, and when a log statement * is emitted all the rate limiters are reset. In particular for {@code onAverageEvery(N)} this * means that logs may occurs less frequently than one-in-N if other rate limiters are active. + * *

* When rate limiting is active, a {@code "skipped"} count is added to log statements to indicate * how many logs were disallowed since the last log statement was emitted. + * *

* If this method is called multiple times for a single log statement, the last invocation will * take precedence. @@ -124,6 +129,7 @@ public interface JvmApi> { * specified duration must not be negative, and it is expected, but not required, that it is * constant. In the absence of any other rate limiting, this method always allows the first * invocation of any log statement to be emitted. + * *

* Note that for performance reasons {@code atMostEvery()} is explicitly not intended to * perform "proper" rate limiting to produce a limited average rate over many samples. @@ -136,6 +142,7 @@ public interface JvmApi> { * }

* where {@code currentTimestampNanos} is the timestamp of the current log statement and * {@code lastTimestampNanos} is a time stamp of the last log statement that was emitted. + * *

* The effect of this is that when logging invocation is relatively infrequent, the period * between emitted log statements can be higher than the specified duration. For example @@ -145,6 +152,7 @@ public interface JvmApi> { * } * logging would occur after {@code 0s}, {@code 2.4s} and {@code 4.8s} (not {@code 4.2s}), * giving an effective duration of {@code 2.4s} between log statements over time. + * *

* Providing a zero-length duration (i.e., {@code n == 0}) disables rate limiting and makes this * method an effective no-op. @@ -165,9 +173,11 @@ public interface JvmApi> { * only be emitted once all rate limiters have reached their threshold, and when a log statement * is emitted all the rate limiters are reset. So even if the rate limit duration has expired, it * does not mean that logging will occur. + * *

* When rate limiting is active, a {@code "skipped"} count is added to log statements to indicate * how many logs were disallowed since the last log statement was emitted. + * *

* If this method is called multiple times for a single log statement, the last invocation will * take precedence. @@ -341,6 +351,7 @@ public interface JvmApi> { * @param key the metadata key (expected to be a static constant) * @param value a value to be associated with the key in this log statement. Null values are * allowed, but the effect is always a no-op + * * @throws NullPointerException if the given key is null * @see JvmMetadataKey */ @@ -431,6 +442,7 @@ public interface JvmApi> { * 16 bits is a log statement index to distinguish multiple statements on the same line * (this becomes important if line numbers are stripped from the class file and everything * appears to be on the same line). + * * @param sourceFileName Optional base name of the source file (this value is strictly for * debugging and does not contribute to either equals() or hashCode() behavior). */ @@ -449,11 +461,13 @@ API withInjectedLogSite( * logger.atFine().log("Message: %s", value); * } * } + * *

* Note that if logging is enabled for a log level, it does not always follow that the log * statement will definitely be written to the backend (due to the effects of other methods in * the fluent chain), but if this method returns {@code false} then it can safely be assumed that * no logging will occur. + * *

* This method is unaffected by additional methods in the fluent chain and should only ever be * invoked immediately after the level selector method. In other words, the expression: @@ -466,6 +480,7 @@ API withInjectedLogSite( *

By avoiding passing a separate {@code Level} at runtime to determine "loggability", this API * makes it easier to coerce bytecode optimizers into doing "dead code" removal on sections * guarded by this method. + * *

* If a proxy logger class is supplied for which: *

{@code logger.atFine()}
@@ -486,6 +501,7 @@ API withInjectedLogSite( * * @param message the message template string containing an argument placeholder for each element * of {@code varargs}. + * * @param varargs the non-null array of arguments to be formatted. */ void logVarargs(String message, @Nullable Object[] varargs); @@ -497,6 +513,7 @@ API withInjectedLogSite( *
{@code
    * logger.at(INFO).withCause(error).log();
    * }
+ * *

* However, as it is good practice to give all log statements a meaningful log message, use of this * method should be rare. @@ -505,6 +522,7 @@ API withInjectedLogSite( /** * Logs the given literal string without interpreting any argument placeholders. + * *

* Important: This is intended only for use with hard-coded, literal strings which cannot * contain user data. If you wish to log user-generated data, you should do something like: @@ -524,6 +542,7 @@ API withInjectedLogSite( * Logs a formatted representation of the given parameter, using the specified message template. * The message string is expected to contain argument placeholder terms appropriate to the * logger's choice of parser. + * *

* Note that printf-style loggers are always expected to accept the standard Java printf * formatting characters (e.g. "%s", "%d", etc...) and all flags unless otherwise stated. @@ -816,6 +835,7 @@ void log( /** * An implementation of {@link JvmApi} which does nothing and discards all parameters. + * *

* This class (or a subclass in the case of an extended API) should be returned whenever logging * is definitely disabled (e.g. when the log level is too low). diff --git a/jvm/middleware/src/main/java/io/spine/logging/jvm/JvmLogSite.java b/jvm/middleware/src/main/java/io/spine/logging/jvm/JvmLogSite.java index 0fc88c274..83e7d7227 100644 --- a/jvm/middleware/src/main/java/io/spine/logging/jvm/JvmLogSite.java +++ b/jvm/middleware/src/main/java/io/spine/logging/jvm/JvmLogSite.java @@ -33,14 +33,17 @@ /** * A value type which representing the location of a single log statement. This class is similar to * the {@code StackTraceElement} class but differs in one important respect. + * *

* A LogSite can be associated with a globally unique ID, which can identify a log statement more * uniquely than a line number (it is possible to have multiple log statements appear to be on a * single line, especially for obfuscated classes). + * *

* Log sites are intended to be injected into code automatically, typically via some form of * bytecode rewriting. Each injection mechanism can have its own implementation of {@code LogSite} * adapted to its needs. + * *

* As a fallback, for cases where no injection mechanism is configured, a log site based upon stack * trace analysis is used. However, due to limitations in the information available from @@ -60,6 +63,7 @@ public abstract class JvmLogSite implements LogSiteKey { * injecting it via {@link JvmApi#withInjectedLogSite} which will suppress any further * log site analysis for that log statement. This is also returned if stack trace analysis * fails for any reason. + * *

* If a log statement does end up with invalid log site information, then any fluent logging * methods which rely on being able to look up site-specific metadata will be disabled and @@ -135,6 +139,7 @@ public final String toString() { /** * Creates a log site injected from constants held a class' constant pool. + * *

* Used for compile-time log site injection, and by the agent. * @@ -145,6 +150,7 @@ public final String toString() { * 16 bits is a log statement index to distinguish multiple statements on the same line * (this becomes important if line numbers are stripped from the class file and everything * appears to be on the same line). + * * @param sourceFileName Optional base name of the source file (this value is strictly for * debugging and does not contribute to either equals() or hashCode() behavior). * diff --git a/jvm/middleware/src/main/java/io/spine/logging/jvm/JvmLogSites.java b/jvm/middleware/src/main/java/io/spine/logging/jvm/JvmLogSites.java index 7e9b24480..a6468f002 100644 --- a/jvm/middleware/src/main/java/io/spine/logging/jvm/JvmLogSites.java +++ b/jvm/middleware/src/main/java/io/spine/logging/jvm/JvmLogSites.java @@ -44,6 +44,7 @@ public final class JvmLogSites { * conjunction with the {@link JvmApi#withInjectedLogSite(JvmLogSite)} method to implement * logging helper methods. In some platforms, log site determination may be unsupported, and in * those cases this method will always return the {@link JvmLogSite#INVALID} instance. + * *

* For example (in {@code MyLoggingHelper}): *

{@code
@@ -53,34 +54,40 @@ public final class JvmLogSites {
    *       .logVarargs(message, args);
    * }
    * }
+ * *

* This method should be used for the simple cases where the class in which the logging occurs is * a public logging API. If the log statement is in a different class (not the public logging API) * and the {@code LogSite} instance needs to be passed through several layers, consider using * {@link #logSite()} instead to avoid too much "magic" in your code. + * *

* You should also seek to ensure that any API used with this method "looks like a logging API". * It's no good if a log entry contains a class and method name which doesn't correspond to * anything the user can relate to. In particular, the API should probably always accept the log * message or at least some of its parameters, and should always have methods with "log" in their * names to make the connection clear. + * *

* It is very important to note that this method can be very slow, since determining the log site * can involve stack trace analysis. It is only recommended that it is used for cases where * logging is expected to occur (e.g. {@code INFO} level or above). Implementing a helper method * for {@code FINE} logging is usually unnecessary (it doesn't normally need to follow any * specific "best practice" behavior). + * *

* Note that even when log site determination is supported, it is not defined as to whether two * invocations of this method on the same line of code will produce the same instance, equivalent * instances or distinct instance. Thus you should never invoke this method twice in a single * statement (and you should never need to). + * *

* Note that this method call may be replaced in compiled applications via bytecode manipulation * or other mechanisms to improve performance. * * @param loggingApi the logging API to be identified as the source of log statements (this must * appear somewhere on the stack above the point at which this method is called). + * * @return the log site of the caller of the specified logging API, * or {@link JvmLogSite#INVALID} if the logging API was not found. */ @@ -94,6 +101,7 @@ public static JvmLogSite callerOf(Class loggingApi) { * the {@link JvmApi#withInjectedLogSite(JvmLogSite)} method to implement logging helper * methods. In some platforms, log site determination may be unsupported, and in those cases this * method will always return the {@link JvmLogSite#INVALID} instance. + * *

* For example (in {@code MyLoggingHelper}): *

{@code
@@ -107,21 +115,25 @@ public static JvmLogSite callerOf(Class loggingApi) {
    * 
{@code
    * MyLoggingHelper.logAndSomethingElse(logSite(), "message...");
    * }
+ * *

* Because this method adds an additional parameter and exposes a Flogger specific type to the * calling code, you should consider using {@link #callerOf(Class)} for simple logging * utilities. + * *

* It is very important to note that this method can be very slow, since determining the log site * can involve stack trace analysis. It is only recommended that it is used for cases where * logging is expected to occur (e.g. {@code INFO} level or above). Implementing a helper method * for {@code FINE} logging is usually unnecessary (it doesn't normally need to follow any * specific "best practice" behavior). + * *

* Note that even when log site determination is supported, it is not defined as to whether two * invocations of this method on the same line of code will produce the same instance, equivalent * instances or distinct instance. Thus you should never invoke this method twice in a single * statement (and you should never need to). + * *

* Note that this method call may be replaced in compiled applications via bytecode manipulation * or other mechanisms to improve performance. diff --git a/jvm/middleware/src/main/java/io/spine/logging/jvm/LogContext.java b/jvm/middleware/src/main/java/io/spine/logging/jvm/LogContext.java index e408b0f1a..82dd14a98 100644 --- a/jvm/middleware/src/main/java/io/spine/logging/jvm/LogContext.java +++ b/jvm/middleware/src/main/java/io/spine/logging/jvm/LogContext.java @@ -387,6 +387,7 @@ public String toString() { * * @param level * the log level for this log statement. + * * @param isForced * whether to force this log statement (see {@link #wasForced()} for details). */ @@ -406,8 +407,10 @@ protected LogContext(Level level, boolean isForced) { * * @param level * the log level for this log statement. + * * @param isForced * whether to force this log statement (see {@link #wasForced()} for details). + * * @param timestampNanos * the nanosecond timestamp for this log statement. */ @@ -524,6 +527,7 @@ public final Metadata getMetadata() { * * @param key * the metadata key (see {@link LogData}). + * * @param value * the metadata value. */ @@ -628,6 +632,7 @@ protected final void removeMetadata(JvmMetadataKey key) { * * @param logSiteKey * used to lookup persistent, per log statement, state. + * * @return true if logging should be attempted (usually based on rate limiter state). */ protected boolean postProcess(@Nullable LogSiteKey logSiteKey) { @@ -703,6 +708,7 @@ protected boolean postProcess(@Nullable LogSiteKey logSiteKey) { * * @param status * a rate limiting status, or {@code null} if the rate limiter was not active. + * * @return whether logging will occur based on the current combined state of * active rate limiters. */ diff --git a/jvm/middleware/src/main/java/io/spine/logging/jvm/LogPerBucketingStrategy.java b/jvm/middleware/src/main/java/io/spine/logging/jvm/LogPerBucketingStrategy.java index 6b4dcd0a9..6779b03e2 100644 --- a/jvm/middleware/src/main/java/io/spine/logging/jvm/LogPerBucketingStrategy.java +++ b/jvm/middleware/src/main/java/io/spine/logging/jvm/LogPerBucketingStrategy.java @@ -254,6 +254,7 @@ protected LogPerBucketingStrategy(String name) { * * @param key * a non-null key from a potentially unbounded set of log aggregation keys. + * * @return an immutable value from some known bounded set, which will be held persistently by * internal Flogger data structures as part of the log aggregation feature. If * {@code null} is diff --git a/jvm/middleware/src/main/java/io/spine/logging/jvm/LogSiteMap.java b/jvm/middleware/src/main/java/io/spine/logging/jvm/LogSiteMap.java index 0f824d8e8..0abd12f43 100644 --- a/jvm/middleware/src/main/java/io/spine/logging/jvm/LogSiteMap.java +++ b/jvm/middleware/src/main/java/io/spine/logging/jvm/LogSiteMap.java @@ -50,6 +50,7 @@ * * @param * The value type in the map. + * * @see * Original Java code of Google Flogger */ diff --git a/jvm/middleware/src/main/java/io/spine/logging/jvm/LogSiteStackTrace.java b/jvm/middleware/src/main/java/io/spine/logging/jvm/LogSiteStackTrace.java index c1d558a12..b5fbdf1d8 100644 --- a/jvm/middleware/src/main/java/io/spine/logging/jvm/LogSiteStackTrace.java +++ b/jvm/middleware/src/main/java/io/spine/logging/jvm/LogSiteStackTrace.java @@ -48,6 +48,7 @@ public final class LogSiteStackTrace extends Exception { /** * Creates a synthetic exception to hold a call-stack generated for the log statement itself. + * *

* This exception is never expected to actually get thrown or caught at any point. * diff --git a/jvm/middleware/src/main/java/io/spine/logging/jvm/Middleman.java b/jvm/middleware/src/main/java/io/spine/logging/jvm/Middleman.java index 892cc5308..18a8bc3e2 100644 --- a/jvm/middleware/src/main/java/io/spine/logging/jvm/Middleman.java +++ b/jvm/middleware/src/main/java/io/spine/logging/jvm/Middleman.java @@ -36,11 +36,13 @@ /** * The default implementation of {@link AbstractLogger} which returns the basic {@link JvmApi} * and uses the default parser and system configured backend. + * *

* Note that when extending the logging API or specifying a new parser, you will need to create a * new logger class (rather than extending this one). Unlike the {@link LogContext} class, * which must be extended in order to modify the logging API, this class is not generified and thus * cannot be modified to produce a different logging API. + * *

* The choice to prevent direct extension of loggers was made deliberately to ensure that users of * a specific logger implementation always get the same behavior. @@ -52,6 +54,7 @@ public final class Middleman extends AbstractLogger { /** * The non-wildcard, fully specified, logging API for this logger. Fluent logger implementations * should specify a non-wildcard API like this with which to generify the abstract logger. + * *

* It is possible to add methods to this logger-specific API directly, but it is recommended that * a separate top-level API and LogContext is created, allowing it to be shared by other diff --git a/jvm/middleware/src/main/java/io/spine/logging/jvm/RateLimitStatus.java b/jvm/middleware/src/main/java/io/spine/logging/jvm/RateLimitStatus.java index 2e1eaad55..cf3779830 100644 --- a/jvm/middleware/src/main/java/io/spine/logging/jvm/RateLimitStatus.java +++ b/jvm/middleware/src/main/java/io/spine/logging/jvm/RateLimitStatus.java @@ -78,6 +78,7 @@ * final class CustomRateLimiter extends RateLimitStatus { * private static final LogSiteMap map = * new LogSiteMap() { + * * @Override protected CustomRateLimiter initialValue() { * return new CustomRateLimiter(); * } diff --git a/jvm/middleware/src/main/java/io/spine/logging/jvm/StackSize.java b/jvm/middleware/src/main/java/io/spine/logging/jvm/StackSize.java index cdbb147c7..c4d77c547 100644 --- a/jvm/middleware/src/main/java/io/spine/logging/jvm/StackSize.java +++ b/jvm/middleware/src/main/java/io/spine/logging/jvm/StackSize.java @@ -43,12 +43,14 @@ public enum StackSize { * also be useful for {@code WARNING} level log statements in cases where context is not as * important. For {@code SEVERE} log statements, it is advised to use a stack size of * {@link #MEDIUM} or above. + * *

* Requesting a small stack trace for log statements which occur under normal circumstances is * acceptable, but may affect performance. Consider using * {@link JvmApi#withStackTrace(StackSize)} in conjunction with rate limiting methods, * such as {@link JvmApi#atMostEvery(int, java.util.concurrent.TimeUnit)}, to mitigate * performance issues. + * *

* The current maximum size of a {@code SMALL} stack trace is 10 elements, but this may change. */ @@ -58,9 +60,11 @@ public enum StackSize { * Produces a medium sized stack suitable for providing contextual information for most log * statements at {@code WARNING} or above. There should be enough stack trace elements in a * {@code MEDIUM} stack to provide sufficient debugging context in most cases. + * *

* Requesting a medium stack trace for any log statements which can occur regularly under normal * circumstances is not recommended. + * *

* The current maximum size of a {@code MEDIUM} stack trace is 20 elements, but this may change. */ @@ -70,9 +74,11 @@ public enum StackSize { * Produces a large stack suitable for providing highly detailed contextual information. * This is most useful for {@code SEVERE} log statements which might be processed by external * tools and subject to automated analysis. + * *

* Requesting a large stack trace for any log statement which can occur under normal circumstances * is not recommended. + * *

* The current maximum size of a {@code LARGE} stack trace is 50 elements, but this may change. */ @@ -81,6 +87,7 @@ public enum StackSize { /** * Provides the complete stack trace. This is included for situations in which it is known that * the upper-most elements of the stack are definitely required for analysis. + * *

* Requesting a full stack trace for any log statement which can occur under normal circumstances * is not recommended. @@ -107,6 +114,7 @@ public enum StackSize { /** * Returns the maximum stack depth to create when adding contextual stack information to a log * statement. + * *

* Note that the precise number of stack elements emitted for the enum values might change over * time, but it can be assumed that {@code NONE < SMALL <= MEDIUM <= LARGE <= FULL}. diff --git a/jvm/middleware/src/main/java/io/spine/logging/jvm/backend/BaseMessageFormatter.java b/jvm/middleware/src/main/java/io/spine/logging/jvm/backend/BaseMessageFormatter.java index 2aa1086eb..2ed52e125 100644 --- a/jvm/middleware/src/main/java/io/spine/logging/jvm/backend/BaseMessageFormatter.java +++ b/jvm/middleware/src/main/java/io/spine/logging/jvm/backend/BaseMessageFormatter.java @@ -66,8 +66,10 @@ public class BaseMessageFormatter extends MessageBuilder * * @param data * the log data with the message to be appended. + * * @param out * a buffer to append to. + * * @return the given buffer (for method chaining). */ @CanIgnoreReturnValue diff --git a/jvm/middleware/src/main/java/io/spine/logging/jvm/backend/FormatChar.java b/jvm/middleware/src/main/java/io/spine/logging/jvm/backend/FormatChar.java index 46edd7692..95823aa19 100644 --- a/jvm/middleware/src/main/java/io/spine/logging/jvm/backend/FormatChar.java +++ b/jvm/middleware/src/main/java/io/spine/logging/jvm/backend/FormatChar.java @@ -32,6 +32,7 @@ * An enum representing the printf-like formatting characters that must be supported by all logging * backends. It is important to note that while backends must accept any of these format specifiers, * they are not obliged to implement all specified formatting behavior. + * *

* The default term formatter takes care of supporting all these options when expressed in their * normal '%X' form (including flags, width and precision). Custom messages parsers must convert @@ -46,6 +47,7 @@ public enum FormatChar { * Formats the argument in a manner specific to the chosen logging backend. In many cases this * will be equivalent to using {@code STRING}, but it allows backend implementations to log more * structured representations of known types. + * *

* This is a non-numeric format with an upper-case variant. */ @@ -53,6 +55,7 @@ public enum FormatChar { /** * Formats the argument as a boolean. + * *

* This is a non-numeric format with an upper-case variant. */ @@ -63,6 +66,7 @@ public enum FormatChar { * integral numeric value, providing that {@link Character#isValidCodePoint(int)} returns * true. Note that if the argument cannot be represented losslessly as an integer, it must be * considered invalid. + * *

* This is a non-numeric format with an upper-case variant. */ @@ -70,6 +74,7 @@ public enum FormatChar { /** * Formats the argument as a decimal integer. + * *

* This is a numeric format. */ @@ -77,8 +82,10 @@ public enum FormatChar { /** * Formats the argument as an unsigned octal integer. + * *

* This is a numeric format. + * *

* '(' is only supported for {@link java.math.BigInteger} or {@link java.math.BigDecimal} */ @@ -86,8 +93,10 @@ public enum FormatChar { /** * Formats the argument as an unsigned hexadecimal integer. + * *

* This is a numeric format with an upper-case variant. + * *

* '(' is only supported for {@link java.math.BigInteger} or {@link java.math.BigDecimal} */ @@ -95,6 +104,7 @@ public enum FormatChar { /** * Formats the argument as a signed decimal floating value. + * *

* This is a numeric format. */ @@ -102,6 +112,7 @@ public enum FormatChar { /** * Formats the argument using computerized scientific notation. + * *

* This is a numeric format with an upper-case variant. */ @@ -109,6 +120,7 @@ public enum FormatChar { /** * Formats the argument using general scientific notation. + * *

* This is a numeric format with an upper-case variant. */ @@ -118,6 +130,7 @@ public enum FormatChar { * Formats the argument using hexadecimal exponential form. This formatting option is primarily * useful when debugging issues with the precise bit-wise representation of doubles because no * rounding of the value takes place. + * *

* This is a numeric format with an upper-case variant. */ @@ -178,6 +191,7 @@ private static boolean isLowerCase(char letter) { /** * Returns the lower-case printf style formatting character. + * *

* Note that as this enumeration is not a subset of any other common formatting syntax, it is * not diff --git a/jvm/middleware/src/main/java/io/spine/logging/jvm/backend/FormatOptions.java b/jvm/middleware/src/main/java/io/spine/logging/jvm/backend/FormatOptions.java index 10002b6ea..5438654ac 100644 --- a/jvm/middleware/src/main/java/io/spine/logging/jvm/backend/FormatOptions.java +++ b/jvm/middleware/src/main/java/io/spine/logging/jvm/backend/FormatOptions.java @@ -170,10 +170,13 @@ public static FormatOptions of(int flags, int width, int precision) { * * @param message * the original log message in which the formatting options have been identified. + * * @param pos * the index of the first character to parse. + * * @param end * the index after the last character to be parsed. + * * @return the parsed options instance. * @throws ParseException * if the specified sub-sequence of the string could not be parsed. @@ -293,8 +296,10 @@ private FormatOptions(int flags, int width, int precision) { * @param allowedFlags * A mask of flag values to be retained in the returned instance. Use * {@link #ALL_FLAGS} to retain all flag values, or {@code 0} to suppress all flags. + * * @param allowWidth * specifies whether to include width in the returned instance. + * * @param allowPrecision * specifies whether to include precision in the returned instance. */ @@ -348,6 +353,7 @@ public int getPrecision() { /** * Validates these options according to the allowed criteria and checks for inconsistencies in * flag values. + * *

* Note that there is not requirement for options used internally in custom message parsers to * be @@ -357,8 +363,10 @@ public int getPrecision() { * @param allowedFlags * a bit mask specifying a subset of the printf flags that are allowed for * these options. + * * @param allowPrecision * true if these options are allowed to have a precision value specified. + * * @return true if these options are valid given the specified constraints. */ public boolean validate(int allowedFlags, boolean allowPrecision) { @@ -399,6 +407,7 @@ static boolean checkFlagConsistency(int flags, boolean hasWidth) { /** * Validates these options as if they were being applied to the given {@link FormatChar} and * checks for inconsistencies in flag values. + * *

* Note that there is not requirement for options used internally in custom message parsers to * be @@ -408,6 +417,7 @@ static boolean checkFlagConsistency(int flags, boolean hasWidth) { * * @param formatChar * the formatting rule to check these options against. + * * @return true if these options are valid for the given format. */ public boolean areValidFor(FormatChar formatChar) { @@ -426,6 +436,7 @@ public int getFlags() { /** * Corresponds to printf flag '-' (incompatible with '0'). + * *

* Logging backends may ignore this flag, though it does provide some visual clarity when * aligning @@ -437,6 +448,7 @@ public boolean shouldLeftAlign() { /** * Corresponds to printf flag '#'. + * *

* Logging backends should honor this flag for hex or octal, as it is a common way to avoid * ambiguity when formatting non-decimal values. @@ -447,6 +459,7 @@ public boolean shouldShowAltForm() { /** * Corresponds to printf flag '0'. + * *

* Logging backends should honor this flag, as it is very commonly used to format hexadecimal or * octal values to allow specific bit values to be calculated. @@ -457,6 +470,7 @@ public boolean shouldShowLeadingZeros() { /** * Corresponds to printf flag '+'. + * *

* Logging backends are free to ignore this flag, though it does provide some visual clarity * when @@ -468,6 +482,7 @@ public boolean shouldPrefixPlusForPositiveValues() { /** * Corresponds to printf flag ' '. + * *

* Logging backends are free to ignore this flag, though if they choose to support * {@link #shouldPrefixPlusForPositiveValues()} then it is advisable to support this as well. @@ -478,6 +493,7 @@ public boolean shouldPrefixSpaceForPositiveValues() { /** * Corresponds to printf flag ','. + * *

* Logging backends are free to select the locale in which the formatting will occur or ignore * this flag altogether. @@ -488,6 +504,7 @@ public boolean shouldShowGrouping() { /** * Corresponds to formatting with an upper-case format character. + * *

* Logging backends are free to ignore this flag. */ diff --git a/jvm/middleware/src/main/java/io/spine/logging/jvm/backend/LogData.java b/jvm/middleware/src/main/java/io/spine/logging/jvm/backend/LogData.java index 511740c45..f1c1c0cda 100644 --- a/jvm/middleware/src/main/java/io/spine/logging/jvm/backend/LogData.java +++ b/jvm/middleware/src/main/java/io/spine/logging/jvm/backend/LogData.java @@ -32,6 +32,7 @@ /** * A backend API for determining metadata associated with a log statement. + * *

* Some metadata is expected to be available for all log statements (such as the log level or a * timestamp) whereas other data is optional (class/method name for example). As well providing the diff --git a/jvm/middleware/src/main/java/io/spine/logging/jvm/backend/LoggerBackend.java b/jvm/middleware/src/main/java/io/spine/logging/jvm/backend/LoggerBackend.java index ea606a437..a565bf1f5 100644 --- a/jvm/middleware/src/main/java/io/spine/logging/jvm/backend/LoggerBackend.java +++ b/jvm/middleware/src/main/java/io/spine/logging/jvm/backend/LoggerBackend.java @@ -111,6 +111,7 @@ public abstract class LoggerBackend { * that simply trying to log this again will succeed and error handlers must be careful in how * they handle this instance, its arguments and metadata. References to {@code badData} must * not be held after the {@code handleError} invocation returns. + * * @throws LoggingException to indicate an error which should be propagated into user code. */ public abstract void handleError(RuntimeException error, LogData badData); diff --git a/jvm/middleware/src/main/java/io/spine/logging/jvm/backend/LoggingException.java b/jvm/middleware/src/main/java/io/spine/logging/jvm/backend/LoggingException.java index e438350eb..0f4c160ff 100644 --- a/jvm/middleware/src/main/java/io/spine/logging/jvm/backend/LoggingException.java +++ b/jvm/middleware/src/main/java/io/spine/logging/jvm/backend/LoggingException.java @@ -33,6 +33,7 @@ /** * Exception thrown when a log statement cannot be emitted correctly. This exception should only be * thrown by logger backend implementations which have opted not to handle specific issues. + * *

* Typically a logger backend would only throw {@code LoggingException} in response to issues in * test code or other debugging environments. In production code, the backend should be configured diff --git a/jvm/middleware/src/main/java/io/spine/logging/jvm/backend/MetadataHandler.java b/jvm/middleware/src/main/java/io/spine/logging/jvm/backend/MetadataHandler.java index 6b355e617..ddb9eefd8 100644 --- a/jvm/middleware/src/main/java/io/spine/logging/jvm/backend/MetadataHandler.java +++ b/jvm/middleware/src/main/java/io/spine/logging/jvm/backend/MetadataHandler.java @@ -47,6 +47,7 @@ * * @param * the arbitrary context type. + * * @see * Original Java code of Google Flogger @@ -61,10 +62,13 @@ public abstract class MetadataHandler { * * @param key * the metadata key (not necessarily a "singleton" key). + * * @param value * associated metadata value. + * * @param context * an arbitrary context object supplied to the process method. + * * @param * the key/value type. */ @@ -77,11 +81,14 @@ public abstract class MetadataHandler { * * @param key * the repeatable metadata key. + * * @param values * a lightweight iterator over all values associated with the key. Note that this * instance is read-only and must not be held beyond the scope of this callback. + * * @param context * an arbitrary context object supplied to the process method. + * * @param * the key/value type. */ @@ -112,6 +119,7 @@ protected void handleRepeated(JvmMetadataKey key, Iterator values, C c * * @param defaultHandler * the default handler for unknown keys/values. + * * @param * the context type. */ @@ -124,6 +132,7 @@ public static Builder builder(ValueHandler defaultHandler) { * * @param * the key/value type. + * * @param * the type of the context passed to the callbacks. */ @@ -134,8 +143,10 @@ public interface ValueHandler { * * @param key * the metadata key (not necessarily a "singleton" key). + * * @param value * associated metadata value. + * * @param context * an arbitrary context object supplied to the process method. */ @@ -147,6 +158,7 @@ public interface ValueHandler { * * @param * the key/value type. + * * @param * the type of the context passed to the callbacks. */ @@ -158,9 +170,11 @@ public interface RepeatedValueHandler { * @param key * the repeatable metadata key for which this handler was registered, or an unknown * key if this is the default handler. + * * @param values * a lightweight iterator over all values associated with the key. Note that this * instance is read-only and must not be held beyond the scope of this callback. + * * @param context * an arbitrary context object supplied to the process method. */ @@ -208,6 +222,7 @@ private Builder(ValueHandler defaultHandler) { * * @param defaultHandler * the default handler for unknown repeated keys/values. + * * @return the builder instance for chaining. */ @CanIgnoreReturnValue @@ -223,10 +238,13 @@ public Builder setDefaultRepeatedHandler( * * @param key * the key for which the handler should be invoked (can be a repeated key). + * * @param handler * the value handler to be invoked for every value associated with the key. + * * @param * the key/value type. + * * @return the builder instance for chaining. */ @CanIgnoreReturnValue @@ -245,10 +263,13 @@ public Builder addHandler( * * @param key * the repeated key for which the handler should be invoked. + * * @param handler * the repeated value handler to be invoked once for all associated values. + * * @param * the key/value type. + * * @return the builder instance for chaining. */ @CanIgnoreReturnValue @@ -267,8 +288,10 @@ public Builder addRepeatedHandler( * * @param key * a key to ignore in the builder. + * * @param rest * additional keys to ignore in the builder. + * * @return the builder instance for chaining. */ @CanIgnoreReturnValue @@ -285,6 +308,7 @@ public Builder ignoring(JvmMetadataKey key, JvmMetadataKey... rest) { * * @param keys * the keys to ignore in the builder. + * * @return the builder instance for chaining. */ @CanIgnoreReturnValue @@ -313,8 +337,10 @@ void checkAndIgnore(JvmMetadataKey key) { * * @param key * a key to remove from the builder. + * * @param rest * additional keys to remove from the builder. + * * @return the builder instance for chaining. */ @CanIgnoreReturnValue diff --git a/jvm/middleware/src/main/java/io/spine/logging/jvm/backend/MetadataProcessor.java b/jvm/middleware/src/main/java/io/spine/logging/jvm/backend/MetadataProcessor.java index c27ab6f01..f743e08d1 100644 --- a/jvm/middleware/src/main/java/io/spine/logging/jvm/backend/MetadataProcessor.java +++ b/jvm/middleware/src/main/java/io/spine/logging/jvm/backend/MetadataProcessor.java @@ -103,8 +103,10 @@ public Set> keySet() { * * @param scopeMetadata * Metadata for the current scope (i.e., from {@code ScopedLoggingContext}) + * * @param logMetadata * Metadata extracted from the current log statement (i.e., from {@code LogData}) + * * @return a processor to handle a unified view of the data */ public static MetadataProcessor forScopeAndLogSite(Metadata scopeMetadata, @@ -159,6 +161,7 @@ private MetadataProcessor() { * * @param handler * the metadata handler to be called back + * * @param context * arbitrary context instance to be passed into each callback. */ diff --git a/jvm/middleware/src/main/java/io/spine/logging/jvm/backend/Platform.java b/jvm/middleware/src/main/java/io/spine/logging/jvm/backend/Platform.java index 1c817d06f..b2770968a 100644 --- a/jvm/middleware/src/main/java/io/spine/logging/jvm/backend/Platform.java +++ b/jvm/middleware/src/main/java/io/spine/logging/jvm/backend/Platform.java @@ -194,6 +194,7 @@ public abstract static class LogCallerFinder { * * @param loggerClass * the class containing the log() methods whose caller we need to find. + * * @return the name of the class that called the specified logger. * @throws IllegalStateException * if there was no caller of the specified logged passed on the @@ -208,9 +209,11 @@ public abstract static class LogCallerFinder { * * @param loggerApi * the class containing the log() methods whose caller we need to find. + * * @param stackFramesToSkip * the number of method calls which exist on the stack between the * {@code log()} method and the point at which this method is invoked. + * * @return A log site inferred from the stack, or {@link JvmLogSite#INVALID} if no log site * can be determined. */ @@ -270,8 +273,10 @@ protected ContextDataProvider getContextDataProviderImpl() { * * @param loggerName * the fully qualified logger name (e.g. "com.example.SomeClass") + * * @param level * the level of the log statement being invoked + * * @param isEnabled * whether the logger is enabled at the given level (i.e., the result of calling * {@code isLoggable()} on the backend instance) @@ -293,6 +298,7 @@ public static boolean shouldForceLogging(String loggerName, Level level, boolean * * @param loggerName * the name of the logger + * * @return the custom level or {@code null} */ public static @Nullable Level getMappedLevel(String loggerName) { diff --git a/jvm/middleware/src/main/java/io/spine/logging/jvm/backend/SimpleMessageFormatter.java b/jvm/middleware/src/main/java/io/spine/logging/jvm/backend/SimpleMessageFormatter.java index 27f41c1e3..a1da41f1b 100644 --- a/jvm/middleware/src/main/java/io/spine/logging/jvm/backend/SimpleMessageFormatter.java +++ b/jvm/middleware/src/main/java/io/spine/logging/jvm/backend/SimpleMessageFormatter.java @@ -142,11 +142,14 @@ public static LogMessageFormatter getSimpleFormatterIgnoring( * @param metadataProcessor * snapshot of the metadata to be processed ({@link MetadataProcessor} is * reusable so passing one in can save repeated processing of the same metadata). + * * @param metadataHandler * a metadata handler for intercepting and dispatching metadata during * formatting. + * * @param buffer * destination buffer into which the log message and metadata will be appended. + * * @return the given destination buffer (for method chaining). */ @CanIgnoreReturnValue @@ -172,6 +175,7 @@ public static StringBuilder appendContext( * * @param logData * the log statement data. + * * @return the single logged value as a string. * @throws IllegalStateException * if the log data had arguments to be formatted (i.e. there was a @@ -204,8 +208,10 @@ public static String getLiteralLogMessage(LogData logData) { * * @param logData * the log statement data. + * * @param metadata * the metadata intended to be formatted with the log statement. + * * @param keysToIgnore * a set of metadata keys which are known not to appear in the final formatted * message. diff --git a/jvm/middleware/src/main/java/io/spine/logging/jvm/backend/TemplateContext.java b/jvm/middleware/src/main/java/io/spine/logging/jvm/backend/TemplateContext.java index f6dadf98e..6f1ce3d19 100644 --- a/jvm/middleware/src/main/java/io/spine/logging/jvm/backend/TemplateContext.java +++ b/jvm/middleware/src/main/java/io/spine/logging/jvm/backend/TemplateContext.java @@ -34,6 +34,7 @@ * A context object for templates that allows caches to validate existing templates or create new * ones. If two template contexts are equal (via {@link #equals}) then the templates they produce * are interchangeable. + * *

* Template contexts are created by the frontend and passed through to backend implementations via * the {@link LogData} interface. diff --git a/jvm/middleware/src/main/java/io/spine/logging/jvm/context/SegmentTrie.java b/jvm/middleware/src/main/java/io/spine/logging/jvm/context/SegmentTrie.java index 71253919a..dddb77ac1 100644 --- a/jvm/middleware/src/main/java/io/spine/logging/jvm/context/SegmentTrie.java +++ b/jvm/middleware/src/main/java/io/spine/logging/jvm/context/SegmentTrie.java @@ -247,10 +247,13 @@ public T find(String key) { * * @param k * the key whose parent value we wish to find. + * * @param idx * the index of the closest matching key in the trie ({@code k < keys[idx]}). + * * @param len * the common prefix length between {@code k} and {@code keys[idx]}. + * * @return the value of the nearest parent of {@code k}. */ private T findParent(String k, int idx, int len) { @@ -282,8 +285,10 @@ private T findParent(String k, int idx, int len) { * * @param p * the candidate parent key to check. + * * @param k * the key whose parent we are looking for. + * * @param len * the maximum length of any possible parent of {@code k}. */ @@ -312,11 +317,14 @@ private boolean isParent(String p, String k, int len) { * * @param lhs * first value to compare. + * * @param rhs * second value to compare. + * * @param start * a lower bound for the common prefix length of the given keys, which must be * {@code <= min(lhs.length(), rhs.length())}. + * * @return the common prefix length, encoded to indicate lexicographical ordering. */ private static int prefixCompare(String lhs, String rhs, int start) { diff --git a/jvm/middleware/src/main/java/io/spine/logging/jvm/parameter/BraceStyleParameter.java b/jvm/middleware/src/main/java/io/spine/logging/jvm/parameter/BraceStyleParameter.java index 36ae60437..d27efebb9 100644 --- a/jvm/middleware/src/main/java/io/spine/logging/jvm/parameter/BraceStyleParameter.java +++ b/jvm/middleware/src/main/java/io/spine/logging/jvm/parameter/BraceStyleParameter.java @@ -74,6 +74,7 @@ public class BraceStyleParameter extends Parameter { * * @param index * the index of the argument to be processed. + * * @return the immutable, thread safe parameter instance. */ public static BraceStyleParameter of(int index) { diff --git a/jvm/middleware/src/main/java/io/spine/logging/jvm/parameter/DateTimeParameter.java b/jvm/middleware/src/main/java/io/spine/logging/jvm/parameter/DateTimeParameter.java index f1143cffa..1b22bb6a2 100644 --- a/jvm/middleware/src/main/java/io/spine/logging/jvm/parameter/DateTimeParameter.java +++ b/jvm/middleware/src/main/java/io/spine/logging/jvm/parameter/DateTimeParameter.java @@ -30,6 +30,7 @@ /** * A parameter for formatting date/time arguments. + * *

* This class is immutable and thread safe, as per the Parameter contract. * diff --git a/jvm/middleware/src/main/java/io/spine/logging/jvm/parameter/Parameter.java b/jvm/middleware/src/main/java/io/spine/logging/jvm/parameter/Parameter.java index 11e58c284..7603e1445 100644 --- a/jvm/middleware/src/main/java/io/spine/logging/jvm/parameter/Parameter.java +++ b/jvm/middleware/src/main/java/io/spine/logging/jvm/parameter/Parameter.java @@ -30,10 +30,12 @@ /** * An abstract representation of a parameter for a message template. + * *

* Note that this is implemented as a class (rather than via an interface) because it is very * helpful to have explicit checks for the index values and count to ensure we can calculate * reliable low bounds for the number of arguments a template can accept. + * *

* Note that all subclasses of Parameter must be immutable and thread safe. * @@ -51,6 +53,7 @@ public abstract class Parameter { * * @param options * the format options for this parameter. + * * @param index * the index of the argument processed by this parameter. */ diff --git a/jvm/middleware/src/main/java/io/spine/logging/jvm/parameter/ParameterVisitor.java b/jvm/middleware/src/main/java/io/spine/logging/jvm/parameter/ParameterVisitor.java index dce687fd0..c814212f5 100644 --- a/jvm/middleware/src/main/java/io/spine/logging/jvm/parameter/ParameterVisitor.java +++ b/jvm/middleware/src/main/java/io/spine/logging/jvm/parameter/ParameterVisitor.java @@ -39,6 +39,7 @@ public interface ParameterVisitor { /** * Visits a log message argument with formatting specified by {@code %s}, {@code %d} etc... + * *

* Note that this method may still visit arguments which represent date/time values if the format * is not explicit (e.g. {@code log("time=%s", dateTime)}). @@ -51,6 +52,7 @@ public interface ParameterVisitor { /** * Visits a date/time log message argument with formatting specified by {@code %t} or similar. + * *

* Note that because this method is called based on the specified format (and not the argument * type) it may visit arguments whose type is not a known date/time value. This is necessary to @@ -65,6 +67,7 @@ public interface ParameterVisitor { /** * Visits a log message argument for which formatting has already occurred. This method is only * invoked when non-printf message formatting is used (e.g. brace style formatting). + * *

* This method is intended for use by {@code Parameter} implementations which describe formatting * rules which cannot by represented by either {@link FormatChar} or {@link DateTimeFormat}. This diff --git a/jvm/middleware/src/main/java/io/spine/logging/jvm/parameter/SimpleParameter.java b/jvm/middleware/src/main/java/io/spine/logging/jvm/parameter/SimpleParameter.java index 200308615..f06153a68 100644 --- a/jvm/middleware/src/main/java/io/spine/logging/jvm/parameter/SimpleParameter.java +++ b/jvm/middleware/src/main/java/io/spine/logging/jvm/parameter/SimpleParameter.java @@ -38,6 +38,7 @@ /** * A simple, single argument, parameter which can format arguments according to the rules specified * by {@link FormatChar}. + * *

* This class is immutable and thread safe, as per the Parameter contract. * @@ -75,10 +76,13 @@ private static SimpleParameter[] createParameterArray(FormatChar formatChar) { * * @param index * the index of the argument to be processed. + * * @param formatChar * the basic formatting type. + * * @param options * additional formatting options. + * * @return the immutable, thread safe parameter instance. */ public static SimpleParameter of(int index, FormatChar formatChar, FormatOptions options) { diff --git a/jvm/middleware/src/main/java/io/spine/logging/jvm/parser/BraceStyleMessageParser.java b/jvm/middleware/src/main/java/io/spine/logging/jvm/parser/BraceStyleMessageParser.java index 09a82d32c..74316cd26 100644 --- a/jvm/middleware/src/main/java/io/spine/logging/jvm/parser/BraceStyleMessageParser.java +++ b/jvm/middleware/src/main/java/io/spine/logging/jvm/parser/BraceStyleMessageParser.java @@ -31,6 +31,7 @@ * {@link java.text.MessageFormat MessageFormat}. This is an abstract parser which knows how to * process and extract place-holder terms at a high level, but does not impose its own semantics * on formatting extensions (eg, "{0,number,#.##}"). + * *

* Typically you should not subclass this class, but instead subclass * {@link DefaultBraceStyleMessageParser}, which provides default behavior for simple place-holders. @@ -49,6 +50,7 @@ public abstract class BraceStyleMessageParser extends MessageParser { * Parses a single brace format term from a log message into a message template builder. Note that * the default brace style parser currently does not handle anything other than the simplest "{n}" * forms of parameter specification, and it will treat anything more complex as a parsing error. + * *

* A simple example of a positional parameter: *

@@ -57,6 +59,7 @@ public abstract class BraceStyleMessageParser extends MessageParser {
    * formatStart: -1    │
    * termEnd: 9 ────────╯
    * 
+ * *

* A more complex example with a trailing format specification: *

@@ -72,6 +75,7 @@ public abstract class BraceStyleMessageParser extends MessageParser {
    * @param termStart the index of the initial '{' character that starts the term.
    * @param formatStart the index of the optional formatting substring after the first comma
    *        (which extends to {@code termEnd - 1}) or -1 if there is no formatting substring.
+ *
    * @param termEnd the index after the final '}' character that completes this term.
    */
   abstract void parseBraceFormatTerm(
diff --git a/jvm/middleware/src/main/java/io/spine/logging/jvm/parser/DefaultBraceStyleMessageParser.java b/jvm/middleware/src/main/java/io/spine/logging/jvm/parser/DefaultBraceStyleMessageParser.java
index bf9773f79..347ab7b2d 100644
--- a/jvm/middleware/src/main/java/io/spine/logging/jvm/parser/DefaultBraceStyleMessageParser.java
+++ b/jvm/middleware/src/main/java/io/spine/logging/jvm/parser/DefaultBraceStyleMessageParser.java
@@ -33,6 +33,7 @@
  * mechanism supports the more general "{n,xxx}" form for brace format style logging, the default
  * message parser is currently limited to simple indexed place holders (e.g. "{0}"). This class
  * could easily be extended to support these trailing format specifiers.
+ *
  * 

* Note also that the implicit place holder syntax used by Log4J (i.e. "{}") is not currently * supported, however this may change. Currently an unescaped "{}" term in a log message will cause diff --git a/jvm/middleware/src/main/java/io/spine/logging/jvm/parser/DefaultPrintfMessageParser.java b/jvm/middleware/src/main/java/io/spine/logging/jvm/parser/DefaultPrintfMessageParser.java index e6cfa7085..e23b64756 100644 --- a/jvm/middleware/src/main/java/io/spine/logging/jvm/parser/DefaultPrintfMessageParser.java +++ b/jvm/middleware/src/main/java/io/spine/logging/jvm/parser/DefaultPrintfMessageParser.java @@ -42,6 +42,7 @@ * available in {@code String#format} but can be extended, if desired, for additional behavior * For consistency it is recommended, but not required, that custom printf parsers always extend * from this class. + * *

* This class is immutable and thread safe (and any subclasses must also be so). * diff --git a/jvm/middleware/src/main/java/io/spine/logging/jvm/parser/MessageBuilder.java b/jvm/middleware/src/main/java/io/spine/logging/jvm/parser/MessageBuilder.java index d57f754a0..866209bb7 100644 --- a/jvm/middleware/src/main/java/io/spine/logging/jvm/parser/MessageBuilder.java +++ b/jvm/middleware/src/main/java/io/spine/logging/jvm/parser/MessageBuilder.java @@ -37,6 +37,7 @@ * * @param * The message type being built. + * * @see * Original Java code of Google Flogger @@ -84,9 +85,11 @@ public final int getExpectedArgumentCount() { * @param termStart * the index of the first character in the log message string that was parsed to * form the given parameter. + * * @param termEnd * the index after the last character in the log message string that was parsed to * form the given parameter. + * * @param param * a parameter representing the format specified by the substring of the log message * in the range {@code [termStart, termEnd)}. @@ -104,6 +107,7 @@ public final void addParameter(int termStart, int termEnd, Parameter param) { /** * Adds the specified parameter to the format instance currently being built. This method is to * signify that the parsing of the next parameter is complete. + * *

* Note that each successive call to this method during parsing will specify a disjoint ranges * of @@ -113,9 +117,11 @@ public final void addParameter(int termStart, int termEnd, Parameter param) { * @param termStart * the index of the first character in the log message string that was parsed to * form the given parameter. + * * @param termEnd * the index after the last character in the log message string that was parsed to * form the given parameter. + * * @param param * a parameter representing the format specified by the substring of the log message * in the range {@code [termStart, termEnd)}. diff --git a/jvm/middleware/src/main/java/io/spine/logging/jvm/parser/MessageParser.java b/jvm/middleware/src/main/java/io/spine/logging/jvm/parser/MessageParser.java index d25bb312d..41738e401 100644 --- a/jvm/middleware/src/main/java/io/spine/logging/jvm/parser/MessageParser.java +++ b/jvm/middleware/src/main/java/io/spine/logging/jvm/parser/MessageParser.java @@ -43,11 +43,13 @@ public abstract class MessageParser { /** * Abstract parse method implemented by specific subclasses to modify parsing behavior. + * *

* Note that when extending parsing behavior, it is expected that specific parsers such as * {@link DefaultPrintfMessageParser} or {@link DefaultBraceStyleMessageParser} will be * sub-classed. Extending this class directly is only necessary when an entirely new type of * format needs to be supported (which should be extremely rare). + * *

* Implementations of this method are required to invoke the * {@link MessageBuilder#addParameterImpl} method of the supplied builder once for each diff --git a/jvm/middleware/src/main/java/io/spine/logging/jvm/parser/ParseException.java b/jvm/middleware/src/main/java/io/spine/logging/jvm/parser/ParseException.java index 8ff2cb0c9..c892509b5 100644 --- a/jvm/middleware/src/main/java/io/spine/logging/jvm/parser/ParseException.java +++ b/jvm/middleware/src/main/java/io/spine/logging/jvm/parser/ParseException.java @@ -61,12 +61,16 @@ public final class ParseException extends RuntimeException { * * @param errorMessage * the user error message. + * * @param logMessage * the original log message. + * * @param start * the index of the first character in the invalid section of the log message. + * * @param end * the index after the last character in the invalid section of the log message. + * * @return the parser exception. */ public static ParseException withBounds( @@ -79,10 +83,13 @@ public static ParseException withBounds( * * @param errorMessage * the user error message. + * * @param logMessage * the original log message. + * * @param position * the index of the invalid character in the log message. + * * @return the parser exception. */ public static ParseException atPosition(String errorMessage, String logMessage, int position) { @@ -95,10 +102,13 @@ public static ParseException atPosition(String errorMessage, String logMessage, * * @param errorMessage * the user error message. + * * @param logMessage * the original log message. + * * @param start * the index of the first character in the invalid section of the log message. + * * @return the parser exception. */ public static ParseException withStartPosition( diff --git a/jvm/middleware/src/main/java/io/spine/logging/jvm/parser/PrintfMessageParser.java b/jvm/middleware/src/main/java/io/spine/logging/jvm/parser/PrintfMessageParser.java index 36668c3c0..9b4f5abb8 100644 --- a/jvm/middleware/src/main/java/io/spine/logging/jvm/parser/PrintfMessageParser.java +++ b/jvm/middleware/src/main/java/io/spine/logging/jvm/parser/PrintfMessageParser.java @@ -31,6 +31,7 @@ * {@link String#format}. This is an abstract parser which knows how to * process and extract placeholder terms at a high level, but does not impose its own semantics * for place-holder types. + * *

* Typically you should not subclass this class, but instead subclass * {@link DefaultPrintfMessageParser}, which provides compatibility with {@link String#format}. @@ -61,6 +62,7 @@ static String getSafeSystemNewline() { /** * Parses a single printf-like term from a log message into a message template builder. + * *

* A simple example of an implicit parameter (the argument index is not specified): *

@@ -71,6 +73,7 @@ static String getSafeSystemNewline() {
    * return: 8 ────────╯
    * 
* If this case there is no format specification, so {@code specStart == formatStart}. + * *

* A complex example with an explicit index: *

@@ -89,6 +92,7 @@ static String getSafeSystemNewline() {
    * @param termStart the index of the initial '%' character that starts the term.
    * @param specStart the index of the first format specification character (after any optional
    *        index specification).
+ *
    * @param formatStart the index of the (first) format character in the term.
    * @return the index after the last character of the term.
    */