MimePath (MIME Lookup API) - NetBeans API Javadoc (Current Development Version)

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

org.netbeans.modules.editor.mimelookup/1 1.6

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

org.netbeans.api.editor.mimelookup
Class MimePath

java.lang.Object
  org.netbeans.api.editor.mimelookup.MimePath

public final class MimePath
extends Object
extends Object

The mime path is a concatenation of one or more mime types. The purpose of a mime path is to describe the fact that a document of a certain mime type can contain fragments of another document with a different mime type. The fragment and its mime type is refered to as an embedded document and an embedded mime type respectively.

In order to fully understand the scale of the problem the mime path is trying to describe you should consider two things. First a document can contain several different embedded fragments each of a different mime type. Second, each embeded fragment itself can possibly contain one or more other embedded fragments and this nesting can in theory go indefinitely deep.

In reality the nesting probably will not be very deep. As an example of a document containing an embedded fragment of another document of the different mime type you could imagine a JSP page containing a Java scriplet. The main document is the JSP page of the 'text/x-jsp' mime type, which includes a fragment of Java source code of the 'text/x-java' mime type.

The mime path comes handy when we want to distinguish between the ordinary 'text/x-java' mime type and the 'text/x-java' mime type embedded in the JSP page, because both of those 'text/x-java' mime types will have a different mime path. The ordinary 'text/x-java' mime type has a mime path consisting of just one mime type - 'text/x-java'. The 'text/x-java' mime type embeded in the JSP page, however, has a mime path comprised from two mime types 'text/x-jsp' and 'text/x-java'. The order of mime types in a mime path is obviously very important, because it describes how the mime types are embedded.

The mime path can be represented as a String simply by concatenating all its mime types separated by the '/' character. Since mime types always contain one and only one '/' character it is clear which '/' character belongs to a mime type and which is the mime path separator.

In the above example the mime path of the 'text/x-java' mime type embedded in the 'text/x-jsp' mime type can be represented as 'text/x-jsp/text/x-java'.

For some languages it is not uncommon to allow embedding of itself. For example in Ruby it is allowed to use Ruby code within strings and Ruby will evaluate this code when evaluating the value of the strings. Depending on the implementation of a lexer there can be tokens with MimePath that contains several consecutive same mime types.

The format of a valid mime type string is described in RFC 4288. MimePath performs internall checks according to this specification.

Identity: By definition two MimePath instances are equal if they represent the same string mime path. The implementation guarantees that by caching and reusing instances of the MimePath that it creates. The MimePath instances can be used as keys in maps.

Lifecycle: Although the instances of MimePath are internally cached and should survive for certain time without being referenced from outside of the MimePath API, clients are strongly encouraged to hold a reference to the MimePath they obtained throughout the whole lifecycle of their component. For example an opened java editor with a document should keep its instance of the 'text/x-java' MimePath for the whole time the editor is open.

See Also:: MimeLookup, RFC 4288

Field Summary

static MimePath EMPTY
          The root of all mime paths.

Method Summary

static MimePath get(MimePath prefix, String mimeType)
          Gets the mime path corresponding to a mime type embedded in another mime type.

static MimePath get(String mimeType)
          Gets the mime path for the given mime type.

String getMimeType(int index)
          Get mime type of this mime-path at the given index.

String getPath()
          Get string path represented by this mime-path.

MimePath getPrefix(int size)
          Return prefix mime-path with the given number of mime-type components ranging from zero till the size of this mime-path.

static MimePath parse(String path)
          Parses a mime path string and returns its MimePath representation.

int size()
          Get total number of mime-types in the mime-path.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Summary
`static MimePath`	`EMPTY` The root of all mime paths.

Method Summary
`static MimePath`	`get(MimePath prefix, String mimeType)` Gets the mime path corresponding to a mime type embedded in another mime type.
`static MimePath`	`get(String mimeType)` Gets the mime path for the given mime type.
`String`	`getMimeType(int index)` Get mime type of this mime-path at the given index.
`String`	`getPath()` Get string path represented by this mime-path.
`MimePath`	`getPrefix(int size)` Return prefix mime-path with the given number of mime-type components ranging from zero till the size of this mime-path.
`static MimePath`	`parse(String path)` Parses a mime path string and returns its `MimePath` representation.
`int`	`size()` Get total number of mime-types in the mime-path.

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Field Detail

EMPTY

public static final MimePath EMPTY

The root of all mime paths. The empty mime path does not refer to any mime type.

Method Detail

get

public static MimePath get(String mimeType)

Gets the mime path for the given mime type. The returned MimePath will contain exactly one element and it will be the mime type passed in as the parameter.

Parameters:: mimeType - The mime type to get the mime path for. If null or empty string is passed in the EMPTY mime path will be returned.
Returns:: The MimePath for the given mime type or MimePath.EMPTY if the mime type is null or empty string.

get

public static MimePath get(MimePath prefix,
                           String mimeType)

Gets the mime path corresponding to a mime type embedded in another mime type. The embedding mime type is described in form of a mime path passed in as the prefix parameter.

For example for a java scriplet embedded in a jsp page the prefix would be the mime path 'text/x-jsp' and mimeType would be 'text/x-java'. The method will return the 'text/x-jsp/text/x-java' mime path.

Parameters:: prefix - The mime path determining the mime type that embedds the mime type passed in in the second parameter. It can be EMPTY in which case the call will be equivalent to calling get(mimeType) method.; mimeType - The mime type that is embedded in the mime type determined by the prefix mime path.
Returns:: The mime path representing the embedded mime type.

parse

public static MimePath parse(String path)

Parses a mime path string and returns its MimePath representation.

The format of a mime path string representation is a string of mime type components comprising the mime path separated by the '/' character. For example a mime path representing the 'text/x-java' mime type embedded in the 'text/x-jsp' mime type can be represented as the following string - 'text/x-jsp/text/x-java'.

The mime path string can be an empty string, which represents the EMPTY mime path. By definition all valid mime paths except of the empty one have to contain odd number of '/' characters.

Parameters:: path - The mime path string representation.
Returns:: non-null mime-path corresponding to the given string path.

getPath

public String getPath()

Get string path represented by this mime-path.
For example "text/x-jsp/text/x-java".

Returns:: non-null string path.

size

public int size()

Get total number of mime-types in the mime-path.
EMPTY mime-path has zero size.
"text/x-jsp/text/x-java" has size 2.

Returns:: >=0 number of mime-types contained in this mime-path.

getMimeType

public String getMimeType(int index)

Get mime type of this mime-path at the given index.
Index zero corresponds to the root mime-type.
For "text/x-jsp/text/x-java" getMimeType(0) returns "text/x-jsp" and getMimeType(1) returns "text/x-java".

Parameters:: index - >=0 && < size().
Returns:: non-null mime-type at the given index.
Throws:: IndexOutOfBoundsException - in case the index is not within required bounds.

getPrefix

public MimePath getPrefix(int size)

Return prefix mime-path with the given number of mime-type components ranging from zero till the size of this mime-path.

Parameters:: size - >=0 && <= size().
For zero size the EMPTY will be returned.
For size() this will be returned.
Returns:: non-null mime-type of the given size.
Throws:: IndexOutOfBoundsException - in case the index is not within required bounds.