The Filesystems API specifies no order in folder children (FileObject.getChildren). But the Datasystems API does assign a meaning to the order of DataFolder.getChildren. Currently there are four ways a folder may get an order:

The third way is the only one suitable for a modular system. It has been in use since NetBeans 3.1. Unfortunately it suffers from several drawbacks:

To ensure that the folder order will hold up even when some modules are disabled, it is common to overspecify ordering, which can lead to a near-quadratic number of attrs; when this is not done, it is common for folders to fall into haphazard order as the set of modules changes in unexpected ways.

To address these problems, the solution is to add a fifth means of ordering a folder. Every file in the folder could have a Number-valued attribute position. Files would then be sorted (in increasing order) by position. This would also be consistent with Lookups.metaInfServices.

For example:

Normally positive integers would be used for positions, but floats or negative integers could be used for emergencies in case an item needed to be inserted between two adjacent integers.

Files with no marked position would be placed at the end (and a brief warning logged). Files with the same position would be ordered alphabetically (and a brief warning logged). As an exception, you may mark files with the position 0 to indicate that their position is irrelevant; no warning is logged if several such files exist in the same folder.

Numeric and relative ordering can coexist, for backwards compatibility.

Uses of relative ordering attributes should be logged as warnings to assist in migration.

DataFolder.setOrder should remove any of the old ordering methods in effect and set positions on each file in the folder. The tricky part is to avoid changing the positions of files which already have positions unless necessary to accommodate the new order.

For example, given an initial folder content:

and asked to set the order to d a c b, it would be best to change only two attributes, e.g.:

or something similar.

I.e. first need to compute a minimal set of transpositions.

Then use some heuristics to decide which of a pair in a transposition to "move", and what its new position should be. Heuristics could include:

Introduce methods to order a folder in FileUtil in the Filesystems API, and to set a new order. This avoids duplicating somewhat subtle code. Since callers might be ignoring some files in a folder (e.g. *.form) the list of files to consider needs to be passed as well.

(used in: core/startup, core/windows, editor/mimelookup/impl, openide/loaders)

For menu folders and other places where there is a distinguished null value or other separator, it is generally permitted to have extra separators. (Leading, trailing, or adjacent duplicate separators are ignored.) With numeric ordering, a simple convention could help group items into separated blocks.

For example:

will display as:

but it is easy to add new items at the top, bottom, or middle of any block; add new blocks at any position; divide existing blocks; etc.

The editor folders under SideBar were using a position attribute for a different purpose. These have been converted (compatibly) to use location instead.

Fixed in bulk mode using apisupport/relative2position.

ValidateLayerConsistencyTest (in core) should verify that:

Implemented. Run not only in the trunk Hudson project (i.e. full IDE), but also in nbms-and-javadoc (to check experimental modules).