Fixed javadocs and added documentation

Signed-off-by: David Matějček <david.matejcek@omnifish.ee>
eclipse-ee4j · May 11, 2024 · 115b2df · 115b2df
1 parent 86c9abc
commit 115b2df
Show file tree

Hide file tree

Showing 3 changed files with 27 additions and 9 deletions.
diff --git a/docs/administration-guide/src/main/asciidoc/logging.adoc b/docs/administration-guide/src/main/asciidoc/logging.adoc
@@ -271,6 +271,22 @@ If you edit `logging.properties` manually on an instance managed by the node, it
 overwritten on the next synchronization with DAS.
 ====
 
+[[log-records]]
+
+=== Log Records
+
+Because the automatic detection of caller class and method from stacktrace significantly affects
+performance of the logging system, we added the `org.glassfish.main.jul.classAndMethodDetection.enabled`
+property which affects the `*.printSource` property of formatters.
+
+* If this key is set to true, GJULE will detect the caller class and method from stacktrace,
+which is quite expensive operation affecting logging throughput.
+* If it is set to false, GJULE will not perform such detection. Formatters which use `getSourceClassName`
+or `getSourceMethodName` of the record will receive `null` unless the log record has set these values explicitly.
+* If the property is not set, GJULE makes the decision based on the (`*.printSource` property) - if
+any formatter requires this feature, the feature is enabled. Note that the `*.printSource` property
+must be explicitly set to true in `logging.properties`.
+* It is disabled otherwise.
 
 [[loggers]]
 

diff --git a/...-extension/src/main/java/org/glassfish/main/jul/cfg/GlassFishLogManagerConfiguration.java b/...-extension/src/main/java/org/glassfish/main/jul/cfg/GlassFishLogManagerConfiguration.java
@@ -100,13 +100,14 @@ public boolean isTracingEnabled() {
      * GJULE will detect the caller class and method from stacktrace,
      * which is quite expensive operation affecting logging throughput.
      * <p>
-     * If it is set to null, GJULE will not perform such detection.
+     * If it is set to false, GJULE will not perform such detection.
      * <p>
-     * If the property is not set, GJULE makes the decision based on known handlers
-     * (<code>*.printSource</code> value) - if any handler requires this feature, it is enabled.
-     * It is disabled otherwise or you can forcibly enable it by setting the value to true or false.
+     * If the property is not set, GJULE makes the decision based on the(<code>*.printSource</code>
+     * property) - if any formatter requires this feature, the feature is enabled.
+     * <p>
+     * It is disabled otherwise.
      *
-     * @return true if handlers can use source class and method in formatters.
+     * @return true if formatters can use autodetected source class and method in formatters.
      */
     public boolean isClassAndMethodDetectionEnabled() {
         return classAndMethodDetectionEnabled;

diff --git a/...ish-jul-extension/src/main/java/org/glassfish/main/jul/cfg/GlassFishLoggingConstants.java b/...ish-jul-extension/src/main/java/org/glassfish/main/jul/cfg/GlassFishLoggingConstants.java
@@ -72,11 +72,12 @@ public class GlassFishLoggingConstants {
      * If this key is set to true, GJULE will detect the caller class and method from stacktrace,
      * which is quite expensive operation affecting logging throughput.
      * <p>
-     * If it is set to null, GJULE will not perform such detection.
+     * If it is set to false, GJULE will not perform such detection.
      * <p>
-     * If the property is not set, GJULE makes the decision based on known handlers
-     * (<code>*.printSource</code> value) - if any handler requires this feature, it is enabled.
-     * It is disabled otherwise or you can forcibly enable it by setting the value to true or false.
+     * If the property is not set, GJULE makes the decision based on the (<code>*.printSource</code>
+     * property) - if any formatter requires this feature, the feature is enabled.
+     * <p>
+     * It is disabled otherwise.
      */
     public static final String KEY_CLASS_AND_METHOD_DETECTION_ENABLED = "org.glassfish.main.jul.classAndMethodDetection.enabled";
     /**