001: /*
002: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
003: *
004: * Copyright 1997-2007 Sun Microsystems, Inc. All rights reserved.
005: *
006: * The contents of this file are subject to the terms of either the GNU
007: * General Public License Version 2 only ("GPL") or the Common
008: * Development and Distribution License("CDDL") (collectively, the
009: * "License"). You may not use this file except in compliance with the
010: * License. You can obtain a copy of the License at
011: * http://www.netbeans.org/cddl-gplv2.html
012: * or nbbuild/licenses/CDDL-GPL-2-CP. See the License for the
013: * specific language governing permissions and limitations under the
014: * License. When distributing the software, include this License Header
015: * Notice in each file and include the License file at
016: * nbbuild/licenses/CDDL-GPL-2-CP. Sun designates this
017: * particular file as subject to the "Classpath" exception as provided
018: * by Sun in the GPL Version 2 section of the License file that
019: * accompanied this code. If applicable, add the following below the
020: * License Header, with the fields enclosed by brackets [] replaced by
021: * your own identifying information:
022: * "Portions Copyrighted [year] [name of copyright owner]"
023: *
024: * Contributor(s):
025: *
026: * The Original Software is NetBeans. The Initial Developer of the Original
027: * Software is Sun Microsystems, Inc. Portions Copyright 1997-2006 Sun
028: * Microsystems, Inc. All Rights Reserved.
029: *
030: * If you wish your version of this file to be governed by only the CDDL
031: * or only the GPL Version 2, indicate your decision by adding
032: * "[Contributor] elects to include this software in this distribution
033: * under the [CDDL or GPL Version 2] license." If you do not indicate a
034: * single choice of license, a recipient has the option to distribute
035: * your version of this file under either the CDDL, the GPL Version 2 or
036: * to extend the choice of license to its licensees as provided above.
037: * However, if you add GPL Version 2 code and therefore, elected the GPL
038: * Version 2 license, then the option applies only if the new code is
039: * made subject to such option by the copyright holder.
040: */
041:
042: package org.netbeans.api.editor.mimelookup;
043:
044: import org.netbeans.modules.editor.mimelookup.MimePathLookup;
045: import org.openide.util.Lookup;
046: import org.openide.util.Lookup.Result;
047: import org.openide.util.Lookup.Template;
048:
049: /**
050: * Mime Lookup provides lookup mechanism for mime type specific objects.
051: * It can be used for example for retrieving mime type specific
052: * editor settings, actions, etc.
053: *
054: * <p>The static method {@link #getLookup(MimePath) getLookup(MimePath mimePath)}
055: * can be used to obtain a mime type specific lookup implementation. This lookup
056: * can then be searched for objects bound to the specific mime type using the
057: * standard <code>Lookup</code> methods.
058: *
059: * <p>Please look at the description of the {@link MimePath} class to learn more
060: * about embedded mime types and how they are represented by the mime path. By
061: * using the <code>MimePath</code> the <code>MimeLookup</code>
062: * class allows to have different <code>Lookup</code>s for a mime type
063: * embedded in different other mime types. So, for example there can be different
064: * editor settings for the 'text/x-java' mime type and for the 'text/x-java' mime
065: * type embedded in the 'text/x-jsp' mime type.
066: *
067: * <p>The <code>Lookup</code> instance returned from the <code>getLookup</code>
068: * method can be used in the same way as any other <code>Lookup</code>. It is
069: * possible to look up class instances, listen on changes in the lookup restults,
070: * etc. The following code snippet shows a typical usage of this class for getting
071: * instances of the <code>YourSetting</code> class from the 'text/x-java' mime
072: * type specific <code>Lookup</code>.
073: *
074: * <pre>
075: * Lookup lookup = MimeLookup.getLookup(MimePath.get("text/x-java"));
076: * Lookup.Result result = lookup.lookup(new Lookup.Template(YourSetting.class));
077: * Collection instances = result.allInstances();
078: * </pre>
079: *
080: * <p><b>Lifecycle:</b> The lifecycle of <code>Lookup</code> instances created
081: * by calling the <code>getLookup</code> or <code>getMimeLookup</code> methods is
082: * tied to the lifecycle of the <code>MimePath</code> instances they were created
083: * for and vice versa. Therefore it is enough to keep reference to either the
084: * <code>MimePath</code> or the <code>Lookup</code> created for that mime path
085: * or even to the <code>Lookup.Result</code> in order to preserve the other instances
086: * in the memory. Clients are strongly encouraged to keep refernce to the
087: * <code>Lookup</code>s they obtain from this class throughout the whole lifecycle
088: * of their component, especially when they need to use that <code>Lookup</code>
089: * several times.
090: *
091: * @author Miloslav Metelka, Martin Roskanin, Vita Stejskal
092: * @see MimePath
093: */
094: public final class MimeLookup extends Lookup {
095:
096: private MimePathLookup mimePathLookup;
097:
098: /**
099: * Gets a <code>Lookup</code> implementation that exposes objects specific
100: * for the given <code>MimePath</code>.
101: *
102: * @param mimePath The mime path to get the <code>Lookup</code> for.
103: *
104: * @return The <code>Lookup</code> containing instances for the <code>MimePath</code>
105: * passed in as a parameter.
106: */
107: public static Lookup getLookup(MimePath mimePath) {
108: if (mimePath == null) {
109: throw new NullPointerException(
110: "The mimePath parameter must not be null."); //NOI18N
111: }
112:
113: return mimePath.getLookup();
114: }
115:
116: /**
117: * Gets a <code>Lookup</code> implementation that exposes objects specific
118: * for the given <code>MimePath</code> for the given mime-type
119: * or mime-path given as string.
120: * <br/>
121: * The method first translates the string mime-path into {@link MimePath}
122: * by using {@link MimePath#parse(String)} and then calls
123: * {@link #getLookup(MimePath)}.
124: *
125: * @param mimePath non-null string which is either a mime-type e.g. "text/plain"
126: * or mime-path (multiple mime-types separated by slash) e.g.
127: * "text/x-jsp/text/x-java".
128: * @return The <code>Lookup</code> containing instances for the given mime-path.
129: * @see #getLookup(MimePath)
130: */
131: public static Lookup getLookup(String mimePath) {
132: return getLookup(MimePath.parse(mimePath));
133: }
134:
135: /**
136: * Gets mime-type specific lookup.
137: *
138: * @param mimeType non-null mime-type string representation, e.g. "text/x-java"
139: * @return non-null mime-type specific lookup
140: * @deprecated Use {@link #getLookup(MimePath) getLookup(MimePath.get(mimeType))} instead.
141: */
142: public static MimeLookup getMimeLookup(String mimeType) {
143: if (mimeType == null) {
144: throw new NullPointerException(
145: "The mimeType parameter must not be null."); //NOI18N
146: }
147:
148: return new MimeLookup(MimePath.get(mimeType).getLookup());
149: }
150:
151: /**
152: * Creates a new instance of MimeLookup.
153: *
154: * @param parent parent of this MimeLookup. Can be null in case of constructing
155: * the root MimeLookup
156: * @param mimeType non-null mime-type string representation, e.g. "text/x-java"
157: */
158: private MimeLookup(MimePathLookup lookup) {
159: this .mimePathLookup = lookup;
160: }
161:
162: /**
163: * Gets mime-type specific child (embeded) lookup. Child mime-type content can be embeded into parent
164: * mime-type content in various embeded languages. In this case mime-type lookup child is
165: * specified as subelement of parent lookup i.e.: MimeLookup("text/x-jsp") can have
166: * a child MimeLookup("text/x-java") in a case of a jsp scriplet.
167: *
168: * @param mimeType non-null mime-type string representation
169: *
170: * @return non-null mime-type specific child (embeded) lookup
171: * @deprecated Use {@link #getLookup(MimePath)} with the <code>MimePath</code>
172: * of the embedded mime type instead.
173: */
174: public MimeLookup childLookup(String mimeType) {
175: if (mimeType == null) {
176: throw new NullPointerException(
177: "The mimeType parameter must not be null."); //NOI18N
178: }
179:
180: MimePath mimePath = MimePath.get(mimePathLookup.getMimePath(),
181: mimeType);
182: return new MimeLookup(mimePath.getLookup());
183: }
184:
185: /**
186: * Looks up an object in this mime path lookup.
187: *
188: * @param clazz The class of the object to search for.
189: *
190: * @return An object implementing the given class or <code>null</code> if no such
191: * implementation is found.
192: * @deprecated Use {@link #getLookup(MimePath)} and the methods provided by
193: * the ordinary <code>Lookup</code> instance returned.
194: */
195: public <T> T lookup(Class<T> clazz) {
196: return mimePathLookup.lookup(clazz);
197: }
198:
199: /**
200: * Looks up objects in this mime path lookup.
201: *
202: * @param template The template describing the objects to look for.
203: *
204: * @return The search result.
205: * @deprecated Use {@link #getLookup(MimePath)} and the methods provided by
206: * the ordinary <code>Lookup</code> instance returned.
207: */
208: public <T> Result<T> lookup(Template<T> template) {
209: return mimePathLookup.lookup(template);
210: }
211:
212: }
|