1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/openide.util.lookup/apichanges.xml Mon Dec 14 19:10:02 2009 +0100
1.3 @@ -0,0 +1,448 @@
1.4 +<?xml version="1.0" encoding="UTF-8"?>
1.5 +<!--
1.6 +DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
1.7 +
1.8 +Copyright 1997-2009 Sun Microsystems, Inc. All rights reserved.
1.9 +
1.10 +
1.11 +The contents of this file are subject to the terms of either the GNU
1.12 +General Public License Version 2 only ("GPL") or the Common
1.13 +Development and Distribution License("CDDL") (collectively, the
1.14 +"License"). You may not use this file except in compliance with the
1.15 +License. You can obtain a copy of the License at
1.16 +http://www.netbeans.org/cddl-gplv2.html
1.17 +or nbbuild/licenses/CDDL-GPL-2-CP. See the License for the
1.18 +specific language governing permissions and limitations under the
1.19 +License. When distributing the software, include this License Header
1.20 +Notice in each file and include the License file at
1.21 +nbbuild/licenses/CDDL-GPL-2-CP. Sun designates this
1.22 +particular file as subject to the "Classpath" exception as provided
1.23 +by Sun in the GPL Version 2 section of the License file that
1.24 +accompanied this code. If applicable, add the following below the
1.25 +License Header, with the fields enclosed by brackets [] replaced by
1.26 +your own identifying information:
1.27 +"Portions Copyrighted [year] [name of copyright owner]"
1.28 +
1.29 +Contributor(s):
1.30 +
1.31 +The Original Software is NetBeans. The Initial Developer of the Original
1.32 +Software is Sun Microsystems, Inc. Portions Copyright 1997-2006 Sun
1.33 +Microsystems, Inc. All Rights Reserved.
1.34 +
1.35 +If you wish your version of this file to be governed by only the CDDL
1.36 +or only the GPL Version 2, indicate your decision by adding
1.37 +"[Contributor] elects to include this software in this distribution
1.38 +under the [CDDL or GPL Version 2] license." If you do not indicate a
1.39 +single choice of license, a recipient has the option to distribute
1.40 +your version of this file under either the CDDL, the GPL Version 2 or
1.41 +to extend the choice of license to its licensees as provided above.
1.42 +However, if you add GPL Version 2 code and therefore, elected the GPL
1.43 +Version 2 license, then the option applies only if the new code is
1.44 +made subject to such option by the copyright holder.
1.45 +-->
1.46 +<!DOCTYPE apichanges PUBLIC "-//NetBeans//DTD API changes list 1.0//EN" "../nbbuild/javadoctools/apichanges.dtd">
1.47 +<apichanges>
1.48 +<apidefs>
1.49 + <apidef name="lookup">Lookup API</apidef>
1.50 +</apidefs>
1.51 +<changes>
1.52 + <change id="org.openide.util.Lookup.paths">
1.53 + <api name="lookup"/>
1.54 + <summary>Added
1.55 + <code>org.openide.util.Lookup.paths</code> property
1.56 + </summary>
1.57 + <version major="7" minor="24"/>
1.58 + <date day="19" month="6" year="2009"/>
1.59 + <author login="jtulach"/>
1.60 + <compatibility addition="yes"/>
1.61 + <description>
1.62 + <p>
1.63 + Better way to integrate Lookup.getDefault() and system filesystem.
1.64 + </p>
1.65 + </description>
1.66 + <class package="org.openide.util" name="Lookup"/>
1.67 + <issue number="166782"/>
1.68 + </change>
1.69 + <change id="ServiceProvider">
1.70 + <api name="lookup"/>
1.71 + <summary>Added <code>ServiceProvider</code> annotation</summary>
1.72 + <version major="7" minor="20"/>
1.73 + <date day="1" month="11" year="2008"/>
1.74 + <author login="jglick"/>
1.75 + <compatibility addition="yes">
1.76 + <p>
1.77 + Modules registering services using <code>META-INF/services</code>
1.78 + files in the source tree are encouraged to switch to the annotation.
1.79 + </p>
1.80 + </compatibility>
1.81 + <description>
1.82 + <p>
1.83 + Added annotations <code>ServiceProvider</code> and <code>ServiceProviders</code>
1.84 + to simplify registration of global singleton services.
1.85 + </p>
1.86 + </description>
1.87 + <class package="org.openide.util.lookup" name="ServiceProvider"/>
1.88 + <class package="org.openide.util.lookup" name="ServiceProviders"/>
1.89 + <issue number="150447"/>
1.90 + </change>
1.91 + <change id="Lookup.asynchronous">
1.92 + <api name="lookup"/>
1.93 + <summary>AbstractLookup and ProxyLookup fire changes asynchronously</summary>
1.94 + <version major="7" minor="16"/>
1.95 + <date day="27" month="6" year="2008"/>
1.96 + <author login="jtulach"/>
1.97 + <compatibility addition="yes" binary="compatible" semantic="compatible"/>
1.98 + <description>
1.99 + <p>
1.100 + All modification methods in <code>AbstractLookup</code> and <code>ProxyLookup</code>
1.101 + were extended to accept an
1.102 + <a href="@JDK@/java/util/concurrent/Executor.html">Executor</a>.
1.103 + If not null, it is used to dispatch events to listeners sometime
1.104 + "later". Also the <code>AbstractLookup.Content</code>
1.105 + and <code>InstanceContent</code> constructors
1.106 + have been extended to accept such <code>Executor</code>s.
1.107 + </p>
1.108 + </description>
1.109 + <class package="org.openide.util.lookup" name="AbstractLookup"/>
1.110 + <class package="org.openide.util.lookup" name="ProxyLookup"/>
1.111 + <class package="org.openide.util.lookup" name="InstanceContent"/>
1.112 + <issue number="134297"/>
1.113 + </change>
1.114 +
1.115 + <change id="Lookups.forPath">
1.116 + <api name="lookup"/>
1.117 + <summary>Added simplified support for named lookups <code>Lookups.forPath</code></summary>
1.118 + <version major="7" minor="9"/>
1.119 + <date day="17" month="4" year="2007"/>
1.120 + <author login="jtulach"/>
1.121 + <compatibility addition="yes"/>
1.122 + <description>
1.123 + <p>
1.124 + New method <a href="@TOP@/org/openide/util/lookup/Lookups.html#forPath(java.lang.String)">Lookups.forPath(String)</a>
1.125 + has been added to replace now deprecated <a href="@org-openide-loaders@/org/openide/loaders/FolderLookup.html">FolderLookup</a>
1.126 + and allow modules who wants to read settings from layers
1.127 + to do so with a simpler code, without dependency on DataSystems API.
1.128 + </p>
1.129 + </description>
1.130 + <class package="org.openide.util.lookup" name="Lookups"/>
1.131 + <issue number="98426"/>
1.132 + </change>
1.133 +
1.134 + <change id="lookupAll-lookupResult">
1.135 + <api name="lookup"/>
1.136 + <summary>Convenience methods added to <code>Lookup</code></summary>
1.137 + <version major="6" minor="10"/>
1.138 + <date day="3" month="4" year="2006"/>
1.139 + <author login="jglick"/>
1.140 + <compatibility addition="yes" binary="compatible" source="incompatible">
1.141 + <p>
1.142 + Could conceivably conflict with existing subclass method with same signature
1.143 + with different semantics or return type.
1.144 + </p>
1.145 + </compatibility>
1.146 + <description>
1.147 + <p>
1.148 + Two methods, <code>lookupResult</code> and <code>lookupAll</code>, were
1.149 + added to <code>Lookup</code> to encapsulate the most common usage patterns
1.150 + with less typing, and more importantly avoiding the need to explicitly
1.151 + make a <code>Lookup.Template</code> object.
1.152 + </p>
1.153 + </description>
1.154 + <class package="org.openide.util" name="Lookup"/>
1.155 + <issue number="73848"/>
1.156 + </change>
1.157 + <change id="less-events-from-proxylookup" >
1.158 + <api name="lookup"/>
1.159 + <summary>Less change notifications from ProxyLookup</summary>
1.160 + <version major="6" minor="7"/>
1.161 + <date day="11" month="11" year="2005"/>
1.162 + <author login="jtulach"/>
1.163 + <compatibility addition="no" modification="yes" binary="compatible" source="compatible" semantic="compatible" deprecation="no" deletion="no"/>
1.164 + <description>
1.165 + <a href="@TOP@/org/openide/util/lookup/ProxyLookup.html">ProxyLookup.setLookups</a>
1.166 + used to fire <a href="@TOP@/org/openide/util/LookupEvent.html">LookupEvent</a> every
1.167 + time it was called. Now it always checks whether there was a change to the
1.168 + previous state. This will reduce the number of events delivered when a small
1.169 + change is made. Also results from both
1.170 + <a href="@TOP@/org/openide/util/lookup/ProxyLookup.html">ProxyLookup</a>
1.171 + and <a href="@TOP@/org/openide/util/lookup/AbstractLookup.html">AbstractLookup</a>
1.172 + were modified to return immutable <code>Collection</code>s.
1.173 + So do not try to modify them. It was always documented that the
1.174 + results, are immutable and also it was never said that a change is
1.175 + delivered when there is no change in the result, so this is considered
1.176 + compatible change, even it is know that at least one piece of code
1.177 + in NetBeans relied on this behaviour.
1.178 + </description>
1.179 + <class package="org.openide.util.lookup" name="ProxyLookup"/>
1.180 + <class package="org.openide.util.lookup" name="AbstractLookup"/>
1.181 + <issue number="68031"/>
1.182 + </change>
1.183 +
1.184 +
1.185 + <change id="excluding-lookup">
1.186 + <api name="lookup"/>
1.187 + <summary>
1.188 +<code>Lookups.exclude</code> added to simplify writing of lookups that filter content of other lookups</summary>
1.189 + <version major="5" minor="4"/>
1.190 + <date day="14" month="1" year="2005"/>
1.191 + <author login="jtulach"/>
1.192 + <compatibility binary="compatible" source="compatible" semantic="compatible" deprecation="no" addition="no" deletion="no" modification="no"/>
1.193 + <description>
1.194 + <p>New method that takes lookup and set of classes and return new lookup
1.195 + which contains everything from the original one except instances of
1.196 + the specified classes has been added.
1.197 + </p>
1.198 + </description>
1.199 + <class package="org.openide.util.lookup" name="Lookups"/>
1.200 + <issue number="53058"/>
1.201 + </change>
1.202 + <change>
1.203 + <api name="lookup"/>
1.204 + <summary>Added ability to order items in META-INF/services/ lookup</summary>
1.205 + <version major="4" minor="34"/>
1.206 + <date day="9" month="5" year="2004"/>
1.207 + <author login="dkonecny"/>
1.208 + <compatibility addition="yes" binary="compatible" source="compatible" semantic="compatible" deprecation="no" deletion="no" modification="no"/>
1.209 + <description>
1.210 + Items in META-INF/services/ lookup can be followed by advisory
1.211 + "position" attribute. The resulting lookup will list first items with lower
1.212 + position value. Items without position attribute will be listed
1.213 + last. See documentation for more details on format.
1.214 + </description>
1.215 + <class package="org.openide.util.lookup" name="Lookups"/>
1.216 + <issue number="41606"/>
1.217 + </change>
1.218 + <change>
1.219 + <api name="lookup"/>
1.220 + <summary>New <code>lookupItem()</code> method in Lookups</summary>
1.221 + <version major="4" minor="8"/>
1.222 + <date day="9" month="7" year="2003"/>
1.223 + <author login="vstejskal"/>
1.224 + <compatibility addition="yes" binary="compatible" source="compatible" semantic="compatible" deprecation="no" deletion="no" modification="no"/>
1.225 + <description>
1.226 + New method that returns Lookup.Item implementation for given instance and key identifying
1.227 + that instance in the lookup. This method is useful when writing Looks which need to
1.228 + return some cookies (Collection of Lookup.Items).
1.229 + </description>
1.230 + <class package="org.openide.util.lookup" name="Lookups"/>
1.231 + </change>
1.232 + <change>
1.233 + <api name="lookup"/>
1.234 + <summary>New method Lookups.metaInfServices</summary>
1.235 + <version major="3" minor="35"/>
1.236 + <date day="5" month="2" year="2003"/>
1.237 + <author login="dstrupl"/>
1.238 + <compatibility addition="yes" binary="compatible" source="compatible" semantic="compatible" deprecation="no" deletion="no" modification="no"/>
1.239 + <description>
1.240 + A lookup that implements the JDK1.3 JAR services mechanism and delegates
1.241 + to META-INF/services/name.of.class files. This lookup was (is) used by core
1.242 + and the core had to use reflection to create an instance. Moreover can
1.243 + be usefull for module authors and in standalone library.
1.244 + </description>
1.245 + <class package="org.openide.util.lookup" name="Lookups"/>
1.246 + <issue number="29126"/>
1.247 + </change>
1.248 + <change>
1.249 + <api name="lookup"/>
1.250 + <summary>New method Lookups.proxy</summary>
1.251 + <version major="3" minor="9"/>
1.252 + <date day="20" month="9" year="2002"/>
1.253 + <author login="dstrupl"/>
1.254 + <compatibility addition="yes" binary="compatible" source="compatible" semantic="compatible" deprecation="no" deletion="no" modification="no"/>
1.255 + <description>
1.256 + Creates a lookup that delegates to another one but that one can change
1.257 + from time to time. The returned lookup checks every time somebody calls
1.258 + lookup or lookupItem method whether the provider still returns
1.259 + the same lookup. If not, it updates state of all Lookup.Results
1.260 + that it created (and that still exists).
1.261 + </description>
1.262 + <class package="org.openide.util.lookup" name="Lookups"/>
1.263 + <issue number="27425"/>
1.264 + </change>
1.265 + <change id="meta-inf-services">
1.266 + <api name="lookup"/>
1.267 + <summary>Modules can specify the content of Lookup.getDefault
1.268 + in META-INF/services</summary>
1.269 + <version major="3" minor="3"/>
1.270 + <date day="22" month="7" year="2002"/>
1.271 + <author login="jtulach"/>
1.272 + <compatibility addition="yes" binary="compatible" source="compatible" semantic="compatible" deprecation="no" deletion="no" modification="no"/>
1.273 + <description>
1.274 + The content of <code>Lookup.getDefault()</code> can be specified
1.275 + by a standard JDK registration mechanism, using JARs'
1.276 + <a href="http://java.sun.com/j2se/1.4/docs/guide/jar/jar.html#Service%20Provider" shape="rect">
1.277 + META-INF/services
1.278 + </a>
1.279 + directory. This is suitable for services that do not change,
1.280 + do not require user modification and that need to be ready
1.281 + soon during initialization of the system.
1.282 + </description>
1.283 + </change>
1.284 + <change>
1.285 + <api name="lookup"/>
1.286 + <summary>Added org.openide.util.lookup.Lookups</summary>
1.287 + <version major="2" minor="21"/>
1.288 + <date day="28" month="5" year="2002"/>
1.289 + <author login="dstrupl"/>
1.290 + <compatibility addition="yes" binary="compatible" source="compatible" semantic="compatible" deprecation="no" deletion="no" modification="no"/>
1.291 + <description>New utility class added. The class cannot be instantiated
1.292 + and contains following static methods:
1.293 + <pre xml:space="preserve">
1.294 +<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>);
1.295 +<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>);
1.296 +<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>);
1.297 +</pre>
1.298 + The methods return an instance of simple lookup implementation
1.299 + that holds the objects passed a parameter.
1.300 + </description>
1.301 + <class package="org.openide.util.lookup" name="Lookups"/>
1.302 + <issue number="20550"/>
1.303 + </change>
1.304 + <change id="AbstractLookup.Content-ProxyLookup.beforeLookup">
1.305 + <api name="lookup"/>
1.306 + <summary>Enhanced usage of ProxyLookup & AbstractLookup.Content</summary>
1.307 + <version major="1" minor="31"/>
1.308 + <date day="18" month="8" year="2001"/>
1.309 + <author login="jtulach"/>
1.310 + <compatibility addition="yes" binary="compatible" source="compatible" semantic="compatible" deprecation="no" deletion="no" modification="no"/>
1.311 + <description>
1.312 + <code>AbstractLookup.Content</code> made public to allow its usage
1.313 + for objects that do not subclass AbstractLookup. <code>ProxyLookup.beforeLookup</code>
1.314 + added so subclasses can update themselves (call setLookups (...)) before the actual lookup is
1.315 + performed.
1.316 + </description>
1.317 + <class package="org.openide.util.lookup" name="AbstractLookup"/>
1.318 + <class package="org.openide.util.lookup" name="ProxyLookup"/>
1.319 + </change>
1.320 + <change>
1.321 + <api name="lookup"/>
1.322 + <summary>Instance content simplifies creation of lookups</summary>
1.323 + <version major="1" minor="25"/>
1.324 + <!-- XXX date unknown -->
1.325 + <author login="jtulach"/>
1.326 + <compatibility addition="yes" binary="compatible" source="compatible" semantic="compatible" deprecation="no" deletion="no" modification="no"/>
1.327 + <description>
1.328 + Added <code>AbstractLookup.Content</code> which can be passed to an
1.329 + abstract lookup in its constructor and used to control the contents
1.330 + easily. Also <code>InstanceLookup</code> provides the common easy
1.331 + implementation.
1.332 + </description>
1.333 + <class package="org.openide.util.lookup" name="AbstractLookup"/>
1.334 + <class package="org.openide.util.lookup" name="InstanceContent"/>
1.335 + </change>
1.336 + <change>
1.337 + <api name="lookup"/>
1.338 + <summary>Folder lookup may be serialized</summary>
1.339 + <version major="3" minor="27"/>
1.340 + <date day="7" month="1" year="2003"/>
1.341 + <author login="jglick"/>
1.342 + <compatibility modification="yes" binary="compatible" source="compatible" semantic="compatible" deprecation="no" addition="no" deletion="no">
1.343 + Modules which rely on a data object under <samp>Services/</samp> gaining
1.344 + or losing <code>InstanceCookie</code> between sessions may not work
1.345 + correctly with the cache. This is probably very rare.
1.346 + </compatibility>
1.347 + <description>
1.348 + To implement lookup caching, some lookup implementations are now
1.349 + serializable: <code>AbstractLookup</code> as well as
1.350 + <code>FolderLookup</code>'s lookup. <code>ProxyLookup</code> has a
1.351 + protected subclass constructor permitting subclasses to be serializable.
1.352 + </description>
1.353 + <class package="org.openide.util.lookup" name="AbstractLookup"/>
1.354 + <class package="org.openide.util.lookup" name="ProxyLookup"/>
1.355 + <issue number="20190"/>
1.356 + </change>
1.357 + <change>
1.358 + <api name="lookup"/>
1.359 + <summary>Changes in access protection of proxy lookup</summary>
1.360 + <version major="1" minor="19"/>
1.361 + <date day="8" month="7" year="2001"/>
1.362 + <compatibility modification="yes" binary="compatible" source="compatible" semantic="compatible" deprecation="no" addition="no" deletion="no">
1.363 + Changes to newly added feature.
1.364 + </compatibility>
1.365 + <description>
1.366 + <code>ProxyLookup.setLookups</code> made protected instead of public so
1.367 + nobody can misuse the method except the creator of the object and
1.368 + <code>ProxyLookup.getLookups</code> added. <code>ProxyLookup</code> made
1.369 + non final.
1.370 + </description>
1.371 + <class package="org.openide.util.lookup" name="ProxyLookup"/>
1.372 + </change>
1.373 + <change>
1.374 + <api name="lookup"/>
1.375 + <summary>Lookup service providers package created</summary>
1.376 + <version major="1" minor="9"/>
1.377 + <date day="1" month="6" year="2001"/>
1.378 + <author login="jtulach"/>
1.379 + <compatibility addition="yes" binary="compatible" source="compatible" semantic="compatible" deprecation="no" deletion="no" modification="no"/>
1.380 + <description>
1.381 + Package <code>org.openide.util.lookup</code> created, should hold SPI
1.382 + interfaces for lookup. Initially filled with <code>AbstractLookup</code>
1.383 + which introduces <code>AbstractLookup.Pair</code> and with
1.384 + <code>ProxyLookup</code>.
1.385 + </description>
1.386 + <class package="org.openide.util.lookup" name="AbstractLookup"/>
1.387 + <class package="org.openide.util.lookup" name="ProxyLookup"/>
1.388 + <package name="org.openide.util.lookup"/>
1.389 + </change>
1.390 + <change>
1.391 + <api name="lookup"/>
1.392 + <summary>Added lookup items and support APIs</summary>
1.393 + <version major="1" minor="8"/>
1.394 + <date day="25" month="5" year="2001"/>
1.395 + <author login="jtulach"/>
1.396 + <compatibility addition="yes" binary="compatible" source="compatible" semantic="compatible" deprecation="no" deletion="no" modification="no"/>
1.397 + <description>
1.398 + <code>Lookup</code> enhanced. Interface <code>Lookup.Item</code> and
1.399 + additional methods to access it also added.
1.400 + </description>
1.401 + <class package="org.openide.util" name="Lookup"/>
1.402 + </change>
1.403 + <change>
1.404 + <api name="lookup"/>
1.405 + <summary>Lookup system introduced</summary>
1.406 + <date day="1" month="3" year="2001"/>
1.407 + <author login="jtulach"/>
1.408 + <compatibility addition="yes" binary="compatible" source="compatible" semantic="compatible" deprecation="no" deletion="no" modification="no"/>
1.409 + <description>
1.410 + Better version of <code>Lookup</code> introduced. There is a
1.411 + <code>org.openide.util.Lookup</code> with bunch of inner classes and
1.412 + <code>org.openide.util.LookupListener</code> and
1.413 + <code>org.openide.util.LookupEvent</code>.
1.414 + </description>
1.415 + <class package="org.openide.util" name="Lookup"/>
1.416 + <class package="org.openide.util" name="LookupEvent"/>
1.417 + <class package="org.openide.util" name="LookupListener"/>
1.418 + </change>
1.419 +</changes>
1.420 +<htmlcontents>
1.421 +<head>
1.422 +<title>Change History for the Lookup API</title>
1.423 +<link rel="stylesheet" href="prose.css" type="text/css"/>
1.424 +</head>
1.425 +<body>
1.426 +<p class="overviewlink">
1.427 +<a href="overview-summary.html">Overview</a>
1.428 +</p>
1.429 +<h1>Introduction</h1>
1.430 +<h2>What do the Dates Mean?</h2>
1.431 +<p>The supplied dates indicate when the API change was made, on the CVS
1.432 +trunk. From this you can generally tell whether the change should be
1.433 +present in a given build or not; for trunk builds, simply whether it
1.434 +was made before or after the change; for builds on a stabilization
1.435 +branch, whether the branch was made before or after the given date. In
1.436 +some cases corresponding API changes have been made both in the trunk
1.437 +and in an in-progress stabilization branch, if they were needed for a
1.438 +bug fix; this ought to be marked in this list.</p>
1.439 +<ul>
1.440 +<li>The <code>release41</code> branch was made on Apr 03 '05 for use in the NetBeans 4.1 release.
1.441 +Specification versions: 6.0 begins after this point.</li>
1.442 +<li>The <code>release40</code> branch was made on Nov 01 '04 for use in the NetBeans 4.0 release.
1.443 +Specification versions: 5.0 begins after this point.</li>
1.444 +</ul>
1.445 +<hr/>
1.446 +<standard-changelists module-code-name="$codebase"/>
1.447 +<hr/>
1.448 +<p>@FOOTER@</p>
1.449 +</body>
1.450 +</htmlcontents>
1.451 +</apichanges>
2.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
2.2 +++ b/openide.util.lookup/arch.xml Mon Dec 14 19:10:02 2009 +0100
2.3 @@ -0,0 +1,1064 @@
2.4 +<?xml version="1.0" encoding="UTF-8"?>
2.5 +<!--
2.6 +DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
2.7 +
2.8 +Copyright 1997-2009 Sun Microsystems, Inc. All rights reserved.
2.9 +
2.10 +
2.11 +The contents of this file are subject to the terms of either the GNU
2.12 +General Public License Version 2 only ("GPL") or the Common
2.13 +Development and Distribution License("CDDL") (collectively, the
2.14 +"License"). You may not use this file except in compliance with the
2.15 +License. You can obtain a copy of the License at
2.16 +http://www.netbeans.org/cddl-gplv2.html
2.17 +or nbbuild/licenses/CDDL-GPL-2-CP. See the License for the
2.18 +specific language governing permissions and limitations under the
2.19 +License. When distributing the software, include this License Header
2.20 +Notice in each file and include the License file at
2.21 +nbbuild/licenses/CDDL-GPL-2-CP. Sun designates this
2.22 +particular file as subject to the "Classpath" exception as provided
2.23 +by Sun in the GPL Version 2 section of the License file that
2.24 +accompanied this code. If applicable, add the following below the
2.25 +License Header, with the fields enclosed by brackets [] replaced by
2.26 +your own identifying information:
2.27 +"Portions Copyrighted [year] [name of copyright owner]"
2.28 +
2.29 +Contributor(s):
2.30 +
2.31 +The Original Software is NetBeans. The Initial Developer of the Original
2.32 +Software is Sun Microsystems, Inc. Portions Copyright 1997-2006 Sun
2.33 +Microsystems, Inc. All Rights Reserved.
2.34 +
2.35 +If you wish your version of this file to be governed by only the CDDL
2.36 +or only the GPL Version 2, indicate your decision by adding
2.37 +"[Contributor] elects to include this software in this distribution
2.38 +under the [CDDL or GPL Version 2] license." If you do not indicate a
2.39 +single choice of license, a recipient has the option to distribute
2.40 +your version of this file under either the CDDL, the GPL Version 2 or
2.41 +to extend the choice of license to its licensees as provided above.
2.42 +However, if you add GPL Version 2 code and therefore, elected the GPL
2.43 +Version 2 license, then the option applies only if the new code is
2.44 +made subject to such option by the copyright holder.
2.45 +-->
2.46 +<!DOCTYPE api-answers PUBLIC "-//NetBeans//DTD Arch Answers//EN" "../nbbuild/antsrc/org/netbeans/nbbuild/Arch.dtd" [
2.47 + <!ENTITY api-questions SYSTEM "../nbbuild/antsrc/org/netbeans/nbbuild/Arch-api-questions.xml">
2.48 +]>
2.49 +
2.50 +<api-answers
2.51 + question-version="1.25"
2.52 + author="jtulach@netbeans.org"
2.53 +>
2.54 +
2.55 + &api-questions;
2.56 +
2.57 + <answer id="arch-overall">
2.58 + <p>
2.59 + This module contains general classes needed in NetBeans, extensions to
2.60 + basic JRE contepts, useful methods and other
2.61 + <api group="java" name="UtilitiesAPI" category="official" type="export" url="@TOP@/org/openide/util/doc-files/api.html" />
2.62 + classes.
2.63 + </p>
2.64 +
2.65 + <p>
2.66 + Also this module defines the <a href="@TOP@/org/openide/util/Lookup.html">
2.67 + Lookup</a> which the NetBeans way for dynamic registration
2.68 + and lookup of
2.69 + components in our modularized component system. It allows lookup and discovery
2.70 + of features by description of their interfaces. The classes are devided
2.71 + into two parts. The
2.72 + <api group="java" name="LookupAPI" type="export" category="official" url="@TOP@/org/openide/util/lookup/doc-files/lookup-api.html">
2.73 + allows the discovery</api> and the
2.74 + <api group="java" name="LookupSPI" type="export" category="official" url="@TOP@/org/openide/util/lookup/doc-files/lookup-spi.html">
2.75 + simplifies creation and registration of own lookup objects</api>.
2.76 + </p>
2.77 + </answer>
2.78 +
2.79 +
2.80 + <answer id="arch-quality">
2.81 + <p>
2.82 + There is a lot of unit tests in
2.83 + <a href="http://www.netbeans.org/source/browse/openide/util/test/unit/src/">CVS</a>.
2.84 + </p>
2.85 + </answer>
2.86 +
2.87 + <answer id="arch-time">
2.88 + <p>
2.89 + The module has been around since 1997 and is stilly improved
2.90 + from time to time.
2.91 + </p>
2.92 + </answer>
2.93 +
2.94 +
2.95 +
2.96 + <answer id="arch-usecases">
2.97 +
2.98 + There is a great introduction to Lookup and its usage in its
2.99 + <a href="@TOP@/org/openide/util/Lookup.html">javadoc</a>. Here is just
2.100 + a list of frequently asked or interesting questions slowly expanding as
2.101 + people ask them:
2.102 +
2.103 + <h3>Lookup faq:</h3>
2.104 +
2.105 + <usecase id="lookup-on-certain-platform" name="How to specify that a service in Lookup should be available only on Windows?" >
2.106 +<em><b>Q:</b>
2.107 +Most of the time I specify interfaces that I want to add to the Lookup class in the layer.xml file.
2.108 +But, let's say I have a platform-specific interface (something on Windows only, for instance).</em>
2.109 +<p>
2.110 +<em>
2.111 +How can I specify (in the xml, or programmatically) that this service should only be added to the Lookup if the platform is Windows?
2.112 +</em>>
2.113 +</p>
2.114 +In general there are three ways to achieve this.
2.115 +<ul>
2.116 + <li><p>It is possible to write a specific module and enable it only on windows.
2.117 + See <a href="@org-openide-modules@/org/openide/modules/doc-files/api.html#how-os-specific">os specific modules</a> documentation.
2.118 + Then you can put a registration of your instance into your module's
2.119 + <a href="@TOP@/org/openide/util/doc-files/api.html#service-lookup">META-INF/services</a> directory and it
2.120 + will be available only on Windows.</p>
2.121 + </li>
2.122 +
2.123 + <li><p>Another possibility that does not require new module, but which executes
2.124 + a code on startup (which may have performance implications) is to use <code>methodvalue</code>
2.125 + attribute. Register your instance in layer using <code>your-Object.instance</code> file
2.126 + as described at
2.127 + <a href="@TOP@/org/openide/util/doc-files/api.html#ido-methodvalue">services
2.128 + </a> documentation and in your factory method either return the instance
2.129 + your want or <code>null</code> depending on result of <a href="@TOP@/org/openide/util/Utilities.html#isWindows()">
2.130 + Utilities.isWindows()</a> call.</p>
2.131 + </li>
2.132 + <li>
2.133 + <p>
2.134 + In some cases, the interface for which you will register an implementation permits a
2.135 + no-operation semantics. For example, <code>InstalledFileLocator.locate(...)</code> can
2.136 + return a valid <code>File</code>, or null. You could always register an
2.137 + <code>InstalledFileLocator</code> instance yet disable it on non-Windows platforms
2.138 + (always returning null).
2.139 + </p>
2.140 + </li>
2.141 +</ul>
2.142 +
2.143 + </usecase>
2.144 +
2.145 + <usecase id="lookup-extension-point" name="How shall I write an extension point for my module?" >
2.146 + <p>
2.147 + <em><b>Q:</b>
2.148 + I have more modules one of them providing the core functionality and
2.149 + few more that wish to extend it. What is the right way to do it?
2.150 + How does the Netbeans platform declare such extension point?
2.151 + </em>
2.152 + </p>
2.153 +
2.154 + <p>
2.155 +
2.156 + Start with declaring an extension interface in your
2.157 + core module and put it into the module's <em>public packages</em>. Imagine
2.158 + for example that the core module is in JAR file <code>org-my-netbeans-coremodule.jar</code>
2.159 + and already contains in manifests line like
2.160 + <code>OpenIDE-Module: org.my.netbeans.coremodule/1</code> and wants
2.161 + to display various tips of the day provided by other modules and thus defines:
2.162 + </p><pre>
2.163 +<span class="java-keywords">package</span> <span class="java-identifier">org</span><span class="java-operators">.</span><span class="java-identifier">my</span><span class="java-operators">.</span><span class="java-identifier">netbeans</span><span class="java-operators">.</span><span class="java-identifier">coremodule</span><span class="java-operators">;</span>
2.164 +
2.165 +<span class="java-keywords">public</span> <span class="java-keywords">interface</span> <span class="java-identifier">TipsOfTheDayProvider</span> <span class="java-operators">{</span>
2.166 + <span class="java-keywords">public</span> <span class="java-identifier">String</span> <span class="java-layer-method">provideTipOfTheDay</span> <span class="java-operators">(</span><span class="java-operators">)</span><span class="java-operators">;</span>
2.167 +<span class="java-operators">}</span>
2.168 +</pre><p>
2.169 + And in its manifest adds line
2.170 + <code>OpenIDE-Module-Public-Packages: org.my.netbeans.coremodule.*</code>
2.171 + to specify that this package contains exported API and shall be
2.172 + accessible to other modules.
2.173 + </p>
2.174 + <p>
2.175 + When the core module is about to display the tip of the day it can ask
2.176 + the system for all registered instances of the <code>TipsOfTheDayProvider</code>,
2.177 + randomly select one of them:
2.178 + </p><pre>
2.179 +<span class="java-keywords">import</span> <span class="java-identifier">java</span><span class="java-operators">.</span><span class="java-identifier">util</span><span class="java-operators">.</span><span class="java-identifier">Collection</span><span class="java-operators">;</span>
2.180 +<span class="java-keywords">import</span> <span class="java-identifier">java</span><span class="java-operators">.</span><span class="java-identifier">util</span><span class="java-operators">.</span><span class="java-identifier">Collections</span><span class="java-operators">;</span>
2.181 +<span class="java-keywords">import</span> <span class="java-identifier">org</span><span class="java-operators">.</span><span class="java-identifier">openide</span><span class="java-operators">.</span><span class="java-identifier">util</span><span class="java-operators">.</span><span class="java-identifier">Lookup</span><span class="java-operators">;</span>
2.182 +
2.183 +<a href="@TOP@org/openide/util/Lookup.Result.html"><span class="java-identifier">Lookup</span><span class="java-operators">.</span><span class="java-identifier">Result</span></a> <span class="java-identifier">result</span> <span class="java-operators">=</span> <a href="@TOP@org/openide/util/Lookup.html"><span class="java-identifier">Lookup</span></a><span class="java-operators">.</span><span class="java-layer-method">getDefault</span> <span class="java-operators">(</span><span class="java-operators">)</span><span class="java-operators">.</span><span class="java-layer-method">lookup</span> <span class="java-operators">(</span><span class="java-keywords">new</span> <a href="@TOP@org/openide/util/Lookup.Template.html"><span class="java-identifier">Lookup</span><span class="java-operators">.</span><span class="java-layer-method">Template</span></a> <span class="java-operators">(</span><span class="java-identifier">TipsOfTheDayProvider</span><span class="java-operators">.</span><span class="java-keywords">class</span><span class="java-operators">)</span><span class="java-operators">)</span><span class="java-operators">;</span>
2.184 +<span class="java-identifier">Collection</span> <span class="java-identifier">c</span> <span class="java-operators">=</span> <span class="java-identifier">result</span><span class="java-operators">.</span><a href="@TOP@org/openide/util/Lookup.Result.html#allInstances()"><span class="java-layer-method">allInstances</span></a> <span class="java-operators">(</span><span class="java-operators">)</span><span class="java-operators">;</span>
2.185 +<span class="java-identifier">Collections</span><span class="java-operators">.</span><span class="java-layer-method">shuffle</span> <span class="java-operators">(</span><span class="java-identifier">c</span><span class="java-operators">)</span><span class="java-operators">;</span>
2.186 +<span class="java-identifier">TipsOfTheDayProvider</span> <span class="java-identifier">selected</span> <span class="java-operators">=</span> <span class="java-operators">(</span><span class="java-identifier">TipsOfTheDayProvider</span><span class="java-operators">)</span><span class="java-identifier">c</span><span class="java-operators">.</span><span class="java-layer-method">iterator</span> <span class="java-operators">(</span><span class="java-operators">)</span><span class="java-operators">.</span><span class="java-layer-method">next</span> <span class="java-operators">(</span><span class="java-operators">)</span><span class="java-operators">;</span>
2.187 +</pre><p>
2.188 + and then display the tip. Simple, trivial, just by the usage of
2.189 + <a href="@TOP@org/openide/util/Lookup.html">Lookup</a> interface once
2.190 + creates a registry that other modules can enhance. But such enhancing
2.191 + of course requires work on the other side. Each module that would like
2.192 + to register its <code>TipsOfTheDayProvider</code> needs to depend on the
2.193 + core module - add
2.194 + <code>OpenIDE-Module-Module-Dependencies: org.my.netbeans.coremodule/1</code>
2.195 + into its manifest and write a class with its own implementation of the
2.196 + provider:</p><pre>
2.197 +<span class="java-keywords">package</span> <span class="java-identifier">org</span><span class="java-operators">.</span><span class="java-identifier">my</span><span class="java-operators">.</span><span class="java-identifier">netbeans</span><span class="java-operators">.</span><span class="java-identifier">extramodule</span><span class="java-operators">;</span>
2.198 +
2.199 +<span class="java-keywords">class</span> <span class="java-identifier">ExtraTip</span> <span class="java-keywords">implements</span> <span class="java-identifier">TipsOfTheDayProvider</span> <span class="java-operators">{</span>
2.200 + <span class="java-keywords">public</span> <span class="java-identifier">String</span> <span class="java-layer-method">provideTipOfTheDay</span> <span class="java-operators">(</span><span class="java-operators">)</span> <span class="java-operators">{</span>
2.201 + <span class="java-keywords">return</span> <span class="java-string-literal">"Do you know that in order to write extension point you should use Lookup?"</span><span class="java-operators">;</span>
2.202 + <span class="java-operators">}</span>
2.203 +<span class="java-operators">}</span>
2.204 +</pre><p>
2.205 + Then, the only necessary thing is to register such class by using the
2.206 + J2SE standard <api name="ProviderRegistrationMechanism"
2.207 + type="import"
2.208 + category="standard"
2.209 + group="java" /> into plain text file
2.210 + <code>META-INF/services/org.my.netbeans.coremodule.TipsOfTheDayProvider</code>
2.211 + in the module JAR containing just one line: </p><pre>
2.212 +org.my.netbeans.extramodule.ExtraTip
2.213 +</pre><p>
2.214 + and your modules are now ready to communicate
2.215 + using your own <em>extension point</em>.
2.216 + </p>
2.217 +
2.218 + </usecase>
2.219 +
2.220 +
2.221 + <usecase id="logging" name="How shall I do or influence logging in NetBeans?">
2.222 + <p>
2.223 + If you are interested in logging from inside your module, or in writing
2.224 + your own log handler or in configuring the whole system, then best place
2.225 + to start is the <a href="@TOP@/org/openide/util/doc-files/logging.html">NetBeans logging guide</a>.
2.226 + </p>
2.227 + </usecase>
2.228 +
2.229 +
2.230 + </answer>
2.231 +
2.232 +
2.233 +
2.234 + <answer id="arch-what">
2.235 + <p>
2.236 + Described in the <a href="@TOP@/architecture-summary.html#answer-arch-overall">overall</a> answer.
2.237 + </p>
2.238 + </answer>
2.239 +
2.240 +
2.241 +
2.242 + <answer id="compat-i18n">
2.243 + <p>
2.244 + There is not much things to localize in this module, so it is properly localized.
2.245 + But it is good to note that the module adds <api name="BrandingSupport" category="official" group="property" type="export" url="@TOP@/org/openide/util/NbBundle.html">
2.246 + which is similar to localization but also supports changes of resorces
2.247 + for application build on top of NetBeans. This is handled by our
2.248 + class <a href="@TOP@/org/openide/util/NbBundle.html">NbBundle</a> which
2.249 + reimplements the JDK's standard <a href="@JDK@/java/util/ResourceBundle.html">ResourceBundle</a>
2.250 + to to take branding into the consideration.
2.251 + </api>.
2.252 + </p>
2.253 + </answer>
2.254 +
2.255 +
2.256 +
2.257 + <answer id="compat-standards">
2.258 + <p>
2.259 + The default lookup registration follows the JDK's
2.260 + <api name="ProviderRegistrationMechanism"
2.261 + type="import"
2.262 + category="standard"
2.263 + url="http://java.sun.com/j2se/1.3/docs/guide/jar/jar.html#Provider%20Configuration%20File"
2.264 + group="java"
2.265 + />
2.266 + but enhances it to also support the
2.267 + <api
2.268 + name="ProviderRegistrationRemoval"
2.269 + type="export"
2.270 + category="devel"
2.271 + url="@TOP@/org/openide/util/doc-files/api.html#service-lookup"
2.272 + group="java"
2.273 + />.
2.274 + </p>
2.275 + </answer>
2.276 +
2.277 + <answer id="compat-version">
2.278 + <p>
2.279 + This module has no settings.
2.280 + </p>
2.281 + </answer>
2.282 +
2.283 +
2.284 +
2.285 + <answer id="dep-jre">
2.286 + <p>
2.287 + Currently JRE 1.4 is needed.
2.288 + </p>
2.289 + </answer>
2.290 +
2.291 +
2.292 +
2.293 + <answer id="dep-jrejdk">
2.294 + <p>
2.295 + JRE is enough.
2.296 + </p>
2.297 + </answer>
2.298 +
2.299 +
2.300 + <answer id="dep-nb">
2.301 + <p>
2.302 + This module is independent of other NetBeans modules and can be used
2.303 + independently. For better interaction with UI parts of NetBeans it however
2.304 + indirectly communicates with <a href="@org-openide-awt@/overview-summary.html">UI Utilities</a>
2.305 + module using <api name="AWTBridge" category="private" group="java" type="export"
2.306 + url="http://www.netbeans.org/source/browse/openide/util/src/org/netbeans/modules/openide/util/AWTBridge.java">
2.307 + a class that is looked up in <a href="@TOP@/org/openide/util/Lookup.html#getDefault()">Lookup.getDefault()</a>
2.308 + and if registered can provide better UI elements for <a href="@JDK@/javax/swing/Action.html">Action</a>s.
2.309 + </api>
2.310 +
2.311 + </p>
2.312 + </answer>
2.313 +
2.314 + <answer id="dep-non-nb">
2.315 + <p>
2.316 + Reexports XML APIs so needs some XML parser implementation, but as one
2.317 + is provided in any 1.4 java, it in fact has no dependencies except on JRE.
2.318 + </p>
2.319 + </answer>
2.320 +
2.321 + <answer id="dep-platform">
2.322 + <p>
2.323 + Platform independent.
2.324 + </p>
2.325 + </answer>
2.326 +
2.327 +
2.328 + <answer id="deploy-dependencies">
2.329 + <p>
2.330 + Nothing.
2.331 + </p>
2.332 + </answer>
2.333 +
2.334 +
2.335 +
2.336 + <answer id="deploy-jar">
2.337 + <p>
2.338 + <api category="devel" group="java.io.File" name="FileLocation" type="export" >
2.339 + the JAR file is located in platform cluster under <code>lib/org-openide-util.jar</code>
2.340 + </api>.
2.341 + </p>
2.342 + </answer>
2.343 +
2.344 +
2.345 +
2.346 + <answer id="deploy-nbm">
2.347 + <p>
2.348 + No reason to not deploy nbm.
2.349 + </p>
2.350 + </answer>
2.351 +
2.352 +
2.353 + <answer id="deploy-packages">
2.354 + <p>
2.355 + Yes, public packages declared.
2.356 + </p>
2.357 + </answer>
2.358 +
2.359 +
2.360 +
2.361 + <answer id="deploy-shared">
2.362 + <p>
2.363 + Module is on real java classpath and as such it has to be in the shared directory.
2.364 + </p>
2.365 + </answer>
2.366 +
2.367 +
2.368 + <answer id="exec-ant-tasks">
2.369 + <p>
2.370 + No.
2.371 + </p>
2.372 + </answer>
2.373 +
2.374 +
2.375 +
2.376 + <answer id="exec-classloader">
2.377 + <p>
2.378 + No, we do not create own classloader.
2.379 + </p>
2.380 + </answer>
2.381 +
2.382 +
2.383 +
2.384 +<!--
2.385 + <question id="exec-component" when="impl">
2.386 + Is execution of your code influenced by any (string) property
2.387 + of any of your components?
2.388 +
2.389 + <hint>
2.390 + Often <code>JComponent.getClientProperty</code>, <code>Action.getValue</code>
2.391 + or <code>PropertyDescriptor.getValue</code>, etc. are used to influence
2.392 + a behavior of some code. This of course forms an interface that should
2.393 + be documented. Also if one depends on some interface that an object
2.394 + implements (<code>component instanceof Runnable</code>) that forms an
2.395 + API as well.
2.396 + </hint>
2.397 + </question>
2.398 +-->
2.399 + <answer id="exec-component">
2.400 + <ul>
2.401 + <li><api name="HelpID" category="standard" group="property" type="export" url="@TOP@/org/openide/util/HelpCtx.html">
2.402 + read from <a href="@JDK@/javax/swing/JComponent.html">JComponent</a>.getClientProperty
2.403 + to simulate the standard javahelp behaviour and extract the help id for given component.
2.404 + </api>
2.405 + </li>
2.406 +
2.407 + <li><api name="iconBase" category="standard" group="property" type="import" >
2.408 + <a href="@TOP@/org/openide/util/actions/SystemAction.html">SystemAction</a>
2.409 + reacts to expected requests from <a href="@org-openide-awt@/overview-summary.html">UI Utilities</a>
2.410 + module for <code>iconBase</code> property by returning value based on its
2.411 + result of its <code>iconResource()</code> method.
2.412 + </api>
2.413 + </li>
2.414 +
2.415 + <li>
2.416 + <api name="org.openide.util.SharedClassObject.initialize" category="private" group="property" type="export">
2.417 + For purposes of
2.418 + <code>SystemOption</code>
2.419 + the
2.420 + <a href="@TOP@/org/openide/util/SharedClassObject.html">SharedClassObject</a>
2.421 + handles
2.422 + <code>getProperty ("org.openide.util.SharedClassObject.initialize")</code>
2.423 + in a special way, by returning
2.424 + <code>null</code> if initialization is not running and <code>Boolean.TRUE</code> if
2.425 + it is.
2.426 + </api>
2.427 + </li>
2.428 +
2.429 + <li><api name="OpenIDE-Transmodal-Action" category="devel" group="property" type="export" >
2.430 + <a href="@TOP@/org/openide/util/actions/CallbackSystemAction.html">CallbackSystemAction</a>
2.431 + checks whether <code>action.getValue("OpenIDE-Transmodal-Action")</code>
2.432 + returns <code>Boolean.TRUE</code> to enable it in dialogs, otherwise
2.433 + the action is disabled when there is an open dialog.
2.434 + </api>
2.435 + </li>
2.436 +
2.437 +
2.438 + </ul>
2.439 + </answer>
2.440 +
2.441 +
2.442 +
2.443 +<!--
2.444 + <question id="exec-introspection" when="impl">
2.445 + Does your module use any kind of runtime type information (<code>instanceof</code>,
2.446 + work with <code>java.lang.Class</code>, etc.)?
2.447 + <hint>
2.448 + Check for cases when you have an object of type A and you also
2.449 + expect it to (possibly) be of type B and do some special action. That
2.450 + should be documented. The same applies on operations in meta-level
2.451 + (Class.isInstance(...), Class.isAssignableFrom(...), etc.).
2.452 + </hint>
2.453 + </question>
2.454 +-->
2.455 + <answer id="exec-introspection">
2.456 + <p>
2.457 + <a href="@TOP@/org/openide/util/Utilities.html">Utilities</a> provide wrapper
2.458 + for java beans introspection. <api category="private" group="java" name="ParserFactory" type="import" >
2.459 + The <a href="@TOP@/org/openide/xml/XMLUtil.html">XMLUtil</a> class is loading
2.460 + a class from <code>core/core.jar</code> to initialize the correct parser factory.
2.461 + This is a fix for <a href="http://www.netbeans.org/issues/show_bug.cgi?id=68942">issue 68942</a>.
2.462 + </api>
2.463 + </p>
2.464 + </answer>
2.465 +
2.466 +
2.467 +
2.468 + <answer id="exec-privateaccess">
2.469 + <p>
2.470 + No.
2.471 + </p>
2.472 + </answer>
2.473 +
2.474 + <answer id="exec-process">
2.475 + <p>
2.476 + No external processes executed.
2.477 + </p>
2.478 + </answer>
2.479 +
2.480 +
2.481 + <answer id="exec-property">
2.482 + <ul>
2.483 + <li><api type="export" group="property" name="netbeans.screen.insets" category="private">
2.484 + Influences results of Utilities.getUsableScreenBounds</api>.</li>
2.485 + <li><api type="export" group="property" name="netbeans.taskbar.height" category="private">
2.486 + Influences results of Utilities.getUsableScreenBounds</api>.</li>
2.487 + <li>
2.488 + <api type='import' group="property" name="line.separator" category="standard" >
2.489 + used on few places
2.490 + </api>.
2.491 + </li>
2.492 +
2.493 + <li>
2.494 + <api type="export" group="property" name="org.openide.util.Lookup" category="devel">
2.495 + checked by the initialization of the
2.496 + <a href="@TOP@/org/openide/util/Lookup.html#getDefault()">Lookup.getDefault()</a>
2.497 + and can
2.498 + contain name of a class that extends <code>org.openide.util.Lookup</code> and
2.499 + has public constructor, that should be instantiated and returned from
2.500 + <a href="@TOP@/org/openide/util/Lookup.html#getDefault()">Lookup.getDefault()</a>
2.501 + the class will be loaded by
2.502 + <a href="@JDK@/java/lang/Thread.html#getContextClassLoader()">
2.503 + Thread.currentThread().getContextClassLoader()</a>
2.504 + classloader the first time <code>Lookup.getDefault</code> is invoked.
2.505 + <p/>
2.506 + The property can also contain value <code>"-"</code> which means to completely
2.507 + disable the lookup instantiation and return <a href="@TOP@/org/openide/util/Lookup.html#EMPTY">Lookup.EMPTY</a>
2.508 + from <a href="@TOP@/org/openide/util/Lookup.html#getDefault()">Lookup.getDefault()</a>.
2.509 + <p/>
2.510 + If the property is unspecified, the default <code>MetaInfServicesLookup</code>
2.511 + is constructed for <code>Thread.currentThread().getContextclassLoader()</code>
2.512 + that implements the <a href="architecture-summary.html#answer-compat-standards">JDK's standard</a>. If, by
2.513 + a chance an instance of
2.514 + <a href="@TOP@/org/openide/util/Lookup.Provider.html">Lookup.Provider</a>
2.515 + is found
2.516 + in there, its lookup is returned as result. Otherwise the <code>MetaInfServicesLookup</code>
2.517 + is the result of <a href="@TOP@/org/openide/util/Lookup.html#getDefault()">Lookup.getDefault()</a>.
2.518 + </api>
2.519 + </li>
2.520 +
2.521 + <li>
2.522 + <api type="export" group="property" name="org.openide.util.Lookup.paths" category="devel">
2.523 + Sometimes it may be useful for the Lookup to contains objects from
2.524 + some system file system folder. This can be done with
2.525 + <code>org.openide.util.Lookup.paths=Folder1:Folder2:Folder3</code>.
2.526 + If this property is set prior to first call to
2.527 + <a href="@TOP@/org/openide/util/Lookup.html#getDefault()">Lookup.getDefault()</a>,
2.528 + it is split into pieces (separator is <code>':'</code>) and individual
2.529 + parts are then used to construct <code>Lookups.forPath("Folder1")</code>,
2.530 + etc. All these lookups then become part of the
2.531 + <a href="@TOP@/org/openide/util/Lookup.html#getDefault()">Lookup.getDefault()</a>
2.532 + one. This property works since version 7.24
2.533 + </api>
2.534 + </li>
2.535 +
2.536 + </ul>
2.537 + </answer>
2.538 +
2.539 +
2.540 +
2.541 +<!--
2.542 + <question id="exec-reflection" when="impl">
2.543 + Does your code use Java Reflection to execute other code?
2.544 + <hint>
2.545 + This usually indicates a missing or insufficient API in the other
2.546 + part of the system. If the other side is not aware of your dependency
2.547 + this contract can be easily broken.
2.548 + </hint>
2.549 + </question>
2.550 +-->
2.551 + <answer id="exec-reflection">
2.552 + <p>
2.553 + <api category="devel" group="java" name="SharedClassObject.setAccessible" type="export" url="@TOP@/org/openide/util/SharedClassObject.html">
2.554 + used to instantiate subclasses.
2.555 + </api>.
2.556 + <api category="devel" group="java" name="WeakListener.setAccessible" type="export" url="@TOP@/org/openide/util/WeakListeners.html">
2.557 + used to call the remove method using reflection
2.558 + </api>.
2.559 + <api category="devel" group="java" name="Lookups.metaInfServices" type="export" url="@TOP@/org/openide/util/lookup/Lookups.html#metaInfServices(java.lang.ClassLoader)">
2.560 + calls constructor of registered classes using reflection
2.561 + </api>.
2.562 + <api category="private" group="lookup" name="ActionManagerInvocation" type="export" >
2.563 + because of the API separation, <a href="@TOP@/org/openide/util/actions/CallableSystemAction.html">CallableSystemAction</a> uses lookup for <code>ActionsBridge</code>
2.564 + provided by <code>org-openide-actions</code> module
2.565 + when looking for <a href="@org-openide-actions@/org/openide/actions/ActionManager.html">org.openide.actions.ActionManager</a> implementation.
2.566 + </api>.
2.567 + <api category="friend" group="java" name="Lookup.resetDefaultLookup" type="export">
2.568 + There is a static private method <code>Lookup.resetDefaultLookup</code> that
2.569 + is called by NbJUnit's <code>MockServices</code> to properly reset default
2.570 + lookup and fire changes to all registred listeners.
2.571 + </api>.
2.572 +
2.573 + </p>
2.574 + </answer>
2.575 +
2.576 +
2.577 +
2.578 +<!--
2.579 + <question id="exec-threading" when="impl">
2.580 + What threading models, if any, does your module adhere to?
2.581 + <hint>
2.582 + If your module calls foreign APIs which have a specific threading model,
2.583 + indicate how you comply with the requirements for multithreaded access
2.584 + (synchronization, mutexes, etc.) applicable to those APIs.
2.585 + If your module defines any APIs, or has complex internal structures
2.586 + that might be used from multiple threads, declare how you protect
2.587 + data against concurrent access, race conditions, deadlocks, etc.,
2.588 + and whether such rules are enforced by runtime warnings, errors, assertions, etc.
2.589 + Examples: a class might be non-thread-safe (like Java Collections); might
2.590 + be fully thread-safe (internal locking); might require access through a mutex
2.591 + (and may or may not automatically acquire that mutex on behalf of a client method);
2.592 + might be able to run only in the event queue; etc.
2.593 + Also describe when any events are fired: synchronously, asynchronously, etc.
2.594 + Ideas: <a href="http://core.netbeans.org/proposals/threading/index.html#recommendations">Threading Recommendations</a> (in progress)
2.595 + </hint>
2.596 + </question>
2.597 +-->
2.598 + <answer id="exec-threading">
2.599 + <p>
2.600 + XXX no answer for exec-threading
2.601 + </p>
2.602 + </answer>
2.603 +
2.604 +
2.605 +
2.606 + <answer id="format-clipboard">
2.607 + <p>
2.608 + <a href="@TOP@/org/openide/util/datatransfer/MultiTransferObject.html">MultiTransferObject</a> can be
2.609 + used in <a href="@JDK@/java/awt/datatransfer/Transferable.html">Transferable</a> to represent content
2.610 + composed of multiple independent
2.611 + <a href="@JDK@/java/awt/datatransfer/Transferable.html">Transferable</a>s.
2.612 + </p>
2.613 + </answer>
2.614 +
2.615 +
2.616 +
2.617 + <answer id="format-dnd">
2.618 + <p>
2.619 + The same as for clipboard.
2.620 + </p>
2.621 + </answer>
2.622 +
2.623 + <answer id="format-types">
2.624 + <p>
2.625 + The <a href="http://java.sun.com/j2se/1.3/docs/guide/jar/jar.html#Provider%20Configuration%20File">META-INF/services/...</a> files.
2.626 + <api name="TranslateNames" category="official" type="export" group="java.io.File"
2.627 + url="@TOP@/org/openide/util/Utilities.html#translate(java.lang.String)">
2.628 + <a href="@TOP@/org/openide/util/Utilities.html#translate(java.lang.String)">Utilities.translate</a>
2.629 + reads <code>META-INF/netbeans/translate.names</code> files from JARs</api>.
2.630 + </p>
2.631 + </answer>
2.632 +
2.633 +
2.634 +
2.635 + <answer id="lookup-lookup">
2.636 + <ul>
2.637 + <li><api name="LookupInitializationLookup" category="devel" group="lookup" type="export" url="#property-org.openide.util.Lookup">
2.638 + during
2.639 + initialization of the <a href="@TOP@/org/openide/util/Lookup.html#getDefault()">Lookup.getDefault()</a>
2.640 + the <a href="@TOP@/org/openide/util/Lookup.Provider.html">Lookup.Provider</a>
2.641 + is being searched</api>.
2.642 + </li>
2.643 +
2.644 + <li><api name="LookupSharedClassObject" category="devel" group="lookup" type="export">
2.645 + singleton subclasses of <a href="@TOP@/org/openide/util/SharedClassObject.html">SharedClassObject</a>
2.646 + are searched for using Lookup.
2.647 + </api>.</li>
2.648 +
2.649 + <li><api name="LookupContextGlobalProvider" category="stable" group="lookup" type="export">
2.650 + <a href="@TOP@/org/openide/util/Utilities.html#actionsGlobalContext()">actionsGlobalContext</a>
2.651 + searches for <a href="@TOP@/org/openide/util/ContextGlobalProvider.html">ContextGlobalProvider</a> in
2.652 + <a href="@TOP@/org/openide/util/Lookup.html#getDefault()">Lookup.getDefault()</a>.
2.653 + The provider is usually provided by <a href="@org-openide-windows@/overview-summary.html">window
2.654 + system implementation</a>.
2.655 + </api>.</li>
2.656 +
2.657 + <li><api name="LookupEntityCatalog" category="devel" group="lookup" type="export">
2.658 + <a href="@TOP@/org/openide/xml/EntityCatalog.html">EntityCatalog</a>
2.659 + delegates its methods to all instances of <a href="@TOP@/org/openide/xml/EntityCatalog.html">EntityCatalog</a>s
2.660 + found in Lookup
2.661 + </api>.</li>
2.662 +
2.663 + <li><api name="LookupErrorManager" category="devel" group="lookup" type="export">
2.664 + <a href="@TOP@/org/openide/ErrorManager.html">ErrorManager</a>
2.665 + delegates its methods to all instances of <a href="@TOP@/org/openide/ErrorManager.html">ErrorManager</a>s
2.666 + found in Lookup
2.667 + </api>.</li>
2.668 +
2.669 + <li><api name="LookupClassLoader" category="devel" group="lookup" type="export">
2.670 + Nearly all resource looking functions and reflective code
2.671 + uses <a href="@JDK@/java/lang/ClassLoader.html">ClassLoader</a>
2.672 + obtained from <a href="@TOP@/org/openide/util/Lookup.html#getDefault()">Lookup.getDefault()</a>
2.673 + for loading system wide resources.
2.674 + </api>.</li>
2.675 +
2.676 + </ul>
2.677 + </answer>
2.678 +
2.679 +
2.680 +
2.681 +<!--
2.682 + <question id="lookup-register" when="final">
2.683 + Do you register anything into lookup for other code to find?
2.684 + <hint>
2.685 + Do you register using layer file or using <code>META-INF/services</code>?
2.686 + Who is supposed to find your component?
2.687 + </hint>
2.688 + </question>
2.689 +-->
2.690 + <answer id="lookup-register">
2.691 + <p>
2.692 + No.
2.693 + </p>
2.694 + </answer>
2.695 +
2.696 +
2.697 +
2.698 +<!--
2.699 + <question id="lookup-remove" when="final">
2.700 + Do you remove entries of other modules from lookup?
2.701 + <hint>
2.702 + Why? Of course, that is possible, but it can be dangerous. Is the module
2.703 + your are masking resource from aware of what you are doing?
2.704 + </hint>
2.705 + </question>
2.706 +-->
2.707 + <answer id="lookup-remove">
2.708 + <p>
2.709 + No.
2.710 + </p>
2.711 + </answer>
2.712 +
2.713 +
2.714 +
2.715 +<!--
2.716 + <question id="perf-exit" when="final">
2.717 + Does your module run any code on exit?
2.718 + </question>
2.719 +-->
2.720 + <answer id="perf-exit">
2.721 + <p>
2.722 + Nothing.
2.723 + </p>
2.724 + </answer>
2.725 +
2.726 +
2.727 +
2.728 +<!--
2.729 + <question id="perf-huge_dialogs" when="final">
2.730 + Does your module contain any dialogs or wizards with a large number of
2.731 + GUI controls such as combo boxes, lists, trees, or text areas?
2.732 + </question>
2.733 +-->
2.734 + <answer id="perf-huge_dialogs">
2.735 + <p>
2.736 + No.
2.737 + </p>
2.738 + </answer>
2.739 +
2.740 +
2.741 +
2.742 +<!--
2.743 + <question id="perf-limit" when="init">
2.744 + Are there any hard-coded or practical limits in the number or size of
2.745 + elements your code can handle?
2.746 + </question>
2.747 +-->
2.748 + <answer id="perf-limit">
2.749 + <p>
2.750 + The default implementation of the <code>MetaInfServicesLookup</code> just
2.751 + keeps hashmap between queried classes and their implementations. The amount
2.752 + of memory is linear to amount of registered classes, but of course we
2.753 + are not counting the memory occupied by the instances which the lookup
2.754 + creates, that can be arbitrary.
2.755 + </p>
2.756 + </answer>
2.757 +
2.758 +
2.759 +
2.760 +<!--
2.761 + <question id="perf-mem" when="final">
2.762 + How much memory does your component consume? Estimate
2.763 + with a relation to the number of windows, etc.
2.764 + </question>
2.765 +-->
2.766 + <answer id="perf-mem">
2.767 + <p>
2.768 + There are no big data structures. The amount of memory occupied by
2.769 + instances of <a href="@TOP@/org/openide/util/lookup/AbstractLookup.html">AbstractLookup</a>
2.770 + is measured by unit tests.
2.771 + </p>
2.772 + </answer>
2.773 +
2.774 +
2.775 +
2.776 +<!--
2.777 + <question id="perf-menus" when="final">
2.778 + Does your module use dynamically updated context menus, or
2.779 + context-sensitive actions with complicated and slow enablement logic?
2.780 + <hint>
2.781 + If you do a lot of tricks when adding actions to regular or context menus, you can significantly
2.782 + slow down display of the menu, even when the user is not using your action. Pay attention to
2.783 + actions you add to the main menu bar, and to context menus of foreign nodes or components. If
2.784 + the action is conditionally enabled, or changes its display dynamically, you need to check the
2.785 + impact on performance. In some cases it may be more appropriate to make a simple action that is
2.786 + always enabled but does more detailed checks in a dialog if it is actually run.
2.787 + </hint>
2.788 + </question>
2.789 +-->
2.790 + <answer id="perf-menus">
2.791 + <p>
2.792 + There are no menus.
2.793 + </p>
2.794 + </answer>
2.795 +
2.796 +
2.797 +
2.798 +<!--
2.799 + <question id="perf-progress" when="final">
2.800 + Does your module execute any long-running tasks?
2.801 +
2.802 + <hint>Long running tasks should never block
2.803 + AWT thread as it badly hurts the UI
2.804 + <a href="http://performance.netbeans.org/responsiveness/issues.html">
2.805 + responsiveness</a>.
2.806 + Tasks like connecting over
2.807 + network, computing huge amount of data, compilation
2.808 + be done asynchronously (for example
2.809 + using <code>RequestProcessor</code>), definitively it should
2.810 + not block AWT thread.
2.811 + </hint>
2.812 + </question>
2.813 +-->
2.814 + <answer id="perf-progress">
2.815 + <p>
2.816 + Actions declared as <a href="@TOP@/org/openide/util/actions/CallableSystemAction.html#asynchronous()">CallableSystemAction.asynchronous()</a>
2.817 + are executed outside of AWT thread on a dedicated request processor one.
2.818 + </p>
2.819 + </answer>
2.820 +
2.821 +
2.822 +
2.823 +<!--
2.824 + <question id="perf-scale" when="init">
2.825 + Which external criteria influence the performance of your
2.826 + program (size of file in editor, number of files in menu,
2.827 + in source directory, etc.) and how well your code scales?
2.828 + <hint>
2.829 + Please include some estimates, there are other more detailed
2.830 + questions to answer in later phases of implementation.
2.831 + </hint>
2.832 + </question>
2.833 +-->
2.834 + <answer id="perf-scale">
2.835 + <p>
2.836 + Lookup code scales linearily.
2.837 + </p>
2.838 + </answer>
2.839 +
2.840 +
2.841 +
2.842 +<!--
2.843 + <question id="perf-spi" when="init">
2.844 + How the performance of the plugged in code will be enforced?
2.845 + <hint>
2.846 + If you allow foreign code to be plugged into your own module, how
2.847 + do you enforce that it will behave correctly and quickly and will not
2.848 + negatively influence the performance of your own module?
2.849 + </hint>
2.850 + </question>
2.851 +-->
2.852 + <answer id="perf-spi">
2.853 + <p>
2.854 + No enforcing is done.
2.855 + </p>
2.856 + </answer>
2.857 +
2.858 +
2.859 +
2.860 +<!--
2.861 + <question id="perf-startup" when="final">
2.862 + Does your module run any code on startup?
2.863 + </question>
2.864 +-->
2.865 + <answer id="perf-startup">
2.866 + <p>
2.867 + No.
2.868 + </p>
2.869 + </answer>
2.870 +
2.871 +
2.872 +
2.873 +<!--
2.874 + <question id="perf-wakeup" when="final">
2.875 + Does any piece of your code wake up periodically and do something
2.876 + even when the system is otherwise idle (no user interaction)?
2.877 + </question>
2.878 +-->
2.879 + <answer id="perf-wakeup">
2.880 + <p>
2.881 + No.
2.882 + </p>
2.883 + </answer>
2.884 +
2.885 +
2.886 +
2.887 +<!--
2.888 + <question id="resources-file" when="final">
2.889 + Does your module use <code>java.io.File</code> directly?
2.890 +
2.891 + <hint>
2.892 + NetBeans provide a logical wrapper over plain files called
2.893 + <code>org.openide.filesystems.FileObject</code> that
2.894 + provides uniform access to such resources and is the preferred
2.895 + way that should be used. But of course there can be situations when
2.896 + this is not suitable.
2.897 + </hint>
2.898 + </question>
2.899 +-->
2.900 + <answer id="resources-file">
2.901 + <p>
2.902 + No.
2.903 + </p>
2.904 + </answer>
2.905 +
2.906 +
2.907 +
2.908 +<!--
2.909 + <question id="resources-layer" when="final">
2.910 + Does your module provide own layer? Does it create any files or
2.911 + folders in it? What it is trying to communicate by that and with which
2.912 + components?
2.913 +
2.914 + <hint>
2.915 + NetBeans allows automatic and declarative installation of resources
2.916 + by module layers. Module register files into appropriate places
2.917 + and other components use that information to perform their task
2.918 + (build menu, toolbar, window layout, list of templates, set of
2.919 + options, etc.).
2.920 + </hint>
2.921 + </question>
2.922 +-->
2.923 + <answer id="resources-layer">
2.924 + <p>
2.925 + No.
2.926 + </p>
2.927 + </answer>
2.928 +
2.929 +
2.930 +
2.931 +<!--
2.932 + <question id="resources-mask" when="final">
2.933 + Does your module mask/hide/override any resources provided by other modules in
2.934 + their layers?
2.935 +
2.936 + <hint>
2.937 + If you mask a file provided by another module, you probably depend
2.938 + on that and do not want the other module to (for example) change
2.939 + the file's name. That module shall thus make that file available as an API
2.940 + of some stability category.
2.941 + </hint>
2.942 + </question>
2.943 +-->
2.944 + <answer id="resources-mask">
2.945 + <p>
2.946 + No.
2.947 + </p>
2.948 + </answer>
2.949 +
2.950 +
2.951 +
2.952 +<!--
2.953 + <question id="resources-read" when="final">
2.954 + Does your module read any resources from layers? For what purpose?
2.955 +
2.956 + <hint>
2.957 + As this is some kind of intermodule dependency, it is a kind of API.
2.958 + Please describe it and classify according to
2.959 + <a href="http://openide.netbeans.org/tutorial/api-design.html#categories">
2.960 + common stability categories</a>.
2.961 + </hint>
2.962 + </question>
2.963 +-->
2.964 + <answer id="resources-read">
2.965 + <p>
2.966 + No.
2.967 + </p>
2.968 + </answer>
2.969 +
2.970 +
2.971 +
2.972 +<!--
2.973 + <question id="security-grant" when="final">
2.974 + Does your code grant additional rights to some other code?
2.975 + <hint>Avoid using a class loader that adds extra
2.976 + permissions to loaded code unless really necessary.
2.977 + Also note that your API implementation
2.978 + can also expose unneeded permissions to enemy code by
2.979 + calling AccessController.doPrivileged().</hint>
2.980 + </question>
2.981 +-->
2.982 + <answer id="security-grant">
2.983 + <p>
2.984 + No security permitions manipulated.
2.985 + </p>
2.986 + </answer>
2.987 +
2.988 +
2.989 +
2.990 +<!--
2.991 + <question id="security-policy" when="final">
2.992 + Does your functionality require modifications to the standard policy file?
2.993 + <hint>Your code might pass control to third-party code not
2.994 + coming from trusted domains. This could be code downloaded over the
2.995 + network or code coming from libraries that are not bundled
2.996 + with NetBeans. Which permissions need to be granted to which domains?</hint>
2.997 + </question>
2.998 +-->
2.999 + <answer id="security-policy">
2.1000 + <p>
2.1001 + No security permissions manipulated.
2.1002 + </p>
2.1003 + </answer>
2.1004 +
2.1005 +
2.1006 +
2.1007 +
2.1008 +<!--
2.1009 + <question id="arch-where" when="init">
2.1010 + Where one can find sources for your module?
2.1011 + <hint>
2.1012 + Please provide link to the CVS web client at
2.1013 + http://www.netbeans.org/download/source_browse.html
2.1014 + or just use tag defaultanswer generate='here'
2.1015 + </hint>
2.1016 + </question>
2.1017 +-->
2.1018 + <answer id="arch-where">
2.1019 + <defaultanswer generate='here' />
2.1020 + </answer>
2.1021 +
2.1022 +
2.1023 +
2.1024 +
2.1025 +<!--
2.1026 + <question id="compat-deprecation" when="init">
2.1027 + How the introduction of your project influences functionality
2.1028 + provided by previous version of the product?
2.1029 + <hint>
2.1030 + If you are planning to deprecate/remove/change any existing APIs,
2.1031 + list them here accompanied with the reason explaining why you
2.1032 + are doing so.
2.1033 + </hint>
2.1034 + </question>
2.1035 +-->
2.1036 + <answer id="compat-deprecation">
2.1037 + <p>
2.1038 + XXX no answer for compat-deprecation
2.1039 + </p>
2.1040 + </answer>
2.1041 +
2.1042 +
2.1043 +
2.1044 +<!--
2.1045 + <question id="resources-preferences" when="final">
2.1046 + Does your module uses preferences via Preferences API? Does your module use NbPreferences or
2.1047 + or regular JDK Preferences ? Does it read, write or both ?
2.1048 + Does it share preferences with other modules ? If so, then why ?
2.1049 + <hint>
2.1050 + You may use
2.1051 + <api type="export" group="preferences"
2.1052 + name="preference node name" category="private">
2.1053 + description of individual keys, where it is used, what it
2.1054 + influences, whether the module reads/write it, etc.
2.1055 + </api>
2.1056 + Due to XML ID restrictions, rather than /org/netbeans/modules/foo give the "name" as org.netbeans.modules.foo.
2.1057 + Note that if you use NbPreferences this name will then be the same as the code name base of the module.
2.1058 + </hint>
2.1059 + </question>
2.1060 +-->
2.1061 + <answer id="resources-preferences">
2.1062 + <p>
2.1063 + XXX no answer for resources-preferences
2.1064 + </p>
2.1065 + </answer>
2.1066 +
2.1067 +</api-answers>
3.1 --- a/openide.util.lookup/nbproject/project.properties Wed Dec 09 16:32:01 2009 +0100
3.2 +++ b/openide.util.lookup/nbproject/project.properties Mon Dec 14 19:10:02 2009 +0100
3.3 @@ -41,3 +41,7 @@
3.4 javac.source=1.5
3.5 javac.compilerargs=-Xlint -Xlint:-serial
3.6 spec.version.base=8.0.0
3.7 +
3.8 +
3.9 +javadoc.arch=${basedir}/arch.xml
3.10 +javadoc.apichanges=${basedir}/apichanges.xml
4.1 --- a/openide.util/apichanges.xml Wed Dec 09 16:32:01 2009 +0100
4.2 +++ b/openide.util/apichanges.xml Mon Dec 14 19:10:02 2009 +0100
4.3 @@ -43,7 +43,6 @@
4.4 <!DOCTYPE apichanges PUBLIC "-//NetBeans//DTD API changes list 1.0//EN" "../nbbuild/javadoctools/apichanges.dtd">
4.5 <apichanges>
4.6 <apidefs>
4.7 - <apidef name="lookup">Lookup API</apidef>
4.8 <apidef name="util">Utilities API</apidef>
4.9 <apidef name="xml">XML API</apidef>
4.10 <apidef name="actions">Actions API</apidef>
4.11 @@ -136,23 +135,6 @@
4.12 <class package="org.openide" name="LifecycleManager"/>
4.13 <issue number="168257"/>
4.14 </change>
4.15 - <change id="org.openide.util.Lookup.paths">
4.16 - <api name="lookup"/>
4.17 - <summary>Added
4.18 - <code>org.openide.util.Lookup.paths</code> property
4.19 - </summary>
4.20 - <version major="7" minor="24"/>
4.21 - <date day="19" month="6" year="2009"/>
4.22 - <author login="jtulach"/>
4.23 - <compatibility addition="yes"/>
4.24 - <description>
4.25 - <p>
4.26 - Better way to integrate Lookup.getDefault() and system filesystem.
4.27 - </p>
4.28 - </description>
4.29 - <class package="org.openide.util" name="Lookup"/>
4.30 - <issue number="166782"/>
4.31 - </change>
4.32 <change id="enableStackTraces">
4.33 <api name="util"/>
4.34 <summary>Added constructor <code>RequestProcessor(String name, int throughput, boolean interruptThread, boolean enableStackTraces)</code></summary>
4.35 @@ -200,28 +182,6 @@
4.36 <class package="org.openide.util" name="Utilities"/>
4.37 <issue number="110492"/>
4.38 </change>
4.39 - <change id="ServiceProvider">
4.40 - <api name="lookup"/>
4.41 - <summary>Added <code>ServiceProvider</code> annotation</summary>
4.42 - <version major="7" minor="20"/>
4.43 - <date day="1" month="11" year="2008"/>
4.44 - <author login="jglick"/>
4.45 - <compatibility addition="yes">
4.46 - <p>
4.47 - Modules registering services using <code>META-INF/services</code>
4.48 - files in the source tree are encouraged to switch to the annotation.
4.49 - </p>
4.50 - </compatibility>
4.51 - <description>
4.52 - <p>
4.53 - Added annotations <code>ServiceProvider</code> and <code>ServiceProviders</code>
4.54 - to simplify registration of global singleton services.
4.55 - </p>
4.56 - </description>
4.57 - <class package="org.openide.util.lookup" name="ServiceProvider"/>
4.58 - <class package="org.openide.util.lookup" name="ServiceProviders"/>
4.59 - <issue number="150447"/>
4.60 - </change>
4.61 <change id="Utilities.OS_OPENBSD">
4.62 <api name="util"/>
4.63 <summary>Added <code>OS_OPENBSD</code> and <code>OS_UNIX_OTHER</code> fields</summary>
4.64 @@ -269,29 +229,6 @@
4.65 <class package="org.openide.xml" name="XMLUtil"/>
4.66 <issue number="42686"/>
4.67 </change>
4.68 - <change id="Lookup.asynchronous">
4.69 - <api name="lookup"/>
4.70 - <summary>AbstractLookup and ProxyLookup fire changes asynchronously</summary>
4.71 - <version major="7" minor="16"/>
4.72 - <date day="27" month="6" year="2008"/>
4.73 - <author login="jtulach"/>
4.74 - <compatibility addition="yes" binary="compatible" semantic="compatible"/>
4.75 - <description>
4.76 - <p>
4.77 - All modification methods in <code>AbstractLookup</code> and <code>ProxyLookup</code>
4.78 - were extended to accept an
4.79 - <a href="@JDK@/java/util/concurrent/Executor.html">Executor</a>.
4.80 - If not null, it is used to dispatch events to listeners sometime
4.81 - "later". Also the <code>AbstractLookup.Content</code>
4.82 - and <code>InstanceContent</code> constructors
4.83 - have been extended to accept such <code>Executor</code>s.
4.84 - </p>
4.85 - </description>
4.86 - <class package="org.openide.util.lookup" name="AbstractLookup"/>
4.87 - <class package="org.openide.util.lookup" name="ProxyLookup"/>
4.88 - <class package="org.openide.util.lookup" name="InstanceContent"/>
4.89 - <issue number="134297"/>
4.90 - </change>
4.91 <change id="RequestProcessor.Executor">
4.92 <api name="util"/>
4.93 <summary>RequestProcessor implements Executor interface</summary>
4.94 @@ -386,25 +323,6 @@
4.95 <issue number="119069"/>
4.96 </change>
4.97
4.98 - <change id="Lookups.forPath">
4.99 - <api name="util"/>
4.100 - <summary>Added simplified support for named lookups <code>Lookups.forPath</code></summary>
4.101 - <version major="7" minor="9"/>
4.102 - <date day="17" month="4" year="2007"/>
4.103 - <author login="jtulach"/>
4.104 - <compatibility addition="yes"/>
4.105 - <description>
4.106 - <p>
4.107 - New method <a href="@TOP@/org/openide/util/lookup/Lookups.html#forPath(java.lang.String)">Lookups.forPath(String)</a>
4.108 - has been added to replace now deprecated <a href="@org-openide-loaders@/org/openide/loaders/FolderLookup.html">FolderLookup</a>
4.109 - and allow modules who wants to read settings from layers
4.110 - to do so with a simpler code, without dependency on DataSystems API.
4.111 - </p>
4.112 - </description>
4.113 - <class package="org.openide.util.lookup" name="Lookups"/>
4.114 - <issue number="98426"/>
4.115 - </change>
4.116 -
4.117 <change id="ChangeSupport">
4.118 <api name="util"/>
4.119 <summary>Added <code>ChangeSupport</code></summary>
4.120 @@ -557,30 +475,6 @@
4.121 <issue number="73637"/>
4.122 </change>
4.123
4.124 - <change id="lookupAll-lookupResult">
4.125 - <api name="lookup"/>
4.126 - <summary>Convenience methods added to <code>Lookup</code></summary>
4.127 - <version major="6" minor="10"/>
4.128 - <date day="3" month="4" year="2006"/>
4.129 - <author login="jglick"/>
4.130 - <compatibility addition="yes" binary="compatible" source="incompatible">
4.131 - <p>
4.132 - Could conceivably conflict with existing subclass method with same signature
4.133 - with different semantics or return type.
4.134 - </p>
4.135 - </compatibility>
4.136 - <description>
4.137 - <p>
4.138 - Two methods, <code>lookupResult</code> and <code>lookupAll</code>, were
4.139 - added to <code>Lookup</code> to encapsulate the most common usage patterns
4.140 - with less typing, and more importantly avoiding the need to explicitly
4.141 - make a <code>Lookup.Template</code> object.
4.142 - </p>
4.143 - </description>
4.144 - <class package="org.openide.util" name="Lookup"/>
4.145 - <issue number="73848"/>
4.146 - </change>
4.147 -
4.148 <change id="use-logging" >
4.149 <api name="util"/>
4.150 <summary>Do not use ErrorManager for logging</summary>
4.151 @@ -646,32 +540,6 @@
4.152 <class package="org.openide.util" name="RequestProcessor"/>
4.153 <issue number="68031"/>
4.154 </change>
4.155 - <change id="less-events-from-proxylookup" >
4.156 - <api name="lookup"/>
4.157 - <summary>Less change notifications from ProxyLookup</summary>
4.158 - <version major="6" minor="7"/>
4.159 - <date day="11" month="11" year="2005"/>
4.160 - <author login="jtulach"/>
4.161 - <compatibility addition="no" modification="yes" binary="compatible" source="compatible" semantic="compatible" deprecation="no" deletion="no"/>
4.162 - <description>
4.163 - <a href="@TOP@/org/openide/util/lookup/ProxyLookup.html">ProxyLookup.setLookups</a>
4.164 - used to fire <a href="@TOP@/org/openide/util/LookupEvent.html">LookupEvent</a> every
4.165 - time it was called. Now it always checks whether there was a change to the
4.166 - previous state. This will reduce the number of events delivered when a small
4.167 - change is made. Also results from both
4.168 - <a href="@TOP@/org/openide/util/lookup/ProxyLookup.html">ProxyLookup</a>
4.169 - and <a href="@TOP@/org/openide/util/lookup/AbstractLookup.html">AbstractLookup</a>
4.170 - were modified to return immutable <code>Collection</code>s.
4.171 - So do not try to modify them. It was always documented that the
4.172 - results, are immutable and also it was never said that a change is
4.173 - delivered when there is no change in the result, so this is considered
4.174 - compatible change, even it is know that at least one piece of code
4.175 - in NetBeans relied on this behaviour.
4.176 - </description>
4.177 - <class package="org.openide.util.lookup" name="ProxyLookup"/>
4.178 - <class package="org.openide.util.lookup" name="AbstractLookup"/>
4.179 - <issue number="68031"/>
4.180 - </change>
4.181
4.182 <change>
4.183 <api name="util"/>
4.184 @@ -803,23 +671,6 @@
4.185 <issue number="27868"/>
4.186 </change>
4.187
4.188 - <change id="excluding-lookup">
4.189 - <api name="lookup"/>
4.190 - <summary>
4.191 -<code>Lookups.exclude</code> added to simplify writing of lookups that filter content of other lookups</summary>
4.192 - <version major="5" minor="4"/>
4.193 - <date day="14" month="1" year="2005"/>
4.194 - <author login="jtulach"/>
4.195 - <compatibility binary="compatible" source="compatible" semantic="compatible" deprecation="no" addition="no" deletion="no" modification="no"/>
4.196 - <description>
4.197 - <p>New method that takes lookup and set of classes and return new lookup
4.198 - which contains everything from the original one except instances of
4.199 - the specified classes has been added.
4.200 - </p>
4.201 - </description>
4.202 - <class package="org.openide.util.lookup" name="Lookups"/>
4.203 - <issue number="53058"/>
4.204 - </change>
4.205 <change id="Task-waitFinished-timeout">
4.206 <api name="util"/>
4.207 <summary>New method <code>task.waitFinished(timeout)</code> added</summary>
4.208 @@ -910,22 +761,6 @@
4.209 <issue number="41166"/>
4.210 </change>
4.211 <change>
4.212 - <api name="lookup"/>
4.213 - <summary>Added ability to order items in META-INF/services/ lookup</summary>
4.214 - <version major="4" minor="34"/>
4.215 - <date day="9" month="5" year="2004"/>
4.216 - <author login="dkonecny"/>
4.217 - <compatibility addition="yes" binary="compatible" source="compatible" semantic="compatible" deprecation="no" deletion="no" modification="no"/>
4.218 - <description>
4.219 - Items in META-INF/services/ lookup can be followed by advisory
4.220 - "position" attribute. The resulting lookup will list first items with lower
4.221 - position value. Items without position attribute will be listed
4.222 - last. See documentation for more details on format.
4.223 - </description>
4.224 - <class package="org.openide.util.lookup" name="Lookups"/>
4.225 - <issue number="41606"/>
4.226 - </change>
4.227 -<change>
4.228 <api name="util"/>
4.229 <summary>Support for complicated listeners</summary>
4.230 <version major="4" minor="12"/>
4.231 @@ -983,20 +818,6 @@
4.232 <class package="org.openide.util" name="WeakListeners"/>
4.233 <issue number="34758"/>
4.234 </change>
4.235 -<change>
4.236 - <api name="lookup"/>
4.237 - <summary>New <code>lookupItem()</code> method in Lookups</summary>
4.238 - <version major="4" minor="8"/>
4.239 - <date day="9" month="7" year="2003"/>
4.240 - <author login="vstejskal"/>
4.241 - <compatibility addition="yes" binary="compatible" source="compatible" semantic="compatible" deprecation="no" deletion="no" modification="no"/>
4.242 - <description>
4.243 - New method that returns Lookup.Item implementation for given instance and key identifying
4.244 - that instance in the lookup. This method is useful when writing Looks which need to
4.245 - return some cookies (Collection of Lookup.Items).
4.246 - </description>
4.247 - <class package="org.openide.util.lookup" name="Lookups"/>
4.248 - </change>
4.249 <change id="HelpCtx.findHelp">
4.250 <api name="util"/>
4.251 <summary>New method to find HelpCtx</summary>
4.252 @@ -1049,22 +870,6 @@
4.253 <issue number="30604"/>
4.254 </change>
4.255 <change>
4.256 - <api name="lookup"/>
4.257 - <summary>New method Lookups.metaInfServices</summary>
4.258 - <version major="3" minor="35"/>
4.259 - <date day="5" month="2" year="2003"/>
4.260 - <author login="dstrupl"/>
4.261 - <compatibility addition="yes" binary="compatible" source="compatible" semantic="compatible" deprecation="no" deletion="no" modification="no"/>
4.262 - <description>
4.263 - A lookup that implements the JDK1.3 JAR services mechanism and delegates
4.264 - to META-INF/services/name.of.class files. This lookup was (is) used by core
4.265 - and the core had to use reflection to create an instance. Moreover can
4.266 - be usefull for module authors and in standalone library.
4.267 - </description>
4.268 - <class package="org.openide.util.lookup" name="Lookups"/>
4.269 - <issue number="29126"/>
4.270 - </change>
4.271 -<change>
4.272 <api name="util"/>
4.273 <summary>org.openide.util.Utilities.createProgressCursor added</summary>
4.274 <version major="3" minor="23"/>
4.275 @@ -1118,23 +923,6 @@
4.276 <issue number="22156"/>
4.277 </change>
4.278 <change>
4.279 - <api name="lookup"/>
4.280 - <summary>New method Lookups.proxy</summary>
4.281 - <version major="3" minor="9"/>
4.282 - <date day="20" month="9" year="2002"/>
4.283 - <author login="dstrupl"/>
4.284 - <compatibility addition="yes" binary="compatible" source="compatible" semantic="compatible" deprecation="no" deletion="no" modification="no"/>
4.285 - <description>
4.286 - Creates a lookup that delegates to another one but that one can change
4.287 - from time to time. The returned lookup checks every time somebody calls
4.288 - lookup or lookupItem method whether the provider still returns
4.289 - the same lookup. If not, it updates state of all Lookup.Results
4.290 - that it created (and that still exists).
4.291 - </description>
4.292 - <class package="org.openide.util.lookup" name="Lookups"/>
4.293 - <issue number="27425"/>
4.294 - </change>
4.295 -<change>
4.296 <api name="util"/>
4.297 <summary>Utilities.activeReferenceQueue()</summary>
4.298 <version major="3" minor="11"/>
4.299 @@ -1151,22 +939,6 @@
4.300 </change>
4.301 <change>
4.302 <api name="util"/>
4.303 - <summary>New interface Lookup.Provider</summary>
4.304 - <version major="3" minor="6"/>
4.305 - <date day="19" month="8" year="2002"/>
4.306 - <author login="dstrupl"/>
4.307 - <compatibility addition="yes" binary="compatible" source="compatible" semantic="compatible" deprecation="no" deletion="no" modification="no"/>
4.308 - <description>
4.309 - An object can have method getLookup if there is a need to provide
4.310 - local loookup instance. To recognize objects with such a facility
4.311 - we are introducing interface Lookup.Provider with only one method:
4.312 - getLookup.
4.313 - </description>
4.314 - <class package="org.openide.util" name="Lookup"/>
4.315 - <issue number="26275"/>
4.316 - </change>
4.317 -<change>
4.318 - <api name="util"/>
4.319 <summary>Deprecation of parts of MouseUtils.PopupMenuAdapter</summary>
4.320 <version major="3" minor="4"/>
4.321 <date day="6" month="8" year="2002"/>
4.322 @@ -1179,46 +951,6 @@
4.323 should be constructed via default constructor.
4.324 </description>
4.325 </change>
4.326 -<change id="meta-inf-services">
4.327 - <api name="lookup"/>
4.328 - <summary>Modules can specify the content of Lookup.getDefault
4.329 - in META-INF/services</summary>
4.330 - <version major="3" minor="3"/>
4.331 - <date day="22" month="7" year="2002"/>
4.332 - <author login="jtulach"/>
4.333 - <compatibility addition="yes" binary="compatible" source="compatible" semantic="compatible" deprecation="no" deletion="no" modification="no"/>
4.334 - <description>
4.335 - The content of <code>Lookup.getDefault()</code> can be specified
4.336 - by a standard JDK registration mechanism, using JARs'
4.337 - <a href="http://java.sun.com/j2se/1.4/docs/guide/jar/jar.html#Service%20Provider" shape="rect">
4.338 - META-INF/services
4.339 - </a>
4.340 - directory. This is suitable for services that do not change,
4.341 - do not require user modification and that need to be ready
4.342 - soon during initialization of the system.
4.343 - </description>
4.344 - </change>
4.345 - <change>
4.346 - <api name="lookup"/>
4.347 - <summary>
4.348 -<code>ErrorManager.isNotifiable</code> added</summary>
4.349 - <version major="3" minor="18"/>
4.350 - <date day="3" month="11" year="2002"/>
4.351 - <author login="jglick"/>
4.352 - <compatibility addition="yes" binary="compatible" source="compatible" semantic="compatible" deprecation="no" deletion="no" modification="no">
4.353 - Existing code which assumes (incorrectly) that <code>isLoggable</code>
4.354 - can be used for this purpose, or which calls <code>notify</code> at a low
4.355 - level such as <code>INFORMATIONAL</code> without first checking
4.356 - <code>isNotifiable</code> for efficiency, should be revised.
4.357 - </compatibility>
4.358 - <description>
4.359 - The method <code>ErrorManager.isNotifiable</code> was added to capture
4.360 - the fact that an error manager implementation might be more aggressive
4.361 - about displaying stack traces than log messages.
4.362 - </description>
4.363 - <class package="org.openide" name="ErrorManager"/>
4.364 - <issue number="24056"/>
4.365 - </change>
4.366 <change>
4.367 <api name="util"/>
4.368 <summary>
4.369 @@ -1246,26 +978,6 @@
4.370 <issue number="29711"/>
4.371 </change>
4.372 <change>
4.373 - <api name="lookup"/>
4.374 - <summary>Added org.openide.util.lookup.Lookups</summary>
4.375 - <version major="2" minor="21"/>
4.376 - <date day="28" month="5" year="2002"/>
4.377 - <author login="dstrupl"/>
4.378 - <compatibility addition="yes" binary="compatible" source="compatible" semantic="compatible" deprecation="no" deletion="no" modification="no"/>
4.379 - <description>New utility class added. The class cannot be instantiated
4.380 - and contains following static methods:
4.381 - <pre xml:space="preserve">
4.382 -<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>);
4.383 -<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>);
4.384 -<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>);
4.385 -</pre>
4.386 - The methods return an instance of simple lookup implementation
4.387 - that holds the objects passed a parameter.
4.388 - </description>
4.389 - <class package="org.openide.util.lookup" name="Lookups"/>
4.390 - <issue number="20550"/>
4.391 - </change>
4.392 -<change>
4.393 <api name="util"/>
4.394 <summary>Added RequestProcessor.getDefault(), deprecated static methods in RequestProcessor</summary>
4.395 <version major="2" minor="12"/>
4.396 @@ -1325,49 +1037,6 @@
4.397 <class package="org.openide" name="ErrorManager"/>
4.398 <issue number="16854"/>
4.399 </change>
4.400 -<change id="AbstractLookup.Content-ProxyLookup.beforeLookup">
4.401 - <api name="lookup"/>
4.402 - <summary>Enhanced usage of ProxyLookup & AbstractLookup.Content</summary>
4.403 - <version major="1" minor="31"/>
4.404 - <date day="18" month="8" year="2001"/>
4.405 - <author login="jtulach"/>
4.406 - <compatibility addition="yes" binary="compatible" source="compatible" semantic="compatible" deprecation="no" deletion="no" modification="no"/>
4.407 - <description>
4.408 - <code>AbstractLookup.Content</code> made public to allow its usage
4.409 - for objects that do not subclass AbstractLookup. <code>ProxyLookup.beforeLookup</code>
4.410 - added so subclasses can update themselves (call setLookups (...)) before the actual lookup is
4.411 - performed.
4.412 - </description>
4.413 - <class package="org.openide.util.lookup" name="AbstractLookup"/>
4.414 - <class package="org.openide.util.lookup" name="ProxyLookup"/>
4.415 - </change>
4.416 -<change>
4.417 - <api name="lookup"/>
4.418 - <summary>Instance content simplifies creation of lookups</summary>
4.419 - <version major="1" minor="25"/>
4.420 - <!-- XXX date unknown -->
4.421 - <author login="jtulach"/>
4.422 - <compatibility addition="yes" binary="compatible" source="compatible" semantic="compatible" deprecation="no" deletion="no" modification="no"/>
4.423 - <description>
4.424 - Added <code>AbstractLookup.Content</code> which can be passed to an
4.425 - abstract lookup in its constructor and used to control the contents
4.426 - easily. Also <code>InstanceLookup</code> provides the common easy
4.427 - implementation.
4.428 - </description>
4.429 - <class package="org.openide.util.lookup" name="AbstractLookup"/>
4.430 - <class package="org.openide.util.lookup" name="InstanceContent"/>
4.431 - </change>
4.432 - <change id="clone-service-type" >
4.433 - <api name="lookup"/>
4.434 - <summary>
4.435 -<code>ServiceType.createClone</code> added</summary>
4.436 - <date day="30" month="11" year="2000"/>
4.437 - <compatibility addition="yes" binary="compatible" source="compatible" semantic="compatible" deprecation="no" deletion="no" modification="no">Subclasses are encouraged to implement <code>Cloneable</code>.</compatibility>
4.438 - <description>
4.439 - <code>public final ServiceType createClone()</code> added.
4.440 - </description>
4.441 - <class package="org.openide" name="ServiceType"/>
4.442 - </change>
4.443 <change id="logging-added-to-error-manager" >
4.444 <api name="util"/>
4.445 <summary>
4.446 @@ -1392,27 +1061,6 @@
4.447 <class package="org.openide" name="ErrorManager"/>
4.448 </change>
4.449 <change>
4.450 - <api name="lookup"/>
4.451 - <summary>Folder lookup may be serialized</summary>
4.452 - <version major="3" minor="27"/>
4.453 - <date day="7" month="1" year="2003"/>
4.454 - <author login="jglick"/>
4.455 - <compatibility modification="yes" binary="compatible" source="compatible" semantic="compatible" deprecation="no" addition="no" deletion="no">
4.456 - Modules which rely on a data object under <samp>Services/</samp> gaining
4.457 - or losing <code>InstanceCookie</code> between sessions may not work
4.458 - correctly with the cache. This is probably very rare.
4.459 - </compatibility>
4.460 - <description>
4.461 - To implement lookup caching, some lookup implementations are now
4.462 - serializable: <code>AbstractLookup</code> as well as
4.463 - <code>FolderLookup</code>'s lookup. <code>ProxyLookup</code> has a
4.464 - protected subclass constructor permitting subclasses to be serializable.
4.465 - </description>
4.466 - <class package="org.openide.util.lookup" name="AbstractLookup"/>
4.467 - <class package="org.openide.util.lookup" name="ProxyLookup"/>
4.468 - <issue number="20190"/>
4.469 - </change>
4.470 - <change>
4.471 <api name="xml"/>
4.472 <summary>Can register entity resolvers</summary>
4.473 <date day="20" month="12" year="2000"/>
4.474 @@ -1534,39 +1182,6 @@
4.475 </description>
4.476 <class package="org.openide.util" name="Mutex"/>
4.477 </change>
4.478 - <change>
4.479 - <api name="lookup"/>
4.480 - <summary>Changes in access protection of proxy lookup</summary>
4.481 - <version major="1" minor="19"/>
4.482 - <date day="8" month="7" year="2001"/>
4.483 - <compatibility modification="yes" binary="compatible" source="compatible" semantic="compatible" deprecation="no" addition="no" deletion="no">
4.484 - Changes to newly added feature.
4.485 - </compatibility>
4.486 - <description>
4.487 - <code>ProxyLookup.setLookups</code> made protected instead of public so
4.488 - nobody can misuse the method except the creator of the object and
4.489 - <code>ProxyLookup.getLookups</code> added. <code>ProxyLookup</code> made
4.490 - non final.
4.491 - </description>
4.492 - <class package="org.openide.util.lookup" name="ProxyLookup"/>
4.493 - </change>
4.494 -<change>
4.495 - <api name="lookup"/>
4.496 - <summary>Lookup service providers package created</summary>
4.497 - <version major="1" minor="9"/>
4.498 - <date day="1" month="6" year="2001"/>
4.499 - <author login="jtulach"/>
4.500 - <compatibility addition="yes" binary="compatible" source="compatible" semantic="compatible" deprecation="no" deletion="no" modification="no"/>
4.501 - <description>
4.502 - Package <code>org.openide.util.lookup</code> created, should hold SPI
4.503 - interfaces for lookup. Initially filled with <code>AbstractLookup</code>
4.504 - which introduces <code>AbstractLookup.Pair</code> and with
4.505 - <code>ProxyLookup</code>.
4.506 - </description>
4.507 - <class package="org.openide.util.lookup" name="AbstractLookup"/>
4.508 - <class package="org.openide.util.lookup" name="ProxyLookup"/>
4.509 - <package name="org.openide.util.lookup"/>
4.510 - </change>
4.511 <change id="Task.notifyRunning">
4.512 <api name="util"/>
4.513 <summary>More flexibility in controlling running of tasks</summary>
4.514 @@ -1580,34 +1195,37 @@
4.515 </description>
4.516 <class package="org.openide.util" name="Task"/>
4.517 </change>
4.518 -<change>
4.519 - <api name="lookup"/>
4.520 - <summary>Added lookup items and support APIs</summary>
4.521 - <version major="1" minor="8"/>
4.522 - <date day="25" month="5" year="2001"/>
4.523 - <author login="jtulach"/>
4.524 - <compatibility addition="yes" binary="compatible" source="compatible" semantic="compatible" deprecation="no" deletion="no" modification="no"/>
4.525 + <change>
4.526 + <api name="util"/>
4.527 + <summary>
4.528 + <code>ErrorManager.isNotifiable</code> added</summary>
4.529 + <version major="3" minor="18"/>
4.530 + <date day="3" month="11" year="2002"/>
4.531 + <author login="jglick"/>
4.532 + <compatibility addition="yes" binary="compatible" source="compatible" semantic="compatible" deprecation="no" deletion="no" modification="no">
4.533 + Existing code which assumes (incorrectly) that <code>isLoggable</code>
4.534 + can be used for this purpose, or which calls <code>notify</code> at a low
4.535 + level such as <code>INFORMATIONAL</code> without first checking
4.536 + <code>isNotifiable</code> for efficiency, should be revised.
4.537 + </compatibility>
4.538 <description>
4.539 - <code>Lookup</code> enhanced. Interface <code>Lookup.Item</code> and
4.540 - additional methods to access it also added.
4.541 + The method <code>ErrorManager.isNotifiable</code> was added to capture
4.542 + the fact that an error manager implementation might be more aggressive
4.543 + about displaying stack traces than log messages.
4.544 </description>
4.545 - <class package="org.openide.util" name="Lookup"/>
4.546 + <class package="org.openide" name="ErrorManager"/>
4.547 + <issue number="24056"/>
4.548 </change>
4.549 -<change>
4.550 - <api name="lookup"/>
4.551 - <summary>Lookup system introduced</summary>
4.552 - <date day="1" month="3" year="2001"/>
4.553 - <author login="jtulach"/>
4.554 - <compatibility addition="yes" binary="compatible" source="compatible" semantic="compatible" deprecation="no" deletion="no" modification="no"/>
4.555 + <change id="clone-service-type" >
4.556 + <api name="util"/>
4.557 + <summary>
4.558 + <code>ServiceType.createClone</code> added</summary>
4.559 + <date day="30" month="11" year="2000"/>
4.560 + <compatibility addition="yes" binary="compatible" source="compatible" semantic="compatible" deprecation="no" deletion="no" modification="no">Subclasses are encouraged to implement <code>Cloneable</code>.</compatibility>
4.561 <description>
4.562 - Better version of <code>Lookup</code> introduced. There is a
4.563 - <code>org.openide.util.Lookup</code> with bunch of inner classes and
4.564 - <code>org.openide.util.LookupListener</code> and
4.565 - <code>org.openide.util.LookupEvent</code>.
4.566 + <code>public final ServiceType createClone()</code> added.
4.567 </description>
4.568 - <class package="org.openide.util" name="Lookup"/>
4.569 - <class package="org.openide.util" name="LookupEvent"/>
4.570 - <class package="org.openide.util" name="LookupListener"/>
4.571 + <class package="org.openide" name="ServiceType"/>
4.572 </change>
4.573 <change>
4.574 <api name="util"/>
5.1 --- a/openide.util/arch.xml Wed Dec 09 16:32:01 2009 +0100
5.2 +++ b/openide.util/arch.xml Mon Dec 14 19:10:02 2009 +0100
5.3 @@ -60,15 +60,15 @@
5.4 </p>
5.5
5.6 <p>
5.7 - Also this module defines the <a href="@TOP@/org/openide/util/Lookup.html">
5.8 + Also this module defines the <a href="@org-openide-util-lookup@/org/openide/util/Lookup.html">
5.9 Lookup</a> which the NetBeans way for dynamic registration
5.10 and lookup of
5.11 components in our modularized component system. It allows lookup and discovery
5.12 of features by description of their interfaces. The classes are devided
5.13 into two parts. The
5.14 - <api group="java" name="LookupAPI" type="export" category="official" url="@TOP@/org/openide/util/lookup/doc-files/lookup-api.html">
5.15 + <api group="java" name="LookupAPI" type="export" category="official" url="@org-openide-util-lookup@/org/openide/util/lookup/doc-files/lookup-api.html">
5.16 allows the discovery</api> and the
5.17 - <api group="java" name="LookupSPI" type="export" category="official" url="@TOP@/org/openide/util/lookup/doc-files/lookup-spi.html">
5.18 + <api group="java" name="LookupSPI" type="export" category="official" url="@org-openide-util-lookup@/org/openide/util/lookup/doc-files/lookup-spi.html">
5.19 simplifies creation and registration of own lookup objects</api>.
5.20 </p>
5.21 </answer>
5.22 @@ -93,7 +93,7 @@
5.23 <answer id="arch-usecases">
5.24
5.25 There is a great introduction to Lookup and its usage in its
5.26 - <a href="@TOP@/org/openide/util/Lookup.html">javadoc</a>. Here is just
5.27 + <a href="@org-openide-util-lookup@/org/openide/util/Lookup.html">javadoc</a>. Here is just
5.28 a list of frequently asked or interesting questions slowly expanding as
5.29 people ask them:
5.30
5.31 @@ -177,13 +177,13 @@
5.32 <span class="java-keywords">import</span> <span class="java-identifier">java</span><span class="java-operators">.</span><span class="java-identifier">util</span><span class="java-operators">.</span><span class="java-identifier">Collections</span><span class="java-operators">;</span>
5.33 <span class="java-keywords">import</span> <span class="java-identifier">org</span><span class="java-operators">.</span><span class="java-identifier">openide</span><span class="java-operators">.</span><span class="java-identifier">util</span><span class="java-operators">.</span><span class="java-identifier">Lookup</span><span class="java-operators">;</span>
5.34
5.35 -<a href="@TOP@org/openide/util/Lookup.Result.html"><span class="java-identifier">Lookup</span><span class="java-operators">.</span><span class="java-identifier">Result</span></a> <span class="java-identifier">result</span> <span class="java-operators">=</span> <a href="@TOP@org/openide/util/Lookup.html"><span class="java-identifier">Lookup</span></a><span class="java-operators">.</span><span class="java-layer-method">getDefault</span> <span class="java-operators">(</span><span class="java-operators">)</span><span class="java-operators">.</span><span class="java-layer-method">lookup</span> <span class="java-operators">(</span><span class="java-keywords">new</span> <a href="@TOP@org/openide/util/Lookup.Template.html"><span class="java-identifier">Lookup</span><span class="java-operators">.</span><span class="java-layer-method">Template</span></a> <span class="java-operators">(</span><span class="java-identifier">TipsOfTheDayProvider</span><span class="java-operators">.</span><span class="java-keywords">class</span><span class="java-operators">)</span><span class="java-operators">)</span><span class="java-operators">;</span>
5.36 -<span class="java-identifier">Collection</span> <span class="java-identifier">c</span> <span class="java-operators">=</span> <span class="java-identifier">result</span><span class="java-operators">.</span><a href="@TOP@org/openide/util/Lookup.Result.html#allInstances()"><span class="java-layer-method">allInstances</span></a> <span class="java-operators">(</span><span class="java-operators">)</span><span class="java-operators">;</span>
5.37 +<a href="@org-openide-util-lookup@/org/openide/util/Lookup.Result.html"><span class="java-identifier">Lookup</span><span class="java-operators">.</span><span class="java-identifier">Result</span></a> <span class="java-identifier">result</span> <span class="java-operators">=</span> <a href="@org-openide-util-lookup@/org/openide/util/Lookup.html"><span class="java-identifier">Lookup</span></a><span class="java-operators">.</span><span class="java-layer-method">getDefault</span> <span class="java-operators">(</span><span class="java-operators">)</span><span class="java-operators">.</span><span class="java-layer-method">lookup</span> <span class="java-operators">(</span><span class="java-keywords">new</span> <a href="@org-openide-util-lookup@/org/openide/util/Lookup.Template.html"><span class="java-identifier">Lookup</span><span class="java-operators">.</span><span class="java-layer-method">Template</span></a> <span class="java-operators">(</span><span class="java-identifier">TipsOfTheDayProvider</span><span class="java-operators">.</span><span class="java-keywords">class</span><span class="java-operators">)</span><span class="java-operators">)</span><span class="java-operators">;</span>
5.38 +<span class="java-identifier">Collection</span> <span class="java-identifier">c</span> <span class="java-operators">=</span> <span class="java-identifier">result</span><span class="java-operators">.</span><a href="@org-openide-util-lookup@/org/openide/util/Lookup.Result.html#allInstances()"><span class="java-layer-method">allInstances</span></a> <span class="java-operators">(</span><span class="java-operators">)</span><span class="java-operators">;</span>
5.39 <span class="java-identifier">Collections</span><span class="java-operators">.</span><span class="java-layer-method">shuffle</span> <span class="java-operators">(</span><span class="java-identifier">c</span><span class="java-operators">)</span><span class="java-operators">;</span>
5.40 <span class="java-identifier">TipsOfTheDayProvider</span> <span class="java-identifier">selected</span> <span class="java-operators">=</span> <span class="java-operators">(</span><span class="java-identifier">TipsOfTheDayProvider</span><span class="java-operators">)</span><span class="java-identifier">c</span><span class="java-operators">.</span><span class="java-layer-method">iterator</span> <span class="java-operators">(</span><span class="java-operators">)</span><span class="java-operators">.</span><span class="java-layer-method">next</span> <span class="java-operators">(</span><span class="java-operators">)</span><span class="java-operators">;</span>
5.41 </pre><p>
5.42 and then display the tip. Simple, trivial, just by the usage of
5.43 - <a href="@TOP@org/openide/util/Lookup.html">Lookup</a> interface once
5.44 + <a href="@org-openide-util-lookup@/org/openide/util/Lookup.html">Lookup</a> interface once
5.45 creates a registry that other modules can enhance. But such enhancing
5.46 of course requires work on the other side. Each module that would like
5.47 to register its <code>TipsOfTheDayProvider</code> needs to depend on the
5.48 @@ -301,7 +301,7 @@
5.49 indirectly communicates with <a href="@org-openide-awt@/overview-summary.html">UI Utilities</a>
5.50 module using <api name="AWTBridge" category="private" group="java" type="export"
5.51 url="http://www.netbeans.org/source/browse/openide/util/src/org/netbeans/modules/openide/util/AWTBridge.java">
5.52 - a class that is looked up in <a href="@TOP@/org/openide/util/Lookup.html#getDefault()">Lookup.getDefault()</a>
5.53 + a class that is looked up in <a href="@org-openide-util-lookup@/org/openide/util/Lookup.html#getDefault()">Lookup.getDefault()</a>
5.54 and if registered can provide better UI elements for <a href="@JDK@/javax/swing/Action.html">Action</a>s.
5.55 </api>
5.56
5.57 @@ -490,28 +490,28 @@
5.58 <li>
5.59 <api type="export" group="property" name="org.openide.util.Lookup" category="devel">
5.60 checked by the initialization of the
5.61 - <a href="@TOP@/org/openide/util/Lookup.html#getDefault()">Lookup.getDefault()</a>
5.62 + <a href="@org-openide-util-lookup@/org/openide/util/Lookup.html#getDefault()">Lookup.getDefault()</a>
5.63 and can
5.64 contain name of a class that extends <code>org.openide.util.Lookup</code> and
5.65 has public constructor, that should be instantiated and returned from
5.66 - <a href="@TOP@/org/openide/util/Lookup.html#getDefault()">Lookup.getDefault()</a>
5.67 + <a href="@org-openide-util-lookup@/org/openide/util/Lookup.html#getDefault()">Lookup.getDefault()</a>
5.68 the class will be loaded by
5.69 <a href="@JDK@/java/lang/Thread.html#getContextClassLoader()">
5.70 Thread.currentThread().getContextClassLoader()</a>
5.71 classloader the first time <code>Lookup.getDefault</code> is invoked.
5.72 <p/>
5.73 The property can also contain value <code>"-"</code> which means to completely
5.74 - disable the lookup instantiation and return <a href="@TOP@/org/openide/util/Lookup.html#EMPTY">Lookup.EMPTY</a>
5.75 - from <a href="@TOP@/org/openide/util/Lookup.html#getDefault()">Lookup.getDefault()</a>.
5.76 + disable the lookup instantiation and return <a href="@org-openide-util-lookup@/org/openide/util/Lookup.html#EMPTY">Lookup.EMPTY</a>
5.77 + from <a href="@org-openide-util-lookup@/org/openide/util/Lookup.html#getDefault()">Lookup.getDefault()</a>.
5.78 <p/>
5.79 If the property is unspecified, the default <code>MetaInfServicesLookup</code>
5.80 is constructed for <code>Thread.currentThread().getContextclassLoader()</code>
5.81 that implements the <a href="architecture-summary.html#answer-compat-standards">JDK's standard</a>. If, by
5.82 a chance an instance of
5.83 - <a href="@TOP@/org/openide/util/Lookup.Provider.html">Lookup.Provider</a>
5.84 + <a href="@org-openide-util-lookup@/org/openide/util/Lookup.Provider.html">Lookup.Provider</a>
5.85 is found
5.86 in there, its lookup is returned as result. Otherwise the <code>MetaInfServicesLookup</code>
5.87 - is the result of <a href="@TOP@/org/openide/util/Lookup.html#getDefault()">Lookup.getDefault()</a>.
5.88 + is the result of <a href="@org-openide-util-lookup@/org/openide/util/Lookup.html#getDefault()">Lookup.getDefault()</a>.
5.89 </api>
5.90 </li>
5.91
5.92 @@ -521,11 +521,11 @@
5.93 some system file system folder. This can be done with
5.94 <code>org.openide.util.Lookup.paths=Folder1:Folder2:Folder3</code>.
5.95 If this property is set prior to first call to
5.96 - <a href="@TOP@/org/openide/util/Lookup.html#getDefault()">Lookup.getDefault()</a>,
5.97 + <a href="@org-openide-util-lookup@/org/openide/util/Lookup.html#getDefault()">Lookup.getDefault()</a>,
5.98 it is split into pieces (separator is <code>':'</code>) and individual
5.99 parts are then used to construct <code>Lookups.forPath("Folder1")</code>,
5.100 etc. All these lookups then become part of the
5.101 - <a href="@TOP@/org/openide/util/Lookup.html#getDefault()">Lookup.getDefault()</a>
5.102 + <a href="@org-openide-util-lookup@/org/openide/util/Lookup.html#getDefault()">Lookup.getDefault()</a>
5.103 one. This property works since version 7.24
5.104 </api>
5.105 </li>
5.106 @@ -553,7 +553,7 @@
5.107 <api category="devel" group="java" name="WeakListener.setAccessible" type="export" url="@TOP@/org/openide/util/WeakListeners.html">
5.108 used to call the remove method using reflection
5.109 </api>.
5.110 - <api category="devel" group="java" name="Lookups.metaInfServices" type="export" url="@TOP@/org/openide/util/lookup/Lookups.html#metaInfServices(java.lang.ClassLoader)">
5.111 + <api category="devel" group="java" name="Lookups.metaInfServices" type="export" url="@org-openide-util-lookup@/org/openide/util/lookup/Lookups.html#metaInfServices(java.lang.ClassLoader)">
5.112 calls constructor of registered classes using reflection
5.113 </api>.
5.114 <api category="private" group="lookup" name="ActionManagerInvocation" type="export" >
5.115 @@ -633,8 +633,8 @@
5.116 <ul>
5.117 <li><api name="LookupInitializationLookup" category="devel" group="lookup" type="export" url="#property-org.openide.util.Lookup">
5.118 during
5.119 - initialization of the <a href="@TOP@/org/openide/util/Lookup.html#getDefault()">Lookup.getDefault()</a>
5.120 - the <a href="@TOP@/org/openide/util/Lookup.Provider.html">Lookup.Provider</a>
5.121 + initialization of the <a href="@org-openide-util-lookup@/org/openide/util/Lookup.html#getDefault()">Lookup.getDefault()</a>
5.122 + the <a href="@org-openide-util-lookup@/org/openide/util/Lookup.Provider.html">Lookup.Provider</a>
5.123 is being searched</api>.
5.124 </li>
5.125
5.126 @@ -646,7 +646,7 @@
5.127 <li><api name="LookupContextGlobalProvider" category="stable" group="lookup" type="export">
5.128 <a href="@TOP@/org/openide/util/Utilities.html#actionsGlobalContext()">actionsGlobalContext</a>
5.129 searches for <a href="@TOP@/org/openide/util/ContextGlobalProvider.html">ContextGlobalProvider</a> in
5.130 - <a href="@TOP@/org/openide/util/Lookup.html#getDefault()">Lookup.getDefault()</a>.
5.131 + <a href="@org-openide-util-lookup@/org/openide/util/Lookup.html#getDefault()">Lookup.getDefault()</a>.
5.132 The provider is usually provided by <a href="@org-openide-windows@/overview-summary.html">window
5.133 system implementation</a>.
5.134 </api>.</li>
5.135 @@ -666,7 +666,7 @@
5.136 <li><api name="LookupClassLoader" category="devel" group="lookup" type="export">
5.137 Nearly all resource looking functions and reflective code
5.138 uses <a href="@JDK@/java/lang/ClassLoader.html">ClassLoader</a>
5.139 - obtained from <a href="@TOP@/org/openide/util/Lookup.html#getDefault()">Lookup.getDefault()</a>
5.140 + obtained from <a href="@org-openide-util-lookup@/org/openide/util/Lookup.html#getDefault()">Lookup.getDefault()</a>
5.141 for loading system wide resources.
5.142 </api>.</li>
5.143
5.144 @@ -762,9 +762,7 @@
5.145 -->
5.146 <answer id="perf-mem">
5.147 <p>
5.148 - There are no big data structures. The amount of memory occupied by
5.149 - instances of <a href="@TOP@/org/openide/util/lookup/AbstractLookup.html">AbstractLookup</a>
5.150 - is measured by unit tests.
5.151 + There are no big data structures.
5.152 </p>
5.153 </answer>
5.154
6.1 --- a/openide.util/src/org/openide/util/doc-files/api.html Wed Dec 09 16:32:01 2009 +0100
6.2 +++ b/openide.util/src/org/openide/util/doc-files/api.html Mon Dec 14 19:10:02 2009 +0100
6.3 @@ -58,8 +58,8 @@
6.4 <h2>Package <a href="../package-summary.html"><code>org.openide.util</code></a></h2>
6.5
6.6 <ol>
6.7 - <li><a href="../Lookup.html">Lookup</a> and its associated
6.8 - <a href="../lookup/package-summary.html">support package</a> as that
6.9 + <li><a href="@org-openide-util-lookup@/org/openide/util/Lookup.html">Lookup</a> and its associated
6.10 + <a href="@org-openide-util-lookup@/org/openide/util/lookup/package-summary.html">support package</a> as that
6.11 is the <em>adaptable</em> interface that objects can provide if
6.12 they wish to offer dynamic capabilities.
6.13 </li>
6.14 @@ -114,11 +114,11 @@
6.15
6.16 <p>For lookup, this centers around
6.17
6.18 -<a href="../Lookup.html"><code>Lookup</code></a>
6.19 +<a href="@org-openide-util-lookup@/org/openide/util/Lookup.html"><code>Lookup</code></a>
6.20
6.21 and helper implementations in
6.22
6.23 -<a href="../lookup/package-summary.html"><code>org.openide.util.lookup</code></a>.
6.24 +<a href="@org-openide-util-lookup@/org/openide/util/lookup/package-summary.html"><code>org.openide.util.lookup</code></a>.
6.25
6.26
6.27
6.28 @@ -447,7 +447,7 @@
6.29
6.30 The client side of the lookup system centers around one class,
6.31
6.32 -<a href="../Lookup.html"><code>Lookup</code></a>.
6.33 +<a href="@org-openide-util-lookup@/org/openide/util/Lookup.html"><code>Lookup</code></a>.
6.34
6.35 In the simplest usage, all that is needed is to get some single
6.36 instance of a given class (or subclass). For example, if some kind of
6.37 @@ -456,7 +456,7 @@
6.38 may simply use:
6.39
6.40 <pre>
6.41 -<font class="type">MyService</font> <font class="variable-name">impl</font> = (<font class="type">MyService</font>)Lookup.getDefault().<a href="../Lookup.html#lookup(java.lang.Class)">lookup</a>(MyService.<font class="keyword">class</font>);
6.42 +<font class="type">MyService</font> <font class="variable-name">impl</font> = (<font class="type">MyService</font>)Lookup.getDefault().<a href="@org-openide-util-lookup@/org/openide/util/Lookup.html#lookup(java.lang.Class)">lookup</a>(MyService.<font class="keyword">class</font>);
6.43 <font class="keyword">if</font> (impl == <font class="constant">null</font>) <font class="comment">/* nothing registered */</font> ...
6.44 impl.useIt();
6.45 </pre>
6.46 @@ -558,12 +558,12 @@
6.47 general method:
6.48
6.49 <pre>
6.50 -<font class="type"><a href="../Lookup.Template.html">Lookup.Template</a></font> <font class="variable-name">templ</font> = <font class="keyword">new</font> <font class="type">Lookup.Template</font>(MyService.<font class="keyword">class</font>);
6.51 -<font class="keyword">final</font> <font class="type"><a href="../Lookup.Result.html">Lookup.Result</a></font> <font class="variable-name">result</font> = Lookup.getDefault().lookup(templ);
6.52 +<font class="type"><a href="@org-openide-util-lookup@/org/openide/util/Lookup.Template.html">Lookup.Template</a></font> <font class="variable-name">templ</font> = <font class="keyword">new</font> <font class="type">Lookup.Template</font>(MyService.<font class="keyword">class</font>);
6.53 +<font class="keyword">final</font> <font class="type"><a href="@org-openide-util-lookup@/org/openide/util/Lookup.Result.html">Lookup.Result</a></font> <font class="variable-name">result</font> = Lookup.getDefault().lookup(templ);
6.54 <font class="type">Collection</font> <font class="variable-name">impls</font> = result.allInstances(); <font class="comment">// Collection<MyService>
6.55 // use Java Collections API to get iterator, ...
6.56 // Pay attention to subsequent changes in the result.
6.57 -</font>result.addLookupListener(<font class="keyword">new</font> <font class="type"><a href="../LookupListener.html">LookupListener</a></font>() {
6.58 +</font>result.addLookupListener(<font class="keyword">new</font> <font class="type"><a href="@org-openide-util-lookup@/org/openide/util/LookupListener.html">LookupListener</a></font>() {
6.59 <font class="keyword">public</font> <font class="type">void</font> <font class="function-name">resultChanged</font>(<font class="type">LookupEvent</font> <font class="variable-name">ev</font>) {
6.60 <font class="comment">// Now it is different.
6.61 </font> <font class="type">Collection</font> <font class="variable-name">impls2</font> = result.allInstances();
6.62 @@ -611,7 +611,7 @@
6.63 <font class="type">Lookup.Result</font> <font class="variable-name">result</font> = Lookup.getDefault().lookup(templ);
6.64 <font class="type">Iterator</font> <font class="variable-name">it</font> = result.allItems().iterator();
6.65 <font class="keyword">while</font> (it.hasNext()) {
6.66 - <font class="type"><a href="../Lookup.Item.html">Lookup.Item</a></font> <font class="variable-name">item</font> = (<font class="type">Lookup.Item</font>)it.next();
6.67 + <font class="type"><a href="@org-openide-util-lookup@/org/openide/util/Lookup.Item.html">Lookup.Item</a></font> <font class="variable-name">item</font> = (<font class="type">Lookup.Item</font>)it.next();
6.68 <font class="type">String</font> <font class="variable-name">displayName</font> = item.getDisplayName();
6.69 <font class="keyword">if</font> (<font class="comment">/* user accepts displayName as the right one */</font>) {
6.70 <font class="type">MyService</font> <font class="variable-name">instance</font> = (<font class="type">MyService</font>)item.getInstance();
6.71 @@ -623,7 +623,7 @@
6.72 }
6.73 <font class="comment">// later...
6.74 </font><font class="type">String</font> <font class="variable-name">storedID</font> = someSettings.getChosenService();
6.75 -<font class="type">Lookup.Template</font> <font class="variable-name">templ</font> = <font class="keyword">new</font> <font class="type"><a href="../Lookup.Template.html#Lookup.Template(java.lang.Class,java.lang.String,java.lang.Object)">Lookup.Template</a></font>(MyService.<font class="keyword">class</font>, storedID, <font class="constant">null</font>);
6.76 +<font class="type">Lookup.Template</font> <font class="variable-name">templ</font> = <font class="keyword">new</font> <font class="type"><a href="@org-openide-util-lookup@/org/openide/util/Lookup.Template.html#Lookup.Template(java.lang.Class,java.lang.String,java.lang.Object)">Lookup.Template</a></font>(MyService.<font class="keyword">class</font>, storedID, <font class="constant">null</font>);
6.77 <font class="type">Iterator</font> <font class="variable-name">it</font> = Lookup.getDefault().lookup(templ).allInstances().iterator();
6.78 <font class="keyword">if</font> (! it.hasNext()) <font class="comment">/* failed to find it... */</font>
6.79 <font class="type">MyService</font> <font class="variable-name">instance</font> = (<font class="type">MyService</font>)it.next();
6.80 @@ -661,7 +661,7 @@
6.81 <p>The simplest way to create a fresh lookup is to base it on other
6.82 existing ones.
6.83
6.84 -<a href="../lookup/ProxyLookup.html"><code>ProxyLookup</code></a>
6.85 +<a href="@org-openide-util-lookup@/org/openide/util/lookup/ProxyLookup.html"><code>ProxyLookup</code></a>
6.86
6.87 accepts a list of other lookup implementations (in the constructor and
6.88 also changeable later). The results it provides are constructed by
6.89 @@ -673,7 +673,7 @@
6.90 If you want to use the common mechanism of finding instances in
6.91 folders (or subfolders) and serving these as the results,
6.92
6.93 -<a href="../lookup/Lookups.html#forPath(java.lang.String)">Lookups.forPath(String)</a>
6.94 +<a href="@org-openide-util-lookup@/org/openide/util/lookup/Lookups.html#forPath(java.lang.String)">Lookups.forPath(String)</a>
6.95
6.96 makes this possible: you need only provide a name of a folder to look in, and
6.97 use
6.98 @@ -723,7 +723,7 @@
6.99 <p>The most powerful way to provide a lookup is to directly define
6.100 what instances and items it should provide, by subclassing. For this,
6.101
6.102 -<a href="../lookup/AbstractLookup.html"><code>AbstractLookup</code></a>
6.103 +<a href="@org-openide-util-lookup@/org/openide/util/lookup/AbstractLookup.html"><code>AbstractLookup</code></a>
6.104
6.105 is recommended as it is easiest to use.
6.106
6.107 @@ -731,18 +731,18 @@
6.108 public constructor (in which case you need not subclass it). Here you
6.109 provide an
6.110
6.111 -<a href="../lookup/AbstractLookup.Content.html"><code>AbstractLookup.Content</code></a>
6.112 +<a href="@org-openide-util-lookup@/org/openide/util/lookup/AbstractLookup.Content.html"><code>AbstractLookup.Content</code></a>
6.113
6.114 object which you have created and hold on to privately, and which
6.115 keeps track of instances and permits them to be registered and
6.116 deregistered. Often
6.117
6.118 -<a href="../lookup/InstanceContent.html"><code>InstanceContent</code></a>
6.119 +<a href="@org-openide-util-lookup@/org/openide/util/lookup/InstanceContent.html"><code>InstanceContent</code></a>
6.120
6.121 is used as the content implementation. To add something to the lookup,
6.122 simply use
6.123
6.124 -<a href="../lookup/InstanceContent.html#add(java.lang.Object)"><code>add(Object)</code></a>
6.125 +<a href="@org-openide-util-lookup@/org/openide/util/lookup/InstanceContent.html#add(java.lang.Object)"><code>add(Object)</code></a>
6.126
6.127 (and <code>remove(Object)</code> for the reverse). These may be called
6.128 at any time and will update the set of registered instances (firing
6.129 @@ -752,7 +752,7 @@
6.130 lookup, but there is some cheap "key" which can easily generate it,
6.131 you may instead register the key by passing in an
6.132
6.133 -<a href="../lookup/InstanceContent.Convertor.html"><code>InstanceContent.Convertor</code></a>.
6.134 +<a href="@org-openide-util-lookup@/org/openide/util/lookup/InstanceContent.Convertor.html"><code>InstanceContent.Convertor</code></a>.
6.135
6.136 This convertor translates the key to the real instance that the lookup
6.137 client sees, if and when needed. For example, if you have a long list