Page History

...

Where 'S' is an optional folder suffix. Note that services registered in subfolders do not mix, and they do not mix with 'generic' services in the base MIMEtype folder (no subfolder suffix) either.  The most generic registrations reside in Editor/{S }. MIME service registrations are usually processed in the order enumerated by the Lookup by editor and other servicessubsystems. So if one defines a position attribute for a registration .instance file, that file is ordered accordingly in the enumeration.

...

Generic services (in Editors/) typically do not have any position/ordering information.  Most languages are just indifferent to the order. Maybe it's not important for the function, or  just do not define any order. I suppose that that the natural (declaration) order (textual order of appearance in the layer XML) is what the language implementation wantssatisfies the needs, especially if the registrations are written in the XML layer file. The This language's assumption may break once an extension is developed, with specific needs for ordering. The important thing to remember is that some or mime-specific folders define order, but some do not.

...

In the current situation, a generic service (in Editors/S ) cannot be safely registered - the committer risks that he will extend a contract (positions defined) from module Foo to all other modules.

The service could eventually register with position=0 (but warning must not have been printed for such situation), but that would also mean it would take precedence over all items in more specific MIME types - typically positioned using positive integers (see docs). Could potentially break existing 3rd party modules.

Overall state

As it turns out, the most obtrusive change is the introduction of LSP CompletionProvider in the Editors/ (MIME type ""). Incidentally this is the service (CompletionProvider) that most languages see that 'natural declaration order' is sufficient. See, for example:
- Latte - https://github.com/apache/netbeans/blob/master/php/php.latte/src/org/netbeans/modules/php/latte/resources/layer.xml#L41
- Smarty - https://github.com/apache/netbeans/blob/master/php/php.smarty/src/org/netbeans/modules/php/smarty/resources/layer.xml#L63
- (Twig, ..)
- JSP - https://github.com/apache/netbeans/blob/master/enterprise/web.core.syntax/src/org/netbeans/modules/web/core/syntax/resources/layer.xml#L138
- HTML - https://github.com/apache/netbeans/blob/master/ide/html.editor/src/org/netbeans/modules/html/editor/resources/layer.xml#L149

...

During fixing commit-validation, in PR-2359 (https://github.com/apache/netbeans/pull/2359), I tried to introduce automatically generated positions, if the annotated element just does not care: this fixes the usual MIME use case: if the provider does not care, just define _some_ order, at the end (to remind: a special value of 0 means that the position is irrelevant, but should be put sorted first).

It turned out that all those declaration order registrations (Latte, HTML, ...) broke and had to define an explicit order now, so they do not produce a warning in presence of auto-generated position attributes. Which is not entirely bad: Without an order explicitly set, with sufficient 'gaps', the MIME type is not extensible: If a XML (text/x-xml) defines two providers with no order, then it is impossible for JavaFX FMXL (text/x-fxml+xml) to insert a provider in between those two.  But for most languages,which (typically) do not provide services or boilerplate for others. this is just a complication. 

Another breakage was introduced by "some module" (java hints) that declared in UpToDateStatusProvider using annotation, which auto-declared the position. As a result, about 10-15 registrations of other UpToDateStatusProviders, in base Editors/ and all other MIME types neede to be changed: at first, the position in a specific MIME type caused generic Providers with positions undefined to fail commit-validation  test. In the subsequent round (when these were fitted with appropriate position values), the other MIME types that declared UpToDateStatusProvider started failing.

Look at an experimental branch and its diff against master: https://github.com/apache/netbeans/compare/master...sdedic:origin/bugfix/commitvalidation-fixes2?expand=1fixes3

Summary of problem

• there's NO WAY how to register a service in Editors/ (unspecified mimetype), that would pass current commit-validation
• the unspecified mimetype ("") was specifically designed to define universal services, for all editors (without that, this is what the entire MIME inheritance is about)
• once some obscure module eregisters a service in "" MIME type, he is likely to force all distribution modules to use positions in their registrations from that time onwards. Remember: if ANY mimetype uses positions in a specific MIME subfolder, all must use them (in that subfolder).

...

DO NOT test for mix positions / no positions in Editors/* area under FileUtil.getConfigRoot(). This is the easiest, but we loose the assurance of some order of the registered services .(which is IMHO too strict anyway, given the scenarios above)

Define positions (almost) everywhere

...

• intvalue="0", defined as it is now: ordered first, order within 0 rack is alphabetical. Do not report duplicates. Compatilibity feature.
• floatvalue="0.0": I don't care, sort last in the declaration order. Do not report duplicates.
• floatvalue="-x.0" (no fractional part): IF order is defined, sort me at the given position; check duplicates.

In addition neither of these values (note the change: even intvalue="0" !) will be treated as 'explicit position', so mix of position/undefined will not be reported, if the only defined positions will be 0es.

The MIME annotation processor would then by default generate nothing (again). LSP or other generic registrations cam use either "floatvalue=0.0", or floatvalue="-whatever.0", depending on whether order is or is not important. Furthermore,

If the FileSystem API changes as 

FileUtil.getOrder(Collection<FileObject> items, @Nullable Number defaultOrder, boolean printWarnings)

MIME lookup implementation can imply its default (in its registration area) without bloating the layers and without printing unnecessary warnings.That the MIME lookup is composed as MultiFileSystem from the layers (individual MIME types), starting with the most specific, the most generic last. Beacause of the way how MultiFileSystem is implemented, child files are enumerated in the order of the delegates: that is, they will be enumerated starting from the most specific to the least specific ones. In this scenario, They could eventually use just intvalue="0", but that would also mean they would take precedence over more specific MIME registrations. Given how (implementation-wise) the MIME MultiFileSystem is composed:

• position float="0.0" will favour the more specific declarations over the less specific ones, provided none of them has position defined;
• declarations with positions defined will sort according to those positions, AFTER all intvalue="0" (compatibility) and BEFORE floatvalue="0.0" (new feature);

If the API extends to 

List<FileObject> FileUtil.getOrder(Collection<FileObject> items, @Nullable Number defaultOrder, boolean printWarning);

MIME lookup could order all undefined registrations into the same (last rack), retaining most-specific to least-specific order between them, and allow all explicit (positive integers and floats) positions to take precedence. 

Benefits of this complicated setup are:

• most modules can continue to write .instance files without any positions.
• @MimeRegistration need not to specify or generate positions
• wherever positions are defined, they are used to order the positioned items.
• the hack for ProjectType service registry will be eliminated

Consistency check

The current consistency check is too strict - as outlined above, it basically prevents introduction of generic services to MIME lookup - only at expense of ordering the service folders in all MIME types in the the whole NetBeans distribution. But it is still good to ensure that the order is well-defined on individual levels of MIME registry, e.g. that a particular language either defines order for all service registrations, or for none of them. With the proposed changes above, generic services will be typically registered in a way that does not define order. So the test will primarily ensure that if the language defines order on services, the order is well-defined.