KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > netbeans > api > editor > mimelookup > MimeLookup


1 /*
2  * The contents of this file are subject to the terms of the Common Development
3  * and Distribution License (the License). You may not use this file except in
4  * compliance with the License.
5  *
6  * You can obtain a copy of the License at http://www.netbeans.org/cddl.html
7  * or http://www.netbeans.org/cddl.txt.
8  *
9  * When distributing Covered Code, include this CDDL Header Notice in each file
10  * and include the License file at http://www.netbeans.org/cddl.txt.
11  * If applicable, add the following below the CDDL Header, with the fields
12  * enclosed by brackets [] replaced by your own identifying information:
13  * "Portions Copyrighted [year] [name of copyright owner]"
14  *
15  * The Original Software is NetBeans. The Initial Developer of the Original
16  * Software is Sun Microsystems, Inc. Portions Copyright 1997-2006 Sun
17  * Microsystems, Inc. All Rights Reserved.
18  */
19
20 package org.netbeans.api.editor.mimelookup;
21
22 import org.netbeans.modules.editor.mimelookup.MimePathLookup;
23 import org.openide.util.Lookup;
24 import org.openide.util.Lookup.Result;
25 import org.openide.util.Lookup.Template;
26
27 /**
28  * Mime Lookup provides lookup mechanism for mime type specific objects.
29  * It can be used for example for retrieving mime type specific
30  * editor settings, actions, etc.
31  *
32  * <p>The static method {@link #getLookup(MimePath) getLookup(MimePath mimePath)}
33  * can be used to obtain a mime type specific lookup implementation. This lookup
34  * can then be searched for objects bound to the specific mime type using the
35  * standard <code>Lookup</code> methods.
36  *
37  * <p>Please look at the description of the {@link MimePath} class to learn more
38  * about embedded mime types and how they are represented by the mime path. By
39  * using the <code>MimePath</code> the <code>MimeLookup</code>
40  * class allows to have different <code>Lookup</code>s for a mime type
41  * embedded in different other mime types. So, for example there can be different
42  * editor settings for the 'text/x-java' mime type and for the 'text/x-java' mime
43  * type embedded in the 'text/x-jsp' mime type.
44  *
45  * <p>The <code>Lookup</code> instance returned from the <code>getLookup</code>
46  * method can be used in the same way as any other <code>Lookup</code>. It is
47  * possible to look up class instances, listen on changes in the lookup restults,
48  * etc. The following code snippet shows a typical usage of this class for getting
49  * instances of the <code>YourSetting</code> class from the 'text/x-java' mime
50  * type specific <code>Lookup</code>.
51  *
52  * <pre>
53  * Lookup lookup = MimeLookup.getLookup(MimePath.get("text/x-java"));
54  * Lookup.Result result = lookup.lookup(new Lookup.Template(YourSetting.class));
55  * Collection instances = result.allInstances();
56  * </pre>
57  *
58  * <p><b>Lifecycle:</b> The lifecycle of <code>Lookup</code> instances created
59  * by calling the <code>getLookup</code> or <code>getMimeLookup</code> methods is
60  * tied to the lifecycle of the <code>MimePath</code> instances they were created
61  * for and vice versa. Therefore it is enough to keep reference to either the
62  * <code>MimePath</code> or the <code>Lookup</code> created for that mime path
63  * or even to the <code>Lookup.Result</code> in order to preserve the other instances
64  * in the memory. Clients are strongly encouraged to keep refernce to the
65  * <code>Lookup</code>s they obtain from this class throughout the whole lifecycle
66  * of their component, especially when they need to use that <code>Lookup</code>
67  * several times.
68  *
69  * @author Miloslav Metelka, Martin Roskanin, Vita Stejskal
70  * @see MimePath
71  */
72 public final class MimeLookup extends Lookup {
73     
74     private MimePathLookup mimePathLookup;
75     
76     /**
77      * Gets a <code>Lookup</code> implementation that exposes objects specific
78      * for the given <code>MimePath</code>.
79      *
80      * @param mimePath The mime path to get the <code>Lookup</code> for.
81      *
82      * @return The <code>Lookup</code> containing instances for the <code>MimePath</code>
83      * passed in as a parameter.
84      */
85     public static Lookup getLookup(MimePath mimePath) {
86         if (mimePath == null) {
87             throw new NullPointerException JavaDoc("The mimePath parameter must not be null."); //NOI18N
88 }
89         
90         return mimePath.getLookup();
91     }
92
93     /**
94      * Gets mime-type specific lookup.
95      *
96      * @param mimeType non-null mime-type string representation, e.g. "text/x-java"
97      * @return non-null mime-type specific lookup
98      * @deprecated Use {@link #getLookup(MimePath) getLookup(MimePath.get(mimeType))} instead.
99      */
100     public static MimeLookup getMimeLookup(String JavaDoc mimeType) {
101         if (mimeType == null) {
102             throw new NullPointerException JavaDoc("The mimeType parameter must not be null."); //NOI18N
103 }
104         
105         return new MimeLookup(MimePath.get(mimeType).getLookup());
106     }
107
108     /**
109      * Creates a new instance of MimeLookup.
110      *
111      * @param parent parent of this MimeLookup. Can be null in case of constructing
112      * the root MimeLookup
113      * @param mimeType non-null mime-type string representation, e.g. "text/x-java"
114      */
115     private MimeLookup(MimePathLookup lookup) {
116         this.mimePathLookup = lookup;
117     }
118     
119     /**
120      * Gets mime-type specific child (embeded) lookup. Child mime-type content can be embeded into parent
121      * mime-type content in various embeded languages. In this case mime-type lookup child is
122      * specified as subelement of parent lookup i.e.: MimeLookup("text/x-jsp") can have
123      * a child MimeLookup("text/x-java") in a case of a jsp scriplet.
124      *
125      * @param mimeType non-null mime-type string representation
126      *
127      * @return non-null mime-type specific child (embeded) lookup
128      * @deprecated Use {@link #getLookup(MimePath)} with the <code>MimePath</code>
129      * of the embedded mime type instead.
130      */
131     public MimeLookup childLookup(String JavaDoc mimeType) {
132         if (mimeType == null) {
133             throw new NullPointerException JavaDoc("The mimeType parameter must not be null."); //NOI18N
134 }
135         
136         MimePath mimePath = MimePath.get(mimePathLookup.getMimePath(), mimeType);
137         return new MimeLookup(mimePath.getLookup());
138     }
139
140     /**
141      * Looks up an object in this mime path lookup.
142      *
143      * @param clazz The class of the object to search for.
144      *
145      * @return An object implementing the given class or <code>null</code> if no such
146      * implementation is found.
147      * @deprecated Use {@link #getLookup(MimePath)} and the methods provided by
148      * the ordinary <code>Lookup</code> instance returned.
149      */
150     public <T> T lookup(Class JavaDoc<T> clazz) {
151         return mimePathLookup.lookup(clazz);
152     }
153
154     /**
155      * Looks up objects in this mime path lookup.
156      *
157      * @param template The template describing the objects to look for.
158      *
159      * @return The search result.
160      * @deprecated Use {@link #getLookup(MimePath)} and the methods provided by
161      * the ordinary <code>Lookup</code> instance returned.
162      */
163     public <T> Result<T> lookup(Template<T> template) {
164         return mimePathLookup.lookup(template);
165     }
166
167 }
168
Popular Tags