feat/java docs for sdk entry points

Author: piotr-szewczyk

.idea/workspace.xml

@@ -1,5 +1,11 @@
 package com.traceo.sdk.builder;
 
+/**
+ * Base class for every client builders.
+ *
+ * @param <Subclass> Client builder.
+ * @param <ConfigurationType> Client configuration class extended by ClientCoreConfiguration.
+ */
 public abstract class CoreBuilder<Subclass extends CoreBuilder, ConfigurationType extends ClientCoreConfiguration> {
 
     protected ConfigurationType configuration;
@@ -16,21 +22,45 @@ public final ConfigurationType build() {
         return configuration;
     }
 
+    /**
+     * Set api key generated for this project.
+     *
+     * @param apiKey
+     * @return This builder for method calling.
+     */
     public final Subclass withApiKey(String apiKey) {
         configuration.setApiKey(apiKey);
         return getSubclass();
     }
 
+    /**
+     * Set host on which Traceo Platform is currently running.
+     *
+     * @param host in format [protocol]://[domain]:[port]
+     * @return This builder for method calling.
+     */
     public final Subclass withHost(String host) {
         configuration.setHost(host);
         return getSubclass();
     }
 
+    /**
+     * If false then client is not initialized. None of the captured exception are send to Traceo Platform.
+     *
+     * @param enabled
+     * @return This builder for method calling.
+     */
     public final Subclass withEnabled(boolean enabled) {
         configuration.setEnabled(enabled);
         return getSubclass();
     }
 
+    /**
+     * Set to true if you want to check internal logs for SDK.
+     *
+     * @param enabled
+     * @return This builder for method calling.
+     */
     public final Subclass withDebug(boolean enabled) {
         configuration.setDebug(enabled);
         return getSubclass();

traceo-sdk-core/src/main/java/com/traceo/sdk/builder/CoreBuilder.java

@@ -34,14 +34,10 @@ public static synchronized <T extends ClientCoreConfiguration> void init(T clien
                 LOGGER.log("You run Traceo SDK with enabled debug option. All internal messages for this SDK will be visible to you.");
             }
 
-//            if (!initSDK()) {
-//                return;
-//            }
-
             LOGGER.log("Traceo SDK has been initialized.");
 
             asyncTransport = new HttpAsyncClient();
-            incidentHandler = new IncidentHandler();
+            incidentHandler = new IncidentHandler(asyncTransport);
 
             shutdownHook();
         } else {

traceo-sdk-core/src/main/java/com/traceo/sdk/client/CoreClient.java

@@ -1,14 +1,52 @@
 package com.traceo.sdk.incident;
 
+import com.traceo.sdk.DefaultRequest;
+import com.traceo.sdk.EventCallback;
 import com.traceo.sdk.TraceoIncident;
 import com.traceo.sdk.TraceoRuntimePlatform;
+import com.traceo.sdk.http.HttpAsyncClient;
+import com.traceo.sdk.logging.ClientLogger;
 import com.traceo.sdk.utils.ThrowableUtils;
 
+import static com.traceo.sdk.client.CoreClient.getConfigs;
+
 public class IncidentHandler {
+    private final static ClientLogger LOGGER = new ClientLogger(IncidentHandler.class);
+
+    private static HttpAsyncClient httpAsyncClient;
+
+    public IncidentHandler(HttpAsyncClient httpClient) {
+        this.httpAsyncClient = httpClient;
+    }
 
-    public IncidentHandler() {}
+    public void catchException(Throwable throwable, String message, EventCallback<TraceoIncident> callback) {
+        if (!getConfigs().isEnabled()) {
+            LOGGER.log("Traceo client is disabled. Use withEnabled(true) to enabled exceptions scrapping.");
+            return;
+        }
+
+        if (throwable == null) {
+            LOGGER.log("Exception has been passed as null.");
+            return;
+        }
+
+        TraceoIncident traceoIncident = processIncident(throwable, message);
+        if (callback != null) {
+            callback.run(traceoIncident);
+        }
+
+        DefaultRequest<TraceoIncident> request = new DefaultRequest<>();
+        request.setContent(traceoIncident);
+        request.setEndpoint("/incident");
+
+        try {
+            httpAsyncClient.executeAsync(request);
+        } catch (Throwable e) {
+            LOGGER.error("Failed to send exception.", e);
+        }
+    }
 
-    public TraceoIncident processIncident(Throwable throwable, String customMessage) {
+    private static TraceoIncident processIncident(Throwable throwable, String customMessage) {
         TraceoIncident traceoIncident = new TraceoIncident();
 
         String stacktrace = ThrowableUtils.stacktraceToString(throwable);

traceo-sdk-core/src/main/java/com/traceo/sdk/incident/IncidentHandler.java

@@ -1,42 +1,48 @@
 package com.traceo.sdk.client;
 
-import com.traceo.sdk.DefaultRequest;
 import com.traceo.sdk.EventCallback;
 import com.traceo.sdk.TraceoIncident;
-import com.traceo.sdk.logging.ClientLogger;
 
-public class TraceoClient extends CoreClient<TraceoClientConfiguration> {
-    private final static ClientLogger LOGGER = new ClientLogger(TraceoClient.class);
+/**
+ * Entry point for accessing Traceo SDK.
+ */
+public final class TraceoClient extends CoreClient<TraceoClientConfiguration> {
 
-    protected TraceoClient() {}
+    private TraceoClient() {}
 
-    public static void catchException(Throwable e) {
-        catchException(e, null);
+    /**
+     * Catch the exception.
+     * @param throwable Exception.
+     */
+    public static void catchException(Throwable throwable) {
+        incidentHandler.catchException(throwable, null, null);
     }
 
-    public static void catchException(String message, Throwable e) {
-        catchException(e, message, null);
+    /**
+     * Catch the exception.
+     * @param message Custom message instead of eq. java.lang.NullPointerException.
+     * @param throwable Exception.
+     */
+    public static void catchException(String message, Throwable throwable) {
+        incidentHandler.catchException(throwable, message, null);
     }
 
-    public static void catchException(Throwable e, EventCallback<TraceoIncident> callback) {
-        catchException(e, null, callback);
+    /**
+     * Catch the exception.
+     * @param throwable Exception.
+     * @param callback The callback to provide operations on already prepared TraceoIncident.
+     */
+    public static void catchException(Throwable throwable, EventCallback<TraceoIncident> callback) {
+        incidentHandler.catchException(throwable, null, callback);
     }
 
-    public static void catchException(Throwable e, String message, EventCallback<TraceoIncident> callback) {
-        if (!getConfigs().isEnabled()) {
-            LOGGER.log("Traceo client is disabled. Use withEnabled(true) to enabled exceptions scrapping.");
-            return;
-        }
-
-        TraceoIncident traceoIncident = incidentHandler.processIncident(e, message);
-        if (callback != null) {
-            callback.run(traceoIncident);
-        }
-
-        DefaultRequest<TraceoIncident> request = new DefaultRequest<>();
-        request.setContent(traceoIncident);
-        request.setEndpoint("/incident");
-
-        asyncTransport.executeAsync(request);
+    /**
+     * Catch the exception.
+     * @param throwable Exception.
+     * @param message Custom message instead of eq. java.lang.NullPointerException.
+     * @param callback The callback to provide operations on already prepared TraceoIncident.
+     */
+    public static void catchException(Throwable throwable, String message, EventCallback<TraceoIncident> callback) {
+        incidentHandler.catchException(throwable, message, callback);
     }
 }

traceo-sdk/src/main/java/com/traceo/sdk/client/TraceoClient.java

@@ -2,11 +2,18 @@
 
 import com.traceo.sdk.builder.CoreBuilder;
 
+/**
+ * Builder for creating configuration for {@link com.traceo.sdk.client.TraceoClient}.
+ */
 public class TraceoClientBuilder extends CoreBuilder<TraceoClientBuilder, TraceoClientConfiguration> {
     protected TraceoClientBuilder() {
         super(new TraceoClientConfiguration());
     }
 
+    /**
+     * Create new instance of this builder with default configuration for each option.
+     * @return Builder instance
+     */
     public static TraceoClientBuilder standard() {
         return new TraceoClientBuilder();
     }
@@ -15,16 +22,23 @@ public static TraceoClientConfiguration defaultClient() {
         return standard().build();
     }
 
-    public final TraceoClientBuilder withMetricsCollection(boolean collect) {
-        configuration.setCollectMetrics(collect);
-        return this;
-    }
+    /**
+     * Set to false if you SDK shouldn't collect any default metrics. It does not affect for OpenTelemetry.
+     * @param collect
+     * @return
+     */
+//    public final TraceoClientBuilder withMetricsCollection(boolean collect) {
+//        configuration.setCollectMetrics(collect);
+//        return this;
+//    }
 
-    public final TraceoClientBuilder withOfflineMode(boolean isOffline) {
-        configuration.setOffline(isOffline);
-        return this;
-    }
 
+    /**
+     * Set custom value for export default metrics interval.
+     *
+     * @param ms value provided in milliseconds
+     * @return
+     */
     public final TraceoClientBuilder withExportIntervalMs(int ms) {
         configuration.setExportIntervalMillis(ms);
         return this;

traceo-sdk/src/main/java/com/traceo/sdk/client/TraceoClientBuilder.java

@@ -6,8 +6,6 @@ public class TraceoClientConfiguration extends ClientCoreConfiguration {
 
     private boolean collectMetrics = false;
 
-    private boolean offline = false;
-
     private int exportIntervalMillis = 15000;
 
     public TraceoClientConfiguration() {}
@@ -20,13 +18,6 @@ public void setCollectMetrics(boolean collectMetrics) {
         this.collectMetrics = collectMetrics;
     }
 
-    public boolean isOffline() {
-        return offline;
-    }
-
-    public void setOffline(boolean offline) {
-        this.offline = offline;
-    }
 
     public int getExportIntervalMillis() {
         return exportIntervalMillis;

traceo-sdk/src/main/java/com/traceo/sdk/client/TraceoClientConfiguration.java

@@ -6,7 +6,7 @@
 import org.junit.Before;
 import org.junit.Test;
 
-public class TraceoIncidentHandlerTest {
+public class IncidentHandlerTest {
 
     @Before
     public void setUp() {