<?xml version="1.0" encoding="UTF-8"?>
<!--
The contents of this file are subject to the terms of the Common Development
and Distribution License (the License). You may not use this file except in
compliance with the License.

You can obtain a copy of the License at http://www.netbeans.org/cddl.html
or http://www.netbeans.org/cddl.txt.

When distributing Covered Code, include this CDDL Header Notice in each file
and include the License file at http://www.netbeans.org/cddl.txt.
If applicable, add the following below the CDDL Header, with the fields
enclosed by brackets [] replaced by your own identifying information:
"Portions Copyrighted [year] [name of copyright owner]"

The Original Software is NetBeans. The Initial Developer of the Original
Software is Sun Microsystems, Inc. Portions Copyright 1997-2006 Sun
Microsystems, Inc. All Rights Reserved.
-->
<!DOCTYPE api-answers PUBLIC "-//NetBeans//DTD Arch Answers//EN" "../../nbbuild/antsrc/org/netbeans/nbbuild/Arch.dtd" [
  <!ENTITY api-questions SYSTEM "../../nbbuild/antsrc/org/netbeans/nbbuild/Arch-api-questions.xml">
]>

<api-answers
    question-version="1.12"
    module="Compiler"
    author="sdedic@netbeans.org"
>

&api-questions;

<answer id="arch-what">
The <api 
    name="CompilerAPI" type="export" category="official"
    url="http://www.netbeans.org/download/dev/javadoc/CompilerAPI/org/openide/compiler/doc-files/api.html" 
    group="java"
/> allows to commence and control compilation or other process on
individual files, or implement and publish a compiler (or other processor).
</answer>

<answer id="dep-nb">
    <api name="LoadersAPI" group="java" type="import" category="official"
	url="http://www.netbeans.org/download/dev/javadoc/LoadersAPI/org/openide/loaders/doc-files/api.html"
    />
    <api name="ExecutionAPI" type="import" category="official"
	url="http://www.netbeans.org/download/dev/javadoc/ExecutionAPI/org/openide/execution/doc-files/api.html"
        group="java"
    />
    <api name="FilesystemsAPI" type="import" category="official"
	url="http://www.netbeans.org/download/dev/javadoc/OpenAPIs/org/openide/filesystems/doc-files/api.html"
        group="java"
    />
    <api name="InputOutputAPI" type="import" category="official"
	url="http://www.netbeans.org/download/dev/javadoc/OpenAPIs/org/openide/windows/doc-files/api.html"
        group="java"
    />
    <api name="NodesAPI" type="import" category="official"
	url="http://www.netbeans.org/download/dev/javadoc/OpenAPIs/org/openide/nodes/doc-files/api.html"
        group="java"
    />
</answer>

<answer id="dep-non-nb">
None.
</answer>

<answer id="dep-platform">
Any.
</answer>

<answer id="dep-jre">
JRE 1.4 and higher.
</answer>

<answer id="dep-jrejdk">
JRE
</answer>

<answer id="deploy-jar">
Classes are packaged as openide-compiler.jar.
</answer>

<answer id="deploy-nbm">
Yes.
</answer>

<answer id="deploy-shared">
Any.
</answer>

<answer id="deploy-packages">
No; all module's packages are public.
</answer>

<answer id="deploy-dependencies">
        <p>
            To use the <code>org.openide.compiler.*</code> classes, you need to declare:
        </p>
        <pre>OpenIDE-Module-Module-Dependencies: org.openide.compiler &gt; @SPECIFICATION-VERSION@</pre>
        <p>
            If you ever call <code>CompilationEngine.getDefault()</code> (directly or indirectly),
            i.e. need an implementation of the engine to be present, you must additionally declare:
        </p>
        <pre>OpenIDE-Module-Requires: org.openide.compiler.CompilationEngine</pre>
</answer>

<answer id="compat-i18n">
Yes.
</answer>

<answer id="compat-standards">
No.
</answer>

<answer id="compat-version">
Yes.
</answer>

<answer id="resources-file">
Yes. To specify working directory for external processes and convert
pathnames reported by external processes back to FileObjects.
</answer>

<answer id="resources-layer">
The core counterpart of this module registers these items in the layer:
    <dl>
        <dt><api name="CompilerTemplatesRegistry" group="layer" type="export" category="friend">
            <b>Templates/Services/CompilerType</b>: 
            Templates for creating additional Compiler Types should be registered here. The core part will present
            those templates when the user chooses to create a new compiler type.
        </api></dt>
        <dt><api name="CompilerServicesRegistry" group="layer" type="export" category="friend">
            <b>Services/CompilerType</b>:
            Compiler-style services should be registered in this folder, rather than directly in <code>Services</code>
            folder.
        </api></dt>
        <dt><api name="CompilerServicesRegistryUI" group="layer" type="export" category="private">
            <b>UI/Services/CompilerType</b>:
            The core counterpart of this module adds a link to the <i>Compiler Services Registry</i> into the Tools | Options
            presentation definition. The core is expected to display Compilers at the appropriate position among other
            Options.
        </api></dt>
    </dl>
</answer>

<answer id="resources-read">
No.
</answer>

<answer id="resources-mask">
No.
</answer>

<answer id="lookup-lookup">
Yes. The module tries to locate:
<ul>
<li><a href="http://www.netbeans.org/download/dev/javadoc/OpenAPIs/org/openide/compiler/CompilationEngine.html">org.openide.compiler.CompilationEngine</a> - 
to perform/execute actual compilation tasks.</li>
<li><a href="http://www.netbeans.org/download/dev/javadoc/OpenAPIs/org/openide/compiler/CompilerType.html">org.openide.compiler.CompilerType</a> - to enumerate
all compiler types registered in the system and to find the default one.</li>
<li><a href="http://www.netbeans.org/download/dev/javadoc/OpenAPIs/org/openide/ServiceType.Registry.html">org.openide.ServiceType.Registry</a> - to find a
compiler by its name.</li>
</ul>
</answer>

<answer id="lookup-register">
No.
</answer>

<answer id="lookup-remove">
No.
</answer>

<answer id="exec-property">
    <api type="import" group="property" name="java.home" category="stable">
    Used as a value of {java.home} tag in external compiler command line templates.
    </api>
    <api type="import" group="property" name="jdk.home" category="stable">
    Used as a value of {jdk.home} tag in external compiler command line templates.
    </api>
    <api type="export" group="property" name="org.openide.compilers.fileListThreshold" category="private">
    Cummulative length of filenames passed to external compiler before the IDE will
    pass the files to process through a "command file".
    </api>
</answer>

<answer id="exec-component">
No.
</answer>

<answer id="exec-classloader">
No.
</answer>

<answer id="exec-reflection">
No.
</answer>

<answer id="exec-privateaccess">
No.
</answer>

<answer id="format-types">
The so-called `command file' uses a simple format, one filename per line. If a file name contains
spaces, the filename is surronded in doublequotes; doublequotes itself are escaped by a backslash.
</answer>

<answer id="format-dnd">
None.
</answer>

<answer id="format-clipboard">
None.
</answer>

<answer id="perf-startup">
No.
</answer>

<answer id="perf-exit">
No.
</answer>

<answer id="perf-scale">
</answer>

<answer id="perf-limit">
</answer>

<answer id="perf-mem">
The module only defines the contract; it does not contain real compiler implementation. It is expected
that the memory requirements raise with O(number-of-compiled-files).
</answer>

<answer id="perf-wakeup">
No.
</answer>

<answer id="perf-progress">
Yes; the module supports execution of external tools asynchronously and provide feedback
from that execution.
</answer>

<answer id="perf-huge_dialogs">
No.
</answer>

<answer id="perf-menus">
The CompileAction and its derivatives enable themselves based on whether the context object
is up-to-date or not. The performance depends entirely on the compiler implementation (outside of this module).
</answer>

</api-answers>
