diff options
Diffstat (limited to 'jill-api/src/com/android/jill/api')
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); + } +} |