MimePath (MIME Lookup API)

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

```
public final class MimePath
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 mime types that are the same.
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

Fields
Modifier and Type Field and Description

static MimePath EMPTY
The root of all mime paths.

Fields
Modifier and Type	Field and Description
`static MimePath`	`EMPTY` The root of all mime paths.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`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.
`List<MimePath>`	`getIncludedPaths()` Returns the included Mime paths.
`String`	`getInheritedType()` Returns the inherited 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.
`String`	`toString()`
`static boolean`	`validate(CharSequence path)` Validates a path to check if it's a valid mime path.
`static boolean`	`validate(CharSequence type, CharSequence subtype)` Validates components of a mime type.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, 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 MimePath.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 MimePath.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.
  - validate
```
public static boolean validate(CharSequence type,
                               CharSequence subtype)
```
    Validates components of a mime type. Each mime types is compound from two components - type and subtype. There are rules that both components must obey. For details see RFC 4288.
    
    Parameters:
    
    type - The type component of a mime type to validate. If null the type component will not be validated.
    
    subtype - The subtype component of a mime type to validate. If null the subtype component will not be validated.
    
    Returns:
    
    true if non-null components passed in are valid mime type components, otherwise false.
    
    Since:
    
    1.7
  - validate
```
public static boolean validate(CharSequence path)
```
    Validates a path to check if it's a valid mime path. If this method returns true the path is a valid mime path string and can be used in the MimePath.parse() method.
    
    Parameters:
    
    path - The path string to validate.
    
    Returns:
    
    true if the path string is a valid mime path.
    
    Since:
    
    1.7
  - 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.
    MimePath.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 && < MimePath.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 && <= MimePath.size().
    For zero size the MimePath.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.
  - toString
```
public String toString()
```
    Overrides:
    
    toString in class Object
  - getInheritedType
```
public String getInheritedType()
```
    Returns the inherited Mime type. For MimePath.EMPTY, returns null. For most other mime types, returns "". If the mime type derives from another one, such as text/ant+xml derives from xml, the return value will be the base mime type (text/xml in the example case).
    For MimePaths that identified embedded content (more components on the MimePath), the method returns the parent MIME of the last MIME type on the path
    
    Returns:
    
    inherited mime type, or null, if no parent exists (for MimePath.EMPTY)
  - getIncludedPaths
```
public List<MimePath> getIncludedPaths()
```
    Returns the included Mime paths. For MimePath, which nests several MIME types (i.e. text/php/text/html/text/css), it enumerates sub-paths so that a following element represents one level of nesting of the content. For the example example, the return would be:
    1. text/php/text/html/text/css -- the full path
    2. text/html/text/css -- outer content is removed
    3. text/css -- the mime type of the identified content itself
    4. (empty string)
    If a MIME type on the path has a generic MIME type (i.e. text/x-ant+xml has a generic MIME type text/xml), that generic type will be inserted. For example, for text/java/text/x-ant+xml/text/javascript, the result will list:
    1. text/java/text/x-ant+xml/text/javascript, -- the full MimePath
    2. text/x-ant+xml/text/javascript -- a prefix
    3. text/xml/text/javascript -- ant+xml is generalized to xml
    4. text/javascript
    5. (empty string)
    For all but MimePath.EMPTY MimePaths, the list contains at least one entry, and the last entry is the MimePath.EMPTY. Note also, that the complete MimePath is always returned as the 1st member of the list.
    The returned sequence of MimePaths is suitable for searching settings or services for the (embedded) content whose type is described by MimePath as it is ordered from the most specific to the least specific paths (including generalization) and always contains the mime type of the identified contents. The last component ("") represents default settings (services).
    Note that for MimePaths created from a mime type (not empty!) string, the getInheritedPaths().get(1) is a parent mime type. Either empty, or the generalized MIME.
    The caller should not modify the returned List.
    Returns:
    
    list of inherited Mime paths

Class MimePath

Field Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

EMPTY

Method Detail

get

get

parse

validate

validate

getPath

size

getMimeType

getPrefix

toString

getInheritedType

getIncludedPaths