Refactoring: Unifying method names.

mjfryc · mjfryc · commit 2db0f41d509e · 2025-03-20T11:47:38.000+01:00
* start() and build() has been unified to open() function names.
* Label values may be created from any primitive type.
diff --git a/README.md b/README.md
@@ -32,9 +32,10 @@ import pl.mjaron.tinyloki.*;
 
 public class Sample {
     public static void main(String[] args) {
-        TinyLoki loki = TinyLoki.withUrl("http://localhost:3100").withBasicAuth("user", "pass").start();
-        ILogStream helloStream = loki.stream().info().l("topic", "hello").build();
-        helloStream.log("Hello world!");
+        TinyLoki loki = TinyLoki.withUrl("http://localhost:3100").withBasicAuth("user", "pass").open();
+        ILogStream logStream = loki.stream().info().l("topic", "shortExample").open();
+        logStream.log("Hello world!");
+        logStream.log("Hello world!", Labels.of("structured_metadata", "My log metadata value."));
         loki.closeSync();
     }
 }
diff --git a/src/main/java/pl/mjaron/tinyloki/ILogMonitor.java b/src/main/java/pl/mjaron/tinyloki/ILogMonitor.java
@@ -85,14 +85,14 @@ static void printError(final String what) {
     void onSync(final boolean isSuccess);
 
     /**
-     * Called when start operation ends.
+     * Called when {@link IExecutor} has started.
      *
      * @since 1.0.0
      */
     void onStart();
 
     /**
-     * Called when stop operation ends.
+     * Called when {@link IExecutor} has stopped.
      *
      * @param isSuccess The stop operation result.
      * @since 1.0.0
diff --git a/src/main/java/pl/mjaron/tinyloki/Labels.java b/src/main/java/pl/mjaron/tinyloki/Labels.java
@@ -419,16 +419,99 @@ public static Labels of(final Map<String, String> labels) {
     /**
      * Creates labels containing single name-value pair. Call {@link #l(String, String)} method to add more labels.
      *
-     * @param name  Label name. Valid label identifier starts with letter and contains only letters, digits or '_'.
-     * @param value Label value. Valid label identifier starts with letter and contains only letters, digits or '_'.
+     * @param name  Label name.
+     * @param value Label value.
      * @return New instance of {@link Labels}.
-     * @see #l(String, String)
      * @since 1.0.1
      */
     public static Labels of(final String name, final String value) {
         return new Labels().l(name, value);
     }
 
+    /**
+     * Creates labels containing single name-value pair. Call {@link #l(String, String)} method to add more labels.
+     *
+     * @param name  Label name.
+     * @param value Label value.
+     * @return New instance of {@link Labels}.
+     * @since 1.1.0
+     */
+    public static Labels of(final String name, final int value) {
+        return new Labels().l(name, value);
+    }
+
+    /**
+     * Creates labels containing single name-value pair. Call {@link #l(String, String)} method to add more labels.
+     *
+     * @param name  Label name.
+     * @param value Label value.
+     * @return New instance of {@link Labels}.
+     * @since 1.1.0
+     */
+    public static Labels of(final String name, final long value) {
+        return new Labels().l(name, value);
+    }
+
+    /**
+     * Creates labels containing single name-value pair. Call {@link #l(String, String)} method to add more labels.
+     *
+     * @param name  Label name.
+     * @param value Label value.
+     * @return New instance of {@link Labels}.
+     * @since 1.1.0
+     */
+    public static Labels of(final String name, final float value) {
+        return new Labels().l(name, value);
+    }
+
+    /**
+     * Creates labels containing single name-value pair. Call {@link #l(String, String)} method to add more labels.
+     *
+     * @param name  Label name.
+     * @param value Label value.
+     * @return New instance of {@link Labels}.
+     * @since 1.1.0
+     */
+    public static Labels of(final String name, final double value) {
+        return new Labels().l(name, value);
+    }
+
+    /**
+     * Creates labels containing single name-value pair. Call {@link #l(String, String)} method to add more labels.
+     *
+     * @param name  Label name.
+     * @param value Label value.
+     * @return New instance of {@link Labels}.
+     * @since 1.1.0
+     */
+    public static Labels of(final String name, final char value) {
+        return new Labels().l(name, value);
+    }
+
+    /**
+     * Creates labels containing single name-value pair. Call {@link #l(String, String)} method to add more labels.
+     *
+     * @param name  Label name.
+     * @param value Label value.
+     * @return New instance of {@link Labels}.
+     * @since 1.1.0
+     */
+    public static Labels of(final String name, final byte value) {
+        return new Labels().l(name, value);
+    }
+
+    /**
+     * Creates labels containing single name-value pair. Call {@link #l(String, String)} method to add more labels.
+     *
+     * @param name  Label name.
+     * @param value Label value.
+     * @return New instance of {@link Labels}.
+     * @since 1.1.0
+     */
+    public static Labels of(final String name, final short value) {
+        return new Labels().l(name, value);
+    }
+
     /**
      * Creates a new empty labels instance. Call {@link #l(String, String)} method to add any labels.
      *
diff --git a/src/main/java/pl/mjaron/tinyloki/Settings.java b/src/main/java/pl/mjaron/tinyloki/Settings.java
@@ -501,7 +501,7 @@ public IExecutor getExecutor() {
      *
      * @return New {@link TinyLoki} instance.
      */
-    public TinyLoki start() {
-        return TinyLoki.createAndStart(this);
+    public TinyLoki open() {
+        return TinyLoki.open(this);
     }
 }
diff --git a/src/main/java/pl/mjaron/tinyloki/StreamBuilder.java b/src/main/java/pl/mjaron/tinyloki/StreamBuilder.java
@@ -5,11 +5,11 @@
 /**
  * Helper class for shorter initialization code.
  * <p>
- * call {@link #build()} to initialize {@link ILogStream} with parameters passed to this builder.
+ * call {@link #open()} to initialize {@link ILogStream} with parameters passed to this builder.
  * <p>
  * Example:
  * <pre>{@code
- * ILogStream myStream = logController.stream().info().l("my_custom_label", "value").build();
+ * ILogStream myStream = logController.stream().info().l("my_custom_label", "value").open();
  * }</pre>
  */
 public class StreamBuilder {
@@ -26,7 +26,7 @@ public StreamBuilder(final TinyLoki tinyLoki) {
      *
      * @return New {@link ILogStream} instance.
      */
-    public ILogStream build() {
+    public ILogStream open() {
         return tinyLoki.createStream(labels);
     }
 
diff --git a/src/main/java/pl/mjaron/tinyloki/TinyLoki.java b/src/main/java/pl/mjaron/tinyloki/TinyLoki.java
@@ -17,10 +17,10 @@
  * <pre>{@code
  *  TinyLoki tinyLoki = TinyLoki.withUrl("http://localhost:3100")
  *      .withBasicAuth("user", "pass")
- *      .start();
+ *      .open();
  *
- *      ILogStream windowStream = tinyLoki.stream().info().l("device", "window").build();
- *      ILogStream doorStream = tinyLoki.stream().info().l("device", "door").build();
+ *      ILogStream windowStream = tinyLoki.stream().info().l("device", "window").open();
+ *      ILogStream doorStream = tinyLoki.stream().info().l("device", "door").open();
  *
  *      windowStream.log("The window is open.");
  *      doorStream.log("The door is open.");
@@ -85,7 +85,7 @@ public class TinyLoki implements java.io.Closeable {
      *             .withConnectTimeout(connectTimeout)
      *             .withLogCollector(logCollector)
      *             .withLogMonitor(logMonitor)
-     *             .start();            // LogController created here.
+     *             .open();            // LogController created here.
      * </pre>
      * <p>
      * Optionally call {@link #withExactUrl(String)} instead to skip URL value normalization
@@ -124,7 +124,7 @@ public static Settings withExactUrl(final String url) {
      * @see #withUrl(String)
      * @since 0.3.0
      */
-    public static TinyLoki createAndStart(final Settings settings) {
+    public static TinyLoki open(final Settings settings) {
         return new TinyLoki(settings.getLogCollector(), settings.getLogEncoder(), settings.getLogSenderSettings(), settings.getLogSender(), settings.getLabelSettings(), settings.getStructuredMetadataLabelSettings(), settings.getExecutor(), settings.getBuffering(), settings.getLogMonitor()).start();
     }
 
@@ -135,13 +135,13 @@ public static TinyLoki createAndStart(final Settings settings) {
      * @param user Basic authentication user. If null, BA header will not be sent.
      * @param pass Basic authentication password. If null, BA header will not be sent.
      * @return New {@link TinyLoki LogController} object.
-     * @deprecated Use {@link TinyLoki#withUrl(String)} to initialize settings and finally call {@link Settings#start()}, e.g:
+     * @deprecated Use {@link TinyLoki#withUrl(String)} to initialize settings and finally call {@link Settings#open()}, e.g:
      * <pre>
-     *     TinyLoki.withUrl(url).withBasicAuth(user, pass).start();
+     *     TinyLoki.withUrl(url).withBasicAuth(user, pass).open();
      * </pre>
      */
-    public static TinyLoki createAndStart(final String url, final String user, final String pass) {
-        return TinyLoki.withUrl(url).withBasicAuth(user, pass).start();
+    public static TinyLoki open(final String url, final String user, final String pass) {
+        return TinyLoki.withUrl(url).withBasicAuth(user, pass).open();
     }
 
     private final ILogCollector logCollector;
@@ -258,7 +258,7 @@ public ILogStream createStream(final Labels labels) {
      * Provides a {@link StreamBuilder} to initialize the stream. E.g:
      *
      * <pre>{@code
-     * ILogStream myStream = logController.stream().info().l("my_custom_label", "value").build();
+     * ILogStream myStream = logController.stream().info().l("my_custom_label", "value").open();
      * }</pre>
      *
      * @return New instance of {@link StreamBuilder}.
diff --git a/src/test/java/pl/mjaron/tinyloki/IntegrationTest.java b/src/test/java/pl/mjaron/tinyloki/IntegrationTest.java
@@ -24,14 +24,15 @@ public static boolean isIntegrationEnabled() {
 
     @Test
     void shortExample() throws InterruptedException {
-        TinyLoki loki = TinyLoki.withUrl("http://localhost:3100").withBasicAuth("user", "pass").start();
-        ILogStream helloStream = loki.stream().info().l("topic", "hello").build();
-        helloStream.log("Hello world!");
+        TinyLoki loki = TinyLoki.withUrl("http://localhost:3100").withBasicAuth("user", "pass").open();
+        ILogStream logStream = loki.stream().info().l("topic", "shortExample").open();
+        logStream.log("Hello world!");
+        logStream.log("Hello world!", Labels.of("structured_metadata", "My log metadata value."));
         loki.closeSync();
     }
 
     @Test
-    void verboseTest() throws InterruptedException {
+    void verboseExample() throws InterruptedException {
 
         // Initialize the log controller instance with URL.
         // The endpoint loki/api/v1/push will be added by default if missing.
@@ -42,7 +43,8 @@ void verboseTest() throws InterruptedException {
         try (TinyLoki loki = TinyLoki.withUrl("http://localhost:3100/loki/api/v1/push")
 
                 // Print all diagnostic information coming from the TinyLoki library. For diagnostic purposes only.
-                .withVerboseLogMonitor()
+                // The messages are printed only if there is no log encoder (comment out .withGzipLogEncoder())
+                .withVerboseLogMonitor(true)
 
                 // Set the custom log processing interval time.
                 // So the executor will try to send the next logs 10 seconds after the previous logs sending operation.
@@ -52,26 +54,37 @@ void verboseTest() throws InterruptedException {
                 .withConnectTimeout(10 * 1000)
 
                 // Encode the logs to limit the size of data sent.
-                .withGzipLogEncoder()
+                // .withGzipLogEncoder()
 
                 // The BasicBuffering is set by default, but here the (not encoded) message size limit may be customized.
                 .withBasicBuffering(3 * 1024 * 1024, 10)
 
                 // Initialize the library with above settings.
                 // The ThreadExecutor will create a new thread and start waiting for the logs to be sent.
-                .start()) {
+                .open()) {
 
             // Some logs here...
-            ILogStream whiteStream = loki.stream().l("color", "white").build();
+
+            // Let's define some labels common for few streams.
+            Labels topic = Labels.of("topic", "verboseExample");
+
+            ILogStream topicStream = loki.stream().l(topic).open();
+            topicStream.log("Hello world.");
+
+            ILogStream whiteStream = loki.stream().l(topic).l("topic", "verboseExample").l("color", "white").open();
             whiteStream.log("Hello white world.");
 
             // Blocking method, tries to send the logs ASAP and wait for sending completion.
             // This method returns false when timeout occurs, but true when sending has completed with success or failure.
             boolean allHttpSendingOperationsFinished = loki.sync();
             System.out.println("Are all logs processed: " + allHttpSendingOperationsFinished);
 
-            ILogStream redStream = loki.stream().l("color", "red").build();
-            redStream.log("Hello white world.");
+            ILogStream redStream = loki.stream().l(topic).l("color", "red").open();
+
+            // Let's attach the Grafana Loki structured metadata.
+            // In current implementation, the duplicated logs with same log line and timestamp (structured metadata doesn't matter) - is sent but may be dropped by Grafana Loki.
+            redStream.log("Hello red world 0", Labels.of("structured_metadata_label", 0).l("other_structured_metadata_label", 'a'));
+            redStream.log("Hello red world 1", Labels.of("structured_metadata_label", 9).l("other_structured_metadata_label", 'z'));
 
             // Blocking method, tries to synchronize the logs than interrupt and join the execution thread.
             // Set the custom timeout time for this operation.
@@ -83,27 +96,26 @@ void verboseTest() throws InterruptedException {
 
     @Test
     void structuredMetadataTest() throws InterruptedException {
-        TinyLoki loki = TinyLoki.withUrl("http://localhost:3100").withVerboseLogMonitor(true).withBasicAuth("user", "pass").start();
-        ILogStream helloStream = loki.stream().info().l("topic", "structured_metadata").l("Number", 3).build();
+        TinyLoki loki = TinyLoki.withUrl("http://localhost:3100").withVerboseLogMonitor(true).withBasicAuth("user", "pass").open();
+        ILogStream helloStream = loki.stream().info().l("topic", "structuredMetadataTest").l("Number", 3).open();
         helloStream.log("Hello world!", Labels.of("struct", "custom label"));
         loki.closeSync();
     }
 
     @Test
     void logLevelTest() throws InterruptedException {
-        TinyLoki loki = TinyLoki.withUrl("http://localhost:3100").withVerboseLogMonitor(true).withBasicAuth("user", "pass").start();
-        loki.stream().critical().l("topic", "loglevel").build().log("Log level: critical");
-        loki.stream().fatal().l("topic", "loglevel").build().log("Log level: fatal");
-        loki.stream().warning().l("topic", "loglevel").build().log("Log level: warning");
-        loki.stream().info().l("topic", "loglevel").build().log("Log level: info");
-        loki.stream().debug().l("topic", "loglevel").build().log("Log level: debug");
-        loki.stream().verbose().l("topic", "loglevel").build().log("Log level: verbose");
-        loki.stream().trace().l("topic", "loglevel").build().log("Log level: trace");
-        loki.stream().unknown().l("topic", "loglevel").build().log("Log level: unknown");
+        TinyLoki loki = TinyLoki.withUrl("http://localhost:3100").withVerboseLogMonitor(true).withBasicAuth("user", "pass").open();
+        loki.stream().critical().l("topic", "logLevelTest").open().log("Log level: critical");
+        loki.stream().fatal().l("topic", "logLevelTest").open().log("Log level: fatal");
+        loki.stream().warning().l("topic", "logLevelTest").open().log("Log level: warning");
+        loki.stream().info().l("topic", "logLevelTest").open().log("Log level: info");
+        loki.stream().debug().l("topic", "logLevelTest").open().log("Log level: debug");
+        loki.stream().verbose().l("topic", "logLevelTest").open().log("Log level: verbose");
+        loki.stream().trace().l("topic", "logLevelTest").open().log("Log level: trace");
+        loki.stream().unknown().l("topic", "logLevelTest").open().log("Log level: unknown");
         loki.closeSync();
     }
 
-
     static class MassiveThread extends Thread {
         static final public String LABEL_STREAM_IDX = "test_stream_index";
 
@@ -142,10 +154,10 @@ void sampleMassiveTest() throws InterruptedException {
         final int testRunId = random.nextInt(1000);
         System.out.println("Running test: " + testRunId);
 
-        try (TinyLoki loki = TinyLoki.withUrl("http://localhost:3100/loki/api/v1/push").withVerboseLogMonitor(false).withExecutor(new ThreadExecutor(100000)).start()) {
+        try (TinyLoki loki = TinyLoki.withUrl("http://localhost:3100/loki/api/v1/push").withVerboseLogMonitor(false).withExecutor(new ThreadExecutor(100000)).open()) {
 
             for (int i = 0; i < 100; ++i) {
-                streams.add(loki.stream().l("test_name", "sampleMassiveTest").l("test_run_id", "test_" + testRunId).l(MassiveThread.LABEL_STREAM_IDX, "index_" + i).build());
+                streams.add(loki.stream().l("test_name", "sampleMassiveTest").l("test_run_id", "test_" + testRunId).l(MassiveThread.LABEL_STREAM_IDX, "index_" + i).open());
             }
 
             for (int i = 0; i < 100; ++i) {
diff --git a/src/test/java/pl/mjaron/tinyloki/LogControllerTest.java b/src/test/java/pl/mjaron/tinyloki/LogControllerTest.java
@@ -14,29 +14,29 @@ class LogControllerTest {
     @Test
     void getLogMonitor() {
         final ILogMonitor logMonitor = new SilentLogMonitor();
-        final TinyLoki controller = TinyLoki.withUrl("http://example.com").withLogMonitor(logMonitor).start();
+        final TinyLoki controller = TinyLoki.withUrl("http://example.com").withLogMonitor(logMonitor).open();
         assertSame(logMonitor, controller.getLogMonitor());
 
     }
 
     @Test
     void getLogCollector() {
         final ILogCollector collector = new JsonLogCollector();
-        final TinyLoki controller = TinyLoki.withUrl("http://example.com").withLogCollector(collector).start();
+        final TinyLoki controller = TinyLoki.withUrl("http://example.com").withLogCollector(collector).open();
         assertSame(collector, controller.getLogCollector());
     }
 
     @Test
     void getExecutor() {
         final IExecutor executor = new ThreadExecutor();
-        final TinyLoki controller = TinyLoki.withUrl("http://example.com").withExecutor(executor).start();
+        final TinyLoki controller = TinyLoki.withUrl("http://example.com").withExecutor(executor).open();
         assertSame(executor, controller.getExecutor());
     }
 
     @Test
     void createStreamFromMap() throws InterruptedException {
         MemoryLogSender logSender = new MemoryLogSender();
-        final TinyLoki controller = TinyLoki.withUrl("http://example.com").withLogSender(logSender).start();
+        final TinyLoki controller = TinyLoki.withUrl("http://example.com").withLogSender(logSender).open();
         Map<String, String> map = new HashMap<>();
         map.put("aaa", "bbb");
         ILogStream stream = controller.createStream(map);
diff --git a/src/test/java/pl/mjaron/tinyloki/SyncExecutorTest.java b/src/test/java/pl/mjaron/tinyloki/SyncExecutorTest.java
@@ -10,8 +10,8 @@ class SyncExecutorTest {
     @Test
     void basic() throws InterruptedException {
 
-        TinyLoki controller = TinyLoki.withUrl("http://example.com").withExecutor(new SyncExecutor()).withLogSender(new DummyLogSender(100)).withVerboseLogMonitor().start();
-        ILogStream stream = controller.stream().l("color", "white").build();
+        TinyLoki controller = TinyLoki.withUrl("http://example.com").withExecutor(new SyncExecutor()).withLogSender(new DummyLogSender(100)).withVerboseLogMonitor().open();
+        ILogStream stream = controller.stream().l("color", "white").open();
         stream.log("My first log.");
         assertTrue(controller.closeSync());
     }
diff --git a/src/test/java/pl/mjaron/tinyloki/ThreadExecutorTest.java b/src/test/java/pl/mjaron/tinyloki/ThreadExecutorTest.java
diff --git a/src/test/java/pl/mjaron/tinyloki/TinyLokiTest.java b/src/test/java/pl/mjaron/tinyloki/TinyLokiTest.java

Original file line number	Diff line number	Diff line change
`@@ -32,9 +32,10 @@ import pl.mjaron.tinyloki.*;`
`32`	`32`
`33`	`33`	`public class Sample {`
`34`	`34`	`public static void main(String[] args) {`
`35`		`- TinyLoki loki = TinyLoki.withUrl("http://localhost:3100").withBasicAuth("user", "pass").start();`
`36`		`- ILogStream helloStream = loki.stream().info().l("topic", "hello").build();`
`37`		`- helloStream.log("Hello world!");`
	`35`	`+ TinyLoki loki = TinyLoki.withUrl("http://localhost:3100").withBasicAuth("user", "pass").open();`
	`36`	`+ ILogStream logStream = loki.stream().info().l("topic", "shortExample").open();`
	`37`	`+ logStream.log("Hello world!");`
	`38`	`+ logStream.log("Hello world!", Labels.of("structured_metadata", "My log metadata value."));`
`38`	`39`	`loki.closeSync();`
`39`	`40`	`}`
`40`	`41`	`}`
Original file line number	Diff line number	Diff line change
`@@ -501,7 +501,7 @@ public IExecutor getExecutor() {`
`501`	`501`	`*`
`502`	`502`	`* @return New {@link TinyLoki} instance.`
`503`	`503`	`*/`
`504`		`- public TinyLoki start() {`
`505`		`- return TinyLoki.createAndStart(this);`
	`504`	`+ public TinyLoki open() {`
	`505`	`+ return TinyLoki.open(this);`
`506`	`506`	`}`
`507`	`507`	`}`