/*
 *                 Sun Public License Notice
 * 
 * The contents of this file are subject to the Sun Public License
 * Version 1.0 (the "License"). You may not use this file except in
 * compliance with the License. A copy of the License is available at
 * http://www.sun.com/
 * 
 * The Original Code is NetBeans. The Initial Developer of the Original
 * Code is Sun Microsystems, Inc. Portions Copyright 1997-2000 Sun
 * Microsystems, Inc. All Rights Reserved.
 */

package org.openide.compiler;

import java.util.*;

import org.openide.util.Mutex;

/** A compiler job consists of more {@link Compiler}s with dependencies
* between each other. The compiler job can compiled, built or
* cleaned. To handle each of these jobs the instance of the
* compilation engine is obtained and its is up to it to
* decide whether it will compile in one thread, a thread group, etc.
*
* 
A module author only needs to instantiate this class if it is
* desired to initiate a whole compilation process from scratch;
* normally {@link org.openide.actions.AbstractCompileAction} does
* this. Usually it is only used as the argument to a constructor for
* a {@link Compiler} implementation.
*
* @author Jaroslav Tulach, Ales Novak */
public final class CompilerJob extends Object implements Compilable {
    /** collection of all added compilers */
    private IdSet compilers = new IdSet ();

    /** non modifiable set of compilers */
    private Collection noModCompilers;
    
    /** name of the job */
    private String name = ""; // NOI18N

    /** the initial depth the job is started for */
    private Compiler.Depth depth;

    /** computed graph that represent this object.
    */
    private Graph graph;

    /** collection of objects this job depends on */
    private IdSet dependsOn;
    
    /** a collection of objects this job depends on for public usage */
    private Collection noModDependsOn = Collections.EMPTY_LIST;
    

    /** Create a new job with the given initial depth.
    * @param depth initial depth of the job; normally {@link Compiler#DEPTH_ONE} for Compile action, and {@link Compiler#DEPTH_INFINITE} for Compile All action
    */
    public CompilerJob (Compiler.Depth depth) {
        this.depth = depth;
    }

    /** Get the depth of the job. This indicates
    * the depth at which the job was started.
    * @return the compiler depth
    */
    public Compiler.Depth getInitialDepth () {
        return depth;
    }


    /** Start asynchronous compilation of the job.
    * 
Usually used by, e.g., AbstractCompileAction.
    * @return a compiler task to track the state of the compilation
    */
    public CompilerTask start () {
        return CompilationEngine.getDefault ().start (this);
    }

    /** Test if the set of compilers in the job still needs to be compiled.
    * Scans the compilers looking for any that are not up to date.
    *
    * @return true if every compiler is up to date, false if at least one compilation
    *   is needed
    */
    public final boolean isUpToDate () {
        return getGraph ().isUpToDate (null);
    }

    /** Test if the set of compilers in the job still needs to be compiled.
     * Scans the compilers looking for any that are not up to date and also 
     * check that timestamps of all compilers are older or equal to the given date.
     * Otherwise the job is considered not up to date.
     *
     * @param date job is up to date only in case timestamps of all compilers
     * are older or equal to the given date. If date is null, the timestamps are ignored
     *
     * @return true if every compiler is up to date, false if at least one compilation
     *   is needed
     *
     * @since 2.16
     */
    public final boolean isUpToDate(Date date) {
        return getGraph().isUpToDate(date);
    }

    /** Set the display name of this job.
    * @param s the human readable name of this job
    */
    public void setDisplayName (String s) {
        name = s;
    }

    /** Takes all compilers in this job and merges them into another job.
    * If any other compiler should depend on result of this compilation,
    * then it should depend on the returned compiler.
    *
    * @param target job to merge into
    * @return compiler compiler representing compilation of whole job in
    *   the target job
    *
    public synchronized Compiler mergeInto (CompilerJob target) {
      return target.add (this);
}
    */

    /** Get the display name of the job
    * @return a human readable name of this job
    */
    public String getDisplayName () {
        return name;
    }

    /** Adds a compiler into the job.
    * @param comp the compiler
    */
    public void add (Compiler comp) {
        add (Collections.singleton(comp));
    }

    /** Adds compilers into the job.
    * @param comps collection of Compiler
    */
    public void add (final Collection comps) {
        MUTEX.readAccess (new Runnable () {
                              public void run () {
                                  synchronized (CompilerJob.this) {
                                      graph = null;
                                      compilers.addAll (comps);
                                  }
                              }
                          });
    }

    /** Adds a dependency. Before any compiler added into this job
    * will be started, given dependency has to be satified (compiled).
    *
    * @param c compilable 
    */
    public void dependsOn (Compilable c) {
        dependsOn (Collections.singleton (c));
    }

    /** Adds a dependency. Before any compiler added into this job
    * will be started, given dependency has to be satified (compiled).
    *
    * @param arr collection of Compilable objects
    */
    public void dependsOn (final Collection arr) {
        MUTEX.readAccess (new Runnable () {
                              public void run () {
                                  synchronized (CompilerJob.this) {
                                      graph = null;
                                      if (dependsOn == null) {
                                          dependsOn = new IdSet ();
                                          noModDependsOn = dependsOn.asImmutableCollection();
                                      }
                                      dependsOn.addAll (arr);
                                  }
                              }
                          });
    }

    /** Called from CompilationEngine.
    * @return list of {@link Set}s of {@link Compiler}s
    */
    final List computationLevels () throws DependencyException {
        return getGraph ().getLevels ();
    }

    /** Getter for graph of references.
    * @return graph the graph
    */
    private Graph getGraph () {
        Graph g = graph;
        if (g != null) return g;

        return graph = (Graph)MUTEX.writeAccess (new Mutex.Action () {
                           public Object run () {
                               return new Graph (CompilerJob.this);
                           }
                       });
    }

    /** A collection of all compilers that have been added by add
    * methods.
    *
    * @return unmodifiable collection of Compiler
    */
    public synchronized final Collection compilers() {
        if (noModCompilers == null) {
            noModCompilers = compilers.asImmutableCollection();
        }
        return noModCompilers;
    }

    /** Collection of all objects this job depends on.
    *
    * @return unmodifiable collection with depenencies on Compilable objects
    */
    public final Collection dependsOn() {
        return noModDependsOn;
    }

    /** @return the name of the job.
    */
    public String toString () {
        return getDisplayName ();
    }
}