Overview (MIME Lookup API)

MIME Lookup API
Package	Description
org.netbeans.api.editor.mimelookup
org.netbeans.spi.editor.mimelookup	The SPI allows registering providers of mime type specific `Lookup`s.

It consists of

MimeLookupAPI in org.netbeans.api.editor.mimelookup
MimeLookupSPI in org.netbeans.spi.editor.mimelookup

API contains only two classes:

1. org.netbeans.api.editor.mimelookup.MimeLookup with public methods:

static MimeLookup getMimeLookup(String mime) - gets mime specific lookup.
static Lookup getLookup(MimePath mimePath) - gets the lookup for the particular mime-path.
MimeLookup childLookup(String mime) - gets mime specific child (embeded) lookup. The method was deprecated in favour of static Lookup getLookup(MimePath mimePath)
Object lookup(Class clazz) - Look up an object matching a given interface.
Result lookup(Lookup.Template template) - The general lookup method. Callers can get list of all instances and classes that match the given template and attach a listener to this be notified about changes.

2. org.netbeans.api.editor.mimelookup.MimePath with public methods:

static MimePath get(String mimeType) - gets root mime-path for the given mime-type.
static MimePath get(MimePath prefix, String mimeType) - gets mime-path corresponding to the mime-type used in the given context mime-path.
static MimePath parse(String path) - parses the given mime-path string e.g. "text/x-jsp/text/x-java" and get the corresponding mime-path.
String getPath() - gets string path represented by this mime-path.
int size() -gets total number of mime-types in the mime-path.
String getMimeType(int index) - gets mime type of this mime-path at the given index.
MimePath getPrefix(int size) - returns prefix mime-path with the given number of mime-type components ranging from zero till the size of this mime-path.

MimeLookup is represented via ProxyLookup that collects registered lookups. Particular lookups, responsible for looking up their objects can be registered using interface MimeDataProvider into default lookup by META-INF/services registration. Previously used registration via interface MimeLookupInitializer was deprecated.

In addition to this basic registration, xml layer folder registration is also available. It is provided by registering implemented interface Class2LayerFolder into default lookup via META-INF/services registration. This approach provides a mapping of class to specific subfolder. Using this mapping one can achieve the convenient way of using MimeLookup e.g.

MimeLookup.getMimeLookup("text/x-java").lookup(FoldManagerFactory.class);

Using this, an instance of FoldManagerFactory is retrieved from the folder with path "Editors/text/x-java/FoldManager" provided that FoldManagerFactory.class is registered to a subfolder "FoldManager" via Class2LayerFolder registration.

There InstanceProvider can be used if there are files of various types in the layer folder that need additional handling before becoming and instance of certain class. For more details look at use case of PopupActions creation.

The Javadoc documentation can be generated by using

    cd /cvs/editor/mimelookup
    ant javadoc

What is New (see all changes)?

Feb 27 '13 Access to parent MIME type and all included paths

getIncludedPaths can be now used to compute all MimePaths that should be considered for the content. In the past, reflection was used to access this functionality.

getInheritedType provides generalized or parent MIME type for the content, which allows to search settings (services) fallbacks.
Oct 4 '10 Class2LayerFolder Deprecated and not used
Class2LayerFolder has been deprecated and is ignored.
Oct 4 '10 @MimeLocation, @MimeRegistration and @MimeRegistrations added
Added @MimeLocation, @MimeRegistration and @MimeRegistrations that allow to register services to the MimeLookup.
Sep 18 '07 MimeLookup.getLookup(String mimePath) method added
MimeLookup.getLookup(String mimePath) converts the (usually held) string mimePath to the MimePath object automatically.
Jun 28 '07 MimePath.validate methods added
The validate(CharSequence path) and validate(CharSequence type, CharSequence subtype) methods were added to the MimePath class to allow validating mime paths and mime type components.

Use Cases

Per mime-type operation

Operation of the editor module must be parametrized by the type of the file being edited. In the past the operation was parametrized by the class of the editor kit but that did not show up as being useful enough.
It is more practical to use a string-based parametrization concretely the mime-type. Anyone can then easily register an additional functionality for the editor because it's just enough to know the right mime-type and the type of the functionality class to be implemented and the xml layer folder where the class should be registered.

Provide list of instances as lookup result

On the modules' implementation side the registered functionality must be retrieved somehow. It's necessary to instantiate the registered objects and react to module enabling/disabling which can affect validity of the registered objects.
As the most convenient solution appears to use org.openide.util.Lookup allowing to provide the registered instances as a Lookup.Result allowing to listen for changes (e.g. caused by the module enabling/disabling).
This resulted into creation of class MimeLookup extends Lookup containing static MimeLookup getMimeLookup(String mimeType).

Nested mime-types

On the lexical level the document can contain nested languages.
For example JSP document can contain pieces of java code which can further contain javadoc comment tokens with nested javadoc language.
The nested languages should allow for special settings such as fonts and colors of nested syntax coloring but even things like actions that would be active in the nested document section.
This resulted into creation of static Lookup getLookup(MimePath mimePath) method in MimeLookup.

Known clients summary

Fold Manager Factories
The editor/fold module expects to find the registered fold manager factories (org.netbeans.spi.editor.fold.FoldManagerFactory classes).

Completion Providers
The editor/completion module expects to find the registered completion providers (org.netbeans.spi.editor.completion.CompletionProvider classes).

Editor Context Menu Actions
The editor module expects to find the registered popup menu actions (javax.swing.Action classes or names of actions (i.e. value of Action.NAME attribute) present in editor kit e.g. "goto-source").

Side Bars
The editor/lib module expects to find factories for components to be placed on the sides of the editor component (org.netbeans.editor.SideBarFactory classes).

Hyperlink Providers
The editor/lib module expects to find hyperlink providers that allow connecting an open document with some other documents (org.netbeans.lib.editor.hyperlink.spi.HyperlinkProvider classes).

Code Template Processors
The editor/codetemplates module expects to find factories for code template processors (org.netbeans.lib.editor.codetemplates.spi.CodeTemplateProcessorFactory classes).

Hints Providers
The editor/hints module expects to find editor hints providers (org.netbeans.modules.editor.hints.spi.HintsProvider classes).

API Use Cases

Find class instances for the given mime-type

An API method


MimeLookup lookup = MimeLookup.getMimeLookup("text/x-java");

can be used for getting the mime specific lookup. Having this we can lookup class or template:


    Object obj = lookup.lookup(LookedUpClass.class);


    Lookup.Result result = lookup.lookup(new Lookup.Template(LookedUpClass.class));

Getting embeded mime-type specific Lookup

As an example a jsp scriptlet is used. Scriptlet in fact consists of parent "text/x-jsp" mime-type and embeded "text/x-java" mime-type. To obtain a scriptlet lookup firstly we need to get a MimePath and then get appropriate lookup:

    MimePath scriptletPath = MimePath.parse("text/x-jsp/text/x-java");
    Lookup lookup = MimeLookup.getLookup(scriptletPath);

SPI Use Cases

Providing implemented MimeLookupInitializer

It is the general way of adding mime specific object into the MimeLookup. Implementation of MimeLookupInitializer should be created and registered to default lookup via META-INF/services registration. For details, please look at the simplified TestMimeLookupInitializer in mimelookup/test/unit or LayerMimeLookupInitializer. Usage of MimeLookupInitializer is deprecated, please use MimeDataProvider instead in similar way

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 Name	In/Out	Stability	Specified in What Document?
MimeLookupAPI	Exported	Official
MimeLookupSPI	Exported	Official

Group of systemproperty interfaces

Interface Name

In/Out

Stability

Specified in What Document?

Implementation Details

Where are the sources for the module?

Sources can be found in editor/mimelookup module.

The default answer to this question is:

The sources for the module are in the Apache Git repositories or in the GitHub repositories.

What do other modules need to do to declare a dependency on this one, in addition to or instead of a plain module dependency?

Nothing.

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

MIME Lookup APIOfficial