<?xml version="1.0" encoding="UTF-8"?>
<!--

    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.

-->
<!DOCTYPE apichanges PUBLIC "-//NetBeans//DTD API changes list 1.0//EN" "../../nbbuild/javadoctools/apichanges.dtd">
<apichanges>
<apidefs>
    <apidef name="lookup">Lookup API</apidef>
</apidefs>
<changes>
    <change id="lookups.execute">
        <api name="lookup"/>
        <summary>A way to control Lookup.getDefault</summary>
        <version major="8" minor="30"/>
        <date day="22" month="10" year="2014"/>
        <author login="jtulach"/>
        <compatibility
            addition="yes"
            binary="compatible" deletion="no" deprecation="no"
            modification="no" semantic="incompatible" source="compatible"
        >
            The clients of <a href="@TOP@/org/openide/util/Lookup.html#getDefault--">
            Lookup.getDefault()</a> are mostly unaffected by this change,
            just they need to be ready for the fact that the return 
            value of the method may no longer be fixed one, but can mutate
            over time.
        </compatibility>
        <description>
            <p>
                One can use <a href="@TOP@/org/openide/util/lookup/Lookups.html#executeWith-org.openide.util.Lookup-java.lang.Runnable-">
                Lookups.execute(yourLookup, yourRunnable)
                </a> to temporarily influence return value from
                <a href="@TOP@/org/openide/util/Lookup.html#getDefault--">
                Lookup.getDefault()</a>. 
            </p>
        </description>
        <class package="org.openide.util.lookup" name="Lookups"/>
        <issue number="247930"/>
    </change>
    <change id="named.service.definition">
        <api name="lookup"/>
        <summary>Easy and robust way to register named services</summary>
        <version major="8" minor="14"/>
        <date day="27" month="3" year="2012"/>
        <author login="jtulach"/>
        <compatibility
            addition="yes"
            binary="compatible" deletion="no" deprecation="no"
            modification="no" semantic="compatible" source="compatible"
        />
        <description>
            <p>
                Meta annotation 
                <a href="@TOP@org/openide/util/lookup/NamedServiceDefinition.html">NamedServiceDefinition</a> 
                for those who define their own annotations that register
                something into 
                <a href="@TOP@org/openide/util/lookup/Lookups.html#forPath-java.lang.String-">
                Lookups.forPath</a> registration area.
            </p>
        </description>
        <class package="org.openide.util.lookup" name="NamedServiceDefinition"/>
        <issue number="209780"/>
    </change>
    <change id="lazy.proxy.lookup">
        <api name="lookup"/>
        <summary><code>ProxyLookup</code> computes results lazily</summary>
        <version major="8" minor="13"/>
        <date day="10" month="3" year="2012"/>
        <author login="jtulach"/>
        <compatibility
            addition="yes"
            binary="compatible" deletion="no" deprecation="no"
            modification="no" semantic="incompatible" source="compatible"
        >
            <p>
            Calling <a href="@TOP@/org/openide/util/lookup/ProxyLookup.html">
            ProxyLookup.lookupAll()</a> and other methods that compute
            aggregate results delays computation of the result. This
            may affect code which called 
            <a href="@TOP@/org/openide/util/Lookup.Result.html">Lookup.Result</a>.<code>allItems</code>, 
            <code>allInstances</code> or <code>allClasses</code> and relied
            on side effect of such call. In case you want to trigger the 
            computation call some method on the returned
            <a href="@JDK@/java/util/Collection.html">Collection</a> 
            (other than <code>iterator()</code>) like <code>size()</code>
            or <code>isEmpty</code>.
            </p>
        </compatibility>
        <description>
            <p>
                <a href="@TOP@/org/openide/util/lookup/ProxyLookup.html">
                ProxyLookup.lookupAll().iterator()</a> is now incremental.
                E.g. you can use traverse part of the results without
                waiting for or creating all of them:
            </p>
           <pre>
for (<a href="@JDK@/java/net/URLStreamHandlerFactory.html">URLStreamHandlerFactory</a> first : <a href="@TOP@/org/openide/util/Lookup.html#getDefault--">Lookup.getDefault()</a>.lookupAll(<a href="@JDK@/java/net/URLStreamHandlerFactory.html">URLStreamHandlerFactory</a>.class)) {
    return first;
}
           </pre>
        </description>
        <issue number="209322"/>
    </change>
    <change id="named.services.provider">
        <api name="lookup"/>
        <summary>Introducing semihidden SPI</summary>
        <version major="8" minor="1"/>
        <date day="15" month="1" year="2010"/>
        <author login="jtulach"/>
        <compatibility
            addition="yes"
            binary="compatible" deletion="no" deprecation="no"
            modification="no" semantic="compatible" source="compatible"
        />
        <description>
            <p>
                Adding SPI interface package for those who implement
                the NetBeans platform. This package is not shown in Javadoc
                as it does not form a generally available public API.
            </p>
        </description>
        <issue number="179289"/>
    </change>
    <change id="lookup.is.free">
        <api name="lookup"/>
        <summary>Separate module for Lookup API</summary>
        <version major="8" minor="0"/>
        <date day="20" month="12" year="2009"/>
        <author login="jtulach"/>
        <compatibility modification="yes">
            <p>
                Runtime compatibility remains, compile time compatibility is
                mostly preserved too. It is however recommended to upgrade
                dependencies of your modules. Try running
                <code>ant fix-dependencies</code> in your Ant module.
            </p>
        </compatibility>
        <description>
            <p>
                <a href="@org-openide-util-lookup@/org/openide/util/Lookup.html">Lookup</a>
                and its associated interfaces are now available as a
                <a href="@org-openide-util-lookup@/overview-summary.html">separate module</a>.
            </p>
        </description>
        <class package="org.openide.util" name="Lookup"/>
        <class package="org.openide.util.lookup" name="AbstractLookup"/>
        <class package="org.openide.util.lookup" name="ProxyLookup"/>
        <class package="org.openide.util.lookup" name="Lookups"/>
        <issue number="170056"/>
    </change>
    <change id="org.openide.util.Lookup.paths">
        <api name="lookup"/>
        <summary>Added
            <code>org.openide.util.Lookup.paths</code> property
        </summary>
        <version major="7" minor="24"/>
        <date day="19" month="6" year="2009"/>
        <author login="jtulach"/>
        <compatibility addition="yes"/>
        <description>
            <p>
                 Better way to integrate Lookup.getDefault() and system filesystem.
            </p>
        </description>
        <class package="org.openide.util" name="Lookup"/>
        <issue number="166782"/>
    </change>
    <change id="ServiceProvider">
        <api name="lookup"/>
        <summary>Added <code>ServiceProvider</code> annotation</summary>
        <version major="7" minor="20"/>
        <date day="1" month="11" year="2008"/>
        <author login="jglick"/>
        <compatibility addition="yes">
            <p>
                Modules registering services using <code>META-INF/services</code>
                files in the source tree are encouraged to switch to the annotation.
            </p>
        </compatibility>
        <description>
            <p>
                Added annotations <code>ServiceProvider</code> and <code>ServiceProviders</code>
                to simplify registration of global singleton services.
            </p>
        </description>
        <class package="org.openide.util.lookup" name="ServiceProvider"/>
        <class package="org.openide.util.lookup" name="ServiceProviders"/>
        <issue number="150447"/>
    </change>
    <change id="Lookup.asynchronous">
        <api name="lookup"/>
        <summary>AbstractLookup and ProxyLookup fire changes asynchronously</summary>
        <version major="7" minor="16"/>
        <date day="27" month="6" year="2008"/>
        <author login="jtulach"/>
        <compatibility addition="yes" binary="compatible" semantic="compatible"/>
        <description>
            <p>
                All modification methods in <code>AbstractLookup</code> and <code>ProxyLookup</code>
                were extended to accept an 
                <a href="@JDK@/java/util/concurrent/Executor.html">Executor</a>.
                If not null, it is used to dispatch events to listeners sometime
                "later". Also the <code>AbstractLookup.Content</code> 
                and <code>InstanceContent</code> constructors
                have been extended to accept such <code>Executor</code>s.
            </p>
        </description> 
        <class package="org.openide.util.lookup" name="AbstractLookup"/>
        <class package="org.openide.util.lookup" name="ProxyLookup"/>
        <class package="org.openide.util.lookup" name="InstanceContent"/>
        <issue number="134297"/>
    </change>

    <change id="Lookups.forPath">
        <api name="lookup"/>
        <summary>Added simplified support for named lookups <code>Lookups.forPath</code></summary>
        <version major="7" minor="9"/>
        <date day="17" month="4" year="2007"/>
        <author login="jtulach"/>
        <compatibility addition="yes"/>
        <description>
            <p>
                New method <a href="@TOP@/org/openide/util/lookup/Lookups.html#forPath-java.lang.String-">Lookups.forPath(String)</a>
                has been added to replace now deprecated <a href="@org-openide-loaders@/org/openide/loaders/FolderLookup.html">FolderLookup</a>
                and allow modules who wants to read settings from layers
                to do so with a simpler code, without dependency on DataSystems API.
            </p>
        </description>
        <class package="org.openide.util.lookup" name="Lookups"/>
        <issue number="98426"/>
    </change>
    
    <change id="lookupAll-lookupResult">
        <api name="lookup"/>
        <summary>Convenience methods added to <code>Lookup</code></summary>
        <version major="6" minor="10"/>
        <date day="3" month="4" year="2006"/>
        <author login="jglick"/>
        <compatibility addition="yes" binary="compatible" source="incompatible">
            <p>
                Could conceivably conflict with existing subclass method with same signature
                with different semantics or return type.
            </p>
        </compatibility>
        <description>
            <p>
                Two methods, <code>lookupResult</code> and <code>lookupAll</code>, were
                added to <code>Lookup</code> to encapsulate the most common usage patterns
                with less typing, and more importantly avoiding the need to explicitly
                make a <code>Lookup.Template</code> object.
            </p>
        </description>
        <class package="org.openide.util" name="Lookup"/>
        <issue number="73848"/>
    </change>
    <change id="less-events-from-proxylookup" >
      <api name="lookup"/>
      <summary>Less change notifications from ProxyLookup</summary>
      <version major="6" minor="7"/>
      <date day="11" month="11" year="2005"/>
      <author login="jtulach"/>
      <compatibility addition="no" modification="yes" binary="compatible" source="compatible" semantic="compatible" deprecation="no" deletion="no"/>
      <description>
        <a href="@TOP@/org/openide/util/lookup/ProxyLookup.html">ProxyLookup.setLookups</a>
        used to fire <a href="@TOP@/org/openide/util/LookupEvent.html">LookupEvent</a> every 
        time it was called. Now it always checks whether there was a change to the
        previous state. This will reduce the number of events delivered when a small
        change is made. Also results from both 
        <a href="@TOP@/org/openide/util/lookup/ProxyLookup.html">ProxyLookup</a>
        and <a href="@TOP@/org/openide/util/lookup/AbstractLookup.html">AbstractLookup</a>
        were modified to return immutable <code>Collection</code>s. 
        So do not try to modify them. It was always documented that the
        results, are immutable and also it was never said that a change is
        delivered when there is no change in the result, so this is considered
        compatible change, even it is know that at least one piece of code 
        in NetBeans relied on this behaviour.
      </description>
      <class package="org.openide.util.lookup" name="ProxyLookup"/>
      <class package="org.openide.util.lookup" name="AbstractLookup"/>
      <issue number="68031"/>
    </change>
    

    <change id="excluding-lookup">
      <api name="lookup"/>
      <summary>
<code>Lookups.exclude</code> added to simplify writing of lookups that filter content of other lookups</summary>
      <version major="5" minor="4"/>
      <date day="14" month="1" year="2005"/>
      <author login="jtulach"/>
      <compatibility binary="compatible" source="compatible" semantic="compatible" deprecation="no" addition="no" deletion="no" modification="no"/>
      <description>
        <p>New method that takes lookup and set of classes and return new lookup 
        which contains everything from the original one except instances of 
        the specified classes has been added.
        </p>
      </description>
      <class package="org.openide.util.lookup" name="Lookups"/>
      <issue number="53058"/>
    </change>
    <change>
        <api name="lookup"/>
        <summary>Added ability to order items in META-INF/services/ lookup</summary>
        <version major="4" minor="34"/>
        <date day="9" month="5" year="2004"/>
        <author login="dkonecny"/>
        <compatibility addition="yes" binary="compatible" source="compatible" semantic="compatible" deprecation="no" deletion="no" modification="no"/>
        <description>
            Items in META-INF/services/ lookup can be followed by advisory
            "position" attribute. The resulting lookup will list first items with lower
            position value. Items without position attribute will be listed 
            last. See documentation for more details on format.
        </description>
        <class package="org.openide.util.lookup" name="Lookups"/>
        <issue number="41606"/>
    </change>
    <change>
     <api name="lookup"/>
     <summary>New <code>lookupItem()</code> method in Lookups</summary>
     <version major="4" minor="8"/>
     <date day="9" month="7" year="2003"/>
     <author login="vstejskal"/>
     <compatibility addition="yes" binary="compatible" source="compatible" semantic="compatible" deprecation="no" deletion="no" modification="no"/>
     <description>
       New method that returns Lookup.Item implementation for given instance and key identifying
       that instance in the lookup. This method is useful when writing Looks which need to
       return some cookies (Collection of Lookup.Items).
     </description>
     <class package="org.openide.util.lookup" name="Lookups"/>
    </change>
    <change>
        <api name="lookup"/>
        <summary>New method Lookups.metaInfServices</summary>
        <version major="3" minor="35"/>
        <date day="5" month="2" year="2003"/>
        <author login="dstrupl"/>
        <compatibility addition="yes" binary="compatible" source="compatible" semantic="compatible" deprecation="no" deletion="no" modification="no"/>
        <description>
            A lookup that implements the JDK1.3 JAR services mechanism and delegates
            to META-INF/services/name.of.class files. This lookup was (is) used by core
            and the core had to use reflection to create an instance. Moreover can
            be usefull for module authors and in standalone library.
        </description>
        <class package="org.openide.util.lookup" name="Lookups"/>
        <issue number="29126"/>
    </change>
    <change>
        <api name="lookup"/>
        <summary>New method Lookups.proxy</summary>
        <version major="3" minor="9"/>
        <date day="20" month="9" year="2002"/>
        <author login="dstrupl"/>
        <compatibility addition="yes" binary="compatible" source="compatible" semantic="compatible" deprecation="no" deletion="no" modification="no"/>
        <description>
            Creates a lookup that delegates to another one but that one can change
            from time to time. The returned lookup checks every time somebody calls
            lookup or lookupItem method whether the provider still returns
            the same lookup. If not, it updates state of all Lookup.Results
            that it created (and that still exists).
        </description>
        <class package="org.openide.util.lookup" name="Lookups"/>
        <issue number="27425"/>
    </change>
    <change id="meta-inf-services">
        <api name="lookup"/>
        <summary>Modules can specify the content of Lookup.getDefault
        in META-INF/services</summary>
        <version major="3" minor="3"/>
        <date day="22" month="7" year="2002"/>
        <author login="jtulach"/>
        <compatibility addition="yes" binary="compatible" source="compatible" semantic="compatible" deprecation="no" deletion="no" modification="no"/>
        <description>
          The content of <code>Lookup.getDefault()</code> can be specified
          by a standard JDK registration mechanism, using JARs'
          <a href="http://java.sun.com/j2se/1.4/docs/guide/jar/jar.html#Service%20Provider" shape="rect">
            META-INF/services
          </a>
          directory. This is suitable for services that do not change,
          do not require user modification and that need to be ready
          soon during initialization of the system. 
        </description>
    </change>
    <change>
         <api name="lookup"/>
         <summary>Added org.openide.util.lookup.Lookups</summary>
         <version major="2" minor="21"/>
         <date day="28" month="5" year="2002"/>
         <author login="dstrupl"/>
         <compatibility addition="yes" binary="compatible" source="compatible" semantic="compatible" deprecation="no" deletion="no" modification="no"/>
         <description>New utility class added. The class cannot be instantiated
           and contains following static methods:
        <pre xml:space="preserve">
<span class="keyword">public</span> <span class="keyword">static</span> <span class="type">Lookup</span> <span class="function-name">singleton</span>(<span class="type">Object</span> <span class="variable-name">objectToLookup</span>);
<span class="keyword">public</span> <span class="keyword">static</span> <span class="type">Lookup</span> <span class="function-name">fixed</span>(<span class="type">Object</span>[] <span class="variable-name">objectsToLookup</span>);
<span class="keyword">public</span> <span class="keyword">static</span> <span class="type">Lookup</span> <span class="function-name">fixed</span>(<span class="type">Object</span>[] <span class="variable-name">keys</span>, <span class="type">InstanceContent.Convertor</span> <span class="variable-name">convertor</span>);
</pre>
           The methods return an instance of simple lookup implementation
           that holds the objects passed a parameter.
         </description>
         <class package="org.openide.util.lookup" name="Lookups"/>
         <issue number="20550"/>
    </change>
    <change id="AbstractLookup.Content-ProxyLookup.beforeLookup">
      <api name="lookup"/>
      <summary>Enhanced usage of ProxyLookup &amp; AbstractLookup.Content</summary>
      <version major="1" minor="31"/>
      <date day="18" month="8" year="2001"/>
      <author login="jtulach"/>
      <compatibility addition="yes" binary="compatible" source="compatible" semantic="compatible" deprecation="no" deletion="no" modification="no"/>
      <description>
        <code>AbstractLookup.Content</code> made public to allow its usage 
        for objects that do not subclass AbstractLookup. <code>ProxyLookup.beforeLookup</code>
        added so subclasses can update themselves (call setLookups (...)) before the actual lookup is
        performed.
      </description>
      <class package="org.openide.util.lookup" name="AbstractLookup"/>
      <class package="org.openide.util.lookup" name="ProxyLookup"/>
    </change>
    <change>
      <api name="lookup"/>
      <summary>Instance content simplifies creation of lookups</summary>
      <version major="1" minor="25"/>
      <!-- XXX date unknown -->
      <author login="jtulach"/>
      <compatibility addition="yes" binary="compatible" source="compatible" semantic="compatible" deprecation="no" deletion="no" modification="no"/>
      <description>
        Added <code>AbstractLookup.Content</code> which can be passed to an
        abstract lookup in its constructor and used to control the contents
        easily. Also <code>InstanceLookup</code> provides the common easy
        implementation.
      </description>
      <class package="org.openide.util.lookup" name="AbstractLookup"/>
      <class package="org.openide.util.lookup" name="InstanceContent"/>
    </change>
    <change>
      <api name="lookup"/>
      <summary>Folder lookup may be serialized</summary>
      <version major="3" minor="27"/>
      <date day="7" month="1" year="2003"/>
      <author login="jglick"/>
      <compatibility modification="yes" binary="compatible" source="compatible" semantic="compatible" deprecation="no" addition="no" deletion="no">
        Modules which rely on a data object under <samp>Services/</samp> gaining
        or losing <code>InstanceCookie</code> between sessions may not work
        correctly with the cache. This is probably very rare.
      </compatibility>
      <description>
        To implement lookup caching, some lookup implementations are now
        serializable: <code>AbstractLookup</code> as well as
        <code>FolderLookup</code>'s lookup. <code>ProxyLookup</code> has a
        protected subclass constructor permitting subclasses to be serializable.
      </description>
      <class package="org.openide.util.lookup" name="AbstractLookup"/>
      <class package="org.openide.util.lookup" name="ProxyLookup"/>
      <issue number="20190"/>
    </change>
    <change>
      <api name="lookup"/>
      <summary>Changes in access protection of proxy lookup</summary>
      <version major="1" minor="19"/>
      <date day="8" month="7" year="2001"/>
      <compatibility modification="yes" binary="compatible" source="compatible" semantic="compatible" deprecation="no" addition="no" deletion="no">
        Changes to newly added feature.
      </compatibility>
      <description>
        <code>ProxyLookup.setLookups</code> made protected instead of public so
        nobody can misuse the method except the creator of the object and
        <code>ProxyLookup.getLookups</code> added. <code>ProxyLookup</code> made
        non final.
      </description>
      <class package="org.openide.util.lookup" name="ProxyLookup"/>
    </change>
    <change>
      <api name="lookup"/>
      <summary>Lookup service providers package created</summary>
      <version major="1" minor="9"/>
      <date day="1" month="6" year="2001"/>
      <author login="jtulach"/>
      <compatibility addition="yes" binary="compatible" source="compatible" semantic="compatible" deprecation="no" deletion="no" modification="no"/>
      <description>
        Package <code>org.openide.util.lookup</code> created, should hold SPI
        interfaces for lookup. Initially filled with <code>AbstractLookup</code>
        which introduces <code>AbstractLookup.Pair</code> and with
        <code>ProxyLookup</code>.
      </description>
      <class package="org.openide.util.lookup" name="AbstractLookup"/>
      <class package="org.openide.util.lookup" name="ProxyLookup"/>
      <package name="org.openide.util.lookup"/>
    </change>
    <change>
      <api name="lookup"/>
      <summary>Added lookup items and support APIs</summary>
      <version major="1" minor="8"/>
      <date day="25" month="5" year="2001"/>
      <author login="jtulach"/>
      <compatibility addition="yes" binary="compatible" source="compatible" semantic="compatible" deprecation="no" deletion="no" modification="no"/>
      <description>
        <code>Lookup</code> enhanced. Interface <code>Lookup.Item</code> and
        additional methods to access it also added.
      </description>
      <class package="org.openide.util" name="Lookup"/>
    </change>
    <change>
      <api name="lookup"/>
      <summary>Lookup system introduced</summary>
      <date day="1" month="3" year="2001"/>
      <author login="jtulach"/>
      <compatibility addition="yes" binary="compatible" source="compatible" semantic="compatible" deprecation="no" deletion="no" modification="no"/>
      <description>
        Better version of <code>Lookup</code> introduced. There is a
        <code>org.openide.util.Lookup</code> with bunch of inner classes and
        <code>org.openide.util.LookupListener</code> and
        <code>org.openide.util.LookupEvent</code>.
      </description>
      <class package="org.openide.util" name="Lookup"/>
      <class package="org.openide.util" name="LookupEvent"/>
      <class package="org.openide.util" name="LookupListener"/>
    </change>
</changes>
<htmlcontents>
<head>
<title>Change History for the Lookup 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>
<hr/>
<standard-changelists module-code-name="$codebase"/>
<hr/>
<p>@FOOTER@</p>
</body>
</htmlcontents>
</apichanges>