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)?

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.
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 NameIn/OutStabilitySpecified in What Document?
UtilitiesAPIExportedOfficial .../org/openide/util/doc-files/api.html

LookupAPIExportedOfficial .../util/lookup/doc-files/lookup-api.html

allows the discovery

LookupSPIExportedOfficial .../util/lookup/doc-files/lookup-spi.html

simplifies creation and registration of own lookup objects

ProviderRegistrationRemovalExportedUnder Development .../org/openide/util/doc-files/api.html

AWTBridgeExportedPrivate .../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.setAccessibleExportedUnder Development .../org/openide/util/SharedClassObject.html

used to instantiate subclasses.

WeakListener.setAccessibleExportedUnder Development .../org/openide/util/WeakListeners.html

used to call the remove method using reflection

Lookups.metaInfServicesExportedUnder Development .../org/openide/util/lookup/Lookups.html

calls constructor of registered classes using reflection

Group of property interfaces
Interface NameIn/OutStabilitySpecified in What Document?
BrandingSupportExportedOfficialorg/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.

HelpIDExportedStandardorg/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.initializeExportedPrivate

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-ActionExportedUnder 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.insetsExportedPrivate

Influences results of Utilities.getUsableScreenBounds

netbeans.taskbar.heightExportedPrivate

Influences results of Utilities.getUsableScreenBounds

org.openide.util.LookupExportedUnder 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 NameIn/OutStabilitySpecified in What Document?
FileLocationExportedUnder Development

the JAR file is located in platform cluster under lib/org-openide-util.jar

TranslateNamesExportedOfficialorg/openide/util/Utilities.html

Utilities.translate reads META-INF/netbeans/translate.names files from JARs

Group of lookup interfaces
Interface NameIn/OutStabilitySpecified in What Document?
ActionManagerInvocationExportedPrivate

because of the API separation,
CallableSystemAction uses lookup for ActionsBridge provided by org-openide-actions module when looking for org.openide.actions.ActionManager implementation.

LookupInitializationLookupExportedUnder Development#property-org.openide.util.Lookup

during initialization of the Lookup.getDefault() the Lookup.Provider is being searched

LookupSharedClassObjectExportedUnder Development

singleton subclasses of
SharedClassObject are searched for using Lookup.

LookupContextGlobalProviderExportedStable

actionsGlobalContext searches for ContextGlobalProvider in Lookup.getDefault(). The provider is usually provided by window system implementation.

LookupEntityCatalogExportedUnder Development

EntityCatalog delegates its methods to all instances of EntityCatalogs found in Lookup

LookupErrorManagerExportedUnder Development

ErrorManager delegates its methods to all instances of ErrorManagers found in Lookup

LookupClassLoaderExportedUnder 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.1

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


 

Built on May 3 2007.  |  Portions Copyright 1997-2005 Sun Microsystems, Inc. All rights reserved.