Javadocs for classes LogCapturingAppender, LogsRule.

Signed-off-by: Lukasz Soszynski <[email protected]>

src/integrationTest/java/org/opensearch/security/http/JwtAuthenticationTests.java

@@ -186,7 +186,7 @@ public void shouldAuthenticateWithJwtToken_failureIncorrectFormatOfToken() {
 			HttpResponse response = client.getAuthInfo();
 
 			response.assertStatusCode(401);
-			logsRule.assertThatContain(String.format("No JWT token found in '%s' header.", JWT_AUTH_HEADER));
+			logsRule.assertThatContain(String.format("No JWT token found in '%s' header header", JWT_AUTH_HEADER));
 		}
 	}
 

src/integrationTest/java/org/opensearch/test/framework/log/LogCapturingAppender.java

@@ -33,24 +33,53 @@
 
 import static org.opensearch.test.framework.log.LogCapturingAppender.PLUGIN_NAME;
 
+/**
+* <p>The class acts as Log4j2 appender with a special purpose. The appender is used to capture logs which are generated during tests and
+* then test can examine logs. To use the appender it is necessary to:</p>
+* <ol>
+*     <li>Add package with appender to log4j2 package scan in Log4j2 configuration file</li>
+*     <li>Create appender in log4j2 configuration</li>
+*     <li>Assign required loggers to appender</li>
+*     <li>Enable appender for certain classes with method {@link #enable(String...)}. Each test can enable appender for distinct classes</li>
+* </ol>
+*/
 @Plugin(name = PLUGIN_NAME, category = Core.CATEGORY_NAME, elementType = Appender.ELEMENT_TYPE, printObject = true)
 public class LogCapturingAppender extends AbstractAppender {
 
 	public final static String PLUGIN_NAME = "LogCapturingAppender";
+	/**
+	* Appender stores only last <code>MAX_SIZE</code> messages to avoid excessive RAM memory usage.
+	*/
 	public static final int MAX_SIZE = 100;
+
+	/**
+	* Buffer for captured log messages
+	*/
 	private static final Buffer messages = BufferUtils.synchronizedBuffer(new CircularFifoBuffer(MAX_SIZE));
 
+	/**
+	* Log messages are stored in buffer {@link #messages} only for classes which are added to the {@link #activeLoggers} set.
+	*/
 	private static final Set<String> activeLoggers = Collections.synchronizedSet(new HashSet<>());
 
 	protected LogCapturingAppender(String name, Filter filter, Layout<? extends Serializable> layout, boolean ignoreExceptions, Property[] properties) {
 		super(name, filter, layout, ignoreExceptions, properties);
 	}
 
+	/**
+	* Method used by Log4j2 to create appender
+	* @param name appender name from Log4j2 configuration
+	* @return newly created appender
+	*/
 	@PluginFactory
 	public static LogCapturingAppender createAppender(@PluginAttribute(value = "name", defaultString = "logCapturingAppender") String name) {
 		return new LogCapturingAppender(name,  null, null, true, Property.EMPTY_ARRAY);
 	}
 
+	/**
+	* Method invoked by Log4j2 to append log events
+	* @param event The LogEvent, represents log message.
+	*/
 	@Override
 	public void append(LogEvent event) {
 		String loggerName = event.getLoggerName();
@@ -60,16 +89,27 @@ public void append(LogEvent event) {
 		}
 	}
 
+	/**
+	* To collect log messages form given logger the logger name must be passed to {@link #enable(String...)} method.
+	* @param loggerNames logger names
+	*/
 	public static void enable(String...loggerNames) {
 		disable();
 		activeLoggers.addAll(Arrays.asList(loggerNames));
 	}
 
+	/**
+	* Invocation cause that appender stops collecting log messages. Additionally, memory used by collected messages so far is released.
+	*/
 	public static void disable() {
 		activeLoggers.clear();
 		messages.clear();
 	}
 
+	/**
+	* Is used to obtain gathered log messages
+	* @return Log messages
+	*/
 	public static List<String> getLogMessages() {
 		return new ArrayList<>(messages);
 	}

src/integrationTest/java/org/opensearch/test/framework/log/LogsRule.java

@@ -18,10 +18,20 @@
 import static org.hamcrest.MatcherAssert.assertThat;
 import static org.hamcrest.Matchers.hasItem;
 
+/**
+* The class is a JUnit 4 rule and enables developers to write assertion related to log messages generated in the course of test. To use
+* {@link LogsRule} appender  {@link LogCapturingAppender} must be properly configured. The rule also manages {@link LogCapturingAppender}
+* so that memory occupied by gathered log messages is released after each test.
+*/
 public class LogsRule extends ExternalResource {
 
 	private final String[] loggerNames;
 
+	/**
+	* Constructor used to start gathering log messages from certain loggers
+	* @param loggerNames Loggers names. Log messages are collected only if the log message is associated with the logger with a name which
+	*                    is present in <code>loggerNames</code> parameter.
+	*/
 	public LogsRule(String...loggerNames) {
 		this.loggerNames = Objects.requireNonNull(loggerNames, "Logger names are required");
 	}
@@ -36,6 +46,10 @@ protected void after() {
 		LogCapturingAppender.disable();
 	}
 
+	/**
+	* Check if during the tests certain log message was logged
+	* @param expectedLogMessage expected log message
+	*/
 	public void assertThatContain(String expectedLogMessage) {
 		List<String> messages = LogCapturingAppender.getLogMessages();
 		String reason = reasonMessage(expectedLogMessage, messages);