<?xml version="1.0" encoding="UTF-8"?>
<!--
DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.

Copyright 1997-2010 Oracle and/or its affiliates. All rights reserved.

Oracle and Java are registered trademarks of Oracle and/or its affiliates.
Other names may be trademarks of their respective owners.


The contents of this file are subject to the terms of either the GNU
General Public License Version 2 only ("GPL") or the Common
Development and Distribution License("CDDL") (collectively, 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-gplv2.html
or nbbuild/licenses/CDDL-GPL-2-CP. See the License for the
specific language governing permissions and limitations under the
License.  When distributing the software, include this License Header
Notice in each file and include the License file at
nbbuild/licenses/CDDL-GPL-2-CP.  Oracle designates this
particular file as subject to the "Classpath" exception as provided
by Oracle in the GPL Version 2 section of the License file that
accompanied this code. If applicable, add the following below the
License Header, with the fields enclosed by brackets [] replaced by
your own identifying information:
"Portions Copyrighted [year] [name of copyright owner]"

Contributor(s):

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.

If you wish your version of this file to be governed by only the CDDL
or only the GPL Version 2, indicate your decision by adding
"[Contributor] elects to include this software in this distribution
under the [CDDL or GPL Version 2] license." If you do not indicate a
single choice of license, a recipient has the option to distribute
your version of this file under either the CDDL, the GPL Version 2 or
to extend the choice of license to its licensees as provided above.
However, if you add GPL Version 2 code and therefore, elected the GPL
Version 2 license, then the option applies only if the new code is
made subject to such option by the copyright holder.
-->
<!DOCTYPE apichanges PUBLIC "-//NetBeans//DTD API changes list 1.0//EN" "../nbbuild/javadoctools/apichanges.dtd">

<apichanges>
	<apidefs>
  	<apidef name="modules">Modules API</apidef>
  </apidefs>
<changes>
    <change id="Dependency.java.keywords">
        <api name="modules"/>
        <summary>Module names can contain Java keywords</summary>
        <version major="7" minor="20"/>
        <date day="22" month="7" year="2010"/>
        <author login="jtulach"/>
        <compatibility semantic="compatible" modification="yes"/>
        <description>
            <p>
                Naming rules for module code name bases are now relaxed.
                The name of a module can contain a Java keyword like 
                <code>org.mysite.import.something</code>, etc.
            </p>
        </description>
        <class package="org.openide.modules" name="Dependency"/>
        <issue number="188686"/>
    </change>
    <change id="Modules">
        <api name="modules"/>
        <summary>Quicker way to find owner of a class</summary>
        <version major="7" minor="19"/>
        <date day="19" month="7" year="2010"/>
        <author login="jglick"/>
        <compatibility addition="yes"/>
        <description>
            <p>
                Class <code>Modules</code> introduced, initially with the ability
                to find the owner of a given class directly without iterating
                through all known modules.
            </p>
        </description>
        <class package="org.openide.modules" name="Modules"/>
        <issue number="157828"/>
    </change>
    <change id="ClassLoader.findLibrary">
        <api name="modules"/>
        <summary>New native library lookup mechanism</summary>
        <version major="7" minor="17"/>
        <date day="17" month="5" year="2010"/>
        <author login="pnejedly"/>
        <compatibility addition="yes"/>
        <description>
            <p>
                You can now distribute native libraries into architecture
                and OS specific directories under <samp>modules/lib</samp>;
                see the <a href="@TOP@/org/openide/modules/doc-files/api.html#jni">documentation</a>.
                The functionality is actually provided by the
                <code>org.netbeans.bootstrap</code> module as of version 2.33.
            </p>
        </description>
        <issue number="186000"/>
    </change>
    <change id="ModuleInstall-no-extern">
        <api name="modules"/>
        <summary>Simplified <code>ModuleInstall</code> lifecycle</summary>
        <version major="7" minor="15"/>
        <date day="6" month="1" year="2010"/>
        <author login="jglick"/>
        <compatibility deletion="yes" source="compatible" semantic="incompatible">
            <p>
                Modules relying on <code>ModuleInstall</code> externalization
                should be using <code>NbPreferences</code> (or similar) instead.
                Use <code>restored</code> rather than <code>installed</code> or
                <code>updated</code> (which have long been unreliable anyway).
            </p>
        </compatibility>
        <description>
            <p>
                The <code>ModuleInstall</code> methods <code>installed</code> and
                <code>updated</code>, while previously deprecated, will no longer
                be called at all. <code>ModuleInstall</code> instances will also
                no longer be serialized to disk. Versioning-related attributes
                are no longer stored in <code>config/Modules/*.xml</code> files.
            </p>
        </description>
        <class package="org.openide.modules" name="ModuleInstall"/>
        <issue number="113341"/>
    </change>
    <change id="InstalledFileLocator.locateAll">
        <api name="modules"/>
        <summary>Added <code>InstalledFileLocator.locateAll</code></summary>
        <version major="7" minor="15"/>
        <date day="6" month="1" year="2010"/>
        <author login="jglick"/>
        <compatibility addition="yes"/>
        <description>
            <p>
                You can now locate multiple variants of an installed file path
                from different clusters.
            </p>
        </description>
        <class package="org.openide.modules" name="InstalledFileLocator"/>
        <issue number="36701"/>
    </change>
    <change id="DependencyIsSerializable">
        <api name="modules"/>
        <summary>Dependency class made serializable</summary>
        <version major="7" minor="10"/>
        <date day="6" month="4" year="2009"/>
        <author login="jtulach"/>
        <compatibility addition="yes"/>
        <description>
            <p>
                <code>Dependency</code> now implements <code>Serializable</code>
            </p>
        </description>
        <class package="org.openide.modules" name="Dependency"/>
        <issue number="160390"/>
    </change>
    <change id="PatchedPublic">
        <api name="modules"/>
        <summary>Added annotation <code>@PatchedPublic</code></summary>
        <version major="7" minor="9"/>
        <date day="6" month="1" year="2009"/>
        <author login="jglick"/>
        <compatibility addition="yes"/>
        <description>
            <p>
                Added <code>@PatchedPublic</code> to request that the module system
                treat binary references to a method as public even if in source is
                is not public.
            </p>
        </description>
        <class package="org.openide.modules" name="PatchedPublic"/>
        <issue number="155796"/>
    </change>
    <change id="OpenIDE-Module-Hide-Classpath-Packages">
        <api name="modules"/>
        <summary>Ability to hide JRE packages from the module classpath</summary>
        <version major="7" minor="6"/>
        <date day="23" month="2" year="2008"/>
        <author login="jglick"/>
        <compatibility semantic="incompatible">
            <p>
                To guarantee that the new tag will be honored you should also:
            </p>
            <pre>OpenIDE-Module-Requires: org.openide.modules.ModuleFormat2</pre>
            <p>
                Several JRE packages used to be hidden automatically but are not any more;
                while these were never documented, modules which relied on being able to override
                these packages could be broken by having the JRE classes exposed instead. Specifically,
                the following packages (or package prefixes) were in NetBeans 6.0 not loaded from the
                classpath, but now will be unless otherwise requested:
            </p>
            <pre>com.sun.javadoc
com.sun.source
com.sun.tools.javac
com.sun.tools.javadoc
javax.annotation
javax.jws
javax.lang.model
javax.tools
javax.xml.bind
javax.xml.soap
javax.xml.stream
javax.xml.ws</pre>
        </compatibility>
        <description>
            <p>
                Packages supplied in a module which overlap those in the JRE or its extensions will normally be ignored
                (as usual, the JRE takes precedence). Modules which wish to specifically suppress loading of some packages
                from the classpath can now request the class loader to do so by specifying:
            </p>
            <pre>OpenIDE-Module-Hide-Classpath-Packages: javax.lang.model.*, com.sun.source.**</pre>
            <p>
                (The syntax is analogous to that of <code>OpenIDE-Module-Public-Packages</code>.)
            </p>
            <p>
                Such a declaration affects not just this module, but any other modules declaring a <em>direct</em>
                dependency on it (<code>OpenIDE-Module-Module-Dependencies</code>). The module is now free to bundle
                its own versions of these classes and be sure they will be used by it and its clients.
                Be aware that as with all changes to the normal class loading scheme,
                careless usage could result in <code>LinkageError</code>s.
            </p>
        </description>
        <issue number="96711"/>
    </change>
    <change id="no-FileObject-for-module-JAR-entry">
        <api name="modules"/>
        <summary>No longer possible to obtain a module JAR entry as a <code>FileObject</code></summary>
        <version major="7" minor="5"/>
        <date day="15" month="2" year="2008"/>
        <author login="jglick"/>
        <compatibility semantic="incompatible"/>
        <description>
            <p>
                Modules used to be able to obtain their own entries as file objects, e.g.:
            </p>
            <pre>FileObject f = URLMapper.findFileObject(ThisClass.class.getResource("something.xml"));</pre>
            <p>
                This is no longer supported.
                Client code should either use module classpath entries directly as URLs;
                or register files of interest in the XML layer and refer to them using the system filesystem.
            </p>
        </description>
        <issue number="127268"/>
    </change>
    <change id="removeWritables">
        <api name="modules"/>
        <summary>An option to revert user's modifications to XML layer files</summary>
        <version major="7" minor="2"/>
        <date day="1" month="8" year="2006"/>
        <author login="saubrecht"/>
        <compatibility binary="compatible" source="compatible" semantic="compatible" deprecation="no" addition="yes" deletion="no" modification="no"/>
        <description>
            <code>FileObject</code>s created on XML layer now support a new 
            attribute <code>"removeWritables"</code> returning an instance of
            <code>Callable</code> which removes the local writable version of the
            given <code>FileObject</code> thus reverting the folder or file to
            its initial state as defined in XML layers. Please note that is *not*
            possible to reset <code>FileObject</code>'s attributes.
        </description>
    </change>
    <change id="needs">
        <api name="modules"/>
        <summary>Requires/Provides and Needs</summary>
        <version major="7" minor="1"/>
        <date day="19" month="7" year="2006"/>
        <author login="jtulach"/>
        <compatibility binary="compatible" source="compatible" semantic="compatible" deprecation="no" addition="yes" deletion="no" modification="no"/>
        <description>
            It is possible to require some implementation using
            <code>OpenIDE-Module-Needs: token</code> which is slightly
            less restrictive than usual
            <code>OpenIDE-Module-Requires: token</code> as
            explain in the <a href="@TOP@/org/openide/modules/doc-files/api.html#7.1">documentation</a>.
        </description>
        <class package="org.openide.modules" name="Dependency"/>
    </change>
    <change id="generified">
        <api name="modules"/>
        <summary>Generified Interfaces</summary>
        <version major="7" minor="0"/>
        <date day="22" month="3" year="2006"/>
        <author login="jtulach"/>
        <compatibility binary="compatible" source="compatible" semantic="compatible" deprecation="no" addition="no" deletion="no" modification="no"/>
        <description>
            Rewritten to use Java5 features, especially generics.
            Affects internal code and <a href="@TOP@org/openide/modules/Dependency.html#create(int,%20java.lang.String)">one public signature</a>.
        </description>
        <class package="org.openide.modules" name="Dependency"/>
    </change>
    <change id="enhanced-support-for-os-specific-modules-iz-109288">
        <api name="modules"/>
        <summary>Enhanced support for OS specific modules (part II)</summary>
        <version major="7" minor="3"/>
        <date day="18" month="7" year="2007"/>
        <author login="jglick"/>
        <compatibility binary="compatible" source="compatible" semantic="compatible" deprecation="no" addition="yes" deletion="no" modification="no"/>
        <description>
            Modules can now express dependencies on
            <code>org.openide.modules.os.Linux</code> and
            <code>org.openide.modules.os.Solaris</code>.
            For more details read <a href="@TOP@/org/openide/modules/doc-files/api.html#how-os-specific">here</a>.
        </description>
        <issue number="109288"/>
    </change>
    <change id="enhanced-support-for-os-specific-modules-iz-50943">
        <api name="modules"/>
        <summary>Enhanced support for OS specific modules</summary>
        <version major="6" minor="3"/>
        <date day="7" month="7" year="2005"/>
        <author login="jtulach"/>
        <compatibility binary="compatible" source="compatible" semantic="compatible" deprecation="no" addition="yes" deletion="no" modification="no"/>
        <description>
            Modules can now express dependency on more operating system types
            than those that were available previously. Now there is 
            <code>org.openide.modules.os.PlainUnix</code> token for all unixes
            but MacOSX and <code>org.openide.modules.os.OS2</code> for 
            OS/2. For more details read <a href="@TOP@/org/openide/modules/doc-files/api.html#how-os-specific">here</a>.
        </description>
        <issue number="50943" />
    </change>
    <change id="split-of-openide-branding-files">
        <api name="modules"/>
        <summary>Branding files used during startup have new location</summary>
        <version major="6" minor="2"/>
        <date day="7" month="6" year="2005"/>
        <author login="jtulach"/>
        <compatibility binary="compatible" source="compatible" semantic="incompatible" deprecation="no" addition="yes" deletion="no" modification="yes"/>
        <description>
            Due to <a href="apichanges.html#split-of-openide-jar">split of openide.jar</a> some important branding files used during startup change their location. 
            Especially the to splash screen picture, location and color of progress bar and the application icon are now in <code>org.netbeans.core.startup</code>
            package. Here is an example of the branding <a href="http://www.netbeans.org/source/browse/ide/branding/core/src/org/netbeans/core/startup/">as used by NetBeans IDE</a>.
        </description>
    </change>
    <change id="split-of-openide-jar">
        <api name="modules"/>
        <summary><code>openide.jar</code> is gone, update your module dependencies!</summary>
        <version major="6" minor="2"/>
        <date day="4" month="6" year="2005"/>
        <author login="jtulach"/>
        <compatibility addition="yes" binary="compatible" source="compatible" semantic="compatible" deprecation="yes" deletion="no" modification="yes"/>
        <description>
            <p>
            The monolithic <code>openide.jar</code> has been split into many small
            JAR files and most of them were made autoload modules. That means they
            are loaded only on demand, which is going to simplify end of life of parts 
            that are no longer needed.
            </p>
            
            <p>
            The layout of files on disk changed and their content as well, but these
            changes shall have no effect on classes from <code>org.openide</code>
            packages during runtime. Modules using them will run unmodified.
            Althrough there will be printed warnings about upgraded module 
            dependencies - one is adviced to use
            <b>ant fix-dependencies</b> in his projectized module to 
            modify the <code>nbproject/project.xml</code>. The 
            manifest's <code>OpenIDE-Module-IDE-Dependencies</code>
            attribute is deprecated and shall no longer be used. Enumerate the 
            individual split submodules instead, as is done by the <b>fix-dependencies</b> 
            task. Moreover one can depend on <code>
OpenIDE-Module-Requires: org.openide.modules.ModuleFormat1</code>
            to express that it requires current format of module manifests -
            this tag is automatically inserted when running in projectized system.
            </p>
            
            <p>
            The current layout of platform cluster directory is:
            </p>
            <ul class="doing">
                <li><code>lib/boot.jar</code> contains what it used to have
                together with module system runtime <q>independent of other NetBeans APIs</q>.
                </li>

                <li><code>lib/org-openide-util.jar</code> is next to boot.jar to provide
                the basic infrastructure used by boot.jar.
                </li>

                <li><code>lib/org-openide-modules.jar</code> provides the APIs that the
                boot.jar implements.
                </li>

                <li><code>core/core.jar</code> is loaded dynamically
                by the boot.jar and contains most of the startup code and the
                <q>NetBeans dependent</q> part of module system. 
                 For its implementation it needs
                filesystems which are along as well.
                </li>

                <li><code>core/org-openide-filesystems.jar</code> the filesystems API is needed
                for the standard launch code to read module config files and listen to changes in their
                amount or content.
                </li>

                <li><code>modules/org-openide-nodes.jar</code> and other openide libraries
                are now turned into real modules.
                </li>


                <li><code>modules/org-netbeans-core.jar</code> is also a module
                and contains the rest of original core.jar. It is likely that this one is going
                to be split even more, as the UI could be separated to core/ui, etc. 
                </li>
            </ul>
        
        </description>
        <issue number="58258"/>
    </change>
  
  
  
    <change id="FriendModulesRestriction">
        <api name="modules"/>
        <summary>Friend Modules</summary>
        <version major="6" minor="1"/>
        <date day="11" month="4" year="2005"/>
        <author login="jtulach"/>
        <compatibility addition="yes" binary="compatible" source="compatible" semantic="compatible" deprecation="no" deletion="no" modification="no"/>
        <description>
            A module can now <a href="@TOP@org/openide/modules/doc-files/api.html#friend">restrict the list</a> of modules that can
            access its public packages, by enumerating their code names 
            in manifest.
        </description>
        <issue number="54123"/>
  </change>
  
  <change id="no-compat-manifest-section">
      <api name="modules"/>
      <summary>Removed compatibility handling of deprecated manifest sections</summary>
      <version major="4" minor="48"/>
      <date day="7" month="5" year="2004"/>
      <author login="jglick"/>
      <compatibility semantic="incompatible" binary="compatible" source="compatible" deprecation="no" addition="no" deletion="no" modification="no">
        <p>
          Modules which did not remove these manifest sections before must do so
          for NetBeans 4.0.
        </p>
      </compatibility>
      <description>
        <p>
          Previously, a number of module manifest sections (e.g.
          <code>OpenIDE-Module-Class: FileSystem</code>) had been deprecated
          in favor of XML-layer-based installation, but a compatibility layer was
          left in place to permit old modules to still function as before. This
          layer has been removed.
        </p>
        <p>
          Manifest-based installation of JavaHelp help sets was also removed.
        </p>
      </description>
  </change>
  <change id="org.openide.modules.os">
        <api name="modules"/>
        <summary>Allow a module to be run only on some class of operating systems</summary>
        <version major="4" minor="44"/>
        <date day="11" month="8" year="2004"/>
        <author login="jtulach"/>
        <compatibility addition="yes" binary="compatible" source="compatible" semantic="compatible" deprecation="no" deletion="no" modification="no"/>
        <description>
            Modules can now declare that they run only on a specific version of
            operating system by requesting a presence of 
            <code>org.openide.modules.os.MacOSX</code>,
            <code>org.openide.modules.os.Unix</code> or 
            <code>org.openide.modules.os.Windows</code> 
            token in their manifest:
            <pre xml:space="preserve">
                OpenIDE-Module-Requires: org.openide.modules.os.Unix
            </pre>
            Such a module will then be enabled only on specified class of 
            operating systems. See also the 
            	<a href="org/openide/modules/doc-files/api.html#how-os-specific">modules api</a>
            description.
        </description>
        <issue number="46833"/>
  </change>
  <change>
        <api name="modules"/>
        <summary>Added ModuleInfo.getBuildVersion()</summary>
        <version major="4" minor="18"/>
        <date day="18" month="12" year="2003"/>
        <author login="jtulach"/>
        <compatibility addition="yes" binary="compatible" source="compatible" semantic="compatible" deprecation="no" deletion="no" modification="no"/>
        <description>
            The implementation version and the build number of modules can
            now be different. One can keep 
            <code>OpenIDE-Module-Implementation-Version</code> unchanged
            to allow implementation dependencies and still identify the
            actual build version by specifying 
            <code>OpenIDE-Module-Build-Version</code>. If omited the 
            build version is equal to implementation version.
        </description>
        <class package="org.openide.modules" name="ModuleInfo"/>
        <issue number="36064"/>
  </change>
  <change>
        <api name="modules"/>
        <summary>Module dependencies no longer considered transitive for purposes of classloading</summary>
        <version major="3" minor="12"/>
        <date day="7" month="10" year="2002"/>
        <author login="jglick"/>
        <compatibility modification="yes" binary="compatible" source="compatible" semantic="compatible" deprecation="no" addition="no" deletion="no">
            Modules which fail to declare an API dependency on <samp>IDE/1 &gt; 3.12</samp>
            or above will behave according to the old semantics: they may load classes and
            resources from undeclared indirect parent modules. But if they declare an API
            dependency on 3.12 or higher, the new semantics apply.
        </compatibility>
        <description>
            Prior to this change, if module B depends on module A, where A provides some
            public packages (implicitly or explicitly), and module C depends on module B,
            then module C could use public packages from A. Now it cannot, unless it also
            declares an <em>explicit</em> dependency on A.
        </description>
        <issue number="27853"/>
  </change>
  <change>
        <api name="modules"/>
        <summary>Possible to deprecate an entire module</summary>
        <version major="3" minor="15"/>
        <date day="16" month="10" year="2002"/>
        <author login="jglick"/>
        <compatibility addition="yes" binary="compatible" source="compatible" semantic="compatible" deprecation="no" deletion="no" modification="no"/>
        <description>
            The new manifest attribute <code>OpenIDE-Module-Deprecated</code>
            and localized attribute <code>OpenIDE-Module-Deprecation-Message</code>
            may be used to warn clients of an obsolete API module.
        </description>
  </change>
  <change id="issue-19443-1">
      <summary>API separation, phase I</summary>
      <version major="3" minor="14"/>
      <date day="15" month="10" year="2002"/>
      <author login="jglick"/>
      <compatibility binary="compatible" source="incompatible" deprecation="yes" semantic="compatible" addition="no" deletion="no" modification="no">
        <p>
          The deprecated classes continue to be available in the module
          <code>org.openide.deprecated</code> which you may depend on it you
          cannot remove uses of the deprecated APIs. In order for
          <code>TopManager.getDefault()</code> to work, you must also require the
          token <code>org.openide.TopManager</code>, which is provided by an
          unspecified module. The deprecated API module and its implementation
          module are autoloads, meaning they will not be loaded unless some
          module still requires them.
        </p>
        <p>
          Similarly, the Java Hierarchy API was moved to the module
          <code>org.openide.src</code> which you should depend on in order to use
          this API.
        </p>
        <p>
          For compatibility, the above three dependencies are added to your module
          <em>automatically</em> in case it either requests no specific API
          version at all, or requests an API version prior to 3.14. Modules
          requesting APIs 3.14 or higher must declare these dependencies
          explicitly if they in fact need them.
        </p>
      </compatibility>
      <description>
        <p>
          Many classes were moved to a separate module,
          <samp>openide-deprecated.jar</samp>, not available to modules by
          default. Uses of these classes in modules should be cleaned up whenever
          possible.
        </p>
        <p>
          Additionally, the entire contents of <code>org.openide.src.*</code> and
          <code>org.openide.src.nodes.*</code>, as well as
          <code>org.openide.cookies.SourceCookie</code> and some associated
          property editors, were moved to a separate module.
        </p>
        <p>
          The most common apparent symptom for module authors will be the absence
          of <code>TopManager</code>. Most methods in this class have been
          replaced by newer utility classes in a straightforward manner. See the
          Upgrade Guide.
        </p>
      </description>
      <issue number="19443"/>
      <issue number="20898"/>
  </change>
  <change id="issue-19443-2">
      <summary>API separation, phase II</summary>
      <version major="3" minor="17"/>
      <date day="1" month="11" year="2002"/>
      <author login="jglick"/>
      <compatibility binary="compatible" source="incompatible" modification="yes" semantic="compatible" deprecation="no" addition="no" deletion="no">
        <p>
          Module authors using the now-separated APIs will need to adjust their
          compilation classpaths to include the new JAR files. Modules wishing to
          use recent APIs and declaring a current openide specification version
          dependency will need to explicitly declare dependencies on these new
          APIs if there are any.
        </p>
        <p>
          For compatibility, modules with no declared Open APIs dependency, or
          declared on a version prior to 3.17, will have their dependencies
          automatically refined as if to include the declarations:
        </p>
        <pre xml:space="preserve">
OpenIDE-Module-Module-Dependencies: org.openide.compiler &gt; 1.0,
  org.openide.execution &gt; 1.0, org.openide.io &gt; 1.0
OpenIDE-Module-Requires: org.openide.compiler.CompilationEngine,
  org.openide.execution.ExecutionEngine, org.openide.windows.IOProvider
        </pre>
        <p>
          And any package dependencies from old modules on
          <code>org.netbeans.lib.terminalemulator</code> will be converted to
          module dependencies.
        </p>
      </compatibility>
      <description>
        <p>
          Three sections of the Open APIs were split into new autoload modules.
        </p>
        <ul>
          <li>
            <p>
              The module <code>org.openide.compiler</code> (version 1.0) contains
              the Compiler API and some other classes directly related to it.
            </p>
          </li>
          <li>
            <p>
              The module <code>org.openide.execution</code> (version 1.0) contains
              the Execution API and some other classes directly related to it.
            </p>
          </li>
          <li>
            <p>
              The module <code>org.openide.io</code> (version 1.0) contains
              <code>InputOutput</code> and related classes (formerly part of the
              Window System API, and still physically in the
              <code>org.openide.windows</code> package).
            </p>
          </li>
        </ul>
        <p>
          New modules wishing to use these APIs must declare regular module
          dependencies on them. Future changes in these APIs will be documented
          separately.
        </p>
        <p>
          Furthermore, modules wishing to use certain services must
          <code>OpenIDE-Module-Require</code> them if appropriate:
        </p>
        <ul>
          <li>
            <p>
              <code>org.openide.compiler.CompilationEngine</code>, in order to
              call <code>CompilationEngine.getDefault()</code>, or safely use
              <code>AbstractCompileAction</code> or one of its subclasses, or
              call <code>CompilerJob.start()</code>, or use
              <code>BeanInfo</code>s for Compiler API classes, etc.
            </p>
          </li>
          <li>
            <p>
              <code>org.openide.execution.ExecutionEngine</code>, in order to
              call <code>ExecutionEngine.getDefault()</code>, or safely use
              <code>ExecuteAction</code>, or call
              <code>Executor.execute(...)</code>, or use <code>BeanInfo</code>s
              for Execution API classes, etc.
            </p>
          </li>
          <li>
            <p>
              <code>org.openide.windows.IOProvider</code>, in order to call
              <code>IOProvider.getDefault()</code>.
            </p>
          </li>
        </ul>
        <p>
          Other minor changes:
        </p>
        <ul>
          <li>
            <p>
              Registration of URL stream handler factories using
              <code>NbfsStreamHandlerFactory.register(...)</code> is deprecated.
              Simply create an instance of <code>URLStreamHandlerFactory</code>
              and add it to Lookup instead.
            </p>
          </li>
          <li>
            <p>
              The method <code>FileUtil.nbfsURLStreamHandler</code> was added,
              but is not intended for use by modules.
            </p>
          </li>
          <li>
            <p>
              All uses of <code>ExecInfo</code> are deprecated as they abuse the
              distinction between Filesystems and the user classpath. Use and
              override only <code>Executor.execute(DataObject)</code>. Similarly,
              <code>ThreadExecutor</code> is deprecated for the time being
              because it suffers from similar problems.
            </p>
          </li>
          <li>
            <p>
              Direct use of <code>NbfsURLConnection</code> is deprecated in favor
              of the more general <code>URLMapper</code> from the Filesystems
              API.
            </p>
          </li>
          <li>
            <p>
              Package dependencies on
              <code>org.netbeans.lib.terminalemulator</code> must be replaced
              with module dependencies on a new autoload module
              <code>org.netbeans.lib.terminalemulator</code> (version 1.0).
            </p>
          </li>
          <li>
            <p>
              Several static convenience methods have been added to
              <code>AbstractCompileAction</code>. Of most interest is
              <code>prepareJobFor</code>. Module code should no longer assume
              that <code>DataFolder</code> has a <code>CompilerCookie</code>
              which recursively compiles the folder and subfolders (according to
              depth); while it is still true, for reasons of compatibility, new
              code should use <code>prepareJobFor</code> to create a compiler job
              from a folder.
            </p>
          </li>
        </ul>
      </description>
      <issue number="19443"/>
  </change>
  
  <change>
      <api name="modules"/>
      <summary>Added <code>InstalledFileLocator</code></summary>
      <version major="3" minor="21"/>
      <date day="13" month="11" year="2002"/>
      <author login="jglick"/>
      <compatibility addition="yes" binary="compatible" source="compatible" semantic="compatible" deprecation="no" deletion="no" modification="no">
        Existing module code which searches system properties such as
        <code>netbeans.home</code> and <code>netbeans.user</code> should be
        replaced with calls to the new supported API.
      </compatibility>
      <description>
        This new service permits modules to find disk files associated with their
        installation. For example, files packed into an NBM alongside the module
        could be found in this way. Using the locator is both safer and more
        convenient than checking undocumented system properties or resorting to
        other tricks. Note that the NBM format is still not specified by the Open
        APIs; however, if there is a packaging format in use, then there should
        be a matching locator implementation that locates files bundled by it.
      </description>
      <class package="org.openide.modules" name="InstalledFileLocator"/>
      <issue number="28683"/>
  </change>
  
  <change id="ModuleInfo.getClassLoader">
      <api name="modules"/>
      <summary>Added method <code>ModuleInfo.getClassLoader()</code></summary>
      <version major="4" minor="21"/>
      <date day="25" month="12" year="2003"/>
      <author login="jglick"/>
      <compatibility addition="yes" binary="compatible" source="compatible" semantic="compatible" deprecation="no" deletion="no" modification="no">
        Note that although the new method is effectively abstract, this is a
        compatible change insofar as no one outside of the core module system
        should be subclassing <code>ModuleInfo</code>.
      </compatibility>
      <description>
        Added a new method <code>ModuleInfo.getClassLoader()</code> making it
        possible to find a Java class loader associated with an enabled module.
      </description>
      <class package="org.openide.modules" name="ModuleInfo"/>
      <issue number="38330"/>
  </change>
  
  <change>
      <api name="modules"/>
      <summary><code>Thread.contextClassLoader</code> defaults to <code>TopManager.systemClassLoader</code></summary>
      <date day="8" month="5" year="2002"/>
      <author login="jglick"/>
      <compatibility modification="yes" binary="compatible" source="compatible" semantic="compatible" deprecation="no" addition="no" deletion="no"/>
      <description>
        The context class loader for all threads now defaults to the system class
        loader, capable of loading from modules and their extensions as well as
        the startup classpath. This is especially useful for modules bundling
        NetBeans-independent libraries such as JAXP which use the context class
        loader as a default whenever no particular class loader is specified to
        some registration mechanism.
      </description>
      <issue number="20663"/>
      <branch name="sierra">
        <date day="25" month="7" year="2002"/>
        <version major="1" minor="43" subminor="3" subsubminor="1"/>
      </branch>
  </change>
  
  <change>
      <api name="modules"/>
      <summary>Modules can declare their public packages</summary>
      <version major="2" minor="19"/>
      <date day="16" month="5" year="2002"/>
      <author login="jglick"/>
      <compatibility addition="yes" binary="compatible" source="compatible" semantic="compatible" deprecation="no" deletion="no" modification="no"/>
      <description>
        <p>Modules which provide Java-level APIs to other modules can now
        specify which packages should be considered part of the public
        API. Other packages are blocked from client modules.</p>
        <p>Utilizing this feature for already released modules
        is <b>very dangerous</b>. See issue
        <a href="http://www.netbeans.org/issues/show_bug.cgi?id=31637">#31637</a>
        for details.</p>
      </description>
      <issue number="19621"/>
  </change>
  
  <change>
      <api name="modules"/>
      <summary>Provides-requires semantics for module dependencies</summary>
      <version major="2" minor="3"/>
      <date day="29" month="1" year="2002"/>
      <author login="jglick"/>
      <compatibility addition="yes" binary="compatible" source="compatible" semantic="compatible" deprecation="no" deletion="no" modification="no"/>
      <description>
        The manifest attributes <code>OpenIDE-Module-Provides</code> and
        <code>OpenIDE-Module-Requires</code> were introduced. These permit
        modules to depend on capabilities offered by other modules, without
        explicitly naming who the provider will be.
      </description>
      <class package="org.openide.modules" name="Dependency"/>
      <class package="org.openide.modules" name="ModuleInfo"/>
      <issue number="18781"/>
  </change>
  
  <change>
      <api name="modules"/>
      <summary>Ranged major release version dependencies</summary>
      <version major="2" minor="3"/>
      <date day="29" month="1" year="2002"/>
      <author login="jglick"/>
      <compatibility addition="yes" binary="compatible" source="compatible" semantic="compatible" deprecation="no" deletion="no" modification="no"/>
      <description>
        Module dependencies may now specify a range of major release versions, to
        indicate that the dependency is valid for all mentioned major releases.
        Though the API-providing module may have had some incompatible changes,
        none of them were found to be relevant to the depending module.
      </description>
      <class package="org.openide.modules" name="Dependency"/>
      <issue number="19714"/>
  </change>
  
  <change>
      <api name="modules"/>
      <summary>Can supply localized messages for failed dependencies</summary>
      <version major="1" minor="26"/>
      <date day="20" month="7" year="2001"/>
      <author login="jglick"/>
      <compatibility addition="yes" binary="compatible" source="compatible" semantic="compatible" deprecation="no" deletion="no" modification="no"/>
      <description>
        Permitting main attributes
        <code>OpenIDE-Module-Module-Dependency-Message</code> and
        <code>OpenIDE-Module-Package-Dependency-Message</code>.
      </description>
      <class package="org.openide.modules" name="ModuleInfo"/>
  </change>
  
  <change id="ModuleInfo.owns">
      <api name="modules"/>
      <summary>Can determine which module owns a given class</summary>
      <version major="1" minor="28"/>
      <date day="31" month="7" year="2001"/>
      <author login="jpokorsky"/>
      <compatibility addition="yes" binary="compatible" source="compatible" semantic="compatible" deprecation="no" deletion="no" modification="no"/>
      <description>
        Added <code>owns(Class)</code> to determine if the provided class was
        loaded as a part of the module.
      </description>
      <class package="org.openide.modules" name="ModuleInfo"/>
  </change>
  
  <change>
      <api name="modules"/>
      <summary>New module installer API</summary>
      <version major="1" minor="24"/>
      <date day="16" month="7" year="2001"/>
      <author login="jglick"/>
      <compatibility addition="yes" deprecation="yes" binary="compatible" source="compatible" semantic="compatible" deletion="no" modification="no"/>
      <description>
        New module installer and corresponding API enhancements.
        <code>ModuleDescription</code>, <code>ManifestSection</code>, and
        <code>IllegalModuleException</code> deprecated. <code>ModuleInfo</code>,
        <code>Dependency</code>, <code>SpecificationVersion</code>, and
        <code>ModuleInstall.validate</code> added. Module information available
        from lookup. Localized properties may be stored in bundles.
      </description>
      <class package="org.openide.modules" name="ModuleInfo"/>
      <class package="org.openide.modules" name="Dependency"/>
      <class package="org.openide.modules" name="SpecificationVersion"/>
      <class package="org.openide.modules" name="ModuleInstall"/>
  </change>
  
  <change id="system-Modules-folder">
      <api name="modules"/>
      <summary>Format of modules XML folder defined</summary>
      <version major="1" minor="31"/>
      <date day="17" month="8" year="2001"/>
      <author login="jglick"/>
      <compatibility modification="yes" binary="compatible" source="compatible" semantic="compatible" deprecation="no" addition="no" deletion="no"/>
      <description>
        Some aspects of the contents of the system <samp>Modules/</samp> folder
        and its XML files are now defined. Additionally, certain kinds of changes
        (module enablement or disablement) are now permitted to these XML files.
      </description>
      <issue number="13921"/>
  </change>
  
  <change>
      <api name="modules"/>
      <summary>JavaHelp may be registered via layer</summary>
      <version major="1" minor="6"/>
      <date day="29" month="4" year="2001"/>
      <author login="jglick"/>
      <compatibility addition="yes" binary="compatible" source="compatible" semantic="compatible" deprecation="no" deletion="no" modification="no"/>
      <description>
        Added ability to specify JavaHelp help sets and links from layer, or
        generally XML file.
      </description>
  </change>
  
  <change>
      <api name="modules"/>
      <summary>JavaHelp split into a separate module</summary>
      <version major="2" minor="2"/>
      <date day="22" month="1" year="2002"/>
      <author login="jglick"/>
      <compatibility modification="yes" deprecation="yes" binary="compatible" source="compatible" semantic="compatible" addition="no" deletion="no">
        <p>
          Existing modules (with an API dependency earlier than 2.2, or none at
          all) for compatibility are given an automatic dependency on the
          <code>org.netbeans.api.javahelp.Help</code> token. Additionally, if
          they declared a package dependency on <code>javax.help.**</code>, they
          are given an automatic dependency on the
          <code>org.netbeans.modules.javahelp/1</code> module.
        </p>
        <p>
          (<strong>Note:</strong> the automatic conversion of the package
          dependency is implemented by issue #27776, which was not fixed for the
          NetBeans 3.4 release, but will be for NetBeans 3.4.1. NetBeans 3.4 did, however, add automatic
          dependencies on the token, by far the more common case.)
        </p>
        <p>
          Both layer- and manifest-based installation of help sets continue to be
          supported; manifest-based installation is still deprecated.
        </p>
      </compatibility>
      <description>
        <p>
          JavaHelp support is now in a separate module,
          <code>org.netbeans.modules.javahelp/1</code>. This module includes the
          <code>javax.help.**</code> packages, and it provides the token
          <code>org.netbeans.api.javahelp.Help</code> which signifies the ability
          to display help, for example using <code>TopManager.showHelp</code>, or
          by querying Lookup for an instance of <code>Help</code>.
        </p>
        <p>
          New modules (declaring a dependency on APIs after 2.2) which wish to
          provide a helpset should continue to do so via XML layer, and need only
          require the token <code>org.netbeans.api.javahelp.Help</code>. New
          modules wishing to display help can either require this token and use
          <code>TopManager.showHelp</code>, or depend on the
          <code>org.netbeans.modules.javahelp/1</code> API module, require the
          token, query Lookup for an instance of <code>Help</code>, and use its
          methods directly. New modules wishing to use the
          <code>javax.help.**</code> packages directly should declare a
          dependency on the <code>org.netbeans.modules.javahelp/1</code> module
          rather than using a package dependency.
        </p>
      </description>
      <issue number="19620"/>
      <issue number="27776"/>
  </change>
  
  <change>
      <api name="modules"/>
      <summary>Added long description for modules</summary>
      <date day="9" month="2" year="2001"/>
      <author login="jglick"/>
      <compatibility addition="yes" binary="compatible" source="compatible" semantic="compatible" deprecation="no" deletion="no" modification="no"/>
      <description>
        Added <code>getLongDescription</code> and
        <code>TAG_LONG_DESCRIPTION</code>.
      </description>
  </change>
  
  <change>
      <api name="modules"/>
      <summary>Can get JavaHelp help set reference as resource rather than URL</summary>
      <date day="22" month="1" year="2001"/>
      <author login="jglick"/>
      <compatibility addition="yes" deprecation="yes" binary="compatible" source="compatible" semantic="compatible" deletion="no" modification="no"/>
      <description>
        Added <code>getDescriptionResource</code>. Retrieving as URL deprecated.
      </description>
  </change>
  
  <change>
      <api name="modules"/>
      <summary>Display category for modules</summary>
      <date day="18" month="1" year="2001"/>
      <author login="jglick"/>
      <compatibility addition="yes" binary="compatible" source="compatible" semantic="compatible" deprecation="no" deletion="no" modification="no"/>
      <description>
        Added <code>getDisplayCategory</code> and <code>TAG_CATEGORY</code>.
      </description>
  </change>
  
  <change>
      <api name="modules"/>
      <summary>Modules can declare their own dependency transformations</summary>
      <version major="3" minor="33"/>
      <date day="27" month="1" year="2003"/>
      <author login="jglick"/>
      <compatibility addition="yes" binary="compatible" source="compatible" semantic="compatible" deprecation="no" deletion="no" modification="no"/>
      <description>
        <p>
          Modules may now declare their own transformations of module
          dependencies using a declarative XML syntax in the folder
          <samp>ModuleAutoDeps/</samp> in the system filesystem. This is useful
          for being able to manage major refactorings of functionality in a
          manner that will retain binary compatibility.
        </p>
      </description>
      <issue number="30161"/>
  </change>
  
  <change>
      <api name="modules"/>
      <summary>Short description for modules</summary>
      <date day="21" month="12" year="2000"/>
      <author login="jglick"/>
      <compatibility addition="yes" binary="compatible" source="compatible" semantic="compatible" deprecation="no" deletion="no" modification="no"/>
      <description>
        Added <code>getShortDescription</code> and
        <code>TAG_SHORT_DESCRIPTION</code>.
      </description>
  </change>
  
  <change>
      <api name="modules"/>
      <summary>Get layer as a resource, not URL</summary>
      <date day="23" month="11" year="2000"/>
      <author login="jglick"/>
      <compatibility addition="yes" deprecation="yes" binary="compatible" source="compatible" semantic="compatible" deletion="no" modification="no"/>
      <description>
        <code>getLayerResource()</code> added. Thus all locale variants of a layer
        may be merged together. Retrieval as URL is deprecated.
      </description>
  </change>
  
  <change>
      <api name="modules"/>
      <summary>Package-accessible classloader</summary>
      <date day="12" month="11" year="2000"/>
      <author login="jglick"/>
      <compatibility addition="yes" binary="compatible" source="compatible" semantic="compatible" deprecation="no" deletion="no" modification="no"/>
      <description>
        Inner interface <code>PackageAccessibleClassLoader</code> added to make it
        easier to check package dependencies. Package dependencies which include
        sample classes are now permitted.
      </description>
  </change>
  
  <change>
      <api name="modules"/>
      <summary>Permit abbreviated sample class names in package dependencies</summary>
      <date day="22" month="11" year="2000"/>
      <author login="jglick"/>
      <compatibility modification="yes" binary="compatible" source="compatible" semantic="compatible" deprecation="no" addition="no" deletion="no"/>
      <description>
        Slight extension to package dependency syntax to allow abbreviated sample
        name.
      </description>
  </change>
  
  <change>
      <api name="modules"/>
      <summary>Support layer specification in a module manifest</summary>
      <date day="2" month="11" year="2000"/>
      <author login="jglick"/>
      <compatibility addition="yes" binary="compatible" source="compatible" semantic="compatible" deprecation="no" deletion="no" modification="no"/>
      <description>
        Now also understands <code>OpenIDE-Module-Layer</code> tag that can specify
        a resource path to XMLFileSystem that is provided by the module. Also
        added method <code>getLayer()</code> that returns the URL of XML
        filesystem if provided.
      </description>
  </change>
  
  <change>
      <api name="modules"/>
      <summary><code>ModuleDescription</code> constructor may specify a classloader</summary>
      <date day="28" month="3" year="2000"/>
      <author login="jglick"/>
      <compatibility addition="yes" binary="compatible" source="compatible" semantic="compatible" deprecation="no" deletion="no" modification="no"/>
      <description>
        Constructors may now specify a classloader to use rather than setting it
        later.
      </description>
  </change>
  
  <change>
      <api name="modules"/>
      <summary>Manipulation of classloader used by a module</summary>
      <date day="27" month="8" year="2000"/>
      <author login="jglick"/>
      <compatibility addition="yes" binary="compatible" source="compatible" semantic="compatible" deprecation="no" deletion="no" modification="no"/>
      <description>
        Added methods <code>getClassLoader</code>, <code>setClassLoader</code> and
        <code>getBadClasses</code>.
      </description>
  </change>
  
  <change>
      <api name="modules"/>
      <summary>Can get the class implementing a manifest section</summary>
      <date day="8" month="3" year="2001"/>
      <compatibility addition="yes" binary="compatible" source="compatible" semantic="compatible" deprecation="no" deletion="no" modification="no"/>
      <description>
        Added method <code>getSectionClass()</code>.
      </description>
  </change>
</changes>

  <htmlcontents>
    <head>
      <title>Change History for the Modules API</title>
      <link rel="stylesheet" href="prose.css" type="text/css"/>
    </head>
    <body>

<p class="overviewlink"><a href="overview-summary.html">Overview</a></p>

<h1>Introduction</h1>

<h2>What do the Dates Mean?</h2>

<p>The supplied dates indicate when the API change was made, on the CVS
trunk. From this you can generally tell whether the change should be
present in a given build or not; for trunk builds, simply whether it
was made before or after the change; for builds on a stabilization
branch, whether the branch was made before or after the given date. In
some cases corresponding API changes have been made both in the trunk
and in an in-progress stabilization branch, if they were needed for a
bug fix; this ought to be marked in this list.</p>

<ul>

<li>The <code>release41</code> branch was made on Apr 03 '05 for use in the NetBeans 4.1 release.
Specification versions: 6.0 begins after this point.</li>

<li>The <code>release40</code> branch was made on Nov 01 '04 for use in the NetBeans 4.0 release.
Specification versions: 5.0 begins after this point.</li>


</ul>

<!-- The actual lists of changes, as summaries and details: -->

      <hr/><standard-changelists module-code-name="org.openide.modules"/>
      
      <hr/><p>@FOOTER@</p>

    </body>
  </htmlcontents>

  
</apichanges>