Add jill-api project

Change-Id: I0552ee390655e89a593f58ef28ebe3ede8eda0bf

8 files changed, 485 insertions, 0 deletions

diff --git a/jill-api/src/com/android/jill/api/ConfigNotSupportedException.java b/jill-api/src/com/android/jill/api/ConfigNotSupportedException.java
new file mode 100644
index 0000000..e4848f5
--- /dev/null
+++ b/jill-api/src/com/android/jill/api/ConfigNotSupportedException.java
@@ -0,0 +1,42 @@
+/*
+ * 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.jill.api;
+
+import javax.annotation.Nonnull;
+
+/**
+ * Thrown when the requested Jill configuration for a given API version is not supported.
+ */
+public class ConfigNotSupportedException extends Exception {
+  private static final long serialVersionUID = 1L;
+
+  public ConfigNotSupportedException() {
+    super();
+  }
+
+  public ConfigNotSupportedException(@Nonnull String message) {
+    super(message);
+  }
+
+  public ConfigNotSupportedException(@Nonnull String message, @Nonnull Throwable cause) {
+    super(message, cause);
+  }
+
+  public ConfigNotSupportedException(@Nonnull Throwable cause) {
+    super(cause);
+  }
+}
diff --git a/jill-api/src/com/android/jill/api/JillConfig.java b/jill-api/src/com/android/jill/api/JillConfig.java
new file mode 100644
index 0000000..cde0c35
--- /dev/null
+++ b/jill-api/src/com/android/jill/api/JillConfig.java
@@ -0,0 +1,23 @@
+/*
+ * 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.jill.api;
+
+/**
+ * Allows to set a configuration for Jill.
+ */
+public interface JillConfig {
+}
diff --git a/jill-api/src/com/android/jill/api/JillProvider.java b/jill-api/src/com/android/jill/api/JillProvider.java
new file mode 100644
index 0000000..30fd4e3
--- /dev/null
+++ b/jill-api/src/com/android/jill/api/JillProvider.java
@@ -0,0 +1,141 @@
+/*
+ * 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.jill.api;
+
+import java.util.Collection;
+
+import javax.annotation.CheckForNull;
+import javax.annotation.Nonnegative;
+import javax.annotation.Nonnull;
+
+/**
+ * Provides instances of {@link JillConfig}.
+ */
+public interface JillProvider {
+  /**
+   * Creates a {@link JillConfig} instance for an interface representing a {@link JillConfig} API
+   * version.
+   * @param cls the {@link JillConfig} API interface
+   * @return the {@link JillConfig} instance
+   * @throws ConfigNotSupportedException If no implementation is found for the given interface.
+   */
+  @Nonnull
+  <T extends JillConfig> T createConfig(@Nonnull Class<T> cls) throws ConfigNotSupportedException;
+
+  /**
+   * Returns whether an interface representing a {@link JillConfig} API version is supported.
+   *
+   * @param cls the {@link JillConfig} API interface
+   * @return <code>true</true> if the config is supported
+   */
+  @Nonnull
+  <T extends JillConfig> boolean isConfigSupported(@Nonnull Class<T> cls);
+
+  /**
+   * Gives a {@link Collection} containing supported {@link JillConfig} API versions.
+   * @return the supported {@link JillConfig} API versions
+   */
+  @Nonnull
+  Collection<Class<? extends JillConfig>> getSupportedConfigs();
+
+  /**
+   * Gives the version of this Jill, summarized in one string (e.g. "1.1-rc1", "2.0-a2",
+   * ...).
+   *
+   * @return the version
+   */
+  @Nonnull
+  String getTranslatorVersion();
+
+  /**
+   * Gives the release name of this Jill (e.g. Arzon, Brest, ...).
+   *
+   * @return the release name
+   */
+  @Nonnull
+  String getTranslatorReleaseName();
+
+  /**
+   * Gives an integer value that represents the release of this Jill, relative to other
+   * releases.
+   *
+   * @return the release code
+   */
+  @Nonnegative
+  int getTranslatorReleaseCode();
+
+  /**
+   * Gives an integer value that represents the sub-release of this Jill, relative to other
+   * sub-releases of the same release.
+   *
+   * @return the sub-release code
+   */
+  @Nonnegative
+  int getTranslatorSubReleaseCode();
+
+  /**
+   * Gives the kind of sub-release of this Jill.
+   *
+   * @return the sub-release kind
+   */
+  @Nonnull
+  SubReleaseKind getTranslatorSubReleaseKind();
+
+  /**
+   * The kind of sub-release.
+   */
+  public enum SubReleaseKind {
+    /**
+     * A sub-release from an engineering development, not tested, not in the code base repository.
+     */
+    ENGINEERING,
+    /**
+     * A sub-release that is not feature complete, not tested.
+     */
+    PRE_ALPHA,
+    /**
+     * A sub-release that is not feature complete, tested.
+     */
+    ALPHA,
+    /**
+     * A sub-release that is feature complete, 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 Jill.
+   * @return the build ID, or null if not available
+   */
+  @CheckForNull
+  String getTranslatorBuildId();
+
+  /**
+   * Identify the source code base of this Jill.
+   * @return the source code base, or null if not available
+   */
+  @CheckForNull
+  String getTranslatorSourceCodeBase();
+}
diff --git a/jill-api/src/com/android/jill/api/example/WithServiceLoader.java b/jill-api/src/com/android/jill/api/example/WithServiceLoader.java
new file mode 100644
index 0000000..cd720f0
--- /dev/null
+++ b/jill-api/src/com/android/jill/api/example/WithServiceLoader.java
@@ -0,0 +1,103 @@
+/*
+ * 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.jill.api.example;
+
+import com.android.jill.api.ConfigNotSupportedException;
+import com.android.jill.api.JillConfig;
+import com.android.jill.api.JillProvider;
+import com.android.jill.api.v01.Api01Config;
+import com.android.jill.api.v01.Api01TranslationTask;
+import com.android.jill.api.v01.ConfigurationException;
+import com.android.jill.api.v01.TranslationException;
+
+import java.io.File;
+import java.util.NoSuchElementException;
+import java.util.ServiceLoader;
+
+/**
+ * Sample of Jill api usage based on a service provider.
+ * This sample requires jill.jar on classpath.
+ */
+public class WithServiceLoader {
+  public static void main(String[] args) throws SecurityException, IllegalArgumentException {
+    if (args.length != 2) {
+      System.out.println(
+          "Usage: <jill input archive> <jill output archive>");
+      return;
+    }
+
+    ServiceLoader<JillProvider> serviceLoader = ServiceLoader.load(JillProvider.class);
+    JillProvider provider;
+    try {
+      provider = serviceLoader.iterator().next();
+    } catch (NoSuchElementException e) {
+      System.out.println("Check that jill.jar is on classpath");
+      return;
+    }
+
+    System.out.println("Translator version: " + provider.getTranslatorVersion());
+    System.out.println("Translator release name: " + provider.getTranslatorReleaseName());
+    System.out.println("Translator release code: " + provider.getTranslatorReleaseCode());
+    System.out.println("Translator sub-release kind: " + provider.getTranslatorSubReleaseKind());
+    System.out.println("Translator sub-release code: " + provider.getTranslatorSubReleaseCode());
+    String str;
+    str = provider.getTranslatorBuildId();
+    System.out.println("Translator build id: " + ((str != null) ? str : "Unknown"));
+    str = provider.getTranslatorSourceCodeBase();
+    System.out.println("Translator souce code base: " + ((str != null) ? str : "Unknown"));
+    System.out.print("Supported configurations: ");
+
+    for (Class<? extends JillConfig> config : provider.getSupportedConfigs()) {
+      System.out.print(config.getSimpleName());
+      assert provider.isConfigSupported(config);
+    }
+    System.out.println();
+
+    Api01TranslationTask translationTask;
+    Api01Config config;
+
+    // Get configuration object
+    try {
+      config = provider.createConfig(Api01Config.class);
+    } catch (ConfigNotSupportedException e1) {
+      System.err.println("Brest config not supported)");
+      return;
+    }
+
+    // Configure
+    try {
+      config.setInputJavaBinaryFile(new File(args[0]));
+
+      config.setOutputJackFile(new File(args[1]));
+
+      // Check and build
+      translationTask = config.getTask();
+
+    } catch (ConfigurationException e) {
+      System.err.println(e.getMessage());
+      return;
+    }
+
+    // Run the translation
+    try {
+      translationTask.run();
+    } catch (TranslationException e) {
+      System.out.println("User error, see reporter");
+      return;
+    }
+  }
+}
diff --git a/jill-api/src/com/android/jill/api/v01/Api01Config.java b/jill-api/src/com/android/jill/api/v01/Api01Config.java
new file mode 100644
index 0000000..b1923bd
--- /dev/null
+++ b/jill-api/src/com/android/jill/api/v01/Api01Config.java
@@ -0,0 +1,64 @@
+/*
+ * 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.jill.api.v01;
+
+
+import com.android.jill.api.JillConfig;
+
+import java.io.File;
+
+import javax.annotation.Nonnull;
+
+/**
+* A configuration implementation for API level 01 of Jill.
+*/
+public interface Api01Config extends JillConfig {
+
+  /**
+   * Sets verbosity mode.
+   * @param isVerbose the desired verbosity mode
+   */
+  void setVerbose(boolean isVerbose) throws ConfigurationException;
+
+  /**
+   * Sets jar file to apply the Jill translation onto. The file must exist.
+   * @param input jar file to translate
+   */
+  void setInputJavaBinaryFile(@Nonnull File input) throws ConfigurationException;
+
+  /**
+   * Sets the file where the output Jack library will be written. The file may already exist and
+   * will be overwritten.
+   * @param outputJackFile The output Jack library file
+   * @throws ConfigurationException
+   */
+  void setOutputJackFile(@Nonnull File outputJackFile) throws ConfigurationException;
+
+
+  /**
+   * Sets whether debug info should be emitted.
+   * @param debugInfo the desired mode for debug info emission
+   */
+  void setDebugInfo(boolean debugInfo) throws ConfigurationException;
+
+  /**
+   * Creates an instance of the {@link Api01TranslationTask} according to this configuration.
+   * @return The {@link Api01TranslationTask}
+   */
+  @Nonnull
+  Api01TranslationTask getTask() throws ConfigurationException;
+}
diff --git a/jill-api/src/com/android/jill/api/v01/Api01TranslationTask.java b/jill-api/src/com/android/jill/api/v01/Api01TranslationTask.java
new file mode 100644
index 0000000..25f70bf
--- /dev/null
+++ b/jill-api/src/com/android/jill/api/v01/Api01TranslationTask.java
@@ -0,0 +1,31 @@
+/*
+ * 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.jill.api.v01;
+
+
+/**
+ * A task allowing to run Jill once.
+ */
+public interface Api01TranslationTask {
+
+  /**
+   * Runs the translation task. May be called only once.
+   * @throws TranslationException If a fatal error occurred during the translation
+   * @throws IllegalStateException If the translation task is run more than once
+   */
+  void run() throws TranslationException, IllegalStateException;
+}
diff --git a/jill-api/src/com/android/jill/api/v01/ConfigurationException.java b/jill-api/src/com/android/jill/api/v01/ConfigurationException.java
new file mode 100644
index 0000000..76f0d87
--- /dev/null
+++ b/jill-api/src/com/android/jill/api/v01/ConfigurationException.java
@@ -0,0 +1,38 @@
+/*
+ * Copyright (C) 2014 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.jill.api.v01;
+
+import javax.annotation.Nonnull;
+
+/**
+ * Thrown when something is wrong in Jill configuration.
+ */
+public class ConfigurationException extends Exception {
+  private static final long serialVersionUID = 1L;
+
+  public ConfigurationException(@Nonnull String message) {
+    super(message);
+  }
+
+  public ConfigurationException(@Nonnull String message, @Nonnull Throwable cause) {
+    super(message, cause);
+  }
+
+  public ConfigurationException(@Nonnull Throwable cause) {
+    super(cause);
+  }
+}
diff --git a/jill-api/src/com/android/jill/api/v01/TranslationException.java b/jill-api/src/com/android/jill/api/v01/TranslationException.java
new file mode 100644
index 0000000..41121b3
--- /dev/null
+++ b/jill-api/src/com/android/jill/api/v01/TranslationException.java
@@ -0,0 +1,43 @@
+/*
+ * 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.jill.api.v01;
+
+import javax.annotation.Nonnull;
+
+/**
+ * A fatal problem that caused Jill to abort the translation. The problem should already have
+ * reported, so it is safe to ignore its message.
+ */
+public class TranslationException extends Exception {
+  private static final long serialVersionUID = 1L;
+
+  public TranslationException() {
+    super();
+  }
+
+  public TranslationException(@Nonnull String message) {
+    super(message);
+  }
+
+  public TranslationException(@Nonnull String message, @Nonnull Throwable cause) {
+    super(message, cause);
+  }
+
+  public TranslationException(@Nonnull Throwable cause) {
+    super(cause);
+  }
+}