Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| org.openide.util 6.8.22
PREV NEXT | FRAMES NO FRAMES

# NetBeans Utilities API

See:
Description

Utilities API
org.openide | Provides ErrorManager - the central place for logging and reproting failures in NetBeans based system.
org.openide.util | A set of utility classes covering a few general infrastructure points in the Open APIs.
org.openide.util.actions | There are several types of standard actions that should be used for many user interactions within NetBeans.
org.openide.util.datatransfer | NetBeans uses special extensions to data transfer.
org.openide.util.io | A set of utility classes providing extensions to the Java I/O system.
org.openide.util.lookup | Support classes for the Registration and `Lookup` extension mechanism.
org.openide.xml | A set of utility classes assisting in the manipulation of XML documents in the IDE.

This module contains general classes needed in NetBeans, extensions to basic JRE contepts, useful methods and other UtilitiesAPI classes.

Also this module defines the Lookup which 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 LookupAPI allows the discovery and the LookupSPI simplifies creation and registration of own lookup objects.

### What is New (see all changes)?

- Nov 22 '05 Ability to create finished RequestProcessor task

  RequestProcessor.create(Runnable, boolean) has been added to allow creation of Task that has not executed its runnable yet, but looks like it is finished.

- Nov 11 '05 Less change notifications from ProxyLookup

  ProxyLookup.setLookups used to fire LookupEvent every time it was called. Now it always checks whether there was a change to the previous state. This will reduce the number of events delivered when a small change is made. Also results from both ProxyLookup and AbstractLookup were modified to return immutable `Collection`s. So do not try to modify them. It was always documented that the results, are immutable and also it was never said that a change is delivered when there is no change in the result, so this is considered compatible change, even it is know that at least one piece of code in NetBeans relied on this behaviour.

- Jun 12 '05 DynamicMenuContent interface added

  In order to support MacOSX top menus and to fix problems with deprecated JInlineMenu, this new interface was added that allows to handle dynamic content in Presenter.Menu and Presenter.Popup. If the instance returned by Presenter.Menu/Popup is an instance of DynamicMenuContent, it's methods are consulted when creating/updating the menu.

- Jun 10 '05 Support for interruption of RequestProcessor tasks

  When one calls RequestProcessor.Task.cancel(), the running thread gets interrupted if the RequestProcessor(string, int, boolean) constructor is used. There always was a way how to cancel not yet running Task, but if the task was already running, one was out of luck. Since now the thread running the task is interrupted and the Runnable can check for that and terminate its execution sooner. In the runnable one shall check for thread interruption and if true, return immediatelly as in this example:

      public void run () {
        while (veryLongTimeLook) {
          doAPieceOfIt ();

          if (Thread.interrupted ()) return;
        }
      }

- Jan 14 '05 `Lookups.exclude` added to simplify writing of lookups that filter content of other lookups

  New method that takes lookup and set of classes and return new lookup which contains everything from the original one except instances of the specified classes has been added.

### Use Cases

There is a great introduction to Lookup and its usage in its javadoc. Here is just a list of frequently asked or interesting questions slowly expanding as people ask them:

### Lookup faq:

##### 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.

- It is possible to write a specific module and enable it only on windows. See os specific modules documentation. Then you can put a registration of your instance into your module's META-INF/services directory and it will be available only on Windows.

- Another possibility that does not require new module, but which executes a code on startup (which may have performance implications) is to use `methodvalue` attribute. Register your instance in layer using `your-Object.instance` file as described at services documentation and in your factory method either return the instance your want or `null` depending on result of Utilities.isWindows() call.

- In some cases, the interface for which you will register an implementation permits a no-operation semantics. For example, `InstalledFileLocator.locate(...)` can return a valid `File`, or null. You could always register an `InstalledFileLocator` instance yet disable it on non-Windows platforms (always returning null).

##### 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 `org-my-netbeans-coremodule.jar` and already contains in manifests line like `OpenIDE-Module: org.my.netbeans.coremodule/1` and wants to display various tips of the day provided by other modules and thus defines:

    package org.my.netbeans.coremodule;

    public interface TipsOfTheDayProvider {
        public String provideTipOfTheDay ();
    }

And in its manifest adds line `OpenIDE-Module-Public-Packages: org.my.netbeans.coremodule.*` 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 `TipsOfTheDayProvider`, randomly select one of them:

    import java.util.Collection;
    import java.util.Collections;
    import org.openide.util.Lookup;

    Lookup.Result result = Lookup.getDefault ().lookup (new Lookup.Template (TipsOfTheDayProvider.class));
    Collection c = result.allInstances ();
    Collections.shuffle (c);
    TipsOfTheDayProvider selected = (TipsOfTheDayProvider)c.iterator ().next ();

and then display the tip. Simple, trivial, just by the usage of Lookup 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 `TipsOfTheDayProvider` needs to depend on the core module - add `OpenIDE-Module-Module-Dependencies: org.my.netbeans.coremodule/1` into its manifest and write a class with its own implementation of the provider:

    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?";
        }
    }

Then, the only necessary thing is to register such class by using the J2SE standard into plain text file `META-INF/services/org.my.netbeans.coremodule.TipsOfTheDayProvider` in the module JAR containing just one line:

    org.my.netbeans.extramodule.ExtraTip

and your modules are now ready to communicate using your own extension point.

### Exported Interfaces

This table lists all of the module exported APIs with defined stability classifications. It is generated based on answers to questions about the architecture of the module. Read them all...

##### Group of java interfaces

Interface Name | In/Out | Stability | Specified in What Document?
UtilitiesAPI | Exported | Official | .../org/openide/util/doc-files/api.html
LookupAPI | Exported | Official | .../util/lookup/doc-files/lookup-api.html allows the discovery
LookupSPI | Exported | Official | .../util/lookup/doc-files/lookup-spi.html simplifies creation and registration of own lookup objects
ProviderRegistrationRemoval | Exported | Under Development | .../org/openide/util/doc-files/api.html
AWTBridge | Exported | Private | .../modules/openide/util/AWTBridge.java a class that is looked up in Lookup.getDefault() and if registered can provide better UI elements for Actions.
SharedClassObject.setAccessible | Exported | Under Development | .../org/openide/util/SharedClassObject.html used to instantiate subclasses.
WeakListener.setAccessible | Exported | Under Development | .../org/openide/util/WeakListeners.html used to call the remove method using reflection
Lookups.metaInfServices | Exported | Under Development | .../org/openide/util/lookup/Lookups.html calls constructor of registered classes using reflection

##### Group of property interfaces

Interface Name | In/Out | Stability | Specified in What Document?
BrandingSupport | Exported | Official | org/openide/util/NbBundle.html which is similar to localization but also supports changes of resorces for application build on top of NetBeans. This is handled by our class NbBundle which reimplements the JDK's standard ResourceBundle to to take branding into the consideration.
HelpID | Exported | Standard | org/openide/util/HelpCtx.html read from JComponent.getClientProperty to simulate the standard javahelp behaviour and extract the help id for given component.
org.openide.util.SharedClassObject.initialize | Exported | Private | For purposes of SystemOption the SharedClassObject handles `getProperty ("org.openide.util.SharedClassObject.initialize")` in a special way, by returning `null` if initialization is not running and `Boolean.TRUE` if it is.
OpenIDE-Transmodal-Action | Exported | Under Development | CallbackSystemAction checks whether `action.getValue("OpenIDE-Transmodal-Action")` returns `Boolean.TRUE` to enable it in dialogs, otherwise the action is disabled when there is an open dialog.
netbeans.screen.insets | Exported | Private | Influences results of Utilities.getUsableScreenBounds
netbeans.taskbar.height | Exported | Private | Influences results of Utilities.getUsableScreenBounds
org.openide.util.Lookup | Exported | Under Development | checked by the initialization of the Lookup.getDefault() and can contain name of a class that extends `org.openide.util.Lookup` and has public constructor, that should be instantiated and returned from Lookup.getDefault() the class will be loaded by Thread.currentThread().getContextClassLoader() classloader the first time `Lookup.getDefault` is invoked. The property can also contain value `"-"` which means to completely disable the lookup instantiation and return Lookup.EMPTY from Lookup.getDefault(). If the property is unspecified, the default `MetaInfServicesLookup` is constructed for `Thread.currentThread().getContextclassLoader()` that implements the JDK's standard. If, by a chance an instance of Lookup.Provider is found in there, its lookup is returned as result. Otherwise the `MetaInfServicesLookup` is the result of Lookup.getDefault().

##### Group of java.io.File interfaces

Interface Name | In/Out | Stability | Specified in What Document?
FileLocation | Exported | Under Development | the JAR file is located in platform cluster under `lib/org-openide-util.jar`
TranslateNames | Exported | Official | org/openide/util/Utilities.html Utilities.translate reads `META-INF/netbeans/translate.names` files from JARs

##### Group of lookup interfaces

Interface Name | In/Out | Stability | Specified in What Document?
ActionManagerInvocation | Exported | Private | because of the API separation, CallableSystemAction uses lookup for `ActionsBridge` provided by `org-openide-actions` module when looking for org.openide.actions.ActionManager implementation.
LookupInitializationLookup | Exported | Under Development | #property-org.openide.util.Lookup during initialization of the Lookup.getDefault() the Lookup.Provider is being searched
LookupSharedClassObject | Exported | Under Development | singleton subclasses of SharedClassObject are searched for using Lookup.
LookupContextGlobalProvider | Exported | Stable | actionsGlobalContext searches for ContextGlobalProvider in Lookup.getDefault(). The provider is usually provided by window system implementation.
LookupEntityCatalog | Exported | Under Development | EntityCatalog delegates its methods to all instances of EntityCatalogs found in Lookup
LookupErrorManager | Exported | Under Development | ErrorManager delegates its methods to all instances of ErrorManagers found in Lookup
LookupClassLoader | Exported | Under Development | Nearly all resource looking functions and reflective code uses ClassLoader obtained from Lookup.getDefault() for loading system wide resources.

### Implementation Details

##### What do other modules need to do to declare a dependency on this one?

OpenIDE-Module-Module-Dependencies: org.openide.util > 6.8.22

Read more about the implementation in the answers to architecture questions.

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| org.openide.util 6.8.22
PREV NEXT | FRAMES NO FRAMES

Built on December 7 2006. | Portions Copyright 1997-2005 Sun Microsystems, Inc. All rights reserved.