All Downloads are FREE. Search and download functionalities are using the official Maven repository.

com.hazelcast.org.codehaus.commons.compiler.ICompiler Maven / Gradle / Ivy

There is a newer version: 5.5.0
Show newest version

/*
 * Janino - An embedded Java[TM] compiler
 *
 * Copyright (c) 2019 Arno Unkrig. All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without modification, are permitted provided that the
 * following conditions are met:
 *
 *    1. Redistributions of source code must retain the above copyright notice, this list of conditions and the
 *       following disclaimer.
 *    2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the
 *       following disclaimer in the documentation and/or other materials provided with the distribution.
 *    3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote
 *       products derived from this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES,
 * INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
 * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
 * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */

package com.hazelcast.org.codehaus.commons.compiler;

import java.io.File;
import java.io.IOException;
import java.io.OutputStream;
import java.nio.charset.Charset;
import java.util.Collections;

import com.hazelcast.org.codehaus.commons.compiler.util.resource.ListableResourceFinder;
import com.hazelcast.org.codehaus.commons.compiler.util.resource.Resource;
import com.hazelcast.org.codehaus.commons.compiler.util.resource.ResourceCreator;
import com.hazelcast.org.codehaus.commons.compiler.util.resource.ResourceFinder;
import com.hazelcast.org.codehaus.commons.nullanalysis.Nullable;

/**
 * A simplified substitute for the javac tool.
 */
public
interface ICompiler {

    /**
     * Special value for {@link #setDestinationDirectory(File, boolean)}'s first parameter: Indicates that .class files
     * are to be created in the directory of the .java file from which they are generated.
     */
    @Nullable File NO_DESTINATION_DIRECTORY = null;

    /**
     * Special value for {@link #setClassFileFinder(ResourceFinder)}.
     *
     * @see #setClassFileFinder(ResourceFinder)
     */
    ResourceFinder FIND_NEXT_TO_SOURCE_FILE = new ListableResourceFinder() {
        @Override @Nullable public Resource           findResource(String resourceName)                { throw new UnsupportedOperationException("FIND_NEXT_TO_SOUJRCE_FILE"); } // SUPPRESS CHECKSTYLE LineLength:2
        @Override @Nullable public Iterable list(String resourceNamePrefix, boolean recurse) { return Collections.emptyList();                                       }
        @Override public String                       toString()                                       { return "FIND_NEXT_TO_SOUJRCE_FILE";                                   }
    };

    /**
     * Special value for {@link #setClassFileCreator(ResourceCreator)}: Indicates that .class resources are to be
     * created in the directory of the .java resource from which they are generated.
     */
    ResourceCreator CREATE_NEXT_TO_SOURCE_FILE = new ResourceCreator() {
        @Override public boolean      deleteResource(String resourceName) { throw new UnsupportedOperationException("CREATE_NEXT_TO_SOURCE_FILE"); } // SUPPRESS CHECKSTYLE LineLength:2
        @Override public OutputStream createResource(String resourceName) { throw new UnsupportedOperationException("CREATE_NEXT_TO_SOURCE_FILE"); }
        @Override public String       toString()                          { return "CREATE_NEXT_TO_SOURCE_FILE";                                   }
    };

    /**
     * The equivalent of JAVA's "{@code -encoding}" command line option.
     *
     * @see #setSourceCharset(Charset)
     */
    void setEncoding(Charset encoding);

    /**
     * Same as {@link #setEncoding(Charset)}, but with a more precise name.
     */
    void setSourceCharset(Charset charset);

    /**
     * @deprecated Use {@link #setSourceCharset(Charset)} instead
     */
    @Deprecated void setCharacterEncoding(@Nullable String characterEncoding);

    /**
     * Equivalent of {@code -g:lines}.
     */
    void setDebugLines(boolean value);

    /**
     * Equivalent of {@code -g:vars}.
     */
    void setDebugVars(boolean value);

    /**
     * Equivalent of {@code -g:source}.
     */
    void setDebugSource(boolean value);

    /**
     * Specifies the version of source code accepted, in analogy with JAVAC's {@code -source} command line option.
     * May be ignored by an implementation (e.g. the {@code janino} implementation always accepts the language features
     * as described on the home page).
     * Allowed values, and the default value, depend on the implementation.
     * {@code -1} means to use a default version.
     */
    void setSourceVersion(int version);

    /**
     * Generates class files that target a specified release of the virtual machine, in analogy with JAVAC's {@code
     * -target} command line option.
     * Allowed values depend on the implementation.
     * The default value also depends on the implementation.
     * The only invariant is that the generated class files are suitable for the currently executing JVM.
     * {@code -1} means to use a default version.
     */
    void setTargetVersion(int version);

    /**
     * Finds more {@code .java} resources that need to be compiled, i.e. implements JAVAC's {@code -sourcepath} option.
     */
    void setSourceFinder(ResourceFinder sourceFinder);

    /**
     * Equivalent of {@code --source-path}.
     * 

* Equivalent with {@code setSourceFinder(new PathResourceFinder(directoriesAndArchives))}. *

*/ void setSourcePath(File[] directoriesAndArchives); /** * Equivalent of *{@code --boot-class-path}. */ void setBootClassPath(File[] directoriesAndArchives); /** * Equivalent of {@code -extdirs}. */ void setExtensionDirectories(File[] directories); /** * Equivalent of *--class-path. */ void setClassPath(File[] directoriesAndArchives); /** * Equivalent of *-d and {@code -rebuild}. *

* Overrides any previously configured {@link #setClassFileFinder(ResourceFinder) class file finder} and {@link * #setClassFileCreator(ResourceCreator) class file creator}. *

* * @param destinationDirectory {@link #NO_DESTINATION_DIRECTORY} means "create .class resources in * the directory of the .java resource from which they are generated" * @see #NO_DESTINATION_DIRECTORY * @see #setClassFileFinder(ResourceFinder) * @see #setClassFileCreator(ResourceCreator) */ void setDestinationDirectory(@Nullable File destinationDirectory, boolean rebuild); /** * Equivalent with {@code setClassFileFinder(rebuild ? ResourceFinder.EMPTY_RESOURCE_FINDER : classFileFinder)}. */ void setClassFileFinder(ResourceFinder classFileFinder, boolean rebuild); /** * This {@link ResourceFinder} is used to check whether a {@code .class} resource already exists and is younger * than the {@code .java} resource from which it was generated. *

* If it is impossible to check whether an already-compiled class file exists, or if you want to enforce * recompilation, pass {@link ResourceFinder#EMPTY_RESOURCE_FINDER} as the classFileFinder. *

*

* The default is, as for JAVAC, {@link #FIND_NEXT_TO_SOURCE_FILE}. *

* * @param classFileFinder Special value {@link #FIND_NEXT_TO_SOURCE_FILE} means ".class file is next to * its source file, not in the destination directory" * @see #FIND_NEXT_TO_SOURCE_FILE */ void setClassFileFinder(ResourceFinder classFileFinder); /** * This {@link ResourceCreator} is used to store generated {@code .class} files. *

* The default is, as for JAVAC, {@link #CREATE_NEXT_TO_SOURCE_FILE}. *

* * @param classFileCreator Special value {@link #CREATE_NEXT_TO_SOURCE_FILE} means "create .class file * next to its source file, not in the destination directory" * @see #CREATE_NEXT_TO_SOURCE_FILE */ void setClassFileCreator(ResourceCreator classFileCreator); /** * Equivalent of {@code -verbose}. */ void setVerbose(boolean verbose); /** * Reads a set of Java compilation units (a.k.a. "source files") from the file system, compiles them into a set of * "class files" and stores these in the file system. Additional source files are parsed and compiled on demand * through the "source path" set of directories. *

* For example, if the source path comprises the directories "A/B" and "../C", then the source file for class * "com.acme.Main" is searched in *

*
*
A/B/com/acme/Main.java *
../C/com/acme/Main.java *
*

* Notice that it does make a difference whether you pass multiple source files to {@link #compile(File[])} or if * you invoke {@link #compile(File[])} multiply: In the former case, the source files may contain arbitrary * references among each other (even circular ones). In the latter case, only the source files on the source path * may contain circular references, not the sourceFiles. *

*

* This method must be called exactly once after object construction. *

*

* Compile errors are reported as described at {@link #setCompileErrorHandler(ErrorHandler)}. *

* * @param sourceFiles Contain the compilation units to compile * @return {@code true} for backwards compatibility (return value can safely be ignored) * @throws CompileException Fatal compilation error, or the {@link CompileException} thrown be the installed * compile error handler * @throws IOException Occurred when reading from the sourceFiles */ boolean compile(File[] sourceFiles) throws CompileException, IOException; /** * See {@link #compile(File[])}. * * @param sourceResources Contain the compilation units to compile */ void compile(Resource[] sourceResources) throws CompileException, IOException; /** * By default, {@link CompileException}s are thrown on compile errors, but an application my install its own * {@link ErrorHandler}. *

* Be aware that a single problem during compilation often causes a bunch of compile errors, so a good {@link * ErrorHandler} counts errors and throws a {@link CompileException} when a limit is reached. *

*

* If the given {@link ErrorHandler} throws {@link CompileException}s, then the compilation is terminated and * the exception is propagated. *

*

* If the given {@link ErrorHandler} does not throw {@link CompileException}s, then the compiler may or may not * continue compilation, but must eventually throw a {@link CompileException}. *

*

* In other words: The {@link ErrorHandler} may throw a {@link CompileException} or not, but the compiler must * definitely throw a {@link CompileException} if one or more compile errors have occurred. *

* * @param errorHandler {@code null} to restore the default behavior (throwing a {@link CompileException} */ void setCompileErrorHandler(@Nullable ErrorHandler errorHandler); /** * By default, warnings are discarded, but an application my install a custom {@link WarningHandler}. * * @param warningHandler {@code null} to indicate that no warnings be issued */ void setWarningHandler(WarningHandler warningHandler); }




© 2015 - 2024 Weber Informatics LLC | Privacy Policy