← Back to branch summary

~ubuntu-branches/ubuntu/trusty/netbeans/trusty

« back to all changes in this revision

Viewing changes to editor/mimelookup/src/org/netbeans/spi/editor/mimelookup/package.html

  • Committer: Bazaar Package Importer
  • Author(s): Marek Slama
  • Date: 2008-01-29 14:11:22 UTC
  • Revision ID: james.westby@ubuntu.com-20080129141122-fnzjbo11ntghxfu7
Tags: upstream-6.0.1
Import upstream version 6.0.1

Show diffs side-by-side

added added

removed removed

Lines of Context:
editor/mimelookup/src/org/netbeans/spi/editor/mimelookup/package.html
 
1
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
 
2
<!--
 
3
DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
 
4
 
 
5
Copyright 1997-2007 Sun Microsystems, Inc. All rights reserved.
 
6
 
 
7
 
 
8
The contents of this file are subject to the terms of either the GNU
 
9
General Public License Version 2 only ("GPL") or the Common
 
10
Development and Distribution License("CDDL") (collectively, the
 
11
"License"). You may not use this file except in compliance with the
 
12
License. You can obtain a copy of the License at
 
13
http://www.netbeans.org/cddl-gplv2.html
 
14
or nbbuild/licenses/CDDL-GPL-2-CP. See the License for the
 
15
specific language governing permissions and limitations under the
 
16
License.  When distributing the software, include this License Header
 
17
Notice in each file and include the License file at
 
18
nbbuild/licenses/CDDL-GPL-2-CP.  Sun designates this
 
19
particular file as subject to the "Classpath" exception as provided
 
20
by Sun in the GPL Version 2 section of the License file that
 
21
accompanied this code. If applicable, add the following below the
 
22
License Header, with the fields enclosed by brackets [] replaced by
 
23
your own identifying information:
 
24
"Portions Copyrighted [year] [name of copyright owner]"
 
25
 
 
26
Contributor(s):
 
27
 
 
28
The Original Software is NetBeans. The Initial Developer of the Original
 
29
Software is Sun Microsystems, Inc. Portions Copyright 1997-2006 Sun
 
30
Microsystems, Inc. All Rights Reserved.
 
31
 
 
32
If you wish your version of this file to be governed by only the CDDL
 
33
or only the GPL Version 2, indicate your decision by adding
 
34
"[Contributor] elects to include this software in this distribution
 
35
under the [CDDL or GPL Version 2] license." If you do not indicate a
 
36
single choice of license, a recipient has the option to distribute
 
37
your version of this file under either the CDDL, the GPL Version 2 or
 
38
to extend the choice of license to its licensees as provided above.
 
39
However, if you add GPL Version 2 code and therefore, elected the GPL
 
40
Version 2 license, then the option applies only if the new code is
 
41
made subject to such option by the copyright holder.
 
42
-->
 
43
 
 
44
<html>
 
45
<body>
 
46
 
 
47
The SPI allows registering providers of mime type specific <code>Lookup</code>s.
 
48
The <code>MimeDataProvider</code> interface can be used to implement such a
 
49
provider and register it among the services in the default lookup. The editor/mimelookup
 
50
module will consult all registered <code>MimeDataProvider</code>s when creating
 
51
a <code>Lookup</code> for a specific <code>MimePath</code>.
 
52
 
 
53
<a name="defaultMimeDataProvider"/><h3>Default MimeDataProvider</h3>
 
54
 
 
55
<p>The module itself provides a default implementation of the <code>MimeDataProvider</code>,
 
56
which creates <code>Lookup</code>s from the data registered in a hierachical
 
57
structure of folders on the system filesystem.
 
58
</p>
 
59
 
 
60
<p>The hierarchy starts with the 'Editors' folder and then contains subfolders for
 
61
each mime type that has some registered objects. Since each mime type is uniquely
 
62
identified by its <code>MimePath</code> the string represantation of the <code>MimePath</code>
 
63
can be used as a filesystem path to the folder holding objects registered for
 
64
that mime type. For example the 'text/x-java' mime type embedded in the 'text/x-jsp'
 
65
mime type is represented by the 'text/x-jsp/text/x-java' mime path and
 
66
the objects/settings specific for this mime type can be registered in the
 
67
'Editors/text/x-jsp/text/x-java' folder.
 
68
 
 
69
<p>The empty <code>MimePath</code> refers to the 'Editors' folder iteslf.
 
70
</p>
 
71
 
 
72
<!-- 
 
73
<p>While it is useful to be able to register objects independently for each mime
 
74
type it seems logical to expect objects registered for the 'text/x-java' mime type
 
75
to be visible for the 'text/x-jsp/text/x-java' mime type as well. Therefore the
 
76
default <code>MimeDataProvider</code> chains the <code>Lookup</code> provided
 
77
for a particular embedded mime type with the <code>Lookup</code> of the unembedded
 
78
version of that mime type.
 
79
</p>
 
80
 
 
81
<p>As an example of this chaining you can think of the
 
82
settings or services available for a plain java editor that will provide good defaults
 
83
for the java scriplets embedded in a jsp page allowing the java scriplets editor
 
84
to use those settings or override them with its own version.
 
85
</p>
 
86
-->
 
87
 
 
88
<p>The <code>Lookup</code> provided for a mime path is in fact a chain of
 
89
<code>Lookup</code>s for all mime paths that can be created from the original
 
90
mime path by cutting off its mime type components from the end. So, for example
 
91
the <code>Lookup</code> for the 'text/x-jsp/text/x-java' mime path is made up of
 
92
three different <code>Lookup</code>s using the following folders:
 
93
</p>
 
94
 
 
95
<pre>
 
96
    Editors/text/x-jsp/text/x-java
 
97
    Editors/text/x-jsp
 
98
    Editors
 
99
</pre>
 
100
 
 
101
<p>The default <code>MimeDataProvider</code> allows registering implementations of
 
102
the <code>Class2LayerFolder</code> interface in order to supply additional
 
103
information about the location of instances registered in the mime type folders.
 
104
Each <code>Class2LayerFolder</code> implementation can specify that instances of
 
105
a certain class will be registered in a special subfolder. The <code>Lookup</code>
 
106
created by the default <code>MimeDataProvider</code> will then look into the
 
107
subfolders rather than to the usual mime type folders when looking for instances
 
108
of that class. An example can be instances of the <code>FoldManager</code> class
 
109
that are registered in the <code>foldManager</code> subfolders. The <code>Lookup</code>s
 
110
hierarchy in this case uses the folders below:
 
111
</p>
 
112
 
 
113
<pre>
 
114
    Editors/text/x-jsp/text/x-java/foldManager
 
115
    Editors/text/x-jsp/foldManager
 
116
    Editors/foldManager
 
117
</pre>
 
118
 
 
119
<h3>Compound MIME types</h3>
 
120
 
 
121
<p>The default <code>MimeDataProvider</code> supports compound mime types, which
 
122
are the mime types that have two parts separated by a plus sign ('+'). The
 
123
compound mime types are heavily used for describing different types of XML files.
 
124
For example an Ant build script's mime type is text/x-ant+xml, which means that
 
125
the file is an XML file, but not an ordinary XML file. It's a build script.
 
126
</p>
 
127
 
 
128
<p>From the editor's point of view a file with a compound mime type should offer
 
129
the behavior of the default mime type (e.g. text/xml) plus special behaviors
 
130
specific for its original mime type (e.g. text/x-ant+xml). Therefore a <code>Lookup</code>
 
131
provided for a mime path that contains a compound mime type will collect settings
 
132
and services from both the folders belonging to the compound mime type and
 
133
the folders belonging to its default part. The example below shows the list of
 
134
folders comprising a <code>Lookup</code> for the 'text/x-ant+xml/text/x-java'
 
135
mime path.
 
136
</p>
 
137
 
 
138
<pre>
 
139
    Editors/text/x-ant+xml/text/x-java
 
140
    Editors/text/x-ant+xml
 
141
    Editors/text/xml/text/x-java
 
142
    Editors/text/xml
 
143
    Editors
 
144
</pre>
 
145
 
 
146
<h3>Ordering and hiding files</h3>
 
147
 
 
148
<p>When registering instances in the mime path folders it is possible to use
 
149
<code>position</code> attributes to order the files the same way as you would do it in any other
 
150
files in a module XML layer. The attributes however will be resolved after all
 
151
the folders belonging to a mime path are merged. Therefore it is possible to
 
152
use attributes that define position relatively to a file in a parent (embedding)
 
153
mime type.
 
154
</p>
 
155
 
 
156
<pre>
 
157
&lt;folder name="Editors"&gt;
 
158
  &lt;folder name="Popup"&gt;
 
159
    &lt;file name="org-openide-actions-CutAction.instance">&lt;attr name="position" intvalue="100"/>&lt;/file>
 
160
    &lt;file name="org-openide-actions-CopyAction.instance">&lt;attr name="position" intvalue="200"/>&lt;/file>
 
161
    &lt;file name="org-openide-actions-PasteAction.instance">&lt;attr name="position" intvalue="300"/>&lt;/file>
 
162
  &lt;/folder&gt;
 
163
  &lt;folder name="text"&gt;
 
164
    &lt;folder name="x-java"&gt;
 
165
      &lt;folder name="Popup">
 
166
        &lt;file name="org-netbeans-modules-project-ui-RunSingle">&lt;attr name="position" intvalue="400"/>&lt;/file>
 
167
      &lt;/folder&gt;
 
168
    &lt;/folder&gt;
 
169
  &lt;/folder&gt;
 
170
&lt;/folder&gt;
 
171
</pre>
 
172
 
 
173
<p>It is also possible to influence the default inheritance of files from
 
174
folders belonging to a parent (embedding) mime type and mask them out by defining
 
175
a 'hidden file' in the child mime type folder. Hidden files are marked by
 
176
a special attribute called <code>hidden</code> with a booleanValue equal to 'true'.
 
177
The example below hides the editor's global CopyAction in documents with the
 
178
'text/x-java' mime type.
 
179
</p>
 
180
 
 
181
<pre>
 
182
&lt;folder name="Editors"&gt;
 
183
  &lt;folder name="Popup"&gt;
 
184
    &lt;file name="org-openide-actions-CutAction.instance" /&gt;
 
185
    &lt;file name="org-openide-actions-CopyAction.instance" /&gt;
 
186
    &lt;file name="org-openide-actions-PasteAction.instance" /&gt;
 
187
  &lt;/folder&gt;
 
188
  &lt;folder name="text"&gt;
 
189
    &lt;folder name="x-java"&gt;
 
190
      &lt;file name="org-openide-actions-CopyAction.instance" &gt;
 
191
        &lt;attr name="hidden" booleanValue="true" /&gt;
 
192
      &lt;/file&gt;
 
193
    &lt;/folder&gt;
 
194
  &lt;/folder&gt;
 
195
&lt;/folder&gt;
 
196
</pre>
 
197
 
 
198
<p>Please note that appending '_hidden' to the name of the
 
199
file does not work, because such a file is made hidden by the XML filesystem
 
200
implementation when the module layer is loaded and therefore such a file is not visible
 
201
to the merging mechanism implemented in the mimelookup module.
 
202
</p>
 
203
 
 
204
</body>
 
205
</html>