1.1 --- a/openide.util/apichanges.xml Wed May 04 14:47:22 2005 +0000
1.2 +++ b/openide.util/apichanges.xml Thu May 12 06:29:13 2005 +0000
1.3 @@ -314,40 +314,6 @@
1.4 <class package="org.openide.util" name="HelpCtx"/>
1.5 <issue number="32143"/>
1.6 </change>
1.7 -<change id="settings.separated">
1.8 - <api name="lookup"/>
1.9 - <summary>Support for XML settings fully modularized</summary>
1.10 - <version major="4" minor="26"/>
1.11 - <date day="19" month="3" year="2004"/>
1.12 - <author login="jglick"/>
1.13 - <compatibility binary="incompatible" source="compatible" semantic="compatible" deprecation="no" addition="no" deletion="no" modification="no">
1.14 - <!-- XXX is it worth making a ModuleAutoDeps fix for this? -->
1.15 - <p>
1.16 - Modules using XML settings files should declare a dependency on the
1.17 - separated module in order to guarantee that the functionality will
1.18 - work.
1.19 - </p>
1.20 - </compatibility>
1.21 - <description>
1.22 - <p>
1.23 - Some time ago (NetBeans 3.4), a module called the <a href="http://www.netbeans.org/download/dev/javadoc/SettingsAPI/index.html" shape="rect">Settings
1.24 - API</a> was created to handle persistent settings in customizable
1.25 - formats. The built-in support for
1.26 - <code>-//NetBeans//DTD Session settings 1.0//EN</code>
1.27 - (i.e., <code>*.settings</code> files) was moved to that module and
1.28 - client modules were encouraged to depend on it; but a copy remained in
1.29 - the core just in case. The redundant code has now been removed so
1.30 - anyone using <code>*.settings</code> files should declare in their
1.31 - manifest:
1.32 - </p>
1.33 - <pre xml:space="preserve">OpenIDE-Module-Module-Dependencies: org.netbeans.modules.settings/1 > 1.4</pre>
1.34 - <p>
1.35 - Failure to do so <em>might</em> result in the settings module being
1.36 - disabled or missing, which would prevent <code>*.settings</code> files
1.37 - from functioning.
1.38 - </p>
1.39 - </description>
1.40 - </change>
1.41 <change>
1.42 <api name="util"/>
1.43 <summary>Retrofit of interface Cancellable into RequestProcessor.Task</summary>
1.44 @@ -617,207 +583,6 @@
1.45 </description>
1.46 <class package="org.openide.util" name="RequestProcessor"/>
1.47 </change>
1.48 -<change id="issue-19443-1">
1.49 - <summary>API separation, phase I</summary>
1.50 - <version major="3" minor="14"/>
1.51 - <date day="15" month="10" year="2002"/>
1.52 - <author login="jglick"/>
1.53 - <compatibility binary="compatible" source="incompatible" deprecation="yes" semantic="compatible" addition="no" deletion="no" modification="no">
1.54 - <p>
1.55 - The deprecated classes continue to be available in the module
1.56 - <code>org.openide.deprecated</code> which you may depend on it you
1.57 - cannot remove uses of the deprecated APIs. In order for
1.58 - <code>TopManager.getDefault()</code> to work, you must also require the
1.59 - token <code>org.openide.TopManager</code>, which is provided by an
1.60 - unspecified module. The deprecated API module and its implementation
1.61 - module are autoloads, meaning they will not be loaded unless some
1.62 - module still requires them.
1.63 - </p>
1.64 - <p>
1.65 - Similarly, the Java Hierarchy API was moved to the module
1.66 - <code>org.openide.src</code> which you should depend on in order to use
1.67 - this API.
1.68 - </p>
1.69 - <p>
1.70 - For compatibility, the above three dependencies are added to your module
1.71 - <em>automatically</em> in case it either requests no specific API
1.72 - version at all, or requests an API version prior to 3.14. Modules
1.73 - requesting APIs 3.14 or higher must declare these dependencies
1.74 - explicitly if they in fact need them.
1.75 - </p>
1.76 - </compatibility>
1.77 - <description>
1.78 - <p>
1.79 - Many classes were moved to a separate module,
1.80 - <samp>openide-deprecated.jar</samp>, not available to modules by
1.81 - default. Uses of these classes in modules should be cleaned up whenever
1.82 - possible.
1.83 - </p>
1.84 - <p>
1.85 - Additionally, the entire contents of <code>org.openide.src.*</code> and
1.86 - <code>org.openide.src.nodes.*</code>, as well as
1.87 - <code>org.openide.cookies.SourceCookie</code> and some associated
1.88 - property editors, were moved to a separate module.
1.89 - </p>
1.90 - <p>
1.91 - The most common apparent symptom for module authors will be the absence
1.92 - of <code>TopManager</code>. Most methods in this class have been
1.93 - replaced by newer utility classes in a straightforward manner. See the
1.94 - Upgrade Guide.
1.95 - </p>
1.96 - </description>
1.97 - <issue number="19443"/>
1.98 - <issue number="20898"/>
1.99 - </change>
1.100 -<change id="issue-19443-2">
1.101 - <summary>API separation, phase II</summary>
1.102 - <version major="3" minor="17"/>
1.103 - <date day="1" month="11" year="2002"/>
1.104 - <author login="jglick"/>
1.105 - <compatibility binary="compatible" source="incompatible" modification="yes" semantic="compatible" deprecation="no" addition="no" deletion="no">
1.106 - <p>
1.107 - Module authors using the now-separated APIs will need to adjust their
1.108 - compilation classpaths to include the new JAR files. Modules wishing to
1.109 - use recent APIs and declaring a current openide specification version
1.110 - dependency will need to explicitly declare dependencies on these new
1.111 - APIs if there are any.
1.112 - </p>
1.113 - <p>
1.114 - For compatibility, modules with no declared Open APIs dependency, or
1.115 - declared on a version prior to 3.17, will have their dependencies
1.116 - automatically refined as if to include the declarations:
1.117 - </p>
1.118 - <pre xml:space="preserve">
1.119 -OpenIDE-Module-Module-Dependencies: org.openide.compiler > 1.0,
1.120 - org.openide.execution > 1.0, org.openide.io > 1.0
1.121 -OpenIDE-Module-Requires: org.openide.compiler.CompilationEngine,
1.122 - org.openide.execution.ExecutionEngine, org.openide.windows.IOProvider
1.123 - </pre>
1.124 - <p>
1.125 - And any package dependencies from old modules on
1.126 - <code>org.netbeans.lib.terminalemulator</code> will be converted to
1.127 - module dependencies.
1.128 - </p>
1.129 - </compatibility>
1.130 - <description>
1.131 - <p>
1.132 - Three sections of the Open APIs were split into new autoload modules.
1.133 - </p>
1.134 - <ul>
1.135 - <li>
1.136 - <p>
1.137 - The module <code>org.openide.compiler</code> (version 1.0) contains
1.138 - the Compiler API and some other classes directly related to it.
1.139 - </p>
1.140 - </li>
1.141 - <li>
1.142 - <p>
1.143 - The module <code>org.openide.execution</code> (version 1.0) contains
1.144 - the Execution API and some other classes directly related to it.
1.145 - </p>
1.146 - </li>
1.147 - <li>
1.148 - <p>
1.149 - The module <code>org.openide.io</code> (version 1.0) contains
1.150 - <code>InputOutput</code> and related classes (formerly part of the
1.151 - Window System API, and still physically in the
1.152 - <code>org.openide.windows</code> package).
1.153 - </p>
1.154 - </li>
1.155 - </ul>
1.156 - <p>
1.157 - New modules wishing to use these APIs must declare regular module
1.158 - dependencies on them. Future changes in these APIs will be documented
1.159 - separately.
1.160 - </p>
1.161 - <p>
1.162 - Furthermore, modules wishing to use certain services must
1.163 - <code>OpenIDE-Module-Require</code> them if appropriate:
1.164 - </p>
1.165 - <ul>
1.166 - <li>
1.167 - <p>
1.168 - <code>org.openide.compiler.CompilationEngine</code>, in order to
1.169 - call <code>CompilationEngine.getDefault()</code>, or safely use
1.170 - <code>AbstractCompileAction</code> or one of its subclasses, or
1.171 - call <code>CompilerJob.start()</code>, or use
1.172 - <code>BeanInfo</code>s for Compiler API classes, etc.
1.173 - </p>
1.174 - </li>
1.175 - <li>
1.176 - <p>
1.177 - <code>org.openide.execution.ExecutionEngine</code>, in order to
1.178 - call <code>ExecutionEngine.getDefault()</code>, or safely use
1.179 - <code>ExecuteAction</code>, or call
1.180 - <code>Executor.execute(...)</code>, or use <code>BeanInfo</code>s
1.181 - for Execution API classes, etc.
1.182 - </p>
1.183 - </li>
1.184 - <li>
1.185 - <p>
1.186 - <code>org.openide.windows.IOProvider</code>, in order to call
1.187 - <code>IOProvider.getDefault()</code>.
1.188 - </p>
1.189 - </li>
1.190 - </ul>
1.191 - <p>
1.192 - Other minor changes:
1.193 - </p>
1.194 - <ul>
1.195 - <li>
1.196 - <p>
1.197 - Registration of URL stream handler factories using
1.198 - <code>NbfsStreamHandlerFactory.register(...)</code> is deprecated.
1.199 - Simply create an instance of <code>URLStreamHandlerFactory</code>
1.200 - and add it to Lookup instead.
1.201 - </p>
1.202 - </li>
1.203 - <li>
1.204 - <p>
1.205 - The method <code>FileUtil.nbfsURLStreamHandler</code> was added,
1.206 - but is not intended for use by modules.
1.207 - </p>
1.208 - </li>
1.209 - <li>
1.210 - <p>
1.211 - All uses of <code>ExecInfo</code> are deprecated as they abuse the
1.212 - distinction between Filesystems and the user classpath. Use and
1.213 - override only <code>Executor.execute(DataObject)</code>. Similarly,
1.214 - <code>ThreadExecutor</code> is deprecated for the time being
1.215 - because it suffers from similar problems.
1.216 - </p>
1.217 - </li>
1.218 - <li>
1.219 - <p>
1.220 - Direct use of <code>NbfsURLConnection</code> is deprecated in favor
1.221 - of the more general <code>URLMapper</code> from the Filesystems
1.222 - API.
1.223 - </p>
1.224 - </li>
1.225 - <li>
1.226 - <p>
1.227 - Package dependencies on
1.228 - <code>org.netbeans.lib.terminalemulator</code> must be replaced
1.229 - with module dependencies on a new autoload module
1.230 - <code>org.netbeans.lib.terminalemulator</code> (version 1.0).
1.231 - </p>
1.232 - </li>
1.233 - <li>
1.234 - <p>
1.235 - Several static convenience methods have been added to
1.236 - <code>AbstractCompileAction</code>. Of most interest is
1.237 - <code>prepareJobFor</code>. Module code should no longer assume
1.238 - that <code>DataFolder</code> has a <code>CompilerCookie</code>
1.239 - which recursively compiles the folder and subfolders (according to
1.240 - depth); while it is still true, for reasons of compatibility, new
1.241 - code should use <code>prepareJobFor</code> to create a compiler job
1.242 - from a folder.
1.243 - </p>
1.244 - </li>
1.245 - </ul>
1.246 - </description>
1.247 - <issue number="19443"/>
1.248 - </change>
1.249 <change>
1.250 <api name="util"/>
1.251 <summary>Added helper methods to aid module developers to write code which works correctly with multiple monitors</summary>
2.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
2.2 +++ b/openide.util/arch.xml Thu May 12 06:29:13 2005 +0000
2.3 @@ -0,0 +1,940 @@
2.4 +<?xml version="1.0" encoding="UTF-8"?><!-- -*- sgml-indent-step: 1 -*- -->
2.5 +<!--
2.6 + Sun Public License Notice
2.7 +
2.8 +The contents of this file are subject to the Sun Public License
2.9 +Version 1.0 (the "License"). You may not use this file except in
2.10 +compliance with the License. A copy of the License is available at
2.11 +http://www.sun.com/
2.12 +
2.13 +The Original Code is NetBeans. The Initial Developer of the Original
2.14 +Code is Sun Microsystems, Inc. Portions Copyright 1997-2005 Sun
2.15 +Microsystems, Inc. All Rights Reserved.
2.16 +-->
2.17 +<!DOCTYPE api-answers PUBLIC "-//NetBeans//DTD Arch Answers//EN" "../../nbbuild/antsrc/org/netbeans/nbbuild/Arch.dtd" [
2.18 + <!ENTITY api-questions SYSTEM "../../nbbuild/antsrc/org/netbeans/nbbuild/Arch-api-questions.xml">
2.19 +]>
2.20 +
2.21 +<api-answers
2.22 + question-version="1.25"
2.23 + module="Utilities"
2.24 + author="jtulach@netbeans.org"
2.25 +>
2.26 +
2.27 + &api-questions;
2.28 +
2.29 + <answer id="arch-overall">
2.30 + <p>
2.31 + This module contains general classes needed in NetBeans, extensions to
2.32 + basic JRE contepts, useful methods and other
2.33 + <api group="java" name="UtilitiesAPI" category="official" type="export" url="@TOP@/org/openide/util/doc-files/api.html" />
2.34 + classes.
2.35 + </p>
2.36 +
2.37 + <p>
2.38 + Also this module defines the <a href="@TOP@/org/openide/util/Lookup.html">
2.39 + Lookup</a> which the NetBeans way for dynamic registration
2.40 + and lookup of
2.41 + components in our modularized component system. It allows lookup and discovery
2.42 + of features by description of their interfaces. The classes are devided
2.43 + into two parts. The
2.44 + <api group="java" name="LookupAPI" type="export" category="official" url="@TOP@/org/openide/util/lookup/doc-files/lookup-api.html">
2.45 + allows the discovery</api> and the
2.46 + <api group="java" name="LookupSPI" type="export" category="official" url="@TOP@/org/openide/util/lookup/doc-files/lookup-spi.html">
2.47 + simplifies creation and registration of own lookup objects</api>.
2.48 + </p>
2.49 + </answer>
2.50 +
2.51 +
2.52 + <answer id="arch-quality">
2.53 + <p>
2.54 + There is a lot of unit tests in
2.55 + <a href="http://www.netbeans.org/source/browse/openide/util/test/unit/src/">CVS</a>.
2.56 + </p>
2.57 + </answer>
2.58 +
2.59 + <answer id="arch-time">
2.60 + <p>
2.61 + The module has been around since 1997 and is stilly improved
2.62 + from time to time.
2.63 + </p>
2.64 + </answer>
2.65 +
2.66 +
2.67 +
2.68 + <answer id="arch-usecases">
2.69 +
2.70 + There is a great introduction to Lookup and its usage in its
2.71 + <a href="@TOP@/org/openide/util/Lookup.html">javadoc</a>. Here is just
2.72 + a list of frequently asked or interesting questions slowly expanding as
2.73 + people ask them:
2.74 +
2.75 + <h3>Lookup faq:</h3>
2.76 +
2.77 + <usecase id="lookup-on-certain-platform" name="How to specify that a service in Lookup should be available only on Windows?" >
2.78 +<em><b>Q:</b>
2.79 +Most of the time I specify interfaces that I want to add to the Lookup class in the layer.xml file.
2.80 +But, let's say I have a platform-specific interface (something on Windows only, for instance).</em>
2.81 +<p>
2.82 +<em>
2.83 +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.84 +</em>>
2.85 +</p>
2.86 +In general there are three ways to achieve this.
2.87 +<ul>
2.88 + <li><p>It is possible to write a specific module and enable it only on windows.
2.89 + See <a href="@org-openide-modules@/org/openide/modules/doc-files/api.html#how-os-specific">os specific modules</a> documentation.
2.90 + Then you can put a registration of your instance into your module's
2.91 + <a href="@TOP@/org/openide/util/doc-files/api.html#service-lookup">META-INF/services</a> directory and it
2.92 + will be available only on Windows.</p>
2.93 + </li>
2.94 +
2.95 + <li><p>Another possibility that does not require new module, but which executes
2.96 + a code on startup (which may have performance implications) is to use <code>methodvalue</code>
2.97 + attribute. Register your instance in layer using <code>your-Object.instance</code> file
2.98 + as described at
2.99 + <a href="@TOP@/org/openide/util/doc-files/api.html#ido-methodvalue">services
2.100 + </a> documentation and in your factory method either return the instance
2.101 + your want or <code>null</code> depending on result of <a href="@TOP@/org/openide/util/Utilities.html#isWindows()">
2.102 + Utilities.isWindows()</a> call.</p>
2.103 + </li>
2.104 + <li>
2.105 + <p>
2.106 + In some cases, the interface for which you will register an implementation permits a
2.107 + no-operation semantics. For example, <code>InstalledFileLocator.locate(...)</code> can
2.108 + return a valid <code>File</code>, or null. You could always register an
2.109 + <code>InstalledFileLocator</code> instance yet disable it on non-Windows platforms
2.110 + (always returning null).
2.111 + </p>
2.112 + </li>
2.113 +</ul>
2.114 +
2.115 + </usecase>
2.116 +
2.117 + <usecase id="lookup-extension-point" name="How shall I write an extension point for my module?" >
2.118 + <p>
2.119 + <em><b>Q:</b>
2.120 + I have more modules one of them providing the core functionality and
2.121 + few more that wish to extend it. What is the right way to do it?
2.122 + How does the Netbeans platform declare such extension point?
2.123 + </em>
2.124 + </p>
2.125 +
2.126 + <p>
2.127 +
2.128 + Start with declaring an extension interface in your
2.129 + core module and put it into the module's <em>public packages</em>. Imagine
2.130 + for example that the core module is in JAR file <code>org-my-netbeans-coremodule.jar</code>
2.131 + and already contains in manifests line like
2.132 + <code>OpenIDE-Module: org.my.netbeans.coremodule/1</code> and wants
2.133 + to display various tips of the day provided by other modules and thus defines:
2.134 + </p><pre>
2.135 +<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.136 +
2.137 +<span class="java-keywords">public</span> <span class="java-keywords">interface</span> <span class="java-identifier">TipsOfTheDayProvider</span> <span class="java-operators">{</span>
2.138 + <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.139 +<span class="java-operators">}</span>
2.140 +</pre><p>
2.141 + And in its manifest adds line
2.142 + <code>OpenIDE-Module-Public-Packages: org.my.netbeans.coremodule.*</code>
2.143 + to specify that this package contains exported API and shall be
2.144 + accessible to other modules.
2.145 + </p>
2.146 + <p>
2.147 + When the core module is about to display the tip of the day it can ask
2.148 + the system for all registered instances of the <code>TipsOfTheDayProvider</code>,
2.149 + randomly select one of them:
2.150 + </p><pre>
2.151 +<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.152 +<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.153 +<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.154 +
2.155 +<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.156 +<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.157 +<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.158 +<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.159 +</pre><p>
2.160 + and then display the tip. Simple, trivial, just by the usage of
2.161 + <a href="@TOP@org/openide/util/Lookup.html">Lookup</a> interface once
2.162 + creates a registry that other modules can enhance. But such enhancing
2.163 + of course requires work on the other side. Each module that would like
2.164 + to register its <code>TipsOfTheDayProvider</code> needs to depend on the
2.165 + core module - add
2.166 + <code>OpenIDE-Module-Module-Dependencies: org.my.netbeans.coremodule/1</code>
2.167 + into its manifest and write a class with its own implementation of the
2.168 + provider:</p><pre>
2.169 +<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.170 +
2.171 +<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.172 + <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.173 + <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.174 + <span class="java-operators">}</span>
2.175 +<span class="java-operators">}</span>
2.176 +</pre><p>
2.177 + Then, the only necessary thing is to register such class by using the
2.178 + J2SE standard <api name="ProviderRegistrationMechanism"
2.179 + type="import"
2.180 + category="standard"
2.181 + group="java" /> into plain text file
2.182 + <code>META-INF/services/org.my.netbeans.coremodule.TipsOfTheDayProvider</code>
2.183 + in the module JAR containing just one line: </p><pre>
2.184 +org.my.netbeans.extramodule.ExtraTip
2.185 +</pre><p>
2.186 + and your modules are now ready to communicate
2.187 + using your own <em>extension point</em>.
2.188 + </p>
2.189 +
2.190 + </usecase>
2.191 +
2.192 +
2.193 + </answer>
2.194 +
2.195 +
2.196 +
2.197 + <answer id="arch-what">
2.198 + <p>
2.199 + Described in the <a href="@TOP@/architecture-summary.html#answer-arch-overall">overall</a> answer.
2.200 + </p>
2.201 + </answer>
2.202 +
2.203 +
2.204 +
2.205 + <answer id="compat-i18n">
2.206 + <p>
2.207 + There is not much things to localize in this module, so it is properly localized.
2.208 + 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.209 + which is similar to localization but also supports changes of resorces
2.210 + for application build on top of NetBeans. This is handled by our
2.211 + class <a href="@TOP@/org/openide/util/NbBundle.html">NbBundle</a> which
2.212 + reimplements the JDK's standard <a href="@JDK@/java/util/ResourceBundle.html">ResourceBundle</a>
2.213 + to to take branding into the consideration.
2.214 + </api>.
2.215 + </p>
2.216 + </answer>
2.217 +
2.218 +
2.219 +
2.220 + <answer id="compat-standards">
2.221 + <p>
2.222 + The default lookup registration follows the JDK's
2.223 + <api name="ProviderRegistrationMechanism"
2.224 + type="import"
2.225 + category="standard"
2.226 + url="http://java.sun.com/j2se/1.3/docs/guide/jar/jar.html#Provider%20Configuration%20File"
2.227 + group="java"
2.228 + />
2.229 + but enhances it to also support the
2.230 + <api
2.231 + name="ProviderRegistrationRemoval"
2.232 + type="export"
2.233 + category="devel"
2.234 + url="@TOP@/org/openide/util/doc-files/api.html#service-lookup"
2.235 + group="java"
2.236 + />.
2.237 + </p>
2.238 + </answer>
2.239 +
2.240 + <answer id="compat-version">
2.241 + <p>
2.242 + This module has no settings.
2.243 + </p>
2.244 + </answer>
2.245 +
2.246 +
2.247 +
2.248 + <answer id="dep-jre">
2.249 + <p>
2.250 + Currently JRE 1.4 is needed.
2.251 + </p>
2.252 + </answer>
2.253 +
2.254 +
2.255 +
2.256 + <answer id="dep-jrejdk">
2.257 + <p>
2.258 + JRE is enough.
2.259 + </p>
2.260 + </answer>
2.261 +
2.262 +
2.263 + <answer id="dep-nb">
2.264 + <p>
2.265 + This module is independent of other NetBeans modules and can be used
2.266 + independently. For better interaction with UI parts of NetBeans it however
2.267 + indirectly communicates with <a href="@org-openide-awt@/overview-summary.html">UI Utilities</a>
2.268 + module using <api name="AWTBridge" category="private" group="java" type="export"
2.269 + url="http://www.netbeans.org/source/browse/openide/util/src/org/netbeans/modules/openide/util/AWTBridge.java">
2.270 + a class that is looked up in <a href="@TOP@/org/openide/util/Lookup.html#getDefault()">Lookup.getDefault()</a>
2.271 + and if registered can provide better UI elements for <a href="@JDK@/javax/swing/Action.html">Action</a>s.
2.272 + </api>
2.273 +
2.274 + </p>
2.275 + </answer>
2.276 +
2.277 + <answer id="dep-non-nb">
2.278 + <p>
2.279 + Reexports XML APIs so needs some XML parser implementation, but as one
2.280 + is provided in any 1.4 java, it in fact has no dependencies except on JRE.
2.281 + </p>
2.282 + </answer>
2.283 +
2.284 + <answer id="dep-platform">
2.285 + <p>
2.286 + Platform independent.
2.287 + </p>
2.288 + </answer>
2.289 +
2.290 +
2.291 + <answer id="deploy-dependencies">
2.292 + <p>
2.293 + OpenIDE-Module-Module-Dependencies: org.openide.util > @SPECIFICATION-VERSION@
2.294 + </p>
2.295 + </answer>
2.296 +
2.297 +
2.298 +
2.299 + <answer id="deploy-jar">
2.300 + <p>
2.301 + <api category="devel" group="java.io.File" name="FileLocation" type="export" >
2.302 + the JAR file is located in platform cluster under <code>lib/org-openide-util.jar</code>
2.303 + </api>.
2.304 + </p>
2.305 + </answer>
2.306 +
2.307 +
2.308 +
2.309 + <answer id="deploy-nbm">
2.310 + <p>
2.311 + No reason to not deploy nbm.
2.312 + </p>
2.313 + </answer>
2.314 +
2.315 +
2.316 + <answer id="deploy-packages">
2.317 + <p>
2.318 + Yes, public packages declared.
2.319 + </p>
2.320 + </answer>
2.321 +
2.322 +
2.323 +
2.324 + <answer id="deploy-shared">
2.325 + <p>
2.326 + Module is on real java classpath and as such it has to be in the shared directory.
2.327 + </p>
2.328 + </answer>
2.329 +
2.330 +
2.331 + <answer id="exec-ant-tasks">
2.332 + <p>
2.333 + No.
2.334 + </p>
2.335 + </answer>
2.336 +
2.337 +
2.338 +
2.339 + <answer id="exec-classloader">
2.340 + <p>
2.341 + No, we do not create own classloader.
2.342 + </p>
2.343 + </answer>
2.344 +
2.345 +
2.346 +
2.347 +<!--
2.348 + <question id="exec-component" when="impl">
2.349 + Is execution of your code influenced by any (string) property
2.350 + of any of your components?
2.351 +
2.352 + <hint>
2.353 + Often <code>JComponent.getClientProperty</code>, <code>Action.getValue</code>
2.354 + or <code>PropertyDescriptor.getValue</code>, etc. are used to influence
2.355 + a behavior of some code. This of course forms an interface that should
2.356 + be documented. Also if one depends on some interface that an object
2.357 + implements (<code>component instanceof Runnable</code>) that forms an
2.358 + API as well.
2.359 + </hint>
2.360 + </question>
2.361 +-->
2.362 + <answer id="exec-component">
2.363 + <ul>
2.364 + <li><api name="HelpID" category="standard" group="property" type="export" url="@TOP@/org/openide/util/HelpCtx.html">
2.365 + read from <a href="@JDK@/javax/swing/JComponent.html">JComponent</a>.getClientProperty
2.366 + to simulate the standard javahelp behaviour and extract the help id for given component.
2.367 + </api>
2.368 + </li>
2.369 +
2.370 + <li><api name="iconBase" category="standard" group="property" type="import" >
2.371 + <a href="@TOP@/org/openide/util/actions/SystemAction.html">SystemAction</a>
2.372 + reacts to expected requests from <a href="@org-openide-awt@/overview-summary.html">UI Utilities</a>
2.373 + module for <code>iconBase</code> property by returning value based on its
2.374 + result of its <code>iconResource()</code> method.
2.375 + </api>
2.376 + </li>
2.377 +
2.378 + <li>
2.379 + <api name="org.openide.util.SharedClassObject.initialize" category="private" group="property" type="export">
2.380 + For purposes of
2.381 + <a href="@org-openide-options@/org/openide/options/SystemOption.html">SystemOption</a>
2.382 + the
2.383 + <a href="@TOP@/org/openide/util/SharedClassObject.html">SharedClassObject</a>
2.384 + handles
2.385 + <code>getProperty ("org.openide.util.SharedClassObject.initialize")</code>
2.386 + in a special way, by returning
2.387 + <code>null</code> if initialization is not running and <code>Boolean.TRUE</code> if
2.388 + it is.
2.389 + </api>
2.390 + </li>
2.391 +
2.392 + <li><api name="OpenIDE-Transmodal-Action" category="devel" group="property" type="export" >
2.393 + <a href="@TOP@/org/openide/util/actions/CallbackSystemAction.html">CallbackSystemAction</a>
2.394 + checks whether <code>action.getValue("OpenIDE-Transmodal-Action")</code>
2.395 + returns <code>Boolean.TRUE</code> to enable it in dialogs, otherwise
2.396 + the action is disabled when there is an open dialog.
2.397 + </api>
2.398 + </li>
2.399 +
2.400 +
2.401 + </ul>
2.402 + </answer>
2.403 +
2.404 +
2.405 +
2.406 +<!--
2.407 + <question id="exec-introspection" when="impl">
2.408 + Does your module use any kind of runtime type information (<code>instanceof</code>,
2.409 + work with <code>java.lang.Class</code>, etc.)?
2.410 + <hint>
2.411 + Check for cases when you have an object of type A and you also
2.412 + expect it to (possibly) be of type B and do some special action. That
2.413 + should be documented. The same applies on operations in meta-level
2.414 + (Class.isInstance(...), Class.isAssignableFrom(...), etc.).
2.415 + </hint>
2.416 + </question>
2.417 +-->
2.418 + <answer id="exec-introspection">
2.419 + <p>
2.420 + <a href="@TOP@/org/openide/util/Utilities.html">Utilities</a> provide wrapper
2.421 + for java beans introspection.
2.422 + </p>
2.423 + </answer>
2.424 +
2.425 +
2.426 +
2.427 + <answer id="exec-privateaccess">
2.428 + <p>
2.429 + No.
2.430 + </p>
2.431 + </answer>
2.432 +
2.433 + <answer id="exec-process">
2.434 + <p>
2.435 + No external processes executed.
2.436 + </p>
2.437 + </answer>
2.438 +
2.439 +
2.440 + <answer id="exec-property">
2.441 + <ul>
2.442 + <li><api type="export" group="property" name="netbeans.screen.insets" category="private">
2.443 + Influences results of Utilities.getUsableScreenBounds</api>.</li>
2.444 + <li><api type="export" group="property" name="netbeans.taskbar.height" category="private">
2.445 + Influences results of Utilities.getUsableScreenBounds</api>.</li>
2.446 + <li>
2.447 + <api type='import' group="property" name="line.separator" category="standard" >
2.448 + used on few places
2.449 + </api>.
2.450 + </li>
2.451 +
2.452 + <li>
2.453 + <api type="export" group="property" name="org.openide.util.Lookup" category="devel">
2.454 + checked by the initialization of the
2.455 + <a href="@TOP@/org/openide/util/Lookup.html#getDefault()">Lookup.getDefault()</a>
2.456 + and can
2.457 + contain name of a class that extends <code>org.openide.util.Lookup</code> and
2.458 + has public constructor, that should be instantiated and returned from
2.459 + <a href="@TOP@/org/openide/util/Lookup.html#getDefault()">Lookup.getDefault()</a>
2.460 + the class will be loaded by
2.461 + <a href="@JDK@/java/lang/Thread.html#getContextClassLoader()">
2.462 + Thread.currentThread().getContextClassLoader()</a>
2.463 + classloader the first time <code>Lookup.getDefault</code> is invoked.
2.464 + <p/>
2.465 + The property can also contain value <code>"-"</code> which means to completely
2.466 + disable the lookup instantiation and return <a href="@TOP@/org/openide/util/Lookup.html#EMPTY">Lookup.EMPTY</a>
2.467 + from <a href="@TOP@/org/openide/util/Lookup.html#getDefault()">Lookup.getDefault()</a>.
2.468 + <p/>
2.469 + If the property is unspecified, the default <code>MetaInfServicesLookup</code>
2.470 + is constructed for <code>Thread.currentThread().getContextclassLoader()</code>
2.471 + that implements the <a href="#answer-compat-standards">JDK's standard</a>. If, by
2.472 + a chance an instance of
2.473 + <a href="@TOP@/org/openide/util/Lookup.Provider.html">Lookup.Provider</a>
2.474 + is found
2.475 + in there, its lookup is returned as result. Otherwise the <code>MetaInfServicesLookup</code>
2.476 + is the result of <a href="@TOP@/org/openide/util/Lookup.html#getDefault()">Lookup.getDefault()</a>.
2.477 + </api>
2.478 + </li>
2.479 +
2.480 + </ul>
2.481 + </answer>
2.482 +
2.483 +
2.484 +
2.485 +<!--
2.486 + <question id="exec-reflection" when="impl">
2.487 + Does your code use Java Reflection to execute other code?
2.488 + <hint>
2.489 + This usually indicates a missing or insufficient API in the other
2.490 + part of the system. If the other side is not aware of your dependency
2.491 + this contract can be easily broken.
2.492 + </hint>
2.493 + </question>
2.494 +-->
2.495 + <answer id="exec-reflection">
2.496 + <p>
2.497 + <api category="devel" group="java" name="SharedClassObject.setAccessible" type="export" url="@TOP@/org/openide/util/SharedClassObject.html">
2.498 + used to instantiate subclasses.
2.499 + </api>.
2.500 + <api category="devel" group="java" name="WeakListener.setAccessible" type="export" url="@TOP@/org/openide/util/WeakListeners.html">
2.501 + used to call the remove method using reflection
2.502 + </api>.
2.503 + <api category="devel" group="java" name="Lookups.metaInfServices" type="export" url="@TOP@/org/openide/util/lookup/Lookups.html#metaInfServices(java.lang.ClassLoader)">
2.504 + calls constructor of registered classes using reflection
2.505 + </api>.
2.506 + <api category="private" group="java" name="ActionManagerInvocation" type="import" >
2.507 + because of the API separation, <a href="@TOP@/org/openide/util/actions/CallableSystemAction.html">CallableSystemAction</a> uses reflection
2.508 + when looking for <a href="@org-openide-actions@/org/openide/actions/ActionManager.html">org.openide.actions.ActionManager</a> implementation.
2.509 + </api>.
2.510 +
2.511 + </p>
2.512 + </answer>
2.513 +
2.514 +
2.515 +
2.516 +<!--
2.517 + <question id="exec-threading" when="impl">
2.518 + What threading models, if any, does your module adhere to?
2.519 + <hint>
2.520 + If your module calls foreign APIs which have a specific threading model,
2.521 + indicate how you comply with the requirements for multithreaded access
2.522 + (synchronization, mutexes, etc.) applicable to those APIs.
2.523 + If your module defines any APIs, or has complex internal structures
2.524 + that might be used from multiple threads, declare how you protect
2.525 + data against concurrent access, race conditions, deadlocks, etc.,
2.526 + and whether such rules are enforced by runtime warnings, errors, assertions, etc.
2.527 + Examples: a class might be non-thread-safe (like Java Collections); might
2.528 + be fully thread-safe (internal locking); might require access through a mutex
2.529 + (and may or may not automatically acquire that mutex on behalf of a client method);
2.530 + might be able to run only in the event queue; etc.
2.531 + Also describe when any events are fired: synchronously, asynchronously, etc.
2.532 + Ideas: <a href="http://core.netbeans.org/proposals/threading/index.html#recommendations">Threading Recommendations</a> (in progress)
2.533 + </hint>
2.534 + </question>
2.535 +-->
2.536 + <answer id="exec-threading">
2.537 + <p>
2.538 + XXX no answer for exec-threading
2.539 + </p>
2.540 + </answer>
2.541 +
2.542 +
2.543 +
2.544 + <answer id="format-clipboard">
2.545 + <p>
2.546 + <a href="@TOP@/org/openide/util/datatransfer/MultiTransferObject.html">MultiTransferObject</a> can be
2.547 + used in <a href="@JDK@/java/awt/datatransfer/Transferable.html">Transferable</a> to represent content
2.548 + composed of multiple independent
2.549 + <a href="@JDK@/java/awt/datatransfer/Transferable.html">Transferable</a>s.
2.550 + </p>
2.551 + </answer>
2.552 +
2.553 +
2.554 +
2.555 + <answer id="format-dnd">
2.556 + <p>
2.557 + The same as for clipboard.
2.558 + </p>
2.559 + </answer>
2.560 +
2.561 + <answer id="format-types">
2.562 + <p>
2.563 + The <a href="http://java.sun.com/j2se/1.3/docs/guide/jar/jar.html#Provider%20Configuration%20File">META-INF/services/...</a> files.
2.564 + <api name="TranslateNames" category="official" type="export" group="java.io.File"
2.565 + url="@TOP@/org/openide/util/Utilities.html#translate(java.lang.String)">
2.566 + <a href="@TOP@/org/openide/util/Utilities.html#translate(java.lang.String)">Utilities.translate</a>
2.567 + reads <code>META-INF/netbeans/translate.names</code> files from JARs</api>.
2.568 + </p>
2.569 + </answer>
2.570 +
2.571 +
2.572 +
2.573 + <answer id="lookup-lookup">
2.574 + <ul>
2.575 + <li><api name="LookupInitializationLookup" category="devel" group="lookup" type="export" url="#property-org.openide.util.Lookup">
2.576 + during
2.577 + initialization of the <a href="@TOP@/org/openide/util/Lookup.html#getDefault()">Lookup.getDefault()</a>
2.578 + the <a href="@TOP@/org/openide/util/Lookup.Provider.html">Lookup.Provider</a>
2.579 + is being searched</api>.
2.580 + </li>
2.581 +
2.582 + <li><api name="LookupSharedClassObject" category="devel" group="lookup" type="export">
2.583 + singleton subclasses of <a href="@TOP@/org/openide/util/SharedClassObject.html">SharedClassObject</a>
2.584 + are searched for using Lookup.
2.585 + </api>.</li>
2.586 +
2.587 + <li><api name="LookupContextGlobalProvider" category="stable" group="lookup" type="export">
2.588 + <a href="@TOP@/org/openide/util/Utilities.html#actionsGlobalContext()">actionsGlobalContext</a>
2.589 + searches for <a href="@TOP@/org/openide/util/ContextGlobalProvider.html">ContextGlobalProvider</a> in
2.590 + <a href="@TOP@/org/openide/util/Lookup.html#getDefault()">Lookup.getDefault()</a>.
2.591 + The provider is usually provided by <a href="@org-openide-windows@/overview-summary.html">window
2.592 + system implementation</a>.
2.593 + </api>.</li>
2.594 +
2.595 + <li><api name="LookupEntityCatalog" category="devel" group="lookup" type="export">
2.596 + <a href="@TOP@/org/openide/xml/EntityCatalog.html">EntityCatalog</a>
2.597 + delegates its methods to all instances of <a href="@TOP@/org/openide/xml/EntityCatalog.html">EntityCatalog</a>s
2.598 + found in Lookup
2.599 + </api>.</li>
2.600 +
2.601 + <li><api name="LookupErrorManager" category="devel" group="lookup" type="export">
2.602 + <a href="@TOP@/org/openide/ErrorManager.html">ErrorManager</a>
2.603 + delegates its methods to all instances of <a href="@TOP@/org/openide/ErrorManager.html">ErrorManager</a>s
2.604 + found in Lookup
2.605 + </api>.</li>
2.606 +
2.607 + <li><api name="LookupClassLoader" category="devel" group="lookup" type="export">
2.608 + Nearly all resource looking functions and reflective code
2.609 + uses <a href="@JDK@/java/lang/ClassLoader.html">ClassLoader</a>
2.610 + obtained from <a href="@TOP@/org/openide/util/Lookup.html#getDefault()">Lookup.getDefault()</a>
2.611 + for loading system wide resources.
2.612 + </api>.</li>
2.613 +
2.614 + </ul>
2.615 + </answer>
2.616 +
2.617 +
2.618 +
2.619 +<!--
2.620 + <question id="lookup-register" when="final">
2.621 + Do you register anything into lookup for other code to find?
2.622 + <hint>
2.623 + Do you register using layer file or using <code>META-INF/services</code>?
2.624 + Who is supposed to find your component?
2.625 + </hint>
2.626 + </question>
2.627 +-->
2.628 + <answer id="lookup-register">
2.629 + <p>
2.630 + No.
2.631 + </p>
2.632 + </answer>
2.633 +
2.634 +
2.635 +
2.636 +<!--
2.637 + <question id="lookup-remove" when="final">
2.638 + Do you remove entries of other modules from lookup?
2.639 + <hint>
2.640 + Why? Of course, that is possible, but it can be dangerous. Is the module
2.641 + your are masking resource from aware of what you are doing?
2.642 + </hint>
2.643 + </question>
2.644 +-->
2.645 + <answer id="lookup-remove">
2.646 + <p>
2.647 + No.
2.648 + </p>
2.649 + </answer>
2.650 +
2.651 +
2.652 +
2.653 +<!--
2.654 + <question id="perf-exit" when="final">
2.655 + Does your module run any code on exit?
2.656 + </question>
2.657 +-->
2.658 + <answer id="perf-exit">
2.659 + <p>
2.660 + Nothing.
2.661 + </p>
2.662 + </answer>
2.663 +
2.664 +
2.665 +
2.666 +<!--
2.667 + <question id="perf-huge_dialogs" when="final">
2.668 + Does your module contain any dialogs or wizards with a large number of
2.669 + GUI controls such as combo boxes, lists, trees, or text areas?
2.670 + </question>
2.671 +-->
2.672 + <answer id="perf-huge_dialogs">
2.673 + <p>
2.674 + No.
2.675 + </p>
2.676 + </answer>
2.677 +
2.678 +
2.679 +
2.680 +<!--
2.681 + <question id="perf-limit" when="init">
2.682 + Are there any hard-coded or practical limits in the number or size of
2.683 + elements your code can handle?
2.684 + </question>
2.685 +-->
2.686 + <answer id="perf-limit">
2.687 + <p>
2.688 + The default implementation of the <code>MetaInfServicesLookup</code> just
2.689 + keeps hashmap between queried classes and their implementations. The amount
2.690 + of memory is linear to amount of registered classes, but of course we
2.691 + are not counting the memory occupied by the instances which the lookup
2.692 + creates, that can be arbitrary.
2.693 + </p>
2.694 + </answer>
2.695 +
2.696 +
2.697 +
2.698 +<!--
2.699 + <question id="perf-mem" when="final">
2.700 + How much memory does your component consume? Estimate
2.701 + with a relation to the number of windows, etc.
2.702 + </question>
2.703 +-->
2.704 + <answer id="perf-mem">
2.705 + <p>
2.706 + There are no big data structures. The amount of memory occupied by
2.707 + instances of <a href="@TOP@/org/openide/util/lookup/AbstractLookup.html">AbstractLookup</a>
2.708 + is measured by unit tests.
2.709 + </p>
2.710 + </answer>
2.711 +
2.712 +
2.713 +
2.714 +<!--
2.715 + <question id="perf-menus" when="final">
2.716 + Does your module use dynamically updated context menus, or
2.717 + context-sensitive actions with complicated and slow enablement logic?
2.718 + <hint>
2.719 + If you do a lot of tricks when adding actions to regular or context menus, you can significantly
2.720 + slow down display of the menu, even when the user is not using your action. Pay attention to
2.721 + actions you add to the main menu bar, and to context menus of foreign nodes or components. If
2.722 + the action is conditionally enabled, or changes its display dynamically, you need to check the
2.723 + impact on performance. In some cases it may be more appropriate to make a simple action that is
2.724 + always enabled but does more detailed checks in a dialog if it is actually run.
2.725 + </hint>
2.726 + </question>
2.727 +-->
2.728 + <answer id="perf-menus">
2.729 + <p>
2.730 + There are no menus.
2.731 + </p>
2.732 + </answer>
2.733 +
2.734 +
2.735 +
2.736 +<!--
2.737 + <question id="perf-progress" when="final">
2.738 + Does your module execute any long-running tasks?
2.739 +
2.740 + <hint>Long running tasks should never block
2.741 + AWT thread as it badly hurts the UI
2.742 + <a href="http://performance.netbeans.org/responsiveness/issues.html">
2.743 + responsiveness</a>.
2.744 + Tasks like connecting over
2.745 + network, computing huge amount of data, compilation
2.746 + be done asynchronously (for example
2.747 + using <code>RequestProcessor</code>), definitively it should
2.748 + not block AWT thread.
2.749 + </hint>
2.750 + </question>
2.751 +-->
2.752 + <answer id="perf-progress">
2.753 + <p>
2.754 + Actions declared as <a href="@TOP@/org/openide/util/actions/CallableSystemAction.html#asynchronous()">CallableSystemAction.asynchronous()</a>
2.755 + are executed outside of AWT thread on a dedicated request processor one.
2.756 + </p>
2.757 + </answer>
2.758 +
2.759 +
2.760 +
2.761 +<!--
2.762 + <question id="perf-scale" when="init">
2.763 + Which external criteria influence the performance of your
2.764 + program (size of file in editor, number of files in menu,
2.765 + in source directory, etc.) and how well your code scales?
2.766 + <hint>
2.767 + Please include some estimates, there are other more detailed
2.768 + questions to answer in later phases of implementation.
2.769 + </hint>
2.770 + </question>
2.771 +-->
2.772 + <answer id="perf-scale">
2.773 + <p>
2.774 + Lookup code scales linearily.
2.775 + </p>
2.776 + </answer>
2.777 +
2.778 +
2.779 +
2.780 +<!--
2.781 + <question id="perf-spi" when="init">
2.782 + How the performance of the plugged in code will be enforced?
2.783 + <hint>
2.784 + If you allow foreign code to be plugged into your own module, how
2.785 + do you enforce that it will behave correctly and quickly and will not
2.786 + negatively influence the performance of your own module?
2.787 + </hint>
2.788 + </question>
2.789 +-->
2.790 + <answer id="perf-spi">
2.791 + <p>
2.792 + No enforcing is done.
2.793 + </p>
2.794 + </answer>
2.795 +
2.796 +
2.797 +
2.798 +<!--
2.799 + <question id="perf-startup" when="final">
2.800 + Does your module run any code on startup?
2.801 + </question>
2.802 +-->
2.803 + <answer id="perf-startup">
2.804 + <p>
2.805 + No.
2.806 + </p>
2.807 + </answer>
2.808 +
2.809 +
2.810 +
2.811 +<!--
2.812 + <question id="perf-wakeup" when="final">
2.813 + Does any piece of your code wake up periodically and do something
2.814 + even when the system is otherwise idle (no user interaction)?
2.815 + </question>
2.816 +-->
2.817 + <answer id="perf-wakeup">
2.818 + <p>
2.819 + No.
2.820 + </p>
2.821 + </answer>
2.822 +
2.823 +
2.824 +
2.825 +<!--
2.826 + <question id="resources-file" when="final">
2.827 + Does your module use <code>java.io.File</code> directly?
2.828 +
2.829 + <hint>
2.830 + NetBeans provide a logical wrapper over plain files called
2.831 + <code>org.openide.filesystems.FileObject</code> that
2.832 + provides uniform access to such resources and is the preferred
2.833 + way that should be used. But of course there can be situations when
2.834 + this is not suitable.
2.835 + </hint>
2.836 + </question>
2.837 +-->
2.838 + <answer id="resources-file">
2.839 + <p>
2.840 + No.
2.841 + </p>
2.842 + </answer>
2.843 +
2.844 +
2.845 +
2.846 +<!--
2.847 + <question id="resources-layer" when="final">
2.848 + Does your module provide own layer? Does it create any files or
2.849 + folders in it? What it is trying to communicate by that and with which
2.850 + components?
2.851 +
2.852 + <hint>
2.853 + NetBeans allows automatic and declarative installation of resources
2.854 + by module layers. Module register files into appropriate places
2.855 + and other components use that information to perform their task
2.856 + (build menu, toolbar, window layout, list of templates, set of
2.857 + options, etc.).
2.858 + </hint>
2.859 + </question>
2.860 +-->
2.861 + <answer id="resources-layer">
2.862 + <p>
2.863 + No.
2.864 + </p>
2.865 + </answer>
2.866 +
2.867 +
2.868 +
2.869 +<!--
2.870 + <question id="resources-mask" when="final">
2.871 + Does your module mask/hide/override any resources provided by other modules in
2.872 + their layers?
2.873 +
2.874 + <hint>
2.875 + If you mask a file provided by another module, you probably depend
2.876 + on that and do not want the other module to (for example) change
2.877 + the file's name. That module shall thus make that file available as an API
2.878 + of some stability category.
2.879 + </hint>
2.880 + </question>
2.881 +-->
2.882 + <answer id="resources-mask">
2.883 + <p>
2.884 + No.
2.885 + </p>
2.886 + </answer>
2.887 +
2.888 +
2.889 +
2.890 +<!--
2.891 + <question id="resources-read" when="final">
2.892 + Does your module read any resources from layers? For what purpose?
2.893 +
2.894 + <hint>
2.895 + As this is some kind of intermodule dependency, it is a kind of API.
2.896 + Please describe it and classify according to
2.897 + <a href="http://openide.netbeans.org/tutorial/api-design.html#categories">
2.898 + common stability categories</a>.
2.899 + </hint>
2.900 + </question>
2.901 +-->
2.902 + <answer id="resources-read">
2.903 + <p>
2.904 + No.
2.905 + </p>
2.906 + </answer>
2.907 +
2.908 +
2.909 +
2.910 +<!--
2.911 + <question id="security-grant" when="final">
2.912 + Does your code grant additional rights to some other code?
2.913 + <hint>Avoid using a class loader that adds extra
2.914 + permissions to loaded code unless really necessary.
2.915 + Also note that your API implementation
2.916 + can also expose unneeded permissions to enemy code by
2.917 + calling AccessController.doPrivileged().</hint>
2.918 + </question>
2.919 +-->
2.920 + <answer id="security-grant">
2.921 + <p>
2.922 + No security permitions manipulated.
2.923 + </p>
2.924 + </answer>
2.925 +
2.926 +
2.927 +
2.928 +<!--
2.929 + <question id="security-policy" when="final">
2.930 + Does your functionality require modifications to the standard policy file?
2.931 + <hint>Your code might pass control to third-party code not
2.932 + coming from trusted domains. This could be code downloaded over the
2.933 + network or code coming from libraries that are not bundled
2.934 + with NetBeans. Which permissions need to be granted to which domains?</hint>
2.935 + </question>
2.936 +-->
2.937 + <answer id="security-policy">
2.938 + <p>
2.939 + No security permissions manipulated.
2.940 + </p>
2.941 + </answer>
2.942 +
2.943 +</api-answers>
3.1 --- a/openide.util/nbproject/project.properties Wed May 04 14:47:22 2005 +0000
3.2 +++ b/openide.util/nbproject/project.properties Thu May 12 06:29:13 2005 +0000
3.3 @@ -12,7 +12,7 @@
3.4 module.jar.dir=lib
3.5 javadoc.title=Utilities API
3.6 javadoc.main.page=org/openide/util/doc-files/api.html
3.7 -javadoc.arch=${basedir}/../arch/arch-openide-utilities.xml
3.8 +javadoc.arch=${basedir}/arch.xml
3.9 javadoc.apichanges=${basedir}/apichanges.xml
3.10 #javadoc.check.failonerror=true
3.11
4.1 --- a/openide.util/src/org/openide/package.html Wed May 04 14:47:22 2005 +0000
4.2 +++ b/openide.util/src/org/openide/package.html Thu May 12 06:29:13 2005 +0000
4.3 @@ -13,7 +13,7 @@
4.4
4.5 <html>
4.6 <body>
4.7 -Provides <a href="ErrorManager.html">ErrorManager</a> - the central place for logging and
4.8 +Provides <a href="@TOP@/org/openide/ErrorManager.html">ErrorManager</a> - the central place for logging and
4.9 reproting failures in <em>NetBeans</em> based system.
4.10 </body>
4.11 </html>
5.1 --- a/openide.util/src/org/openide/util/Lookup.java Wed May 04 14:47:22 2005 +0000
5.2 +++ b/openide.util/src/org/openide/util/Lookup.java Thu May 12 06:29:13 2005 +0000
5.3 @@ -32,11 +32,11 @@
5.4 * <p>
5.5 * For a general talk about the idea behind the lookup pattern please see
5.6 * <UL>
5.7 - * <LI><a href="http://openide.netbeans.org/lookup/">The Solution to Comunication Between Components</a>
5.8 + * <LI><a href="lookup/doc-files/index.html">The Solution to Comunication Between Components</a>
5.9 * page
5.10 - * <LI>the introduction to the <a href="http://openide.netbeans.org/lookup/lookup-api.html">lookup API via
5.11 + * <LI>the introduction to the <a href="lookup/doc-files/lookup-api.html">lookup API via
5.12 * use cases</a>
5.13 - * <LI>the examples of <a href="http://openide.netbeans.org/lookup/lookup-spi.html">how to write your own lookup</a>
5.14 + * <LI>the examples of <a href="lookup/doc-files/lookup-spi.html">how to write your own lookup</a>
5.15 * </UL>
5.16 *
5.17 * @see org.openide.util.lookup.AbstractLookup
6.1 --- a/openide.util/src/org/openide/util/doc-files/api.html Wed May 04 14:47:22 2005 +0000
6.2 +++ b/openide.util/src/org/openide/util/doc-files/api.html Thu May 12 06:29:13 2005 +0000
6.3 @@ -7,7 +7,7 @@
6.4 - http://www.sun.com/
6.5 -
6.6 - The Original Code is NetBeans. The Initial Developer of the Original
6.7 - - Code is Sun Microsystems, Inc. Portions Copyright 1997-2000 Sun
6.8 + - Code is Sun Microsystems, Inc. Portions Copyright 1997-2005 Sun
6.9 - Microsystems, Inc. All Rights Reserved.
6.10 -->
6.11
6.12 @@ -68,7 +68,7 @@
6.13 <a href="@JDK@/java/util/Enumeration.html">Enumeration</a>s and especially
6.14 their on-demand generation.
6.15 </li>
6.16 -<ol>
6.17 +</ol>
6.18
6.19 <!--
6.20 <li><a href="../io/package-summary.html"><code>org.openide.util.io</code></a>:
6.21 @@ -310,7 +310,7 @@
6.22 not very useful from a layer, because you should avoid putting
6.23 binary data into a layer, but may be useful in some circumstances.</p>
6.24
6.25 -<dt><a name="xml-instances"><em>XML-based instances</em></a>
6.26 +<dt><a name="xml-instances"><em>XML-based instances</em></a></dt>
6.27
6.28
6.29 <a href="../../xml/EntityCatalog.html"><code>EntityCatalog</code></a>
7.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
7.2 +++ b/openide.util/src/org/openide/util/lookup/doc-files/index.html Thu May 12 06:29:13 2005 +0000
7.3 @@ -0,0 +1,188 @@
7.4 +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
7.5 +<!--
7.6 + - Sun Public License Notice
7.7 + -
7.8 + - The contents of this file are subject to the Sun Public License
7.9 + - Version 1.0 (the "License"). You may not use this file except in
7.10 + - compliance with the License. A copy of the License is available at
7.11 + - http://www.sun.com/
7.12 + -
7.13 + - The Original Code is NetBeans. The Initial Developer of the Original
7.14 + - Code is Sun Microsystems, Inc. Portions Copyright 1997-2005 Sun
7.15 + - Microsystems, Inc. All Rights Reserved.
7.16 + -->
7.17 +<HTML>
7.18 +<HEAD>
7.19 +<TITLE>Lookup Library</TITLE>
7.20 +<link rel="Stylesheet" href="@TOP@/prose.css" type="text/css" title="NetBeans Open APIs Style">
7.21 +</HEAD>
7.22 +<BODY>
7.23 +
7.24 +<H1>Lookup Library - The Solution to Comunication Between Components</H1>
7.25 +
7.26 +<B>$Revision$</B><BR>
7.27 +<B>History:</B> Available in <a
7.28 +href="http://www.netbeans.org/source/browse/openide/util/src/org/openide/util/lookup/doc-files/index.html">CVS</a>
7.29 +
7.30 +<P>
7.31 +
7.32 +This is the home page of the <em>lookup library</em> implementation, which
7.33 +is intended to solve a general problem that every <cite>component-based system</CITE>
7.34 +has had to face: how different components <b>register</b> to the system
7.35 +and how other parts of the system can <b>look</b> them <b>up</B>.
7.36 +<P>
7.37 +There already are libraries trying to solve this problem, usually by querying for
7.38 +an interface and finding its appropriate implementaion. The most famous is
7.39 +<A href="http://www.jini.org/">Jini</A>, the platform for development of
7.40 +distributed network services. Our library does something similar, but tries
7.41 +to stay small and easy
7.42 +to use. The NetBeans <em>Lookup
7.43 +Library</EM>'s main focus is a modular application consisting of independent modules
7.44 +that want to communicate with each other. It does not try to solve networking or
7.45 +legacy application integration. It is simple but powerful.
7.46 +
7.47 +<H2>Why would you want to use it?</H2>
7.48 +
7.49 +A well-written modular program separates <em>development</EM>
7.50 +and <em>deployment</EM>.
7.51 +There are many situations where a component needs some functionality but
7.52 +does not actually care about the implementation. It is up to the <em>system
7.53 +adminstrator</em> that deploys (installs) the application to decide which
7.54 +implementation to use.
7.55 +<P>
7.56 +The most simple and most often used method for allowing other implementations
7.57 +to be plugged in is the <em>system property</em> pattern:
7.58 +
7.59 +<pre>
7.60 + <font class="keyword">public</font> <font class="type">Toolkit</font> <font class="function-name">getDefaultToolkit</font> () {
7.61 + java.awt.<font class="type">Toolkit</font> <font class="variable-name">t</font> = <font class="constant">null</font>;
7.62 + <font class="type">String</font> <font class="variable-name">classname</font> = System.getProperty (<font class="string">"java.awt.Toolkit"</font>);
7.63 + <font class="keyword">if</font> (classname != <font class="constant">null</font>) {
7.64 + <font class="keyword">try</font> {
7.65 + <font class="type">Class</font> <font class="variable-name">c</font> = Class.forName (classname);
7.66 + t = (java.awt.<font class="type">Toolkit</font>)c.newInstance ();
7.67 + } <font class="keyword">catch</font> (<font class="type">Exception</font> <font class="variable-name">ex</font>) {
7.68 + System.out.println (<font class="string">"Cannot initialize toolkit: "</font> + classname);
7.69 + ex.printStackTrace ();
7.70 + }
7.71 + }
7.72 + <font class="comment">// fallback </font>
7.73 + <font class="keyword">if</font> (t == <font class="constant">null</font>) {
7.74 + t = <font class="keyword">new</font> <font class="type">GenericAWTToolkit</font> ();
7.75 + }
7.76 + }
7.77 +</pre>
7.78 +
7.79 +
7.80 +The idea is simple. The <em>deployer</em> can start the Java VM with the flag
7.81 +<code>-Djava.awt.Toolkit=org.myorg.MyToolkit</code> where the <code>MyToolkit</code>
7.82 +is his class with default constructor and the code in the <code>getDefaultToolkit</CODE>
7.83 +method will instantiate the class and use it.
7.84 +<P>
7.85 +In principle this is general enough of a solution and works well, except that writing the
7.86 +code above is error prone and it also requires passing the arguments to the virtual machine.
7.87 +It would be much nicer if the registation could be done just by putting a JAR file with the <code>MyToolkit</code> class
7.88 +into the application classpath.
7.89 +<P>
7.90 +Actually this has been realized also by the JDK development team and addressed in
7.91 +JDK 1.3 as part of the <a href="http://java.sun.com/j2se/1.3/docs/guide/jar/jar.html#Provider%20Configuration%20File">provider extension mechanism</A>.
7.92 +The <code>MyToolkit</code> could be registered by adding a file
7.93 +<code>/META-INF/services/java.awt.Toolkit</code> with one line
7.94 +<code>org.myorg.MyToolkit</code> into the JAR file that contains the
7.95 +<code>MyToolkit</CODE> implementation. The code in <code>getDefaultToolkit</CODE>
7.96 +will scan all JAR files in classpath and search for that file,
7.97 +create an instance of <code>MyToolkit</code> and use it.
7.98 +The deployer can influence which toolkit will be created by
7.99 +adding the right JAR files into the classpath.
7.100 +<P>
7.101 +Of course the code to access the <code>META-INF/services/</code> files is even
7.102 +more error prone than the <em>property pattern</EM>. And this is exactly the
7.103 +place where the <em>lookup library</em> can help. It provides an implementation of
7.104 +the search algorithm with an easy interface. Just write:
7.105 +<pre>
7.106 + <font class="keyword">import</font> <font class="type">java.awt.Toolkit</font>;
7.107 + <font class="keyword">import</font> <font class="type">org.openide.util.Lookup;</font>;
7.108 + <font class="type">Toolkit</font> <font class="variable-name">t</font> = (<font class="type">Toolkit</font>)Lookup.getDefault().<a href="@TOP@org/openide/util/Lookup.html#lookup(java.lang.Class)">lookup</a>(Toolkit.<font class="keyword">class</font>);
7.109 +</PRE>
7.110 +and if the JAR with <code>MyToolkit</CODE> is in the class path, the simple call
7.111 +above will do the rest.
7.112 +<P>
7.113 +So whenever one writes an application divided into several independent modules (jar files)
7.114 +that are being developed and deployed independently, there is a need for registering
7.115 +and discovering components. First of all, a set of interfaces can be defined to enable
7.116 +inter-module communication (like the abstract class <code>java.awt.Toolkit</CODE>).
7.117 +After that a set of modules providing implementation can written (<code>MyToolkit</code> and other concurent implementations)
7.118 +and after that, whenever a module trying to utilitize the functionality wants to access
7.119 +the <code>Toolkit</code> via lookup, the real implementation is returned.
7.120 +<P>
7.121 +It is the responsibility of lookup to find a suitable implementation of the
7.122 +requested service and return an object implementing the service. This is the
7.123 +the basic functionality and while the library provides you with a little bit
7.124 +more, even this simple usage might be extremaly useful: the client code knows
7.125 +nothing about the implementation and the implementation can be switched in
7.126 +deployment time by simply replacing one implementation jar with other. There
7.127 +is no code change required.
7.128 +
7.129 +<H2> Local lookup usage </H2>
7.130 +The example in previous paragraph demostrated the usage of lookup as a global
7.131 +registry (by using the <CODE>Lookup.getDefault()</CODE> call). One can also
7.132 +consider another scenario where the lookup can help.
7.133 +<P>
7.134 +Let's switch hats to be an API designer for a while. The goal is to introduce a
7.135 +new object into the system. But you either are not sure yet what all the roles
7.136 +of the new object will be or you (more importantly) want to be able to add (or
7.137 +change) roles of the object dynamically. So why not to introduce following
7.138 +method to the object's interface:
7.139 +<pre>
7.140 +<font class="keyword">public class </FONT> <font class="type">MorphingObject</FONT> {
7.141 + <font class="keyword">public</FONT> <font class="type"><a href="@TOP@org/openide/util/Lookup.html">Lookup</A></FONT> getLookup() {
7.142 + <font class="keyword">return</FONT> <font class="variable-name">myLookup;</FONT>
7.143 + }
7.144 + ...
7.145 +}
7.146 +</pre>
7.147 +By exposing the method getLookup you can attach different functionality to the
7.148 +MorphingObject at runtime and whoever gets a reference to your object can ask it
7.149 +whether the object supports a given interface like this:
7.150 +<pre>
7.151 +<font class="type">MorphingObject</FONT> <font class="variable-name">morph</FONT> = ...
7.152 +<font class="type">AnInterface</font> <font class="variable-name">impl</font> = (<font
7.153 +class="type">AnInterface</font>)morph.getLookup().<a
7.154 +href="@TOP@org/openide/util/Lookup.html#lookup(java.lang.Class)">lookup</a>(AnInterface.<font class="keyword">class</font>);
7.155 +<font class="keyword">if</font> (impl == <font class="constant">null</font>) {
7.156 + <font class="keyword">return;</font><font class="comment">/* AnInterface not supported now! */</font>
7.157 +}
7.158 +impl.useIt();
7.159 +</PRE>
7.160 +
7.161 +<H2>Additional functionality</H2>
7.162 +The NetBeans lookup library also provides:
7.163 +<UL>
7.164 +<LI>Support for dynamically changing the lookup content.</LI>
7.165 +<LI>The ability to return multiple results.</LI>
7.166 +<LI>Notification of changes. After retrieving the result, the client can attach a
7.167 +listener and be notified when the result of the lookup is changed.</LI>
7.168 +<LI>Lazy initialization of the implementation. The implementation objects are
7.169 +initialized only after someone asks for them. Even the implementation classes
7.170 +are not loaded if they are not going to be used! </LI>
7.171 +</UL>
7.172 +
7.173 +<H2>Further information</H2>
7.174 +<UL>
7.175 + <LI><A HREF="lookup-api.html">Lookup Library APIs</A> for those writing the client code.
7.176 +Specifying the query, getting the result and listenning on changes.</LI>
7.177 + <LI><A HREF="lookup-spi.html">Lookup Library SPIs</A> for those writing the
7.178 +implementaion code and registering it with lookup. Includes also writing own
7.179 +lookup implementation.</LI>
7.180 + <LI>Download <A HREF="http://www.netbeans.org/">NetBeans platform</A> which
7.181 +contains <code>org-openide-util.jar</code></LI>
7.182 + <LI>Source code:
7.183 + directly on netbeans.org on-line CVS view
7.184 + <A HREF="http://www.netbeans.org/source/browse/openide/util/src/org/openide/util/lookup/">
7.185 + implementation package (org.openide.util.lookup) </A>
7.186 + + classes Lookup, LookupEvent, LookupListener in
7.187 + <A href="http://www.netbeans.org/source/browse/openide/util/src/org/openide/util/">util package</A></LI>
7.188 + <li><a href="http://www.martinfowler.com/articles/injection.html">Inversion of Control Containers and the Dependency Injection pattern</a> (Martin Fowler)</li>
7.189 +</UL>
7.190 +</BODY>
7.191 +</HTML>
8.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
8.2 +++ b/openide.util/src/org/openide/util/lookup/doc-files/lookup-api.html Thu May 12 06:29:13 2005 +0000
8.3 @@ -0,0 +1,161 @@
8.4 +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
8.5 +<!--
8.6 + - Sun Public License Notice
8.7 + -
8.8 + - The contents of this file are subject to the Sun Public License
8.9 + - Version 1.0 (the "License"). You may not use this file except in
8.10 + - compliance with the License. A copy of the License is available at
8.11 + - http://www.sun.com/
8.12 + -
8.13 + - The Original Code is NetBeans. The Initial Developer of the Original
8.14 + - Code is Sun Microsystems, Inc. Portions Copyright 1997-2005 Sun
8.15 + - Microsystems, Inc. All Rights Reserved.
8.16 + -->
8.17 +<HTML>
8.18 +<HEAD>
8.19 +<TITLE>Lookup Library API</TITLE>
8.20 +<link rel="Stylesheet" href="@TOP@/prose.css" type="text/css" title="NetBeans Open APIs Style">
8.21 +</HEAD>
8.22 +<BODY>
8.23 +<H1>Lookup library API</H1>
8.24 +<B>History:</B> Available in
8.25 +<a href="http://www.netbeans.org/source/browse/openide/util/src/org/openide/util/lookup/doc-files/lookup-api.html">
8.26 +CVS</a>
8.27 +<p>
8.28 +This document describes usage of the API provided by the Lookup Library. In this
8.29 +document we assume that someone has already provided us with a lookup
8.30 +implementation (for those seeking how to write a lookup implementation please
8.31 +check <A href="lookup-spi.html">the SPI document</A>).
8.32 +
8.33 +<H2> Getting the lookup </H2>
8.34 +
8.35 +The first question you might ask is this: how can I get hold of a
8.36 +lookup instance? There are basically two ways how you can get it.
8.37 +
8.38 +<H3> Global lookup </H3>
8.39 +As you can see in the
8.40 +
8.41 +<a href="@TOP@org/openide/util/Lookup.html">Lookup</a>
8.42 +
8.43 +Javadoc there is a static method
8.44 +
8.45 +<pre><a href="@TOP@org/openide/util/Lookup.html#getDefault()">public static Lookup getDefault()</a></pre>
8.46 +
8.47 +The object returned from this method is
8.48 +a global lookup that can serve as a central place for registering services.
8.49 +The default implementation is a lookup that implements
8.50 +<a href="http://java.sun.com/j2se/1.4/docs/guide/jar/jar.html#Service%20Provider">
8.51 +the JDK JAR services</A>
8.52 +mechanism and delegates to <samp>META-INF/services/name.of.Class</samp> files.
8.53 +<P>
8.54 +If you want to add your class to this lookup just create a file in your
8.55 +jar file under the <code>META-INF</code> directory (e.g. <samp>META-INF/services/com.my.APIClass</samp>)
8.56 +and let the file contain only one line of text
8.57 +
8.58 +<pre>com.foo.impl.ImplOfTheAPI</pre>
8.59 +
8.60 +The following code will return you a newly created instance of
8.61 +<code>com.foo.impl.ImplOfTheAPI</code>:
8.62 +
8.63 +<PRE>
8.64 + <font class="keyword">import</FONT> org.openide.util.Lookup;
8.65 + return (com.my.APIClass)Lookup.getDefault().lookup(com.my.APIClass.class);
8.66 +</PRE>
8.67 +
8.68 +<H3> Local lookup </H3>
8.69 +
8.70 +This is just a reminder that whenever you find a method called getLookup
8.71 +or similar returning a lookup instance, the provided lookup is <EM>not</EM> the
8.72 +general lookup described in the previous paragraph. Rather, it is a private lookup
8.73 +implementation that is usually bound to the object you invoked the method on.
8.74 +
8.75 +<H2> Use of Lookup.Template and Lookup.Result </H2>
8.76 +
8.77 +There are more ways how you can ask lookup besides the variant with one class
8.78 +parameter. If you want more functionality, you have to implement the interface
8.79 +Lookup.Template and pass an instance of such object to the lookup call.
8.80 +<p>
8.81 +<EM>Note:</EM> If you use Lookup.Template, the object returned from the lookup is
8.82 +<EM>not</EM> the object you are looking for but rather a result object
8.83 +(Lookup.Result). You can call methods on such a result object to get the actual
8.84 +results.
8.85 +<p>
8.86 +Let's examine following example:
8.87 +
8.88 +<pre>
8.89 + <font class="keyword">import</FONT> org.openide.util.Lookup;
8.90 +
8.91 + <font class="type">Lookup</font> <font class="variable-name">lookup</font> = ...;
8.92 + Lookup.<font class="type">Template</font> <font class="variable-name">template</font> = <font class="keyword">new</font> Lookup.<font class="type">Template</font>(MyService.<font class="keyword">class</font>);
8.93 + Lookup.<font class="type">Result</font> <font class="variable-name">result</font> = lookup.lookup(template);
8.94 + <font class="type">Collection</font> <font class="variable-name">c</font> = result.allInstances();
8.95 + <font class="keyword">for</font> (<font class="type">Iterator</font> <font class="variable-name">i</font> = c.iterator(); i.hasNext(); ) {
8.96 + <font class="type">MyService</font> <font class="variable-name">s</font> = (<font class="type">MyService</font>)i.next();
8.97 + s.callMyService();
8.98 + }
8.99 +</pre>
8.100 +
8.101 +In this example the call to method lookup(...) returns immediately because the
8.102 +result object can be constructed even without real results. The first time you
8.103 +ask for the result object by calling r.allInstances(), the lookup has to supply you
8.104 +the real results and this method can block until the required data are really
8.105 +available.
8.106 +<p>
8.107 +If you are not interested in all objects as in the previous example, you can use the
8.108 +template to ask for one resulting object (wrapped in special Item instance):
8.109 +<pre>
8.110 + <font class="keyword">import</FONT> org.openide.util.Lookup;
8.111 +
8.112 + <font class="type">Lookup</font> <font class="variable-name">lookup</font> = ...;
8.113 + Lookup.<font class="type">Template</font> <font class="variable-name">template</font> = <font class="keyword">new</font> Lookup.<font class="type">Template</font>(MyService.<font class="keyword">class</font>);
8.114 + Lookup.<font class="type">Item</font> <font class="variable-name">item</font> = lookup.lookupItem(template);
8.115 + <font class="type">MyService</font> <font class="variable-name">s</font> = (<font class="type">MyService</font>)item.getInstance();
8.116 + s.callMyService();
8.117 +</pre>
8.118 +
8.119 +Again, the Item object can construct the real instance only if you call
8.120 +getInstance. The item can be useful even without calling getInstance - you can get
8.121 +its display name or an unique id. You can use this information, for example, for
8.122 +constructing menu items without the need to instantiate (or even load!)
8.123 +the class implementing the functionality. Only when the real functionality is
8.124 +needed (e.g. the user has selected the menu item) you can call getInstance
8.125 +and call the real meat of the implementation.
8.126 +
8.127 +<H2> Listenning on lookup changes </H2>
8.128 +There is one additional piece of functionality bound to the Lookup.Result object worth
8.129 +mentioning: you can attach a listener to it and be informed about any changes in
8.130 +the lookup. This might be extremly usefull when the lookup dynamically changes
8.131 +(from other threads). The listener can keep state of your object up-to-date even
8.132 +in cases where the lookup changes asynchronously.
8.133 +<p>
8.134 +So here is some sample code using the listenner:
8.135 +
8.136 +<pre>
8.137 + <font class="keyword">import</FONT> org.openide.util.Lookup;
8.138 + <font class="keyword">import</FONT> org.openide.util.LookupListener;
8.139 + <font class="keyword">import</FONT> org.openide.util.LookupEvent;
8.140 +
8.141 + <font class="type">Lookup</font> <font class="variable-name">lookup</font> = ...;
8.142 + Lookup.<font class="type">Template</font> <font class="variable-name">template</font> = <font class="keyword">new</font> Lookup.<font class="type">Template</font>(MyService.<font class="keyword">class</font>);
8.143 + <font class="keyword">final</font> <font class="variable-name">Lookup</font>.<font class="type">Result</font> <font class="variable-name">result</font> = lookup.lookup(template);
8.144 + result.addLookupListener(<font class="keyword">new</font> <font class="type">LookupListener</font>() {
8.145 + <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">e</font>) {
8.146 + reaction(result);
8.147 + }
8.148 + });
8.149 + reaction(result);
8.150 + }
8.151 + <font class="keyword">private</font> <font class="keyword">static</font> <font class="type">void</font> <font class="function-name">reaction</font>(Lookup.<font class="type">Result</font> <font class="variable-name">r</font>) {
8.152 + <font class="keyword">for</font> (<font class="type">Iterator</font> <font class="variable-name">i</font> = r.allInstances().iterator(); i.hasNext(); ) {
8.153 + <font class="type">MyService</font> <font class="variable-name">s</font> = (<font class="type">MyService</font>)i.next();
8.154 + s.callMyService();
8.155 + }
8.156 + }
8.157 +</pre>
8.158 +
8.159 +Please note that we first attach a listener and then call the reaction method.
8.160 +This ensures that we always get the newest possible state. Also you must be
8.161 +careful in the reaction method since it can be called from two different
8.162 +threads simultaneously (your code has to be prepared for this).
8.163 +</BODY>
8.164 +</HTML>
9.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
9.2 +++ b/openide.util/src/org/openide/util/lookup/doc-files/lookup-spi.html Thu May 12 06:29:13 2005 +0000
9.3 @@ -0,0 +1,123 @@
9.4 +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
9.5 +<!--
9.6 + - Sun Public License Notice
9.7 + -
9.8 + - The contents of this file are subject to the Sun Public License
9.9 + - Version 1.0 (the "License"). You may not use this file except in
9.10 + - compliance with the License. A copy of the License is available at
9.11 + - http://www.sun.com/
9.12 + -
9.13 + - The Original Code is NetBeans. The Initial Developer of the Original
9.14 + - Code is Sun Microsystems, Inc. Portions Copyright 1997-2005 Sun
9.15 + - Microsystems, Inc. All Rights Reserved.
9.16 + -->
9.17 +<HTML>
9.18 +<HEAD>
9.19 +<TITLE>Lookup Library SPI</TITLE>
9.20 +<link rel="Stylesheet" href="@TOP@/prose.css" type="text/css" title="NetBeans Open APIs Style">
9.21 +</HEAD>
9.22 +<BODY>
9.23 +<H1>Lookup library SPI</H1>
9.24 +<B>History:</B> Available in
9.25 +<a href="http://www.netbeans.org/source/browse/openide/util/src/org/openide/util/lookup/doc-files/lookup-spi.html">
9.26 +CVS</a>
9.27 +<p>
9.28 +This document describe usage of the SPI provided by the Lookup Library
9.29 +(for those seeking how to use lookup instance please
9.30 +check <A href="lookup-api.html">the API document</A>).
9.31 +<p>
9.32 +By using the SPI you can create lookups that can be used by the users of the
9.33 +Lookup API. While the Lookup API consists of a couple of classes in the package
9.34 +<em>org.openide.util.*</EM>,
9.35 +the SPI has its own package <em>org.openide.util.lookup.*</EM>.
9.36 +
9.37 +<H2> Simple lookups </H2>
9.38 +Let us start with the simplest case. You have decided that your newly created
9.39 +object will provide an API in the form of a getLookup() method. You have to
9.40 +return a functional lookup from this call. You can use static methods in class
9.41 +<a href="@TOP@org/openide/util/lookup/Lookups.html">
9.42 +<code>Lookups</code></A> to create a lookup for you. If you want only one
9.43 +object to be returned, just call
9.44 +<a href="@TOP@org/openide/util/lookup/Lookups.html#singleton(java.lang.Object)">
9.45 +<code>Lookups.singleton(x)</code></A> where x is the object to be
9.46 +returned by the lookup. Or if you want to supply more objects, use a call to the method
9.47 +<a href="@TOP@org/openide/util/lookup/Lookups.html#fixed(java.lang.Object[])">
9.48 +<code>fixed(Object []x)</CODE></A>.
9.49 +<EM> Note: </EM> The lookups returned from methods <code>singleton(...)</code> and
9.50 +<code>fixed(...)</code> do <EM>
9.51 +not </EM> support dynamic changes and attaching listeners. Their content is
9.52 +fixed from the time you call the creating method.
9.53 +
9.54 +<H2> ProxyLookup </H2>
9.55 +There can be situations where you get a lookup object from someone else and you
9.56 +want your lookup to return exactly the instances from the original lookup plus
9.57 +your own results. Here the class ProxyLookup comes into the play.
9.58 +<p>
9.59 +You simply create a new lookup like this:
9.60 +
9.61 +<pre>
9.62 + <font class="keyword">import</FONT> org.openide.util.Lookup;
9.63 + <font class="keyword">import</FONT> org.openide.util.lookup.*;
9.64 +
9.65 + <font class="type">Lookup</font> <font class="variable-name">lookup1</font> = ...;
9.66 +
9.67 + <font class="type">Lookup</font> <font class="variable-name">lookup2</font> = Lookups.singleton(MyService.<font class="keyword">class</font>);
9.68 + <font class="keyword">return</font> <font class="keyword">new</font> <font class="type">ProxyLookup</font>(<font class="keyword">new</font> <font class="type">Lookup</font>[] { lookup, lookup2 });
9.69 +</pre>
9.70 +
9.71 +<H2> AbstractLookup </H2>
9.72 +<!-- This paragraph originally copied from
9.73 +@TOP@org/openide/doc-files/services-api.html#lookup-impl
9.74 +-->
9.75 +
9.76 +<p>The most powerful way to provide a lookup is to directly define
9.77 +what instances and items it should provide, by subclassing. For this,
9.78 +
9.79 +<a href="@TOP@org/openide/util/lookup/AbstractLookup.html"><code>AbstractLookup</code></a>
9.80 +
9.81 +is recommended as it is easiest to use.
9.82 +
9.83 +<p>The simplest way to use <code>AbstractLookup</code> is to use its
9.84 +public constructor (in which case you need not subclass it). Here you
9.85 +provide an
9.86 +
9.87 +<a href="@TOP@org/openide/util/lookup/AbstractLookup.Content.html"><code>AbstractLookup.Content</code></a>
9.88 +
9.89 +object which you have created and hold on to privately, and which
9.90 +keeps track of instances and permits them to be registered and
9.91 +deregistered. Often
9.92 +
9.93 +<a href="@TOP@org/openide/util/lookup/InstanceContent.html"><code>InstanceContent</code></a>
9.94 +
9.95 +is used as the content implementation. To add something to the lookup,
9.96 +simply use
9.97 +
9.98 +<a href="@TOP@org/openide/util/lookup/InstanceContent.html#add(java.lang.Object)"><code>add(Object)</code></a>
9.99 +
9.100 +(and <code>remove(Object)</code> for the reverse). These may be called
9.101 +at any time and will update the set of registered instances (firing
9.102 +result changes as needed).
9.103 +
9.104 +<pre>
9.105 + <font class="keyword">import</FONT> org.openide.util.lookup.*;
9.106 + <font class="type">InstanceContent</font> <font class="variable-name">ic</font> = <font class="keyword">new</font> <font class="type">InstanceContent</font> ();
9.107 + ic.add(firstObject);
9.108 + <font class="keyword">return</font> <font class="keyword">new</font> <font class="type">AbstractLookup</font> (ic);
9.109 +</pre>
9.110 +
9.111 +<p>In case it is expensive to actually compute the object in the
9.112 +lookup, but there is some cheap "key" which can easily generate it,
9.113 +you may instead register the key by passing in an
9.114 +
9.115 +<a href="@TOP@org/openide/util/lookup/InstanceContent.Convertor.html"><code>InstanceContent.Convertor</code></a>.
9.116 +
9.117 +This convertor translates the key to the real instance that the lookup
9.118 +client sees, if and when needed. For example, if you have a long list
9.119 +of class names and wish to register default instances of each class,
9.120 +you might actually register the class name as the key, and supply a
9.121 +convertor which really loads the class and instantiates it. This makes
9.122 +it easy to set up the lookup, but nothing is really loaded until
9.123 +someone asks for it.
9.124 +
9.125 +</BODY>
9.126 +</HTML>
10.1 --- a/openide.util/src/org/openide/util/package.html Wed May 04 14:47:22 2005 +0000
10.2 +++ b/openide.util/src/org/openide/util/package.html Thu May 12 06:29:13 2005 +0000
10.3 @@ -16,7 +16,7 @@
10.4
10.5 A set of
10.6
10.7 -<a href="doc-files/api.html">utility classes</a>
10.8 +<a href="@TOP@/org/openide/util/doc-files/api.html">utility classes</a>
10.9
10.10 covering a few general infrastructure points in the Open APIs.
10.11