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-2007 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.spi.lexer;
043:
044: import java.beans.PropertyChangeListener;
045: import java.beans.PropertyChangeSupport;
046: import org.netbeans.api.lexer.InputAttributes;
047: import org.netbeans.api.lexer.Language;
048: import org.netbeans.api.lexer.LanguagePath;
049: import org.netbeans.api.lexer.Token;
050:
051: /**
052: * The <code>Language</code> provider. This class is a hook into the
053: * lexer framework allowing modules to provide a language resolution service.
054: * Whenever a <code>Language</code> is not explicitly known the
055: * framework tries to determine it by asking <code>LanguageProvider</code>s registered
056: * in the <code>Lookup.getDefault()</code>.
057: *
058: * <code>Language</code>s might be needed for a mime type or mime path
059: * of a <code>Document</code> used as an input source or they might be needed for
060: * some tokens that contain text in an another (embedded) language. In both cases
061: * a <code>Language</code> can either be explicitely provided by setting
062: * the document's property or implementing the <code>LanguageHierarchy.embedded()</code>
063: * method respectively or the framework will use <code>LanguageProvider</code>s to
064: * create the appropriate <code>Language</code>.
065: *
066: * @author Vita Stejskal
067: */
068: public abstract class LanguageProvider {
069:
070: /**
071: * The name of the property, which should be fired when the mime paths to
072: * <code>Language</code> mapping changes.
073: */
074: public static final String PROP_LANGUAGE = "LanguageProvider.PROP_LANGUAGE"; //NOI18N
075:
076: /**
077: * The name of the property, which should be fired when the embedded language to
078: * <code>Language</code> mapping changes.
079: */
080: public static final String PROP_EMBEDDED_LANGUAGE = "LanguageProvider.PROP_EMBEDDED_LANGUAGE"; //NOI18N
081:
082: /**
083: * Finds <code>Language</code> for a given mime type.
084: *
085: * <p>The lexer framework uses this method to find a <code>Language</code>
086: * for <code>Document</code>s that are used as an input source. If the document
087: * itself does not specify its <code>Language</code> the framework
088: * will consult registered <code>LanguageProvider</code>s to find out the
089: * <code>Language</code> appropriate for the document's mime type.
090: *
091: * @param mimeType The mime type of a <code>Language</code> to find.
092: *
093: * @return The <code>Language</code> registered for the given
094: * mime type or <code>null</code> if no such <code>Language</code> exists.
095: */
096: public abstract Language<?> findLanguage(String mimeType);
097:
098: /**
099: * Finds <code>LanguageEmbedding</code> that will define what language is
100: * embedded in a given token.
101: *
102: * <p>If a <code>Token</code> contains text in a different language that could
103: * further be used for lexing of this <code>Token</code> the framework will try
104: * to find out the <code>Language</code> of that language by asking
105: * the <code>Token</code>'s own <code>Language</code> first and then
106: * by consulting registered <code>LanguageProvider</code>s. The <code>LanguageProvider</code>s
107: * are expected to return a <code>LanguageEmbedding</code> for tokens they
108: * care about and <code>null</code> for the rest. The first non-null
109: * <code>LanguageEmbedding</code> found will be used.
110: *
111: * <p><code>LanguageEmbedding</code> instances returned from this method
112: * <b>must not</b> reference any of the attributes passed in and especially not
113: * the <code>token</code> instance.
114: *
115: * @param token The <code>Token</code> to get the <code>Language</code>
116: * for.
117: * @param languagePath The <code>LanguagePath</code> of the token, which
118: * embedded language should be returned.
119: * @param inputAttributes The attributes that could affect the creation of
120: * the embedded <code>Language</code>. It may be <code>null</code>
121: * if there are no extra attributes.
122: *
123: * @return The <code>LanguageEmbedding</code> for the given <code>Token</code>
124: * or <code>null</code> if the token can't embedd any language
125: * or the token is unknown to this <code>LanguageProvider</code>.
126: */
127: public abstract LanguageEmbedding<?> findLanguageEmbedding(
128: Token<?> token, LanguagePath languagePath,
129: InputAttributes inputAttributes);
130:
131: /**
132: * Add a listener for change notifications.
133: *
134: * @param l The listener to add.
135: */
136: public final void addPropertyChangeListener(PropertyChangeListener l) {
137: pcs.addPropertyChangeListener(l);
138: }
139:
140: /**
141: * Remove a listener.
142: *
143: * @param l The listener to remove.
144: */
145: public final void removePropertyChangeListener(
146: PropertyChangeListener l) {
147: pcs.removePropertyChangeListener(l);
148: }
149:
150: protected final void firePropertyChange(String propertyName) {
151: pcs.firePropertyChange(propertyName, null, null);
152: }
153:
154: /**
155: * The default constructor for subclasses.
156: */
157: protected LanguageProvider() {
158:
159: }
160:
161: private final PropertyChangeSupport pcs = new PropertyChangeSupport(
162: this);
163: }
|