From 78163492bbbcb46692004388aed32b4cc09fba33 Mon Sep 17 00:00:00 2001 From: Anikesh348 Date: Tue, 11 Aug 2026 08:29:06 +0000 Subject: [PATCH] Document log metadata API --- .../gctoolkit/io/LogFileMetadata.java | 16 ++++++++ .../gctoolkit/io/LogFileSegment.java | 38 +++++++++++++++++++ .../gctoolkit/io/RotatingLogFileMetadata.java | 11 ++++++ .../gctoolkit/io/SingleLogFileMetadata.java | 16 ++++++++ 4 files changed, 81 insertions(+) diff --git a/api/src/main/java/com/microsoft/gctoolkit/io/LogFileMetadata.java b/api/src/main/java/com/microsoft/gctoolkit/io/LogFileMetadata.java index 97c4bba73..16bf36515 100644 --- a/api/src/main/java/com/microsoft/gctoolkit/io/LogFileMetadata.java +++ b/api/src/main/java/com/microsoft/gctoolkit/io/LogFileMetadata.java @@ -24,11 +24,22 @@ public abstract class LogFileMetadata { private FileFormat fileFormat = FileFormat.UNKNOWN; private final Path path; + /** + * Creates metadata for the file system entry at the supplied path and detects its format. + * + * @param path path to a log file, archive, or directory + * @throws IOException if the path cannot be inspected + */ public LogFileMetadata(Path path) throws IOException { this.path = path; magic(); } + /** + * Returns the path described by this metadata. + * + * @return path to the log file, archive, or directory + */ public Path getPath() { return path; } @@ -44,6 +55,11 @@ boolean magic(int field1, int field2) { return false; } + /** + * Streams the log segments discovered at this metadata path. + * + * @return a stream of discovered log segments + */ public abstract Stream logFiles(); private void magic() { diff --git a/api/src/main/java/com/microsoft/gctoolkit/io/LogFileSegment.java b/api/src/main/java/com/microsoft/gctoolkit/io/LogFileSegment.java index 53e103a54..899cacce5 100644 --- a/api/src/main/java/com/microsoft/gctoolkit/io/LogFileSegment.java +++ b/api/src/main/java/com/microsoft/gctoolkit/io/LogFileSegment.java @@ -4,14 +4,52 @@ import java.util.regex.Pattern; import java.util.stream.Stream; +/** + * A segment of a garbage collection log, including its location and time range. + * + *

A segment may be a standalone file or an entry within an archive. Implementations stream the + * segment contents one line at a time. + */ public interface LogFileSegment { + /** The suffix used by rotating garbage collection log file names. */ String ROTATING_LOG_SUFFIX = ".*\\.(\\d+)(\\.current)?$"; + + /** The compiled pattern used to identify rotating garbage collection log file names. */ Pattern ROTATING_LOG_PATTERN = Pattern.compile(ROTATING_LOG_SUFFIX); + /** + * Returns the path containing this segment. + * + * @return the segment file path, or the archive path for an archived segment + */ Path getPath(); + + /** + * Returns the name that identifies this segment within its containing path. + * + * @return the segment name + */ String getSegmentName(); + + /** + * Returns the earliest timestamp represented by this segment. + * + * @return the segment start time as either JVM uptime or epoch time + */ double getStartTime(); + + /** + * Returns the latest timestamp represented by this segment. + * + * @return the segment end time as either JVM uptime or epoch time + */ double getEndTime(); + + /** + * Streams the segment contents one line at a time. + * + * @return a stream of log lines + */ Stream stream(); } diff --git a/api/src/main/java/com/microsoft/gctoolkit/io/RotatingLogFileMetadata.java b/api/src/main/java/com/microsoft/gctoolkit/io/RotatingLogFileMetadata.java index d5215160c..2b2764be5 100644 --- a/api/src/main/java/com/microsoft/gctoolkit/io/RotatingLogFileMetadata.java +++ b/api/src/main/java/com/microsoft/gctoolkit/io/RotatingLogFileMetadata.java @@ -26,10 +26,21 @@ public class RotatingLogFileMetadata extends LogFileMetadata { private List segments; + /** + * Creates metadata for a rotating garbage collection log source. + * + * @param path path to a rotating log file, archive, or directory + * @throws IOException if the path cannot be inspected + */ public RotatingLogFileMetadata(Path path) throws IOException { super(path); } + /** + * Streams the contiguous log segments in chronological order. + * + * @return a stream of ordered log segments + */ public Stream logFiles() { if ( segments == null) { if ( isPlainText() || isDirectory()) diff --git a/api/src/main/java/com/microsoft/gctoolkit/io/SingleLogFileMetadata.java b/api/src/main/java/com/microsoft/gctoolkit/io/SingleLogFileMetadata.java index 7f65cfd69..8be508c78 100644 --- a/api/src/main/java/com/microsoft/gctoolkit/io/SingleLogFileMetadata.java +++ b/api/src/main/java/com/microsoft/gctoolkit/io/SingleLogFileMetadata.java @@ -17,15 +17,31 @@ public class SingleLogFileMetadata extends LogFileMetadata { private LogFileSegment logFile; + /** + * Creates metadata for a single garbage collection log file. + * + * @param path path to the log file + * @throws IOException if the path cannot be inspected + */ public SingleLogFileMetadata(Path path) throws IOException { super(path); this.logFile = new GCLogFileSegment(path); } + /** + * Returns a stream containing the single log segment. + * + * @return a stream containing the log segment + */ public Stream logFiles() { return List.of(logFile).stream(); } + /** + * Returns the number of log segments represented by this metadata. + * + * @return {@code 1} when the segment is present; otherwise {@code 0} + */ public int getNumberOfFiles() { return ( logFile != null) ? 1 : 0; }