Quelle arch.xml Sprache: XML

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

<!DOCTYPE api-answers PUBLIC "-//NetBeans//DTD Arch Answers//EN" "../../nbbuild/antsrc/org/netbeans/nbbuild/Arch.dtd" [
 <!ENTITY api-questions SYSTEM "../../nbbuild/antsrc/org/netbeans/nbbuild/Arch-api-questions.xml">
]>

<api-answers
 question-version="1.25"
 author="jtulach@netbeans.org"
>

 &api-questions;

<answer id="arch-overall">
 
 This module defines the <a href="@TOP@/org/openide/util/Lookup.html">
 Lookup</a> which is the NetBeans way for dynamic registration
 and lookup of
 components in our modularized component system. It allows lookup and discovery
 of features by description of their interfaces. The classes are devided
 into two parts. The
 <api group="java" name="LookupAPI" type="export" category="official" url="@TOP@/org/openide/util/lookup/doc-files/lookup-api.html">
 allows the discovery</api> and the
 <api group="java" name="LookupSPI" type="export" category="official" url="@TOP@/org/openide/util/lookup/doc-files/lookup-spi.html">
 simplifies creation and registration of own lookup objects</api>.
 
</answer>

<answer id="arch-quality">
 
 There is a lot of unit tests in
 <a href="https://github.com/apache/netbeans/tree/master/platform/openide.util.lookup/test/unit/src">version control</a>
 system.
 
</answer>

<answer id="arch-time">
 
 The module has been around since 1997 and is continously being improved
 from time to time.
 
</answer>

<answer id="arch-usecases">
 <a href="https://leanpub.com/nbp4beginners">
 <img src="http://wiki.apidesign.org/images/0/03/NetBeansPlatformForBeginners.jpg"
 style="float: right"
 width="60" height="70" alt="Cover of NetBeans Platform for Beginners book"/>
 </a>

 There is a great introduction to Lookup and its usage in its
 <a href="@TOP@/org/openide/util/Lookup.html">javadoc</a>.
 For details on this topic,
 together with code samples, see chapter 4,
 of <a href="https://leanpub.com/nbp4beginners">NetBeans Platform for Beginners</a>
 by Jason Wexbridge and Walter Nyland.
 In addition to that here is
 a list of frequently asked or interesting questions slowly expanding as
 people ask them:

 <h3>Lookup faq:</h3>

 <usecase id="lookup-on-certain-platform" name="How to specify that a service in Lookup should be available only on Windows?" >
Q:
Most of the time I specify interfaces that I want to add to the Lookup class in the layer.xml file.
But, let's say I have a platform-specific interface (something on Windows only, for instance).


How can I specify (in the xml, or programmatically) that this service should only be added to the Lookup if the platform is Windows?
>

In general there are three ways to achieve this.
<ul>
 <li>It is possible to write a specific module and enable it only on windows.
 See <a href="@org-openide-modules@/org/openide/modules/doc-files/api.html#how-os-specific">os specific modules</a> documentation.
 Then you can put a registration of your instance into your module's
 <a href="@org-openide-util@/org/openide/util/doc-files/api.html#service-lookup">META-INF/services</a> directory and it
 will be available only on Windows.
 </li>

 <li>Another possibility that does not require new module, but which executes
 a code on startup (which may have performance implications) is to use <code>methodvalue</code>
 attribute. Register your instance in layer using <code>your-Object.instance</code> file
 as described at
 <a href="@org-openide-util@/org/openide/util/doc-files/api.html#ido-methodvalue">services
 </a> documentation and in your factory method either return the instance
 your want or <code>null</code> depending on result of <a href="@org-openide-util@/org/openide/util/BaseUtilities.html#isWindows()">
 Utilities.isWindows()</a> call.
 </li>
 <li>
 
 In some cases, the interface for which you will register an implementation permits a
 no-operation semantics. For example, <code>InstalledFileLocator.locate(...)</code> can
 return a valid <code>File</code>, or null. You could always register an
 <code>InstalledFileLocator</code> instance yet disable it on non-Windows platforms
 (always returning null).
 
 </li>
</ul>

 </usecase>

 <usecase id="lookup-extension-point" name="How shall I write an extension point for my module?" >
 
 Q:
 I have more modules one of them providing the core functionality and
 few more that wish to extend it. What is the right way to do it?
 How does the Netbeans platform declare such extension point?
 
 

 

 Start with declaring an extension interface in your
 core module and put it into the module's public packages. Imagine
 for example that the core module is in JAR file <code>org-my-netbeans-coremodule.jar</code>
 and already contains in manifests line like
 <code>OpenIDE-Module: org.my.netbeans.coremodule/1</code> and wants
 to display various tips of the day provided by other modules and thus defines:
 <pre>
package org.my.netbeans.coremodule;

public interface TipsOfTheDayProvider {
 public String provideTipOfTheDay ();
}
</pre>
 And in its manifest adds line
 <code>OpenIDE-Module-Public-Packages: org.my.netbeans.coremodule.*</code>
 to specify that this package contains exported API and shall be
 accessible to other modules.
 
 
 When the core module is about to display the tip of the day it can ask
 the system for all registered instances of the <code>TipsOfTheDayProvider</code>,
 randomly select one of them:
 <pre>
import java.util.Collection;
import java.util.Collections;
import org.openide.util.Lookup;

<a href="@TOP@org/openide/util/Lookup.Result.html">Lookup.Result</a> result = <a href="@TOP@org/openide/util/Lookup.html">Lookup</a>.getDefault ().lookup (new <a href="@TOP@org/openide/util/Lookup.Template.html">Lookup.Template</a> (TipsOfTheDayProvider.class));
Collection c = result.<a href="@TOP@org/openide/util/Lookup.Result.html#allInstances()">allInstances</a> ();
Collections.shuffle (c);
TipsOfTheDayProvider selected = (TipsOfTheDayProvider)c.iterator ().next ();
</pre>
 and then display the tip. Simple, trivial, just by the usage of
 <a href="@TOP@org/openide/util/Lookup.html">Lookup</a> interface once
 creates a registry that other modules can enhance. But such enhancing
 of course requires work on the other side. Each module that would like
 to register its <code>TipsOfTheDayProvider</code> needs to depend on the
 core module - add
 <code>OpenIDE-Module-Module-Dependencies: org.my.netbeans.coremodule/1</code>
 into its manifest and write a class with its own implementation of the
 provider:<pre>
package org.my.netbeans.extramodule;

class ExtraTip implements TipsOfTheDayProvider {
 public String provideTipOfTheDay () {
 return "Do you know that in order to write extension point you should use Lookup?";
 }
}
</pre>
 Then, the only necessary thing is to register such class by using the
 J2SE standard <api name="ProviderRegistrationMechanism"
 type="import"
 category="standard"
 group="java" /> into plain text file
 <code>META-INF/services/org.my.netbeans.coremodule.TipsOfTheDayProvider</code>
 in the module JAR containing just one line: <pre>
org.my.netbeans.extramodule.ExtraTip
</pre>
 and your modules are now ready to communicate
 using your own extension point.
 

 </usecase>
</answer>

<answer id="arch-what">
 
 Described in the <a href="@TOP@/architecture-summary.html#answer-arch-overall">overall</a> answer.
 
</answer>

<answer id="compat-standards">
 
 The default lookup registration follows the JDK's
 <api name="ProviderRegistrationMechanism"
 type="import"
 category="standard"
 url="https://docs.oracle.com/javase/1.5.0/docs/guide/jar/jar.html#Provider%20Configuration%20File"
 group="java"
 />
 
 but enhances it to also support the
 <api
 name="ProviderRegistrationRemoval"
 type="export"
 category="devel"
 url="@org-openide-util@/org/openide/util/doc-files/api.html#service-lookup"
 group="java"
 />.
 
</answer>

<answer id="compat-version">
 
 This module has no settings.
 
</answer>

<answer id="dep-jre">
 
 Currently JRE 1.5 is needed.
 
</answer>

<answer id="dep-jrejdk">
 
 JRE is enough.
 
</answer>

<answer id="dep-nb">
 N/A
</answer>

<answer id="dep-platform">
 
 Platform independent.
 
</answer>

<answer id="deploy-dependencies">
 
 Nothing.
 
</answer>

<answer id="deploy-jar">
 
 <api category="devel" group="java.io.File" name="FileLocation" type="export" >
 the JAR file is located in platform cluster under <code>lib/org-openide-util-lookup.jar</code>
 </api>.
 
</answer>

<answer id="deploy-shared">
 
 Module is on real java classpath and as such it has to be in the shared directory.
 
</answer>

<answer id="exec-ant-tasks">
 
 No.
 
</answer>

<answer id="exec-classloader">
 
 No, we do not create own classloader.
 
</answer>

<answer id="exec-privateaccess">
 
 No.
 
</answer>

<answer id="exec-process">
 
 No external processes executed.
 
</answer>

<answer id="exec-property">
 <ul>
 <li>
 <api type="export" group="systemproperty" name="org.openide.util.Lookup" category="devel">
 checked by the initialization of the
 <a href="@TOP@/org/openide/util/Lookup.html#getDefault()">Lookup.getDefault()</a>
 and can
 contain name of a class that extends <code>org.openide.util.Lookup</code> and
 has public constructor, that should be instantiated and returned from
 <a href="@TOP@/org/openide/util/Lookup.html#getDefault()">Lookup.getDefault()</a>
 the class will be loaded by
 <a href="@JDK@@JDKMODULE_JAVA_BASE@/java/lang/Thread.html#getContextClassLoader()">
 Thread.currentThread().getContextClassLoader()</a>
 classloader the first time <code>Lookup.getDefault</code> is invoked.
 
 The property can also contain value <code>"-"</code> which means to completely
 disable the lookup instantiation and return <a href="@TOP@/org/openide/util/Lookup.html#EMPTY">Lookup.EMPTY</a>
 from <a href="@TOP@/org/openide/util/Lookup.html#getDefault()">Lookup.getDefault()</a>.
 
 If the property is unspecified, the default <code>MetaInfServicesLookup</code>
 is constructed for <code>Thread.currentThread().getContextclassLoader()</code>
 that implements the <a href="architecture-summary.html#answer-compat-standards">JDK's standard. If, by
 a chance an instance of
 <a href="@TOP@/org/openide/util/Lookup.Provider.html">Lookup.Provider</a>
 is found
 in there, its lookup is returned as result. Otherwise the <code>MetaInfServicesLookup</code>
 is the result of <a href="@TOP@/org/openide/util/Lookup.html#getDefault()">Lookup.getDefault()</a>.
 </api>
 </li>

 <li>
 <api type="export" group="systemproperty" name="org.openide.util.Lookup.paths" category="devel">
 Sometimes it may be useful for the Lookup to contains objects from
 some system file system folder. This can be done with
 <code>org.openide.util.Lookup.paths=Folder1:Folder2:Folder3</code>.
 If this property is set prior to first call to
 <a href="@TOP@/org/openide/util/Lookup.html#getDefault()">Lookup.getDefault()</a>,
 it is split into pieces (separator is <code>':'</code>) and individual
 parts are then used to construct <code>Lookups.forPath("Folder1")</code>,
 etc. All these lookups then become part of the
 <a href="@TOP@/org/openide/util/Lookup.html#getDefault()">Lookup.getDefault()</a>
 one. This property works since version 7.24
 </api>
 </li>

 </ul>
</answer>

<answer id="exec-reflection">
 
 <api category="devel" group="java" name="Lookups.metaInfServices" type="export" url="@TOP@/org/openide/util/lookup/Lookups.html#metaInfServices(java.lang.ClassLoader)">
 calls constructor of registered classes using reflection
 </api>.
 <api category="friend" group="java" name="Lookup.resetDefaultLookup" type="export">
 There is a static private method <code>Lookup.resetDefaultLookup</code> that
 is called by NbJUnit's MockServices to properly reset default
 lookup and fire changes to all registred listeners.
 </api>.

 
</answer>

<answer id="exec-threading">
 
 Everything is synchronous, except pluggable use of <code>java.util.concurrent.Executor</code>
 that allows to make calls asynchronous. The default implementation only delivers
 changes from <a href="@TOP@/org/openide/util/lookup/Lookups.html#metaInfServices(java.lang.ClassLoader)">metaInfServices</a>
 lookup in asynchronous thread.
 
</answer>

<answer id="format-clipboard">
 
 Not used.
 
</answer>

<answer id="format-dnd">
 
 The same as for clipboard.
 
</answer>

<answer id="format-types">
 
 No.
 
</answer>

<answer id="lookup-lookup">
 <ul>
 <li><api name="LookupInitializationLookup" category="devel" group="lookup" type="export" url="#systemproperty-org.openide.util.Lookup">
 during
 initialization of the <a href="@TOP@/org/openide/util/Lookup.html#getDefault()">Lookup.getDefault()</a>
 the <a href="@TOP@/org/openide/util/Lookup.Provider.html">Lookup.Provider</a>
 is being searched</api>.
 </li>

 <li><api name="LookupSharedClassObject" category="devel" group="lookup" type="export">
 singleton subclasses of <a href="@org-openide-util-ui@/org/openide/util/SharedClassObject.html">SharedClassObject</a>
 are searched for using Lookup.
 </api>.</li>

 <li><api name="LookupClassLoader" category="devel" group="lookup" type="export">
 Nearly all resource looking functions and reflective code
 uses <a href="@JDK@@JDKMODULE_JAVA_BASE@/java/lang/ClassLoader.html">ClassLoader</a>
 obtained from <a href="@TOP@/org/openide/util/Lookup.html#getDefault()">Lookup.getDefault()</a>
 for loading system wide resources.
 </api>.</li>

 </ul>
</answer>

<answer id="lookup-register">
 
 No.
 
</answer>


<answer id="lookup-remove">
 
 No.
 
</answer>


<answer id="perf-exit">
 
 Nothing.
 
</answer>


<answer id="perf-huge_dialogs">
 
 No.
 
</answer>


<answer id="perf-limit">
 
 The default implementation of the <code>MetaInfServicesLookup</code> just
 keeps hashmap between queried classes and their implementations. The amount
 of memory is linear to amount of registered classes, but of course we
 are not counting the memory occupied by the instances which the lookup
 creates, that can be arbitrary.
 
</answer>


<answer id="perf-mem">
 
 There are no big data structures. The amount of memory occupied by
 instances of <a href="@TOP@/org/openide/util/lookup/AbstractLookup.html">AbstractLookup</a>
 is measured by unit tests.
 
</answer>


<answer id="perf-menus">
 
 There are no menus.
 
</answer>


<answer id="perf-progress">
 
 No.
 
</answer>


<answer id="perf-scale">
 
 Lookup code scales linearily.
 
</answer>


<answer id="perf-spi">
 
 No enforcing is done.
 
</answer>


<answer id="perf-startup">
 
 No.
 
</answer>


<answer id="perf-wakeup">
 
 No.
 
</answer>


<answer id="resources-file">
 
 No.
 
</answer>


<answer id="resources-layer">
 
 No.
 
</answer>


<answer id="resources-mask">
 
 No.
 
</answer>


<answer id="resources-read">
 
 No.
 
</answer>


<answer id="security-grant">
 
 No security permitions manipulated.
 
</answer>


<answer id="security-policy">
 
 No security permissions manipulated.
 
</answer>


<answer id="arch-where">
 <defaultanswer generate='here' />
</answer>


<answer id="compat-deprecation">
 
 XXX no answer for compat-deprecation
 
</answer>


<answer id="resources-preferences">
 
 XXX no answer for resources-preferences
 
</answer>

</api-answers>

quality100%

¤ Dauer der Verarbeitung: 0.22 Sekunden (vorverarbeitet) ¤

Wurzel

Suchen

Beweissystem der NASA

Beweissystem Isabelle

NIST Cobol Testsuite

Cephes Mathematical Library

Wiener Entwicklungsmethode

Haftungshinweis

Die Informationen auf dieser Webseite wurden nach bestem Wissen sorgfältig zusammengestellt. Es wird jedoch weder Vollständigkeit, noch Richtigkeit, noch Qualität der bereit gestellten Informationen zugesichert.

Bemerkung:

Die farbliche Syntaxdarstellung ist noch experimentell.