Method Detail

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:

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.

parseParameters

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:

Include command names with embedded spaces, such as c:\Program Files\jdk\bin\javac.

Include extra command arguments, such as -Dname=value.

Do anything else which might require unusual characters or processing. For example:

This example would create the following executable name and arguments:

c:\program files\jdk\bin\java

-Dmessage=Hello /\/\ there!

-Xmx128m

Note that the command string does not escape its backslashes--under the assumption
that Windows users will not think to do this, meaningless escapes are just left
as backslashes plus following character.

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.

topologicalSort

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

translate

Provides support for parts of the system that deal with classnames
(use Class.forName, NbObjectInputStream, etc.) or filenames
in layers.

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
# class was removed without replacement
org.mypackage.OldClass=

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)

Similar behaviour applies to filenames provided by layers (system filesystem). Filenames
can be also translated to adapt to location changes e.g. in action registrations. Note that
no spaces or special characters are allowed in both translated filenames or translation
results. Filenames must conform to regexp ^[/a-zA-Z0-9$_.+-]+$. Keys and values are treated
as paths from fs root.