Rework Jack API, add better control over versioning

Change-Id: I1afa95dae0177c19891c3669a672bd5481191dba

6 files changed, 176 insertions, 194 deletions

diff --git a/jack-api/src/com/android/jack/api/JackConfigProvider.java b/jack-api/src/com/android/jack/api/JackConfigProvider.java
deleted file mode 100644
index 018b6d2..0000000
--- a/jack-api/src/com/android/jack/api/JackConfigProvider.java
+++ /dev/null
@@ -1,74 +0,0 @@
-/*
- * Copyright (C) 2015 The Android Open Source Project
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *      http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-
-package com.android.jack.api;
-
-import java.util.Collection;
-
-import javax.annotation.Nonnull;
-
-/**
- * Provides instances of {@link JackConfig}.
- */
-public interface JackConfigProvider {
-  @Nonnull
-  static final String CLASS_NAME = "com.android.jack.api.impl.JackConfigProviderImpl";
-
-  /**
-   * Creates a {@link JackConfig} instance for an interface representing a {@link JackConfig} API
-   * version.
-   * @param cls the {@link JackConfig} API interface
-   * @return the {@link JackConfig} instance
-   * @throws ConfigNotSupportedException If no implementation is found for the given interface.
-   */
-  @Nonnull
-  <T extends JackConfig> T getConfig(@Nonnull Class<T> cls) throws ConfigNotSupportedException;
-
-  /**
-   * Gives a {@link Collection} containing supported {@link JackConfig} API versions.
-   * @return the supported {@link JackConfig} API versions
-   */
-  @Nonnull
-  Collection<Class<? extends JackConfig>> getSupportedConfigs();
-
-  /**
-   * The code name of this Jack compiler.
-   * @return the code name
-   */
-  @Nonnull
-  String getCompilerCodeName();
-
-  /**
-   * The version of this Jack compiler.
-   * @return the version
-   */
-  @Nonnull
-  String getCompilerVersion();
-
-  /**
-   * The build ID of this Jack compiler.
-   * @return the build ID
-   */
-  @Nonnull
-  String getCompilerBuildId();
-
-  /**
-   * The code base of this Jack compiler.
-   * @return the code base
-   */
-  @Nonnull
-  String getCompilerCodeBase();
-}
diff --git a/jack-api/src/com/android/jack/api/JackProvider.java b/jack-api/src/com/android/jack/api/JackProvider.java
new file mode 100644
index 0000000..50cbfc1
--- /dev/null
+++ b/jack-api/src/com/android/jack/api/JackProvider.java
@@ -0,0 +1,140 @@
+/*
+ * Copyright (C) 2015 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.android.jack.api;
+
+import java.util.Collection;
+
+import javax.annotation.CheckForNull;
+import javax.annotation.Nonnegative;
+import javax.annotation.Nonnull;
+
+/**
+ * Provides instances of {@link JackConfig}.
+ */
+public interface JackProvider {
+  /**
+   * Creates a {@link JackConfig} instance for an interface representing a {@link JackConfig} API
+   * version.
+   * @param cls the {@link JackConfig} API interface
+   * @return the {@link JackConfig} instance
+   * @throws ConfigNotSupportedException If no implementation is found for the given interface.
+   */
+  @Nonnull
+  <T extends JackConfig> T createConfig(@Nonnull Class<T> cls) throws ConfigNotSupportedException;
+
+  /**
+   * Gives if an interface representing a {@link JackConfig} API version is supported.
+   *
+   * @param cls the {@link JackConfig} API interface
+   * @return if the config is supported
+   */
+  @Nonnull
+  <T extends JackConfig> boolean isConfigSupported(@Nonnull Class<T> cls);
+
+  /**
+   * Gives a {@link Collection} containing supported {@link JackConfig} API versions.
+   * @return the supported {@link JackConfig} API versions
+   */
+  @Nonnull
+  Collection<Class<? extends JackConfig>> getSupportedConfigs();
+
+  /**
+   * Gives the version of this Jack compiler, summarized in one string (e.g. "1.1-rc1", "2.0-a2",
+   * ...).
+   *
+   * @return the version
+   */
+  @Nonnull
+  String getCompilerVersion();
+
+  /**
+   * Gives the release name of this Jack compiler (e.g. Arzon, Brest, ...).
+   *
+   * @return the release name
+   */
+  @Nonnull
+  String getCompilerReleaseName();
+
+  /**
+   * Gives an integer value that represents the release of Jack compiler, relative to other release.
+   *
+   * @return the release code
+   */
+  @Nonnegative
+  int getCompilerReleaseCode();
+
+  /**
+   * Gives an integer value that represents the sub-release of Jack compiler, relative to other
+   * sub-release of the same release.
+   *
+   * @return the sub-release code
+   */
+  @Nonnegative
+  int getCompilerSubReleaseCode();
+
+  /**
+   * Gives the kind of the sub-release of Jack compiler.
+   *
+   * @return the sub-release kind
+   */
+  @Nonnull
+  SubReleaseKind getCompilerSubReleaseKind();
+
+  /**
+   * The kind of a sub-release.
+   */
+  public enum SubReleaseKind {
+    /**
+     * A sub-release from an engineering development, not tested, not in the code base repository.
+     */
+    ENGINEERING,
+    /**
+     * A sub-release not functionally completed, not tested.
+     */
+    PRE_ALPHA,
+    /**
+     * A sub-release not functionally completed, tested.
+     */
+    ALPHA,
+    /**
+     * A sub-release functionally completed, tested, but likely contains known or unknown bugs.
+     */
+    BETA,
+    /**
+     * A pre-production sub-release, tested.
+     */
+    CANDIDATE,
+    /**
+     * A production and stable sub-release.
+     */
+    RELEASE;
+  }
+
+  /**
+   * The build ID of this Jack compiler.
+   * @return the build ID, or null if not available
+   */
+  @CheckForNull
+  String getCompilerBuildId();
+
+  /**
+   * Identify the source code base of this Jack compiler.
+   * @return the source code base, or null if not available
+   */
+  @CheckForNull
+  String getCompilerSourceCodeBase();
+}
diff --git a/jack-api/src/com/android/jack/api/example/SampleWithClassLoader.java b/jack-api/src/com/android/jack/api/example/SampleWithClassLoader.java
deleted file mode 100644
index f2b3040..0000000
--- a/jack-api/src/com/android/jack/api/example/SampleWithClassLoader.java
+++ /dev/null
@@ -1,102 +0,0 @@
-/*
- * Copyright (C) 2015 The Android Open Source Project
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *      http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-
-package com.android.jack.api.example;
-
-import com.android.jack.api.ConfigNotSupportedException;
-import com.android.jack.api.JackConfig;
-import com.android.jack.api.JackConfigProvider;
-import com.android.jack.api.v01.AbortException;
-import com.android.jack.api.v01.Api01CompilationTask;
-import com.android.jack.api.v01.Api01Config;
-import com.android.jack.api.v01.ConfigurationException;
-import com.android.jack.api.v01.UnrecoverableException;
-
-import java.io.File;
-import java.lang.reflect.InvocationTargetException;
-import java.net.MalformedURLException;
-import java.net.URL;
-import java.net.URLClassLoader;
-
-/**
- * STOPSHIP
- */
-public class SampleWithClassLoader {
-
-  public static void main(String[] args) throws MalformedURLException, ClassNotFoundException,
-      SecurityException, NoSuchMethodException, IllegalArgumentException, InstantiationException,
-      IllegalAccessException, InvocationTargetException {
-    ClassLoader loader =
-        URLClassLoader.newInstance(new URL[] {new File(
-            "<replace_with_a_path_to_jack.jar>").toURI().toURL()},
-            SampleWithClassLoader.class.getClassLoader());
-
-    Class<? extends JackConfigProvider> confProviderClass =
-        Class.forName(JackConfigProvider.CLASS_NAME, true, loader).asSubclass(
-            JackConfigProvider.class);
-
-    JackConfigProvider confProvider = confProviderClass.getConstructor().newInstance();
-
-    System.out.println("Jack version: " + confProvider.getCompilerVersion() + " '"
-        + confProvider.getCompilerCodeName() + "' (" + confProvider.getCompilerBuildId() + " "
-        + confProvider.getCompilerCodeBase() + ")");
-
-    System.out.println("Supported configs: ");
-    for (Class<? extends JackConfig> cls : confProvider.getSupportedConfigs()) {
-      System.out.print(cls.getSimpleName() + " ");
-    }
-    System.out.println();
-
-    Api01CompilationTask compilationTask;
-    Api01Config config;
-
-    // Get configuration object
-    try {
-      config = confProvider.getConfig(Api01Config.class);
-    } catch (ConfigNotSupportedException e1) {
-      System.err.println("Brest config not supported)");
-      return;
-    }
-
-    // Configure the compiler
-    try {
-      // Set standard options
-      config.setOutputDexDir(new File("out/"));
-      config.setJarJarConfigFile(new File("rules.jarjar"));
-      // Set provisional properties
-      config.setProperty("jack.internal.test", "true");
-      // Check and build compiler
-      compilationTask = config.getTask();
-    } catch (ConfigurationException e) {
-      System.err.println(e.getMessage());
-      return;
-    }
-
-    // Run the compilation
-    try {
-      compilationTask.run();
-    } catch (AbortException e) {
-      System.out.println("User error, see reporter");
-      return;
-    } catch (UnrecoverableException e) {
-      System.out.println("Something out of Jack control has happen: " + e.getMessage());
-      return;
-    } catch (ConfigurationException e) {
-      System.err.println(e.getMessage());
-      return;
-    }
-  }
-}
diff --git a/jack-api/src/com/android/jack/api/example/SampleWithServiceLoader.java b/jack-api/src/com/android/jack/api/example/WithServiceLoader.java
index 3754946..3e2a82a 100644
--- a/jack-api/src/com/android/jack/api/example/SampleWithServiceLoader.java
+++ b/jack-api/src/com/android/jack/api/example/WithServiceLoader.java
@@ -17,10 +17,11 @@
 package com.android.jack.api.example;
 
 import com.android.jack.api.ConfigNotSupportedException;
-import com.android.jack.api.JackConfigProvider;
-import com.android.jack.api.v01.AbortException;
+import com.android.jack.api.JackConfig;
+import com.android.jack.api.JackProvider;
 import com.android.jack.api.v01.Api01CompilationTask;
 import com.android.jack.api.v01.Api01Config;
+import com.android.jack.api.v01.CompilationException;
 import com.android.jack.api.v01.ConfigurationException;
 import com.android.jack.api.v01.UnrecoverableException;
 
@@ -33,8 +34,7 @@ import java.util.ServiceLoader;
  * Sample of Jack api usage based on a service provider.
  * This sample requires jack.jar on classpath.
  */
-public class SampleWithServiceLoader {
-
+public class WithServiceLoader {
   public static void main(String[] args) throws SecurityException, IllegalArgumentException {
     if (args.length != 3) {
       System.out.println(
@@ -42,21 +42,39 @@ public class SampleWithServiceLoader {
       return;
     }
 
-    ServiceLoader<JackConfigProvider> serviceLoader = ServiceLoader.load(JackConfigProvider.class);
-    JackConfigProvider confProvider;
+    ServiceLoader<JackProvider> serviceLoader = ServiceLoader.load(JackProvider.class);
+    JackProvider provider;
     try {
-      confProvider = serviceLoader.iterator().next();
+      provider = serviceLoader.iterator().next();
     } catch (NoSuchElementException e) {
       System.out.println("Check that jack.jar is on classpath");
       return;
     }
 
+    System.out.println("Compiler version: " + provider.getCompilerVersion());
+    System.out.println("Compiler release name: " + provider.getCompilerReleaseName());
+    System.out.println("Compiler release code: " + provider.getCompilerReleaseCode());
+    System.out.println("Compiler sub-release kind: " + provider.getCompilerSubReleaseKind());
+    System.out.println("Compiler sub-release code: " + provider.getCompilerSubReleaseCode());
+    String str;
+    str = provider.getCompilerBuildId();
+    System.out.println("Compiler build id: " + ((str != null) ? str : "Unknown"));
+    str = provider.getCompilerSourceCodeBase();
+    System.out.println("Compiler souce code base: " + ((str != null) ? str : "Unknown"));
+    System.out.print("Supported configurations: ");
+
+    for (Class<? extends JackConfig> config : provider.getSupportedConfigs()) {
+      System.out.print(config.getSimpleName());
+      assert provider.isConfigSupported(config);
+    }
+    System.out.println();
+
     Api01CompilationTask compilationTask;
     Api01Config config;
 
     // Get configuration object
     try {
-      config = confProvider.getConfig(Api01Config.class);
+      config = provider.createConfig(Api01Config.class);
     } catch (ConfigNotSupportedException e1) {
       System.err.println("Brest config not supported)");
       return;
@@ -80,7 +98,7 @@ public class SampleWithServiceLoader {
     // Run the compilation
     try {
       compilationTask.run();
-    } catch (AbortException e) {
+    } catch (CompilationException e) {
       System.out.println("User error, see reporter");
       return;
     } catch (UnrecoverableException e) {
diff --git a/jack-api/src/com/android/jack/api/v01/Api01CompilationTask.java b/jack-api/src/com/android/jack/api/v01/Api01CompilationTask.java
index 479abc8..cf6141f 100644
--- a/jack-api/src/com/android/jack/api/v01/Api01CompilationTask.java
+++ b/jack-api/src/com/android/jack/api/v01/Api01CompilationTask.java
@@ -24,11 +24,11 @@ public interface Api01CompilationTask {
 
   /**
    * Runs the Jack compiler. May be called only once.
-   * @throws AbortException If a fatal error occurred during the compilation
+   * @throws CompilationException If a fatal error occurred during the compilation
    * @throws UnrecoverableException If an error out of Jack's control occurred
    * @throws ConfigurationException If there is an error in the configuration
    * @throws IllegalStateException If Jack is run more than once
    */
-  void run() throws AbortException, UnrecoverableException, ConfigurationException,
+  void run() throws CompilationException, UnrecoverableException, ConfigurationException,
       IllegalStateException;
 }
diff --git a/jack-api/src/com/android/jack/api/v01/AbortException.java b/jack-api/src/com/android/jack/api/v01/CompilationException.java
index 294efd1..99423a8 100644
--- a/jack-api/src/com/android/jack/api/v01/AbortException.java
+++ b/jack-api/src/com/android/jack/api/v01/CompilationException.java
@@ -19,25 +19,25 @@ package com.android.jack.api.v01;
 import javax.annotation.Nonnull;
 
 /**
- * A fatal problem that caused Jack to abort. The problem should already have reported, so it is
- * safe to ignore its message.
+ * A fatal problem that caused Jack to abort the compilation. The problem should already have
+ * reported, so it is safe to ignore its message.
  */
-public class AbortException extends Exception {
+public class CompilationException extends Exception {
   private static final long serialVersionUID = 1L;
 
-  public AbortException() {
+  public CompilationException() {
     super();
   }
 
-  public AbortException(@Nonnull String message) {
+  public CompilationException(@Nonnull String message) {
     super(message);
   }
 
-  public AbortException(@Nonnull String message, @Nonnull Throwable cause) {
+  public CompilationException(@Nonnull String message, @Nonnull Throwable cause) {
     super(message, cause);
   }
 
-  public AbortException(@Nonnull Throwable cause) {
+  public CompilationException(@Nonnull Throwable cause) {
     super(cause);
   }
 }