Merge pull request #38 from comet-ml/CM-1597-builder-refactoring

[CM-1597] Clarify Java-SDK Experiment creation API

Author: yaricom

README.md

@@ -18,7 +18,7 @@
 ```
 #### Create experiment and log metrics and parameters:
 ```java
-OnlineExperiment experiment = OnlineExperimentImpl.builder()
+OnlineExperiment experiment = ExperimentBuilder.OnlineExperiment()
                 .withApiKey("someApiKey")
                 .withProjectName("someProject")
                 .withWorkspace("someWorkspace")
@@ -31,13 +31,13 @@ OnlineExperiment experiment = OnlineExperimentImpl.builder()
 
 #### Configure you experiment object:
 ```java
-#Configuration hierarchy:
-#Environment Variable > Configuration File Override > Default config file (application.conf)
+# Configuration hierarchy:
+Environment Variable > Configuration File Override > Default config file (application.conf)
 
-#Setting configuration in code:
+# Setting configuration in code:
 OnlineExperimentImpl.builder().withApiKey("someApiKey").build();
 
-#Override configuration file (can have partial keys)
+# Override configuration file (can have partial keys)
 OnlineExperimentImpl.builder().withConfig(new File("/tmp/comet.conf")).build();
 
 # Read from environment variables OR from configuration file in classpath (application.conf)
@@ -55,5 +55,7 @@ COMET_MAX_AUTH_RETRIES
 
 #### Examples
 
-* You also can check [sample experiment](comet-examples/src/main/java/ml/comet/examples/OnlineExperimentExample.java)
+* You also can check 
+  * [sample experiment](comet-examples/src/main/java/ml/comet/examples/OnlineExperimentExample.java)
+  * [MNIST classification experiment](comet-examples/src/main/java/ml/comet/examples/mnist/MnistExperimentExample.java)
 * For more usage examples refer to [tests](comet-java-client/src/test/java/ml/comet/experiment)

comet-examples/src/main/java/ml/comet/examples/OnlineExperimentExample.java

@@ -1,7 +1,7 @@
 package ml.comet.examples;
 
+import ml.comet.experiment.ExperimentBuilder;
 import ml.comet.experiment.OnlineExperiment;
-import ml.comet.experiment.OnlineExperimentImpl;
 
 import java.io.IOException;
 
@@ -40,13 +40,13 @@ private void run() throws IOException {
         //this will take configs from /comet-java-sdk/comet-examples/src/main/resources/application.conf
         //be sure you have set up apiKey, project, workspace in defaults.conf before you start!
 
-        OnlineExperiment experiment = OnlineExperimentImpl
-                .builder()
+        OnlineExperiment experiment = ExperimentBuilder
+                .OnlineExperiment()
                 .interceptStdout()
                 .build();
 
-        //you can use a builder or just inject params
-        //OnlineExperimentImpl.builder();
+        //you can use a default builder or just inject params
+        //OnlineExperiment experiment = ExperimentBuilder.OnlineExperiment().builder();
 
         experiment.setExperimentName("Java-SDK 2.0.2");
         experiment.nextStep();

comet-examples/src/main/java/ml/comet/examples/mnist/MnistExperimentExample.java

@@ -2,8 +2,8 @@
 
 import com.beust.jcommander.JCommander;
 import com.beust.jcommander.Parameter;
+import ml.comet.experiment.ExperimentBuilder;
 import ml.comet.experiment.OnlineExperiment;
-import ml.comet.experiment.OnlineExperimentImpl;
 import org.deeplearning4j.datasets.iterator.impl.MnistDataSetIterator;
 import org.deeplearning4j.nn.api.Model;
 import org.deeplearning4j.nn.api.OptimizationAlgorithm;
@@ -63,18 +63,17 @@ public final class MnistExperimentExample {
      * <p>Alternatively you can set these values in the <strong>resources/application.conf</strong> file
      *
      * @param args the command line arguments.
-     * @throws Exception if any exception occurs during experiment execution.
      */
-    public static void main(String[] args) throws Exception {
+    public static void main(String[] args) {
         MnistExperimentExample main = new MnistExperimentExample();
         JCommander.newBuilder()
                 .addObject(main)
                 .build()
                 .parse(args);
 
         // update application.conf or provide environment variables as described in JavaDoc.
-        OnlineExperiment experiment = OnlineExperimentImpl
-                .builder()
+        OnlineExperiment experiment = ExperimentBuilder
+                .OnlineExperiment()
                 .interceptStdout()
                 .build();
         try {

comet-java-client/src/main/java/ml/comet/experiment/Experiment.java

@@ -1,9 +1,9 @@
 package ml.comet.experiment;
 
 import ml.comet.experiment.impl.constants.AssetType;
-import ml.comet.experiment.model.GitMetadata;
 import ml.comet.experiment.model.ExperimentAssetLink;
 import ml.comet.experiment.model.ExperimentMetadataRest;
+import ml.comet.experiment.model.GitMetadata;
 import ml.comet.experiment.model.GitMetadataRest;
 import ml.comet.experiment.model.ValueMinMaxDto;
 
@@ -12,7 +12,14 @@
 import java.util.Optional;
 
 /**
- * Describes the public contract of the Experiment.
+ * The {@link Experiment} is a unit of measurable research that defines a single run with
+ * some data/parameters/code/results.
+ *
+ * <p>Creating an {@link Experiment} object in your code will report a new experiment to
+ * your Comet.ml project.
+ *
+ * <p>Your {@link Experiment} will automatically track and collect many things and will also
+ * allow you to manually report anything.
  */
 public interface Experiment {
 

comet-java-client/src/main/java/ml/comet/experiment/ExperimentBuilder.java

@@ -0,0 +1,29 @@
+package ml.comet.experiment;
+
+import lombok.experimental.UtilityClass;
+import ml.comet.experiment.builder.OnlineExperimentBuilder;
+import ml.comet.experiment.impl.OnlineExperimentImpl;
+
+/**
+ * The factory of builders to be used for creation of different {@link Experiment} implementations.
+ */
+@UtilityClass
+public class ExperimentBuilder {
+
+    /**
+     * Returns instance of the {@link OnlineExperimentBuilder} which can be used to
+     * configure and create fully initialized instance of the {@link OnlineExperiment}.
+     *
+     * <p>The configured instance of {@link OnlineExperiment} can be created as following:
+     * <pre>
+     *     OnlineExperiment experiment = ExperimentBuilder
+     *                                      .OnlineExperiment()
+     *                                      .build();
+     * </pre>
+     *
+     * @return the instance of the {@link OnlineExperimentBuilder}.
+     */
+    public static OnlineExperimentBuilder OnlineExperiment() {
+        return OnlineExperimentImpl.builder();
+    }
+}

comet-java-client/src/main/java/ml/comet/experiment/OnlineExperimentImpl.java

@@ -5,14 +5,16 @@
 /**
  * This is stub to support backward compatibility.
  *
- * @deprecated It would be replaced in the future with new experiment creation API.
+ * @deprecated You should use {@link ExperimentBuilder#OnlineExperiment()} instead to create
+ * instance of the {@link OnlineExperiment}.
  */
 @UtilityClass
 public final class OnlineExperimentImpl {
     /**
      * Returns builder to be used to create properly configured instance of {@link OnlineExperiment}.
      *
      * @return the builder to be used to create properly configured instance of {@link OnlineExperiment}.
+     * @deprecated please use {@link ExperimentBuilder#OnlineExperiment()} instead.
      */
     public static ml.comet.experiment.builder.OnlineExperimentBuilder builder() {
         return ml.comet.experiment.impl.OnlineExperimentImpl.builder();

comet-java-client/src/main/java/ml/comet/experiment/builder/ApiExperimentBuilder.java

@@ -7,5 +7,11 @@
  * to work with Comet API synchronously.
  */
 public interface ApiExperimentBuilder extends BaseCometBuilder<Experiment> {
-
+    /**
+     * Allows to continue a previous experiment by providing the key of the existing experiment.
+     *
+     * @param experimentKey The experiment key for the experiment that is being continued
+     * @return the builder configured with specified key of the previous experiment.
+     */
+    ApiExperimentBuilder withExistingExperimentKey(String experimentKey);
 }

comet-java-client/src/main/java/ml/comet/experiment/impl/ApiExperimentImpl.java

@@ -47,16 +47,6 @@ void init() {
         super.init();
     }
 
-    /**
-     * Returns builder to create ApiExperiment instance.
-     *
-     * @param experimentKey the unique identifier of the existing experiment.
-     * @return the initialized ApiExperiment instance.
-     */
-    public static ApiExperimentImpl.ApiExperimentBuilderImpl builder(@NonNull final String experimentKey) {
-        return new ApiExperimentImpl.ApiExperimentBuilderImpl(experimentKey);
-    }
-
     @Override
     public String getWorkspaceName() {
         return getMetadata().getWorkspaceName();
@@ -86,16 +76,40 @@ public Optional<String> getExperimentLink() {
         }
     }
 
+    /**
+     * Returns builder to create {@link Experiment} instance.
+     *
+     * @param experimentKey the unique identifier of the existing experiment.
+     * @return the initialized {@link ApiExperimentBuilder} instance.
+     */
+    public static ApiExperimentImpl.ApiExperimentBuilderImpl builder(@NonNull final String experimentKey) {
+        return builder().withExistingExperimentKey(experimentKey);
+    }
+
+    /**
+     * Returns builder to create {@link Experiment} instance.
+     *
+     * @return the initialized {@link ApiExperimentBuilder} instance.
+     */
+    public static ApiExperimentImpl.ApiExperimentBuilderImpl builder() {
+        return new ApiExperimentImpl.ApiExperimentBuilderImpl();
+    }
+
     /**
      * The builder to create properly configured ApiExperiment instance.
      */
     public static final class ApiExperimentBuilderImpl implements ApiExperimentBuilder {
-        private final String experimentKey;
+        private String experimentKey;
         private String apiKey;
         private Logger logger;
 
-        private ApiExperimentBuilderImpl(final String anExperimentKey) {
-            this.experimentKey = anExperimentKey;
+        private ApiExperimentBuilderImpl() {
+        }
+
+        @Override
+        public ApiExperimentImpl.ApiExperimentBuilderImpl withExistingExperimentKey(@NonNull String experimentKey) {
+            this.experimentKey = experimentKey;
+            return this;
         }
 
         @Override

comet-java-client/src/main/java/ml/comet/experiment/impl/CometApiImpl.java

@@ -39,7 +39,7 @@ public final class CometApiImpl implements CometApi {
         CometUtils.printCometSdkVersion();
     }
 
-    @SuppressWarnings("checkstyle:MissingJavadocMethod")
+    @Override
     public List<String> getAllWorkspaces() {
         if (this.logger.isDebugEnabled()) {
             this.logger.debug("getAllWorkspaces invoked");
@@ -51,7 +51,7 @@ public List<String> getAllWorkspaces() {
                 .getWorkspaceNames();
     }
 
-    @SuppressWarnings("checkstyle:MissingJavadocMethod")
+    @Override
     public List<RestProject> getAllProjects(@NonNull String workspaceName) {
         if (this.logger.isDebugEnabled()) {
             this.logger.debug("getAllProjects invoked");
@@ -63,7 +63,7 @@ public List<RestProject> getAllProjects(@NonNull String workspaceName) {
                 .getProjects();
     }
 
-    @SuppressWarnings("checkstyle:MissingJavadocMethod")
+    @Override
     public List<ExperimentMetadataRest> getAllExperiments(@NonNull String projectId) {
         if (this.logger.isDebugEnabled()) {
             this.logger.debug("getAllExperiments invoked");
@@ -120,7 +120,7 @@ public CometApiBuilder withApiKey(@NonNull String apiKey) {
         }
 
         /**
-         * Factory method to build fully initialized instance of the CometApiImpl.
+         * Factory method to build fully initialized instance of the {@link CometApi}.
          *
          * @return the fully initialized instance of the CometApiImpl.
          */