org.openide.util
Class Utilities

java.lang.Object
  extended by org.openide.util.Utilities

public final class Utilities
extends java.lang.Object

Otherwise uncategorized useful static methods.

Author:
Jan Palka, Ian Formanek, Jaroslav Tulach

Nested Class Summary
(package private) static interface Utilities.RE
          Interfaces for communication between Utilities.translate and regular expression impl.
static class Utilities.UnorderableException
          Deprecated. Used only by the deprecated partialSort
 
Field Summary
static int OS_AIX
          Operating system is IBM AIX.
static int OS_DEC
          Deprecated. please use OS_TRU64 instead
static int OS_FREEBSD
          Operating system is FreeBSD
static int OS_HP
          Operating system is HP-UX.
static int OS_IRIX
          Operating system is SGI IRIX.
static int OS_LINUX
          Operating system is Linux.
static int OS_MAC
          Operating system is Mac.
static int OS_OS2
          Operating system is OS/2.
static int OS_OTHER
          Operating system is unknown.
static int OS_SOLARIS
          Operating system is Solaris.
static int OS_SUNOS
          Operating system is Sun OS.
static int OS_TRU64
          Operating system is Compaq TRU64 Unix
static int OS_UNIX_MASK
          A mask for Unix platforms.
static int OS_VMS
          Operating system is Compaq OpenVMS
static int OS_WIN_OTHER
          Operating system is one of the Windows variants but we don't know which one it is
static int OS_WIN2000
          Operating system is Windows 2000.
static int OS_WIN95
          Operating system is Windows 95.
static int OS_WIN98
          Operating system is Windows 98.
static int OS_WINDOWS_MASK
          A mask for Windows platforms.
static int OS_WINNT
          Operating system is Windows NT.
static int TYPICAL_WINDOWS_TASKBAR_HEIGHT
          A height of the windows's taskbar
 
Method Summary
static Lookup actionsGlobalContext()
          Global context for actions.
static javax.swing.JPopupMenu actionsToPopup(javax.swing.Action[] actions, java.awt.Component component)
          Builds a popup menu for provided component.
static javax.swing.JPopupMenu actionsToPopup(javax.swing.Action[] actions, Lookup context)
          Builds a popup menu from actions for provided context specified by Lookup.
static java.lang.ref.ReferenceQueue<java.lang.Object> activeReferenceQueue()
          Useful queue for all parts of system that use java.lang.ref.References together with some ReferenceQueue and need to do some clean up when the reference is enqueued.
static int arrayHashCode(java.lang.Object[] arr)
          Compute hash code of array.
static void attachInitJob(java.awt.Component comp4Init, AsyncGUIJob initJob)
          Attaches asynchronous init job to given component.
static boolean compareObjects(java.lang.Object o1, java.lang.Object o2)
          Safe equality check.
static boolean compareObjectsImpl(java.lang.Object o1, java.lang.Object o2, int checkArraysDepth)
          Safe equality check with array recursion.
static java.awt.Cursor createCustomCursor(java.awt.Component component, java.awt.Image icon, java.lang.String name)
           
static java.awt.Cursor createProgressCursor(java.awt.Component component)
          Returns a cursor with an arrow and an hourglass (or stop watch) badge, to be used when a component is busy but the UI is still responding to the user.
static java.lang.String escapeParameters(java.lang.String[] params)
          Complementary method to parseParameters
static java.awt.Rectangle findCenterBounds(java.awt.Dimension componentSize)
          Helps client code place components on the center of the screen.
static java.beans.BeanInfo getBeanInfo(java.lang.Class clazz)
          Central method for obtaining BeanInfo for potential JavaBean classes.
static java.beans.BeanInfo getBeanInfo(java.lang.Class clazz, java.lang.Class stopClass)
          Central method for obtaining BeanInfo for potential JavaBean classes, with a stop class.
static java.lang.String getClassName(java.lang.Class clazz)
          Assemble a human-presentable class name for a specified class.
static java.awt.Component getFocusTraversableComponent(java.awt.Component c)
          Find a focus-traverable component.
static java.lang.Class getObjectType(java.lang.Class c)
          Get the object type for given primitive type.
static int getOperatingSystem()
          Get the operating system on which NetBeans is running.
static java.lang.Class getPrimitiveType(java.lang.Class c)
          Get the primitive type for given object type.
static java.awt.Dimension getScreenSize()
          Deprecated. this method is almost useless in multiple monitor configuration
static java.lang.String getShortClassName(java.lang.Class clazz)
          Assemble a human-presentable class name for a specified class (omitting the package).
static java.awt.Rectangle getUsableScreenBounds()
          Returns the usable area of the screen where applications can place its windows.
static java.awt.Rectangle getUsableScreenBounds(java.awt.GraphicsConfiguration gconf)
          Returns the usable area of the screen where applications can place its windows.
static java.awt.Image icon2Image(javax.swing.Icon icon)
          Converts given icon to a Image.
(package private) static void initForLoader(java.lang.ClassLoader current, java.lang.Object set)
           
static boolean isJavaIdentifier(java.lang.String id)
          Test whether a given string is a valid Java identifier.
static boolean isLargeFrameIcons()
          Deprecated. Obsolete, useless method, no replacement.
static boolean isMac()
          Test whether NetBeans is running on MacOS.
static boolean isUnix()
          Test whether NetBeans is running on some variant of Unix.
static boolean isWindows()
          Test whether NetBeans is running on some variant of Windows.
static java.lang.String keyToString(javax.swing.KeyStroke stroke)
          Converts a Swing key stroke descriptor to a familiar Emacs-like name.
static java.awt.Image loadImage(java.lang.String resourceID)
          Loads an image from the specified resource ID.
static java.awt.Image loadImage(java.lang.String resource, boolean localized)
          Loads an image based on resource path.
static java.awt.Image mergeImages(java.awt.Image image1, java.awt.Image image2, int x, int y)
          This method merges two images into the new one.
static java.lang.String[] parseParameters(java.lang.String s)
          Parses parameters from a given string in shell-like manner.
static java.util.List partialSort(java.util.List l, java.util.Comparator c, boolean stable)
          Deprecated. Deprecated in favor of the potentially much faster (and possibly more correct) topologicalSort(java.util.Collection, java.util.Map>).
static java.lang.String pureClassName(java.lang.String fullName)
          Turn full name of an inner class into its pure form.
static java.lang.String replaceString(java.lang.String original, java.lang.String replaceFrom, java.lang.String replaceTo)
          Search-and-replace fixed string matches within a string.
(package private) static void resetOperatingSystem()
           
static int showJFileChooser(javax.swing.JFileChooser chooser, java.awt.Component parent, java.lang.String approveButtonText)
          Deprecated. Not needed in JDK 1.4.
static javax.swing.KeyStroke stringToKey(java.lang.String s)
          Construct a new key description from a given universal string description.
static javax.swing.KeyStroke[] stringToKeys(java.lang.String s)
          Convert a space-separated list of user-friendly key binding names to a list of Swing key strokes.
static java.io.File toFile(java.net.URL u)
          Deprecated. Use URI.URI(String) and File.File(URI) instead under JDK 1.4. (There was no proper equivalent under JDK 1.3.)
static java.lang.Object[] toObjectArray(java.lang.Object array)
          Convert an array of primitive types to an array of objects.
static
<T> java.util.List<T>
topologicalSort(java.util.Collection<T> c, java.util.Map<? super T,? extends java.util.Collection<? extends T>> edges)
          Topologically sort some objects.
static java.lang.Object toPrimitiveArray(java.lang.Object[] array)
          Convert an array of objects to an array of primitive types.
static java.net.URL toURL(java.io.File f)
          Deprecated. Use File.toURI() and URI.toURL() instead under JDK 1.4. (File.toURL() is buggy in JDK 1.3 and the bugs are not fixed in JDK 1.4.)
static java.lang.String translate(java.lang.String className)
          Provides support for parts of the system that deal with classnames (use Class.forName, NbObjectInputStream, etc.).
(package private) static
<T> java.util.List<T>
visit(T node, java.util.Map<? super T,? extends java.util.Collection<? extends T>> edges, java.util.Map<T,java.lang.Boolean> finished, java.util.List<T> r)
          Visit one node in the DAG.
static java.lang.String wrapString(java.lang.String original, int width, boolean wrapWords, boolean removeNewLines)
          Deprecated. Use (String, int, BreakIterator, boolean) as it is friendlier to I18N.
static java.lang.String wrapString(java.lang.String original, int width, java.text.BreakIterator breakIterator, boolean removeNewLines)
          Wrap multi-line strings.
static java.lang.String[] wrapStringToArray(java.lang.String original, int width, boolean wrapWords, boolean removeNewLines)
          Deprecated. use wrapStringToArray(String, int, BreakIterator, boolean) since it is better for I18N
static java.lang.String[] wrapStringToArray(java.lang.String original, int width, java.text.BreakIterator breakIterator, boolean removeNewLines)
          Wrap multi-line strings (and get the individual lines).
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

OS_WINNT

public static final int OS_WINNT
Operating system is Windows NT.

See Also:
Constant Field Values

OS_WIN95

public static final int OS_WIN95
Operating system is Windows 95.

See Also:
Constant Field Values

OS_WIN98

public static final int OS_WIN98
Operating system is Windows 98.

See Also:
Constant Field Values

OS_SOLARIS

public static final int OS_SOLARIS
Operating system is Solaris.

See Also:
Constant Field Values

OS_LINUX

public static final int OS_LINUX
Operating system is Linux.

See Also:
Constant Field Values

OS_HP

public static final int OS_HP
Operating system is HP-UX.

See Also:
Constant Field Values

OS_AIX

public static final int OS_AIX
Operating system is IBM AIX.

See Also:
Constant Field Values

OS_IRIX

public static final int OS_IRIX
Operating system is SGI IRIX.

See Also:
Constant Field Values

OS_SUNOS

public static final int OS_SUNOS
Operating system is Sun OS.

See Also:
Constant Field Values

OS_TRU64

public static final int OS_TRU64
Operating system is Compaq TRU64 Unix

See Also:
Constant Field Values

OS_DEC

@Deprecated
public static final int OS_DEC
Deprecated. please use OS_TRU64 instead
See Also:
Constant Field Values

OS_OS2

public static final int OS_OS2
Operating system is OS/2.

See Also:
Constant Field Values

OS_MAC

public static final int OS_MAC
Operating system is Mac.

See Also:
Constant Field Values

OS_WIN2000

public static final int OS_WIN2000
Operating system is Windows 2000.

See Also:
Constant Field Values

OS_VMS

public static final int OS_VMS
Operating system is Compaq OpenVMS

See Also:
Constant Field Values

OS_WIN_OTHER

public static final int OS_WIN_OTHER
Operating system is one of the Windows variants but we don't know which one it is

See Also:
Constant Field Values

OS_OTHER

public static final int OS_OTHER
Operating system is unknown.

See Also:
Constant Field Values

OS_FREEBSD

public static final int OS_FREEBSD
Operating system is FreeBSD

Since:
4.50
See Also:
Constant Field Values

OS_WINDOWS_MASK

public static final int OS_WINDOWS_MASK
A mask for Windows platforms.

See Also:
Constant Field Values

OS_UNIX_MASK

public static final int OS_UNIX_MASK
A mask for Unix platforms.

See Also:
Constant Field Values

TYPICAL_WINDOWS_TASKBAR_HEIGHT

public static final int TYPICAL_WINDOWS_TASKBAR_HEIGHT
A height of the windows's taskbar

See Also:
Constant Field Values
Method Detail

activeReferenceQueue

public static java.lang.ref.ReferenceQueue<java.lang.Object> activeReferenceQueue()
Useful queue for all parts of system that use java.lang.ref.References together with some ReferenceQueue and need to do some clean up when the reference is enqueued. Usually, in order to be notified about that, one needs to either create a dedicated thread that blocks on the queue and is Object.notify-ed, which is the right approach but consumes valuable system resources (threads) or one can periodically check the content of the queue by RequestProcessor.Task.schedule which is completely wrong, because it wakes up the system every (say) 15 seconds. In order to provide useful support for this problem, this queue has been provided.

If you have a reference that needs cleanup, make it implement Runnable and register it with the queue:

 class MyReference extends WeakReference implements Runnable {
     private final OtherInfo dataToCleanUp;
     public MyReference(Thing ref, OtherInfo data) {
         super(ref, Utilities.activeReferenceQueue());
         dataToCleanUp = data;
     }
     public void run() {
         dataToCleanUp.releaseOrWhateverYouNeed();
     }
 }
 
When the ref object is garbage collected, your run method will be invoked by calling ((Runnable) reference).run() and you can perform whatever cleanup is necessary. Be sure not to block in such cleanup for a long time as this prevents other waiting references from cleaning themselves up.

Do not call any ReferenceQueue methods. They will throw exceptions. You may only enqueue a reference.

Be sure to call this method anew for each reference. Do not attempt to cache the return value.

Since:
3.11

getOperatingSystem

public static final int getOperatingSystem()
Get the operating system on which NetBeans is running.

Returns:
one of the OS_* constants (such as OS_WINNT)

isWindows

public static final boolean isWindows()
Test whether NetBeans is running on some variant of Windows.

Returns:
true if Windows, false if some other manner of operating system

isMac

public static final boolean isMac()
Test whether NetBeans is running on MacOS.

Returns:
true if Mac, false if some other manner of operating system
Since:
7.7

isUnix

public static final boolean isUnix()
Test whether NetBeans is running on some variant of Unix. Linux is included as well as the commercial vendors.

Returns:
true some sort of Unix, false if some other manner of operating system

resetOperatingSystem

static final void resetOperatingSystem()

isJavaIdentifier

public static final boolean isJavaIdentifier(java.lang.String id)
Test whether a given string is a valid Java identifier.

Parameters:
id - string which should be checked
Returns:
true if a valid identifier

getBeanInfo

public static java.beans.BeanInfo getBeanInfo(java.lang.Class clazz)
                                       throws java.beans.IntrospectionException
Central method for obtaining BeanInfo for potential JavaBean classes.

Parameters:
clazz - class of the bean to provide the BeanInfo for
Returns:
the bean info
Throws:
java.beans.IntrospectionException - for the usual reasons
See Also:
Introspector.getBeanInfo(Class)

getBeanInfo

public static java.beans.BeanInfo getBeanInfo(java.lang.Class clazz,
                                              java.lang.Class stopClass)
                                       throws java.beans.IntrospectionException
Central method for obtaining BeanInfo for potential JavaBean classes, with a stop class.

Parameters:
clazz - class of the bean to provide the BeanInfo for
stopClass - the stop class
Returns:
the bean info
Throws:
java.beans.IntrospectionException - for the usual reasons
See Also:
Introspector.getBeanInfo(Class, Class)

wrapStringToArray

@Deprecated
public static java.lang.String[] wrapStringToArray(java.lang.String original,
                                                              int width,
                                                              boolean wrapWords,
                                                              boolean removeNewLines)
Deprecated. use wrapStringToArray(String, int, BreakIterator, boolean) since it is better for I18N

Wrap multi-line strings (and get the individual lines).

Parameters:
original - the original string to wrap
width - the maximum width of lines
wrapWords - if true, the lines are wrapped on word boundaries (if possible); if false, character boundaries are used
removeNewLines - if true, any newlines in the original string are ignored
Returns:
the lines after wrapping

wrapStringToArray

public static java.lang.String[] wrapStringToArray(java.lang.String original,
                                                   int width,
                                                   java.text.BreakIterator breakIterator,
                                                   boolean removeNewLines)
Wrap multi-line strings (and get the individual lines).

Parameters:
original - the original string to wrap
width - the maximum width of lines
breakIterator - breaks original to chars, words, sentences, depending on what instance you provide.
removeNewLines - if true, any newlines in the original string are ignored
Returns:
the lines after wrapping

wrapString

public static java.lang.String wrapString(java.lang.String original,
                                          int width,
                                          java.text.BreakIterator breakIterator,
                                          boolean removeNewLines)
Wrap multi-line strings.

Parameters:
original - the original string to wrap
width - the maximum width of lines
breakIterator - algorithm for breaking lines
removeNewLines - if true, any newlines in the original string are ignored
Returns:
the whole string with embedded newlines

wrapString

@Deprecated
public static java.lang.String wrapString(java.lang.String original,
                                                     int width,
                                                     boolean wrapWords,
                                                     boolean removeNewLines)
Deprecated. Use (String, int, BreakIterator, boolean) as it is friendlier to I18N.

Wrap multi-line strings.

Parameters:
original - the original string to wrap
width - the maximum width of lines
wrapWords - if true, the lines are wrapped on word boundaries (if possible); if false, character boundaries are used
removeNewLines - if true, any newlines in the original string are ignored
Returns:
the whole string with embedded newlines

replaceString

public static java.lang.String replaceString(java.lang.String original,
                                             java.lang.String replaceFrom,
                                             java.lang.String replaceTo)
Search-and-replace fixed string matches within a string.

Parameters:
original - the original string
replaceFrom - the substring to be find
replaceTo - the substring to replace it with
Returns:
a new string with all occurrences replaced

pureClassName

public static final java.lang.String pureClassName(java.lang.String fullName)
Turn full name of an inner class into its pure form.

Parameters:
fullName - e.g. some.pkg.SomeClass$Inner
Returns:
e.g. Inner

isLargeFrameIcons

@Deprecated
public static final boolean isLargeFrameIcons()
Deprecated. Obsolete, useless method, no replacement.

Test whether the operating system supports icons on frames (windows).

Returns:
true if it does not

arrayHashCode

public static int arrayHashCode(java.lang.Object[] arr)
Compute hash code of array. Asks all elements for their own code and composes the values.

Parameters:
arr - array of objects, can contain nulls
Returns:
the hash code
See Also:
Object.hashCode()

compareObjects

public static boolean compareObjects(java.lang.Object o1,
                                     java.lang.Object o2)
Safe equality check. The supplied objects are equal if: This method is null-safe, so if one of the parameters is true and the second not, it returns false.

Parameters:
o1 - the first object to compare
o2 - the second object to compare
Returns:
true if the objects are equal

compareObjectsImpl

public static boolean compareObjectsImpl(java.lang.Object o1,
                                         java.lang.Object o2,
                                         int checkArraysDepth)
Safe equality check with array recursion.

Parameters:
o1 - the first object to compare
o2 - the second object to compare
checkArraysDepth - the depth to which arrays should be compared for equality (negative for infinite depth, zero for no comparison of elements, one for shallow, etc.)
Returns:
true if the objects are equal
See Also:
compareObjects(Object, Object)

getClassName

public static java.lang.String getClassName(java.lang.Class clazz)
Assemble a human-presentable class name for a specified class. Arrays are represented as e.g. java.lang.String[].

Parameters:
clazz - the class to name
Returns:
the human-presentable name

getShortClassName

public static java.lang.String getShortClassName(java.lang.Class clazz)
Assemble a human-presentable class name for a specified class (omitting the package). Arrays are represented as e.g. String[].

Parameters:
clazz - the class to name
Returns:
the human-presentable name

toPrimitiveArray

public static java.lang.Object toPrimitiveArray(java.lang.Object[] array)
Convert an array of objects to an array of primitive types. E.g. an Integer[] would be changed to an int[].

Parameters:
array - the wrapper array
Returns:
a primitive array
Throws:
java.lang.IllegalArgumentException - if the array element type is not a primitive wrapper

toObjectArray

public static java.lang.Object[] toObjectArray(java.lang.Object array)
Convert an array of primitive types to an array of objects. E.g. an int[] would be turned into an Integer[].

Parameters:
array - the primitive array
Returns:
a wrapper array
Throws:
java.lang.IllegalArgumentException - if the array element type is not primitive

getObjectType

public static java.lang.Class getObjectType(java.lang.Class c)
Get the object type for given primitive type.

Parameters:
c - primitive type (e.g. int)
Returns:
object type (e.g. Integer)

getPrimitiveType

public static java.lang.Class getPrimitiveType(java.lang.Class c)
Get the primitive type for given object type.

Parameters:
c - object type (e.g. Integer)
Returns:
primitive type (e.g. int)

getFocusTraversableComponent

public static java.awt.Component getFocusTraversableComponent(java.awt.Component c)
Find a focus-traverable component.

Parameters:
c - the component to look in
Returns:
the same component if traversable, else a child component if present, else null
See Also:
Component.isFocusTraversable()

parseParameters

public static java.lang.String[] parseParameters(java.lang.String s)
Parses parameters from a given string in shell-like manner. Users of the Bourne shell (e.g. on Unix) will already be familiar with the behavior. For example, when using org.openide.execution.NbProcessDescriptor (Execution API) you should be able to: Caveat: even after parsing, Windows programs (such as the Java launcher) may not fully honor certain characters, such as quotes, in command names or arguments. This is because programs under Windows frequently perform their own parsing and unescaping (since the shell cannot be relied on to do this). On Unix, this problem should not occur.

Parameters:
s - a string to parse
Returns:
an array of parameters

escapeParameters

public static java.lang.String escapeParameters(java.lang.String[] params)
Complementary method to parseParameters

See Also:
parseParameters(java.lang.String)

keyToString

public static java.lang.String keyToString(javax.swing.KeyStroke stroke)
Converts a Swing key stroke descriptor to a familiar Emacs-like name.

Parameters:
stroke - key description
Returns:
name of the key (e.g. CS-F1 for control-shift-function key one)
See Also:
stringToKey(java.lang.String)

stringToKey

public static javax.swing.KeyStroke stringToKey(java.lang.String s)
Construct a new key description from a given universal string description. Provides mapping between Emacs-like textual key descriptions and the KeyStroke object used in Swing.

This format has following form:

[C][A][S][M]-identifier

Where:

The format also supports two wildcard codes, to support differences in platforms. These are the preferred choices for registering keystrokes, since platform conflicts will automatically be handled: If you use the wildcard characters, and specify a key which will conflict with keys the operating system consumes, it will be mapped to whichever choice can work - for example, on Macintosh, Command-Q is always consumed by the operating system, so D-Q will always map to Control-Q.

Every modifier before the hyphen must be pressed. identifier can be any text constant from KeyEvent but without the leading VK_ characters. So KeyEvent.VK_ENTER is described as ENTER.

Parameters:
s - the string with the description of the key
Returns:
key description object, or null if the string does not represent any valid key

stringToKeys

public static javax.swing.KeyStroke[] stringToKeys(java.lang.String s)
Convert a space-separated list of user-friendly key binding names to a list of Swing key strokes.

Parameters:
s - the string with keys
Returns:
array of key strokes, or null if the string description is not valid
See Also:
stringToKey(java.lang.String)

getUsableScreenBounds

public static java.awt.Rectangle getUsableScreenBounds()
Returns the usable area of the screen where applications can place its windows. The method subtracts from the screen the area of taskbars, system menus and the like. The screen this method applies to is the one which is considered current, ussually the one where the current input focus is.

Returns:
the rectangle of the screen where one can place windows
Since:
2.5

getUsableScreenBounds

public static java.awt.Rectangle getUsableScreenBounds(java.awt.GraphicsConfiguration gconf)
Returns the usable area of the screen where applications can place its windows. The method subtracts from the screen the area of taskbars, system menus and the like.

Parameters:
gconf - the GraphicsConfiguration of the monitor
Returns:
the rectangle of the screen where one can place windows
Since:
2.5

findCenterBounds

public static java.awt.Rectangle findCenterBounds(java.awt.Dimension componentSize)
Helps client code place components on the center of the screen. It handles multiple monitor configuration correctly

Parameters:
componentSize - the size of the component
Returns:
bounds of the centered component
Since:
2.5

getScreenSize

@Deprecated
public static final java.awt.Dimension getScreenSize()
Deprecated. this method is almost useless in multiple monitor configuration

Returns:
size of the screen. The size is modified for Windows OS - some points are subtracted to reflect a presence of the taskbar
See Also:
getUsableScreenBounds(), findCenterBounds(Dimension)

showJFileChooser

@Deprecated
public static final int showJFileChooser(javax.swing.JFileChooser chooser,
                                                    java.awt.Component parent,
                                                    java.lang.String approveButtonText)
Deprecated. Not needed in JDK 1.4.

Utility method for avoiding of memory leak in JDK 1.3 / JFileChooser.showDialog(...)

Parameters:
parent -
approveButtonText -

partialSort

@Deprecated
public static java.util.List partialSort(java.util.List l,
                                                    java.util.Comparator c,
                                                    boolean stable)
                                  throws Utilities.UnorderableException
Deprecated. Deprecated in favor of the potentially much faster (and possibly more correct) topologicalSort(java.util.Collection, java.util.Map>).

Sort a list according to a specified partial order. Note that in the current implementation, the comparator will be called exactly once for each distinct pair of list elements, ignoring order, so caching its results is a waste of time.

Parameters:
l - the list to sort (will not be modified)
c - a comparator to impose the partial order; "equal" means that the elements are not ordered with respect to one another, i.e. may be only a partial order
stable - whether to attempt a stable sort, meaning that the position of elements will be disturbed as little as possible; might be slightly slower
Returns:
the partially-sorted list
Throws:
Utilities.UnorderableException - if the specified partial order is inconsistent on this list

topologicalSort

public static <T> java.util.List<T> topologicalSort(java.util.Collection<T> c,
                                                    java.util.Map<? super T,? extends java.util.Collection<? extends T>> edges)
                                         throws TopologicalSortException
Topologically sort some objects.

There may not be any nulls among the objects, nor duplicates (as per hash/equals), nor duplicates among the edge lists. The edge map need not contain an entry for every object, only if it has some outgoing edges (empty but not null map values are permitted). The edge map shall not contain neither keys nor value entries for objects not in the collection to be sorted, if that happens they will be ignored (since version 7.9).

The incoming parameters will not be modified; they must not be changed during the call and possible calls to TopologicalSortException methods. The returned list will support modifications.

There is a weak stability guarantee: if there are no edges which contradict the incoming order, the resulting list will be in the same order as the incoming elements. However if some elements need to be rearranged, it is not guaranteed that others will not also be rearranged, even if they did not strictly speaking need to be.

Parameters:
c - a collection of objects to be topologically sorted
edges - constraints among those objects, of type Map<Object,Collection>; if an object is a key in this map, the resulting order will have that object before any objects listed in the value
Returns:
a partial ordering of the objects in the collection,
Throws:
TopologicalSortException - if the sort cannot succeed due to cycles in the graph, the exception contains additional information to describe and possibly recover from the error
Since:
3.30
See Also:
Issue #27286

visit

static <T> java.util.List<T> visit(T node,
                                   java.util.Map<? super T,? extends java.util.Collection<? extends T>> edges,
                                   java.util.Map<T,java.lang.Boolean> finished,
                                   java.util.List<T> r)
Visit one node in the DAG.

Parameters:
node - node to visit
edges - edges in the DAG
finished - which nodes are finished; a node has no entry if it has not yet been visited, else it is set to false while recurring and true when it has finished
r - the order in progress
Returns:
list with detected cycle

translate

public static java.lang.String translate(java.lang.String className)
Provides support for parts of the system that deal with classnames (use Class.forName, NbObjectInputStream, etc.).

Often class names (especially package names) changes during lifecycle of a module. When some piece of the system stores the name of a class in certain point of a time and wants to find the correct Class later it needs to count with the possibility of rename.

For such purposes this method has been created. It allows modules to register their classes that changed names and other parts of system that deal with class names to find the correct names.

To register a mapping from old class names to new ones create a file META-INF/netbeans/translate.names in your module and fill it with your mapping:

 #
 # Mapping of legacy classes to new ones
 #

 org.oldpackage.MyClass=org.newpackage.MyClass # rename of package for one class
 org.mypackage.OldClass=org.mypackage.NewClass # rename of class in a package

 # rename of class and package
 org.oldpackage.OldClass=org.newpackage.NewClass

 # rename of whole package
 org.someoldpackage=org.my.new.package.structure

 
Btw. one can use spaces instead of = sign. For a real world example check the xml module.

For purposes of org.openide.util.io.NbObjectInputStream there is a following special convention: If the className is not listed as one that is to be renamed, the returned string == className, if the className is registered to be renamed than the className != returned value, even in a case when className.equals (retValue)

Parameters:
className - fully qualified name of a class to translate
Returns:
new name of the class according to renaming rules.

initForLoader

static void initForLoader(java.lang.ClassLoader current,
                          java.lang.Object set)

mergeImages

public static final java.awt.Image mergeImages(java.awt.Image image1,
                                               java.awt.Image image2,
                                               int x,
                                               int y)
This method merges two images into the new one. The second image is drawn over the first one with its top-left corner at x, y. Images need not be of the same size. New image will have a size of max(second image size + top-left corner, first image size). Method is used mostly when second image contains transparent pixels (e.g. for badging). If both images are null, it makes default transparent 16x16 image.

Parameters:
image1 - underlying image
image2 - second image
x - x position of top-left corner
y - y position of top-left corner
Returns:
new merged image

loadImage

public static final java.awt.Image loadImage(java.lang.String resourceID)
Loads an image from the specified resource ID. The image is loaded using the "system" classloader registered in Lookup.

Parameters:
resourceID - resource path of the icon (no initial slash)
Returns:
icon's Image, or null, if the icon cannot be loaded.

icon2Image

public static final java.awt.Image icon2Image(javax.swing.Icon icon)
Converts given icon to a Image.

Parameters:
icon - Icon to be converted.
Since:
7.3

actionsToPopup

public static javax.swing.JPopupMenu actionsToPopup(javax.swing.Action[] actions,
                                                    Lookup context)
Builds a popup menu from actions for provided context specified by Lookup. Takes list of actions and for actions whic are instances of ContextAwareAction creates and uses the context aware instance. Then gets the action presenter or simple menu item for the action to the popup menu for each action (or separator for each 'lonely' null array member).

Parameters:
actions - array of actions to build menu for. Can contain null elements, they will be replaced by separators
context - the context for which the popup is build
Returns:
the constructed popup menu
Since:
3.29
See Also:
ContextAwareAction

actionsToPopup

public static javax.swing.JPopupMenu actionsToPopup(javax.swing.Action[] actions,
                                                    java.awt.Component component)
Builds a popup menu for provided component. It retrieves context (lookup) from provided component instance or one of its parent (it searches up to the hierarchy for Lookup.Provider instance). If none of the components is Lookup.Provider instance, then it is created context which is fed with composite ActionMap which delegates to all components up to hierarchy started from the specified one. Then actionsToPopup(Action[], Lookup)} is called with the found Lookup instance, which actually creates a popup menu.

Parameters:
actions - array of actions to build menu for. Can contain null elements, they will be replaced by separators
component - a component in which to search for a context
Returns:
the constructed popup menu
Since:
3.29
See Also:
Lookup.Provider, actionsToPopup(Action[], Lookup)

actionsGlobalContext

public static Lookup actionsGlobalContext()
Global context for actions. Toolbar, menu or any other "global" action presenters shall operate in this context. Presenters for context menu items should not use this method; instead see ContextAwareAction.

Returns:
the context for actions
Since:
4.10
See Also:
ContextGlobalProvider

loadImage

public static final java.awt.Image loadImage(java.lang.String resource,
                                             boolean localized)
Loads an image based on resource path. Exactly like loadImage(String) but may do a localized search. For example, requesting org/netbeans/modules/foo/resources/foo.gif might actually find org/netbeans/modules/foo/resources/foo_ja.gif or org/netbeans/modules/foo/resources/foo_mybranding.gif.

Caching of loaded images can be used internally to improve performance.

Since:
3.24

createProgressCursor

public static final java.awt.Cursor createProgressCursor(java.awt.Component component)
Returns a cursor with an arrow and an hourglass (or stop watch) badge, to be used when a component is busy but the UI is still responding to the user. Similar to the predefined Cursor.WAIT_CURSOR, but has an arrow to indicate a still-responsive UI.

Typically you will set the cursor only temporarily:

  // code is running in other then event dispatch thread
  currentComponent.setCursor(Utilities.createProgressCursor(currentComponent));
  try {
      // perform some work in other than event dispatch thread
      // (do not block UI)
  } finally {
      currentComponent.setCursor(null);
  }
  

This implementation provides one cursor for all Mac systems, one for all Unix systems (regardless of window manager), and one for all other systems including Windows.

Parameters:
component - the non-null component that will use the progress cursor
Returns:
a progress cursor (Unix, Windows or Mac)
Since:
3.23

createCustomCursor

public static java.awt.Cursor createCustomCursor(java.awt.Component component,
                                                 java.awt.Image icon,
                                                 java.lang.String name)

attachInitJob

public static final void attachInitJob(java.awt.Component comp4Init,
                                       AsyncGUIJob initJob)
Attaches asynchronous init job to given component. AsyncGUIJob.construct() will be called after first paint, when paint event arrives. Later, AsyncGUIJob.finished() will be called according to the rules of the AsyncGUIJob interface. Useful for components that have slower initialization phase, component can benefit from more responsive behaviour during init.

Parameters:
comp4Init - Regular component in its pre-inited state, state in which component will be shown between first paint and init completion.
initJob - Initialization job to be called asynchronously. Job can optionally implement Cancellable interface for proper cancel logic. Cancel method will be called when component stops to be showing during job's progress. See Component.isShowing()
Since:
3.36

toURL

@Deprecated
public static java.net.URL toURL(java.io.File f)
                          throws java.net.MalformedURLException
Deprecated. Use File.toURI() and URI.toURL() instead under JDK 1.4. (File.toURL() is buggy in JDK 1.3 and the bugs are not fixed in JDK 1.4.)

Convert a file to a matching file: URL.

Parameters:
f - a file (absolute only)
Returns:
a URL using the file protocol
Throws:
java.net.MalformedURLException - for no good reason
Since:
3.26
See Also:
toFile(java.net.URL), Issue #29711

toFile

@Deprecated
public static java.io.File toFile(java.net.URL u)
Deprecated. Use URI.URI(String) and File.File(URI) instead under JDK 1.4. (There was no proper equivalent under JDK 1.3.)

Convert a file: URL to a matching file.

You may not use a URL generated from a file on a different platform, as file name conventions may make the result meaningless or even unparsable.

Parameters:
u - a URL with the file protocol
Returns:
an absolute file it points to, or null if the URL does not seem to point to a file at all
Since:
3.26
See Also:
toURL(java.io.File), Issue #29711