compiler/src/org/apache/flex/compiler/units/ICompilationUnit.java

/*
 *
 *  Licensed to the Apache Software Foundation (ASF) under one or more
 *  contributor license agreements.  See the NOTICE file distributed with
 *  this work for additional information regarding copyright ownership.
 *  The ASF licenses this file to You 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 org.apache.flex.compiler.units;

import java.io.File;
import java.util.Collection;
import java.util.List;
import java.util.Map;
import java.util.Set;
import java.util.concurrent.atomic.AtomicInteger;

import org.apache.flex.compiler.common.IDefinitionPriority;
import org.apache.flex.compiler.definitions.IDefinition;
import org.apache.flex.compiler.internal.targets.Target;
import org.apache.flex.compiler.internal.units.CompilationUnitBase;
import org.apache.flex.compiler.problems.ICompilerProblem;
import org.apache.flex.compiler.projects.ICompilerProject;
import org.apache.flex.compiler.targets.ITarget.TargetType;
import org.apache.flex.compiler.units.requests.IABCBytesRequestResult;
import org.apache.flex.compiler.units.requests.IFileScopeRequestResult;
import org.apache.flex.compiler.units.requests.IOutgoingDependenciesRequestResult;
import org.apache.flex.compiler.units.requests.IRequest;
import org.apache.flex.compiler.units.requests.ISWFTagsRequestResult;
import org.apache.flex.compiler.units.requests.ISyntaxTreeRequestResult;


/**
 * A unit of compilation. Implementations provide methods to request definitions
 * ( getFileScopeRequest ), semantic errors/warnings (
 * getOutgoingDependenciesRequest ), abc bytes ( getABCBytesRequest ), and SWF tags
 * ( getSWFTagsRequest ). Implementations of this interface are the main means
 * that AS3, MXML, and associated source files are converted to bytes in SWF.
 */
public interface ICompilationUnit
{
    /**
     * An enumeration with an entry for each ICompilationUnit operation. Used in
     * tracking which operation results of another ICompilaitonUnit that an
     * ICompilationUnit depends on.
     */
    enum Operation
    {
        GET_SYNTAX_TREE,
        GET_FILESCOPE,
        GET_SEMANTIC_PROBLEMS,
        GET_ABC_BYTES,
        GET_SWF_TAGS,
        INVALIDATE_CU;
        
        Operation()
        {
            assert ordinal() < 31 : "We should not have more than 8 operations, let alone 31!";
            mask = 1 << ordinal();
        }
        
        /**
         * This mask is used by {@link CompilationUnitBase}  to update
         * a {@link AtomicInteger} that keeps track of which operations have
         * been completed.
         */
        public final int mask;
    }

    /**
     * An enumeration with an entry for each ICompilationUnit source type.
     */
    enum UnitType
    {
        AS_UNIT,
        ABC_UNIT,
        FXG_UNIT,
        MXML_UNIT,
        CSS_UNIT,
        SWC_UNIT,
        EMBED_UNIT,
        RESOURCE_UNIT
    }

    /**
     * @return The project that contains this ICompilationUnit.
     */
    ICompilerProject getProject();

    /**
     * Gets the request object from which the caller can extract the syntax tree
     * and any source file parsing {@link ICompilerProblem}'s
     * for this {@link ICompilationUnit}. Implementations may update the dependency
     * graph in the project as a side
     * affect of this operation.
     * 
     * @return The request object for the getFileScope operation.
     */
    IRequest<ISyntaxTreeRequestResult, ICompilationUnit> getSyntaxTreeRequest();
    
    /**
     * Gets the request object from which the caller can extract the root scope,
     * AST, and any parsing ICompilerProblems, for the CompilationUnit.
     * Implementations may update the dependency graph in the project as a side
     * affect of this operation.
     * 
     * @return The request object for the getFileScope operation.
     */
    IRequest<IFileScopeRequestResult, ICompilationUnit> getFileScopeRequest();

    /**
     * Gets the request object from which the caller cause the dependency graph to be updated
     * with all the dependencies from this compilation unit.
     * 
     * @return The request object for the getFileScope operation.
     */
    IRequest<IOutgoingDependenciesRequestResult, ICompilationUnit> getOutgoingDependenciesRequest ();

    /**
     * Gets the request object from which the caller can extract the abc bytes
     * generated for this ICompilationUnit. Implementations may update the
     * dependency graph in the project as a side affect of this operation.
     * 
     * @return The request object for the getFileScope operation.
     */
    IRequest<IABCBytesRequestResult, ICompilationUnit> getABCBytesRequest();

    /**
     * Gets the request object with which the caller can add the SWF tags
     * generated for this ICompilationUnit to a ISWF. Implementations may update
     * the dependency graph in the project as a side affect of this operation.
     * 
     * @return The request object for the getFileScope operation.
     */
    IRequest<ISWFTagsRequestResult, ICompilationUnit> getSWFTagsRequest();

    /**
     * @return The identifier names defined by the compilation unit
     * @throws InterruptedException 
     */
    List<String> getShortNames() throws InterruptedException;

    /**
     * @return The qualified names defined by the compilation unit
     * @throws InterruptedException 
     */
    List<String> getQualifiedNames() throws InterruptedException;

    /**
     * Gets a string that is unique to the compilation unit instance and can be
     * used to produce an ordering of compilation units that is stable across
     * different compilation runs.
     * 
     * Note that is is critical that everyone who implements this interface
     * implements this method correctly. If not, the compiler will act in
     * a non-deterministic way.
     * 
     * Also, note that this is the String that will be written to the link report as
     * the name of this compilation unit.
     * 
     * @return The unique name string for the compilation unit.
     */
    String getName();

    /**
     * Gets the path to the compilation unit instance. The string is unique to
     * the compilation unit instance. This string will also be used in reporting
     * errors.
     * 
     * @return The absolute path for the compilation unit.
     */
    String getAbsoluteFilename();

    /**
     * @return List of definition promises
     */
    List<IDefinition> getDefinitionPromises();

    /**
     * @return the compilation unit type
     */
    UnitType getCompilationUnitType();

    /**
     * Removes all data created during a compile Clients should not call this
     * method directly, as it can potentially leave the ICompilationUnit in an
     * invalid state. Read the CompilerProject.clean implementation for more
     * details.
     * 
     * @param invalidatedSWCFiles Map of SWC filenames and depending projects
     * which have been invalidated by this call
     * @param cusToUpdate {@link Map} from {@link ICompilerProject} to
     * {@link Set} of {@link ICompilationUnit}s in the project whose externally
     * visible symbols need to be re-registered with the symbol table of the
     * containing {@link ICompilerProject} when cleaning is complete.
     * @param clearFileScope Whether to clear the file scope
     * @return whether an invalidation was done
     */
    boolean clean(Map<ICompilerProject, Set<File>> invalidatedSWCFiles, Map<ICompilerProject, Set<ICompilationUnit>> cusToUpdate, boolean clearFileScope);

    /**
     * Gets the definition priority for definitions defined by the compilation
     * unit. The "priority" of a definition determines whether that definition
     * shadows definitions from other compilation units that have the same
     * qname.
     * 
     * @return The definition priority for definitions defined by the compilation
     * unit.
     */
    IDefinitionPriority getDefinitionPriority();

    /**
     * Called by {@link ICompilerProject}'s when an {@link ICompilationUnit}
     * is removed from a project.  Implementations should clear an references
     * to the containing project when this method is called.  After this
     * method is called {@link #getProject()} should return null.
     */
    void clearProject();

    /**
     * Wait till the compilation unit finishes building, and collect compiler
     * problems. After calling this method, this compilation unit will be in a
     * fully compiled state.
     * 
     * @see ICompilationUnit#startBuildAsync
     * @param problems Problems from executing the requests.
     * @param targetType type of the active {@link Target}
     * @throws InterruptedException Concurrency error.
     */
    void waitForBuildFinish(Collection<ICompilerProblem> problems, TargetType targetType) throws InterruptedException;
    
    /**
     * This method starts to build the compilation unit asynchronously. It kicks
     * off all the request methods on the compilation unit.
     * 
     * @param targetType type of the active {@link Target}
     */
    void startBuildAsync(TargetType targetType);

    /**
     * @return true if this {@link ICompilationUnit} does *not*
     * put its global definitions in the {@link ICompilerProject}'s
     * symbol table, false otherwise.
     */
    boolean isInvisible();

    /**
     * @return A collection of all filenames which are embedded in
     * this {@link ICompilationUnit} through Embed metadata. This
     * will never return null.
     */
    Collection<String> getEmbeddedFilenames();
}