KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > netbeans > spi > lexer > LanguageProvider


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-2007 Sun
17  * Microsystems, Inc. All Rights Reserved.
18  */

19
20 package org.netbeans.spi.lexer;
21
22 import java.beans.PropertyChangeListener JavaDoc;
23 import java.beans.PropertyChangeSupport JavaDoc;
24 import org.netbeans.api.lexer.InputAttributes;
25 import org.netbeans.api.lexer.Language;
26 import org.netbeans.api.lexer.LanguagePath;
27 import org.netbeans.api.lexer.Token;
28 import org.netbeans.api.lexer.TokenId;
29
30 /**
31  * The <code>Language</code> provider. This class is a hook into the
32  * lexer framework allowing modules to provide a language resolution service.
33  * Whenever a <code>Language</code> is not explicitly known the
34  * framework tries to determine it by asking <code>LanguageProvider</code>s registered
35  * in the <code>Lookup.getDefault()</code>.
36  *
37  * <code>Language</code>s might be needed for a mime type or mime path
38  * of a <code>Document</code> used as an input source or they might be needed for
39  * some tokens that contain text in an another (embedded) language. In both cases
40  * a <code>Language</code> can either be explicitely provided by setting
41  * the document's property or implementing the <code>LanguageHierarchy.embedded()</code>
42  * method respectively or the framework will use <code>LanguageProvider</code>s to
43  * create the appropriate <code>Language</code>.
44  *
45  * @author Vita Stejskal
46  */

47 public abstract class LanguageProvider {
48     
49     /**
50      * The name of the property, which should be fired when the mime paths to
51      * <code>Language</code> mapping changes.
52      */

53     public static final String JavaDoc PROP_LANGUAGE = "LanguageProvider.PROP_LANGUAGE"; //NOI18N
54

55     /**
56      * The name of the property, which should be fired when the embedded language to
57      * <code>Language</code> mapping changes.
58      */

59     public static final String JavaDoc PROP_EMBEDDED_LANGUAGE = "LanguageProvider.PROP_EMBEDDED_LANGUAGE"; //NOI18N
60

61     /**
62      * Finds <code>Language</code> for a given mime path.
63      *
64      * <p>The lexer framework uses this method to find a <code>Language</code>
65      * for <code>Document</code>s that are used as an input source. If the document
66      * itself does not specify its <code>Language</code> the framework
67      * will consult registered <code>LanguageProvider</code>s to find out the
68      * <code>Language</code> appropriate for the document's mime type.
69      *
70      * @param mimePath The mime path or mime type to get a <code>Language</code>
71      * for. It is allowed to pass in an empty string or <code>null</code>.
72      *
73      * @return The <code>Language</code> registered for the given
74      * mime path or <code>null</code> if no such <code>Language</code> exists.
75      */

76     public abstract Language<? extends TokenId> findLanguage(String JavaDoc mimePath);
77     
78     /**
79      * Finds <code>LanguageEmbedding</code> that will define what language is
80      * embedded in a given token.
81      *
82      * <p>If a <code>Token</code> contains text in a different language that could
83      * further be used for lexing of this <code>Token</code> the framework will try
84      * to find out the <code>Language</code> of that language by asking
85      * the <code>Token</code>'s own <code>Language</code> first and then
86      * by consulting registered <code>LanguageProvider</code>s. The <code>LanguageProvider</code>s
87      * are expected to return a <code>LanguageEmbedding</code> for tokens they
88      * care about and <code>null</code> for the rest. The first non-null
89      * <code>LanguageEmbedding</code> found will be used.
90      *
91      * <p><code>LanguageEmbedding</code> instances returned from this method
92      * <b>must not</b> reference any of the attributes passed in and especially not
93      * the <code>token</code> instance.
94      *
95      * @param token The <code>Token</code> to get the <code>Language</code>
96      * for.
97      * @param languagePath The <code>LanguagePath</code> of the token, which
98      * embedded language should be returned.
99      * @param inputAttributes The attributes that could affect the creation of
100      * the embedded <code>Language</code>. It may be <code>null</code>
101      * if there are no extra attributes.
102      *
103      * @return The <code>LanguageEmbedding</code> for the given <code>Token</code>
104      * or <code>null</code> if the token can't embedd any language
105      * or the token is unknown to this <code>LanguageProvider</code>.
106      */

107     public abstract LanguageEmbedding<? extends TokenId> findLanguageEmbedding(
108     Token<? extends TokenId> token, LanguagePath languagePath, InputAttributes inputAttributes);
109     
110     /**
111      * Add a listener for change notifications.
112      *
113      * @param l The listener to add.
114      */

115     public final void addPropertyChangeListener(PropertyChangeListener JavaDoc l) {
116         pcs.addPropertyChangeListener(l);
117     }
118
119     /**
120      * Remove a listener.
121      *
122      * @param l The listener to remove.
123      */

124     public final void removePropertyChangeListener(PropertyChangeListener JavaDoc l) {
125         pcs.removePropertyChangeListener(l);
126     }
127     
128     protected final void firePropertyChange(String JavaDoc propertyName) {
129         pcs.firePropertyChange(propertyName, null, null);
130     }
131     
132     /**
133      * The default constructor for subclasses.
134      */

135     protected LanguageProvider() {
136         
137     }
138     
139     private final PropertyChangeSupport JavaDoc pcs = new PropertyChangeSupport JavaDoc(this);
140 }
141
Popular Tags