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  ;
23  import java.beans.PropertyChangeSupport  ;
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   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   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   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   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   l) {
125         pcs.removePropertyChangeListener(l);
126     }
127     
128     protected final void firePropertyChange(String   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   pcs = new PropertyChangeSupport  (this);
140 }
141
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags