1.1 --- a/openide.util.lookup/arch.xml Mon Dec 14 19:10:02 2009 +0100
1.2 +++ b/openide.util.lookup/arch.xml Mon Dec 14 20:23:03 2009 +0100
1.3 @@ -53,15 +53,8 @@
1.4
1.5 <answer id="arch-overall">
1.6 <p>
1.7 - This module contains general classes needed in NetBeans, extensions to
1.8 - basic JRE contepts, useful methods and other
1.9 - <api group="java" name="UtilitiesAPI" category="official" type="export" url="@TOP@/org/openide/util/doc-files/api.html" />
1.10 - classes.
1.11 - </p>
1.12 -
1.13 - <p>
1.14 Also this module defines the <a href="@TOP@/org/openide/util/Lookup.html">
1.15 - Lookup</a> which the NetBeans way for dynamic registration
1.16 + Lookup</a> which is the NetBeans way for dynamic registration
1.17 and lookup of
1.18 components in our modularized component system. It allows lookup and discovery
1.19 of features by description of their interfaces. The classes are devided
1.20 @@ -77,13 +70,14 @@
1.21 <answer id="arch-quality">
1.22 <p>
1.23 There is a lot of unit tests in
1.24 - <a href="http://www.netbeans.org/source/browse/openide/util/test/unit/src/">CVS</a>.
1.25 + <a href="http://hg.netbeans.org/main-golden/openide.util.lookup/test/unit/src/">version control</a>
1.26 + system.
1.27 </p>
1.28 </answer>
1.29
1.30 <answer id="arch-time">
1.31 <p>
1.32 - The module has been around since 1997 and is stilly improved
1.33 + The module has been around since 1997 and is continously being improved
1.34 from time to time.
1.35 </p>
1.36 </answer>
1.37 @@ -113,7 +107,7 @@
1.38 <li><p>It is possible to write a specific module and enable it only on windows.
1.39 See <a href="@org-openide-modules@/org/openide/modules/doc-files/api.html#how-os-specific">os specific modules</a> documentation.
1.40 Then you can put a registration of your instance into your module's
1.41 - <a href="@TOP@/org/openide/util/doc-files/api.html#service-lookup">META-INF/services</a> directory and it
1.42 + <a href="@org-openide-util@/org/openide/util/doc-files/api.html#service-lookup">META-INF/services</a> directory and it
1.43 will be available only on Windows.</p>
1.44 </li>
1.45
1.46 @@ -121,9 +115,9 @@
1.47 a code on startup (which may have performance implications) is to use <code>methodvalue</code>
1.48 attribute. Register your instance in layer using <code>your-Object.instance</code> file
1.49 as described at
1.50 - <a href="@TOP@/org/openide/util/doc-files/api.html#ido-methodvalue">services
1.51 + <a href="@org-openide-util@/org/openide/util/doc-files/api.html#ido-methodvalue">services
1.52 </a> documentation and in your factory method either return the instance
1.53 - your want or <code>null</code> depending on result of <a href="@TOP@/org/openide/util/Utilities.html#isWindows()">
1.54 + your want or <code>null</code> depending on result of <a href="@org-openide-util@/org/openide/util/Utilities.html#isWindows()">
1.55 Utilities.isWindows()</a> call.</p>
1.56 </li>
1.57 <li>
1.58 @@ -213,17 +207,6 @@
1.59 </p>
1.60
1.61 </usecase>
1.62 -
1.63 -
1.64 - <usecase id="logging" name="How shall I do or influence logging in NetBeans?">
1.65 - <p>
1.66 - If you are interested in logging from inside your module, or in writing
1.67 - your own log handler or in configuring the whole system, then best place
1.68 - to start is the <a href="@TOP@/org/openide/util/doc-files/logging.html">NetBeans logging guide</a>.
1.69 - </p>
1.70 - </usecase>
1.71 -
1.72 -
1.73 </answer>
1.74
1.75
1.76 @@ -236,21 +219,6 @@
1.77
1.78
1.79
1.80 - <answer id="compat-i18n">
1.81 - <p>
1.82 - There is not much things to localize in this module, so it is properly localized.
1.83 - 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">
1.84 - which is similar to localization but also supports changes of resorces
1.85 - for application build on top of NetBeans. This is handled by our
1.86 - class <a href="@TOP@/org/openide/util/NbBundle.html">NbBundle</a> which
1.87 - reimplements the JDK's standard <a href="@JDK@/java/util/ResourceBundle.html">ResourceBundle</a>
1.88 - to to take branding into the consideration.
1.89 - </api>.
1.90 - </p>
1.91 - </answer>
1.92 -
1.93 -
1.94 -
1.95 <answer id="compat-standards">
1.96 <p>
1.97 The default lookup registration follows the JDK's
1.98 @@ -265,7 +233,7 @@
1.99 name="ProviderRegistrationRemoval"
1.100 type="export"
1.101 category="devel"
1.102 - url="@TOP@/org/openide/util/doc-files/api.html#service-lookup"
1.103 + url="@org-openide-util@/org/openide/util/doc-files/api.html#service-lookup"
1.104 group="java"
1.105 />.
1.106 </p>
1.107 @@ -281,7 +249,7 @@
1.108
1.109 <answer id="dep-jre">
1.110 <p>
1.111 - Currently JRE 1.4 is needed.
1.112 + Currently JRE 1.5 is needed.
1.113 </p>
1.114 </answer>
1.115
1.116 @@ -295,24 +263,7 @@
1.117
1.118
1.119 <answer id="dep-nb">
1.120 - <p>
1.121 - This module is independent of other NetBeans modules and can be used
1.122 - independently. For better interaction with UI parts of NetBeans it however
1.123 - indirectly communicates with <a href="@org-openide-awt@/overview-summary.html">UI Utilities</a>
1.124 - module using <api name="AWTBridge" category="private" group="java" type="export"
1.125 - url="http://www.netbeans.org/source/browse/openide/util/src/org/netbeans/modules/openide/util/AWTBridge.java">
1.126 - a class that is looked up in <a href="@TOP@/org/openide/util/Lookup.html#getDefault()">Lookup.getDefault()</a>
1.127 - and if registered can provide better UI elements for <a href="@JDK@/javax/swing/Action.html">Action</a>s.
1.128 - </api>
1.129 -
1.130 - </p>
1.131 - </answer>
1.132 -
1.133 - <answer id="dep-non-nb">
1.134 - <p>
1.135 - Reexports XML APIs so needs some XML parser implementation, but as one
1.136 - is provided in any 1.4 java, it in fact has no dependencies except on JRE.
1.137 - </p>
1.138 + <p>N/A</p>
1.139 </answer>
1.140
1.141 <answer id="dep-platform">
1.142 @@ -333,28 +284,11 @@
1.143 <answer id="deploy-jar">
1.144 <p>
1.145 <api category="devel" group="java.io.File" name="FileLocation" type="export" >
1.146 - the JAR file is located in platform cluster under <code>lib/org-openide-util.jar</code>
1.147 + the JAR file is located in platform cluster under <code>lib/org-openide-util-lookup.jar</code>
1.148 </api>.
1.149 </p>
1.150 </answer>
1.151
1.152 -
1.153 -
1.154 - <answer id="deploy-nbm">
1.155 - <p>
1.156 - No reason to not deploy nbm.
1.157 - </p>
1.158 - </answer>
1.159 -
1.160 -
1.161 - <answer id="deploy-packages">
1.162 - <p>
1.163 - Yes, public packages declared.
1.164 - </p>
1.165 - </answer>
1.166 -
1.167 -
1.168 -
1.169 <answer id="deploy-shared">
1.170 <p>
1.171 Module is on real java classpath and as such it has to be in the shared directory.
1.172 @@ -378,91 +312,7 @@
1.173
1.174
1.175
1.176 -<!--
1.177 - <question id="exec-component" when="impl">
1.178 - Is execution of your code influenced by any (string) property
1.179 - of any of your components?
1.180 -
1.181 - <hint>
1.182 - Often <code>JComponent.getClientProperty</code>, <code>Action.getValue</code>
1.183 - or <code>PropertyDescriptor.getValue</code>, etc. are used to influence
1.184 - a behavior of some code. This of course forms an interface that should
1.185 - be documented. Also if one depends on some interface that an object
1.186 - implements (<code>component instanceof Runnable</code>) that forms an
1.187 - API as well.
1.188 - </hint>
1.189 - </question>
1.190 --->
1.191 - <answer id="exec-component">
1.192 - <ul>
1.193 - <li><api name="HelpID" category="standard" group="property" type="export" url="@TOP@/org/openide/util/HelpCtx.html">
1.194 - read from <a href="@JDK@/javax/swing/JComponent.html">JComponent</a>.getClientProperty
1.195 - to simulate the standard javahelp behaviour and extract the help id for given component.
1.196 - </api>
1.197 - </li>
1.198 -
1.199 - <li><api name="iconBase" category="standard" group="property" type="import" >
1.200 - <a href="@TOP@/org/openide/util/actions/SystemAction.html">SystemAction</a>
1.201 - reacts to expected requests from <a href="@org-openide-awt@/overview-summary.html">UI Utilities</a>
1.202 - module for <code>iconBase</code> property by returning value based on its
1.203 - result of its <code>iconResource()</code> method.
1.204 - </api>
1.205 - </li>
1.206 -
1.207 - <li>
1.208 - <api name="org.openide.util.SharedClassObject.initialize" category="private" group="property" type="export">
1.209 - For purposes of
1.210 - <code>SystemOption</code>
1.211 - the
1.212 - <a href="@TOP@/org/openide/util/SharedClassObject.html">SharedClassObject</a>
1.213 - handles
1.214 - <code>getProperty ("org.openide.util.SharedClassObject.initialize")</code>
1.215 - in a special way, by returning
1.216 - <code>null</code> if initialization is not running and <code>Boolean.TRUE</code> if
1.217 - it is.
1.218 - </api>
1.219 - </li>
1.220 -
1.221 - <li><api name="OpenIDE-Transmodal-Action" category="devel" group="property" type="export" >
1.222 - <a href="@TOP@/org/openide/util/actions/CallbackSystemAction.html">CallbackSystemAction</a>
1.223 - checks whether <code>action.getValue("OpenIDE-Transmodal-Action")</code>
1.224 - returns <code>Boolean.TRUE</code> to enable it in dialogs, otherwise
1.225 - the action is disabled when there is an open dialog.
1.226 - </api>
1.227 - </li>
1.228 -
1.229 -
1.230 - </ul>
1.231 - </answer>
1.232 -
1.233 -
1.234 -
1.235 -<!--
1.236 - <question id="exec-introspection" when="impl">
1.237 - Does your module use any kind of runtime type information (<code>instanceof</code>,
1.238 - work with <code>java.lang.Class</code>, etc.)?
1.239 - <hint>
1.240 - Check for cases when you have an object of type A and you also
1.241 - expect it to (possibly) be of type B and do some special action. That
1.242 - should be documented. The same applies on operations in meta-level
1.243 - (Class.isInstance(...), Class.isAssignableFrom(...), etc.).
1.244 - </hint>
1.245 - </question>
1.246 --->
1.247 - <answer id="exec-introspection">
1.248 - <p>
1.249 - <a href="@TOP@/org/openide/util/Utilities.html">Utilities</a> provide wrapper
1.250 - for java beans introspection. <api category="private" group="java" name="ParserFactory" type="import" >
1.251 - The <a href="@TOP@/org/openide/xml/XMLUtil.html">XMLUtil</a> class is loading
1.252 - a class from <code>core/core.jar</code> to initialize the correct parser factory.
1.253 - This is a fix for <a href="http://www.netbeans.org/issues/show_bug.cgi?id=68942">issue 68942</a>.
1.254 - </api>
1.255 - </p>
1.256 - </answer>
1.257 -
1.258 -
1.259 -
1.260 - <answer id="exec-privateaccess">
1.261 +<answer id="exec-privateaccess">
1.262 <p>
1.263 No.
1.264 </p>
1.265 @@ -477,16 +327,6 @@
1.266
1.267 <answer id="exec-property">
1.268 <ul>
1.269 - <li><api type="export" group="property" name="netbeans.screen.insets" category="private">
1.270 - Influences results of Utilities.getUsableScreenBounds</api>.</li>
1.271 - <li><api type="export" group="property" name="netbeans.taskbar.height" category="private">
1.272 - Influences results of Utilities.getUsableScreenBounds</api>.</li>
1.273 - <li>
1.274 - <api type='import' group="property" name="line.separator" category="standard" >
1.275 - used on few places
1.276 - </api>.
1.277 - </li>
1.278 -
1.279 <li>
1.280 <api type="export" group="property" name="org.openide.util.Lookup" category="devel">
1.281 checked by the initialization of the
1.282 @@ -535,32 +375,11 @@
1.283
1.284
1.285
1.286 -<!--
1.287 - <question id="exec-reflection" when="impl">
1.288 - Does your code use Java Reflection to execute other code?
1.289 - <hint>
1.290 - This usually indicates a missing or insufficient API in the other
1.291 - part of the system. If the other side is not aware of your dependency
1.292 - this contract can be easily broken.
1.293 - </hint>
1.294 - </question>
1.295 --->
1.296 <answer id="exec-reflection">
1.297 <p>
1.298 - <api category="devel" group="java" name="SharedClassObject.setAccessible" type="export" url="@TOP@/org/openide/util/SharedClassObject.html">
1.299 - used to instantiate subclasses.
1.300 - </api>.
1.301 - <api category="devel" group="java" name="WeakListener.setAccessible" type="export" url="@TOP@/org/openide/util/WeakListeners.html">
1.302 - used to call the remove method using reflection
1.303 - </api>.
1.304 <api category="devel" group="java" name="Lookups.metaInfServices" type="export" url="@TOP@/org/openide/util/lookup/Lookups.html#metaInfServices(java.lang.ClassLoader)">
1.305 calls constructor of registered classes using reflection
1.306 </api>.
1.307 - <api category="private" group="lookup" name="ActionManagerInvocation" type="export" >
1.308 - because of the API separation, <a href="@TOP@/org/openide/util/actions/CallableSystemAction.html">CallableSystemAction</a> uses lookup for <code>ActionsBridge</code>
1.309 - provided by <code>org-openide-actions</code> module
1.310 - when looking for <a href="@org-openide-actions@/org/openide/actions/ActionManager.html">org.openide.actions.ActionManager</a> implementation.
1.311 - </api>.
1.312 <api category="friend" group="java" name="Lookup.resetDefaultLookup" type="export">
1.313 There is a static private method <code>Lookup.resetDefaultLookup</code> that
1.314 is called by NbJUnit's <code>MockServices</code> to properly reset default
1.315 @@ -570,31 +389,12 @@
1.316 </p>
1.317 </answer>
1.318
1.319 -
1.320 -
1.321 -<!--
1.322 - <question id="exec-threading" when="impl">
1.323 - What threading models, if any, does your module adhere to?
1.324 - <hint>
1.325 - If your module calls foreign APIs which have a specific threading model,
1.326 - indicate how you comply with the requirements for multithreaded access
1.327 - (synchronization, mutexes, etc.) applicable to those APIs.
1.328 - If your module defines any APIs, or has complex internal structures
1.329 - that might be used from multiple threads, declare how you protect
1.330 - data against concurrent access, race conditions, deadlocks, etc.,
1.331 - and whether such rules are enforced by runtime warnings, errors, assertions, etc.
1.332 - Examples: a class might be non-thread-safe (like Java Collections); might
1.333 - be fully thread-safe (internal locking); might require access through a mutex
1.334 - (and may or may not automatically acquire that mutex on behalf of a client method);
1.335 - might be able to run only in the event queue; etc.
1.336 - Also describe when any events are fired: synchronously, asynchronously, etc.
1.337 - Ideas: <a href="http://core.netbeans.org/proposals/threading/index.html#recommendations">Threading Recommendations</a> (in progress)
1.338 - </hint>
1.339 - </question>
1.340 --->
1.341 <answer id="exec-threading">
1.342 <p>
1.343 - XXX no answer for exec-threading
1.344 + Everything is synchronous, except pluggable use of <code>java.util.concurrent.Executor</code>
1.345 + that allows to make calls asynchronous. The default implementation only delivers
1.346 + changes from <a href="@TOP@/org/openide/util/lookup/Lookups.html#metaInfServices(java.lang.ClassLoader)">metaInfServices</a>
1.347 + lookup in asynchronous thread.
1.348 </p>
1.349 </answer>
1.350
1.351 @@ -602,10 +402,7 @@
1.352
1.353 <answer id="format-clipboard">
1.354 <p>
1.355 - <a href="@TOP@/org/openide/util/datatransfer/MultiTransferObject.html">MultiTransferObject</a> can be
1.356 - used in <a href="@JDK@/java/awt/datatransfer/Transferable.html">Transferable</a> to represent content
1.357 - composed of multiple independent
1.358 - <a href="@JDK@/java/awt/datatransfer/Transferable.html">Transferable</a>s.
1.359 + Not used.
1.360 </p>
1.361 </answer>
1.362
1.363 @@ -619,11 +416,7 @@
1.364
1.365 <answer id="format-types">
1.366 <p>
1.367 - The <a href="http://java.sun.com/j2se/1.3/docs/guide/jar/jar.html#Provider%20Configuration%20File">META-INF/services/...</a> files.
1.368 - <api name="TranslateNames" category="official" type="export" group="java.io.File"
1.369 - url="@TOP@/org/openide/util/Utilities.html#translate(java.lang.String)">
1.370 - <a href="@TOP@/org/openide/util/Utilities.html#translate(java.lang.String)">Utilities.translate</a>
1.371 - reads <code>META-INF/netbeans/translate.names</code> files from JARs</api>.
1.372 + No.
1.373 </p>
1.374 </answer>
1.375
1.376 @@ -639,29 +432,9 @@
1.377 </li>
1.378
1.379 <li><api name="LookupSharedClassObject" category="devel" group="lookup" type="export">
1.380 - singleton subclasses of <a href="@TOP@/org/openide/util/SharedClassObject.html">SharedClassObject</a>
1.381 + singleton subclasses of <a href="@org-openide-util@/org/openide/util/SharedClassObject.html">SharedClassObject</a>
1.382 are searched for using Lookup.
1.383 </api>.</li>
1.384 -
1.385 - <li><api name="LookupContextGlobalProvider" category="stable" group="lookup" type="export">
1.386 - <a href="@TOP@/org/openide/util/Utilities.html#actionsGlobalContext()">actionsGlobalContext</a>
1.387 - searches for <a href="@TOP@/org/openide/util/ContextGlobalProvider.html">ContextGlobalProvider</a> in
1.388 - <a href="@TOP@/org/openide/util/Lookup.html#getDefault()">Lookup.getDefault()</a>.
1.389 - The provider is usually provided by <a href="@org-openide-windows@/overview-summary.html">window
1.390 - system implementation</a>.
1.391 - </api>.</li>
1.392 -
1.393 - <li><api name="LookupEntityCatalog" category="devel" group="lookup" type="export">
1.394 - <a href="@TOP@/org/openide/xml/EntityCatalog.html">EntityCatalog</a>
1.395 - delegates its methods to all instances of <a href="@TOP@/org/openide/xml/EntityCatalog.html">EntityCatalog</a>s
1.396 - found in Lookup
1.397 - </api>.</li>
1.398 -
1.399 - <li><api name="LookupErrorManager" category="devel" group="lookup" type="export">
1.400 - <a href="@TOP@/org/openide/ErrorManager.html">ErrorManager</a>
1.401 - delegates its methods to all instances of <a href="@TOP@/org/openide/ErrorManager.html">ErrorManager</a>s
1.402 - found in Lookup
1.403 - </api>.</li>
1.404
1.405 <li><api name="LookupClassLoader" category="devel" group="lookup" type="export">
1.406 Nearly all resource looking functions and reflective code
1.407 @@ -675,15 +448,6 @@
1.408
1.409
1.410
1.411 -<!--
1.412 - <question id="lookup-register" when="final">
1.413 - Do you register anything into lookup for other code to find?
1.414 - <hint>
1.415 - Do you register using layer file or using <code>META-INF/services</code>?
1.416 - Who is supposed to find your component?
1.417 - </hint>
1.418 - </question>
1.419 --->
1.420 <answer id="lookup-register">
1.421 <p>
1.422 No.
1.423 @@ -810,8 +574,7 @@
1.424 -->
1.425 <answer id="perf-progress">
1.426 <p>
1.427 - Actions declared as <a href="@TOP@/org/openide/util/actions/CallableSystemAction.html#asynchronous()">CallableSystemAction.asynchronous()</a>
1.428 - are executed outside of AWT thread on a dedicated request processor one.
1.429 + No.
1.430 </p>
1.431 </answer>
1.432
2.1 --- a/openide.util.lookup/src/org/openide/util/lookup/Lookups.java Mon Dec 14 19:10:02 2009 +0100
2.2 +++ b/openide.util.lookup/src/org/openide/util/lookup/Lookups.java Mon Dec 14 20:23:03 2009 +0100
2.3 @@ -207,7 +207,7 @@
2.4 * sub-folders, the second one retrieves instances from the whole sub-tree.
2.5 * </p>
2.6 * <p>
2.7 - * Read more about the <a href="../doc-files/api.html#folderlookup">usage of this method</a>.
2.8 + * Read more about the <a href="@org-openide-util@/org/openide/util/doc-files/api.html#folderlookup">usage of this method</a>.
2.9 *
2.10 * @param path the path identifying the lookup, e.g. <code>Projects/Actions</code>
2.11 * @return lookup associated with this path
3.1 --- a/openide.util/arch.xml Mon Dec 14 19:10:02 2009 +0100
3.2 +++ b/openide.util/arch.xml Mon Dec 14 20:23:03 2009 +0100
3.3 @@ -58,32 +58,20 @@
3.4 <api group="java" name="UtilitiesAPI" category="official" type="export" url="@TOP@/org/openide/util/doc-files/api.html" />
3.5 classes.
3.6 </p>
3.7 -
3.8 - <p>
3.9 - Also this module defines the <a href="@org-openide-util-lookup@/org/openide/util/Lookup.html">
3.10 - Lookup</a> which the NetBeans way for dynamic registration
3.11 - and lookup of
3.12 - components in our modularized component system. It allows lookup and discovery
3.13 - of features by description of their interfaces. The classes are devided
3.14 - into two parts. The
3.15 - <api group="java" name="LookupAPI" type="export" category="official" url="@org-openide-util-lookup@/org/openide/util/lookup/doc-files/lookup-api.html">
3.16 - allows the discovery</api> and the
3.17 - <api group="java" name="LookupSPI" type="export" category="official" url="@org-openide-util-lookup@/org/openide/util/lookup/doc-files/lookup-spi.html">
3.18 - simplifies creation and registration of own lookup objects</api>.
3.19 - </p>
3.20 </answer>
3.21
3.22
3.23 <answer id="arch-quality">
3.24 <p>
3.25 There is a lot of unit tests in
3.26 - <a href="http://www.netbeans.org/source/browse/openide/util/test/unit/src/">CVS</a>.
3.27 + <a href="http://hg.netbeans.org/main-golden/openide.util/test/unit/src/">version control</a>
3.28 + system.
3.29 </p>
3.30 </answer>
3.31
3.32 <answer id="arch-time">
3.33 <p>
3.34 - The module has been around since 1997 and is stilly improved
3.35 + The module has been around since 1997 and is still improved
3.36 from time to time.
3.37 </p>
3.38 </answer>
3.39 @@ -91,130 +79,6 @@
3.40
3.41
3.42 <answer id="arch-usecases">
3.43 -
3.44 - There is a great introduction to Lookup and its usage in its
3.45 - <a href="@org-openide-util-lookup@/org/openide/util/Lookup.html">javadoc</a>. Here is just
3.46 - a list of frequently asked or interesting questions slowly expanding as
3.47 - people ask them:
3.48 -
3.49 - <h3>Lookup faq:</h3>
3.50 -
3.51 - <usecase id="lookup-on-certain-platform" name="How to specify that a service in Lookup should be available only on Windows?" >
3.52 -<em><b>Q:</b>
3.53 -Most of the time I specify interfaces that I want to add to the Lookup class in the layer.xml file.
3.54 -But, let's say I have a platform-specific interface (something on Windows only, for instance).</em>
3.55 -<p>
3.56 -<em>
3.57 -How can I specify (in the xml, or programmatically) that this service should only be added to the Lookup if the platform is Windows?
3.58 -</em>>
3.59 -</p>
3.60 -In general there are three ways to achieve this.
3.61 -<ul>
3.62 - <li><p>It is possible to write a specific module and enable it only on windows.
3.63 - See <a href="@org-openide-modules@/org/openide/modules/doc-files/api.html#how-os-specific">os specific modules</a> documentation.
3.64 - Then you can put a registration of your instance into your module's
3.65 - <a href="@TOP@/org/openide/util/doc-files/api.html#service-lookup">META-INF/services</a> directory and it
3.66 - will be available only on Windows.</p>
3.67 - </li>
3.68 -
3.69 - <li><p>Another possibility that does not require new module, but which executes
3.70 - a code on startup (which may have performance implications) is to use <code>methodvalue</code>
3.71 - attribute. Register your instance in layer using <code>your-Object.instance</code> file
3.72 - as described at
3.73 - <a href="@TOP@/org/openide/util/doc-files/api.html#ido-methodvalue">services
3.74 - </a> documentation and in your factory method either return the instance
3.75 - your want or <code>null</code> depending on result of <a href="@TOP@/org/openide/util/Utilities.html#isWindows()">
3.76 - Utilities.isWindows()</a> call.</p>
3.77 - </li>
3.78 - <li>
3.79 - <p>
3.80 - In some cases, the interface for which you will register an implementation permits a
3.81 - no-operation semantics. For example, <code>InstalledFileLocator.locate(...)</code> can
3.82 - return a valid <code>File</code>, or null. You could always register an
3.83 - <code>InstalledFileLocator</code> instance yet disable it on non-Windows platforms
3.84 - (always returning null).
3.85 - </p>
3.86 - </li>
3.87 -</ul>
3.88 -
3.89 - </usecase>
3.90 -
3.91 - <usecase id="lookup-extension-point" name="How shall I write an extension point for my module?" >
3.92 - <p>
3.93 - <em><b>Q:</b>
3.94 - I have more modules one of them providing the core functionality and
3.95 - few more that wish to extend it. What is the right way to do it?
3.96 - How does the Netbeans platform declare such extension point?
3.97 - </em>
3.98 - </p>
3.99 -
3.100 - <p>
3.101 -
3.102 - Start with declaring an extension interface in your
3.103 - core module and put it into the module's <em>public packages</em>. Imagine
3.104 - for example that the core module is in JAR file <code>org-my-netbeans-coremodule.jar</code>
3.105 - and already contains in manifests line like
3.106 - <code>OpenIDE-Module: org.my.netbeans.coremodule/1</code> and wants
3.107 - to display various tips of the day provided by other modules and thus defines:
3.108 - </p><pre>
3.109 -<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>
3.110 -
3.111 -<span class="java-keywords">public</span> <span class="java-keywords">interface</span> <span class="java-identifier">TipsOfTheDayProvider</span> <span class="java-operators">{</span>
3.112 - <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>
3.113 -<span class="java-operators">}</span>
3.114 -</pre><p>
3.115 - And in its manifest adds line
3.116 - <code>OpenIDE-Module-Public-Packages: org.my.netbeans.coremodule.*</code>
3.117 - to specify that this package contains exported API and shall be
3.118 - accessible to other modules.
3.119 - </p>
3.120 - <p>
3.121 - When the core module is about to display the tip of the day it can ask
3.122 - the system for all registered instances of the <code>TipsOfTheDayProvider</code>,
3.123 - randomly select one of them:
3.124 - </p><pre>
3.125 -<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>
3.126 -<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>
3.127 -<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>
3.128 -
3.129 -<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>
3.130 -<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>
3.131 -<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>
3.132 -<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>
3.133 -</pre><p>
3.134 - and then display the tip. Simple, trivial, just by the usage of
3.135 - <a href="@org-openide-util-lookup@/org/openide/util/Lookup.html">Lookup</a> interface once
3.136 - creates a registry that other modules can enhance. But such enhancing
3.137 - of course requires work on the other side. Each module that would like
3.138 - to register its <code>TipsOfTheDayProvider</code> needs to depend on the
3.139 - core module - add
3.140 - <code>OpenIDE-Module-Module-Dependencies: org.my.netbeans.coremodule/1</code>
3.141 - into its manifest and write a class with its own implementation of the
3.142 - provider:</p><pre>
3.143 -<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>
3.144 -
3.145 -<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>
3.146 - <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>
3.147 - <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>
3.148 - <span class="java-operators">}</span>
3.149 -<span class="java-operators">}</span>
3.150 -</pre><p>
3.151 - Then, the only necessary thing is to register such class by using the
3.152 - J2SE standard <api name="ProviderRegistrationMechanism"
3.153 - type="import"
3.154 - category="standard"
3.155 - group="java" /> into plain text file
3.156 - <code>META-INF/services/org.my.netbeans.coremodule.TipsOfTheDayProvider</code>
3.157 - in the module JAR containing just one line: </p><pre>
3.158 -org.my.netbeans.extramodule.ExtraTip
3.159 -</pre><p>
3.160 - and your modules are now ready to communicate
3.161 - using your own <em>extension point</em>.
3.162 - </p>
3.163 -
3.164 - </usecase>
3.165 -
3.166 -
3.167 <usecase id="logging" name="How shall I do or influence logging in NetBeans?">
3.168 <p>
3.169 If you are interested in logging from inside your module, or in writing
3.170 @@ -222,8 +86,6 @@
3.171 to start is the <a href="@TOP@/org/openide/util/doc-files/logging.html">NetBeans logging guide</a>.
3.172 </p>
3.173 </usecase>
3.174 -
3.175 -
3.176 </answer>
3.177
3.178
3.179 @@ -249,28 +111,6 @@
3.180 </p>
3.181 </answer>
3.182
3.183 -
3.184 -
3.185 - <answer id="compat-standards">
3.186 - <p>
3.187 - The default lookup registration follows the JDK's
3.188 - <api name="ProviderRegistrationMechanism"
3.189 - type="import"
3.190 - category="standard"
3.191 - url="http://java.sun.com/j2se/1.3/docs/guide/jar/jar.html#Provider%20Configuration%20File"
3.192 - group="java"
3.193 - />
3.194 - but enhances it to also support the
3.195 - <api
3.196 - name="ProviderRegistrationRemoval"
3.197 - type="export"
3.198 - category="devel"
3.199 - url="@TOP@/org/openide/util/doc-files/api.html#service-lookup"
3.200 - group="java"
3.201 - />.
3.202 - </p>
3.203 - </answer>
3.204 -
3.205 <answer id="compat-version">
3.206 <p>
3.207 This module has no settings.
3.208 @@ -486,50 +326,6 @@
3.209 used on few places
3.210 </api>.
3.211 </li>
3.212 -
3.213 - <li>
3.214 - <api type="export" group="property" name="org.openide.util.Lookup" category="devel">
3.215 - checked by the initialization of the
3.216 - <a href="@org-openide-util-lookup@/org/openide/util/Lookup.html#getDefault()">Lookup.getDefault()</a>
3.217 - and can
3.218 - contain name of a class that extends <code>org.openide.util.Lookup</code> and
3.219 - has public constructor, that should be instantiated and returned from
3.220 - <a href="@org-openide-util-lookup@/org/openide/util/Lookup.html#getDefault()">Lookup.getDefault()</a>
3.221 - the class will be loaded by
3.222 - <a href="@JDK@/java/lang/Thread.html#getContextClassLoader()">
3.223 - Thread.currentThread().getContextClassLoader()</a>
3.224 - classloader the first time <code>Lookup.getDefault</code> is invoked.
3.225 - <p/>
3.226 - The property can also contain value <code>"-"</code> which means to completely
3.227 - disable the lookup instantiation and return <a href="@org-openide-util-lookup@/org/openide/util/Lookup.html#EMPTY">Lookup.EMPTY</a>
3.228 - from <a href="@org-openide-util-lookup@/org/openide/util/Lookup.html#getDefault()">Lookup.getDefault()</a>.
3.229 - <p/>
3.230 - If the property is unspecified, the default <code>MetaInfServicesLookup</code>
3.231 - is constructed for <code>Thread.currentThread().getContextclassLoader()</code>
3.232 - that implements the <a href="architecture-summary.html#answer-compat-standards">JDK's standard</a>. If, by
3.233 - a chance an instance of
3.234 - <a href="@org-openide-util-lookup@/org/openide/util/Lookup.Provider.html">Lookup.Provider</a>
3.235 - is found
3.236 - in there, its lookup is returned as result. Otherwise the <code>MetaInfServicesLookup</code>
3.237 - is the result of <a href="@org-openide-util-lookup@/org/openide/util/Lookup.html#getDefault()">Lookup.getDefault()</a>.
3.238 - </api>
3.239 - </li>
3.240 -
3.241 - <li>
3.242 - <api type="export" group="property" name="org.openide.util.Lookup.paths" category="devel">
3.243 - Sometimes it may be useful for the Lookup to contains objects from
3.244 - some system file system folder. This can be done with
3.245 - <code>org.openide.util.Lookup.paths=Folder1:Folder2:Folder3</code>.
3.246 - If this property is set prior to first call to
3.247 - <a href="@org-openide-util-lookup@/org/openide/util/Lookup.html#getDefault()">Lookup.getDefault()</a>,
3.248 - it is split into pieces (separator is <code>':'</code>) and individual
3.249 - parts are then used to construct <code>Lookups.forPath("Folder1")</code>,
3.250 - etc. All these lookups then become part of the
3.251 - <a href="@org-openide-util-lookup@/org/openide/util/Lookup.html#getDefault()">Lookup.getDefault()</a>
3.252 - one. This property works since version 7.24
3.253 - </api>
3.254 - </li>
3.255 -
3.256 </ul>
3.257 </answer>
3.258
3.259 @@ -553,20 +349,11 @@
3.260 <api category="devel" group="java" name="WeakListener.setAccessible" type="export" url="@TOP@/org/openide/util/WeakListeners.html">
3.261 used to call the remove method using reflection
3.262 </api>.
3.263 - <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)">
3.264 - calls constructor of registered classes using reflection
3.265 - </api>.
3.266 <api category="private" group="lookup" name="ActionManagerInvocation" type="export" >
3.267 because of the API separation, <a href="@TOP@/org/openide/util/actions/CallableSystemAction.html">CallableSystemAction</a> uses lookup for <code>ActionsBridge</code>
3.268 provided by <code>org-openide-actions</code> module
3.269 when looking for <a href="@org-openide-actions@/org/openide/actions/ActionManager.html">org.openide.actions.ActionManager</a> implementation.
3.270 </api>.
3.271 - <api category="friend" group="java" name="Lookup.resetDefaultLookup" type="export">
3.272 - There is a static private method <code>Lookup.resetDefaultLookup</code> that
3.273 - is called by NbJUnit's <code>MockServices</code> to properly reset default
3.274 - lookup and fire changes to all registred listeners.
3.275 - </api>.
3.276 -
3.277 </p>
3.278 </answer>
3.279
3.280 @@ -631,12 +418,6 @@
3.281
3.282 <answer id="lookup-lookup">
3.283 <ul>
3.284 - <li><api name="LookupInitializationLookup" category="devel" group="lookup" type="export" url="#property-org.openide.util.Lookup">
3.285 - during
3.286 - initialization of the <a href="@org-openide-util-lookup@/org/openide/util/Lookup.html#getDefault()">Lookup.getDefault()</a>
3.287 - the <a href="@org-openide-util-lookup@/org/openide/util/Lookup.Provider.html">Lookup.Provider</a>
3.288 - is being searched</api>.
3.289 - </li>
3.290
3.291 <li><api name="LookupSharedClassObject" category="devel" group="lookup" type="export">
3.292 singleton subclasses of <a href="@TOP@/org/openide/util/SharedClassObject.html">SharedClassObject</a>
3.293 @@ -744,11 +525,6 @@
3.294 -->
3.295 <answer id="perf-limit">
3.296 <p>
3.297 - The default implementation of the <code>MetaInfServicesLookup</code> just
3.298 - keeps hashmap between queried classes and their implementations. The amount
3.299 - of memory is linear to amount of registered classes, but of course we
3.300 - are not counting the memory occupied by the instances which the lookup
3.301 - creates, that can be arbitrary.
3.302 </p>
3.303 </answer>
3.304