Parser


1   /*
2    * Copyright (c) 1999 World Wide Web Consortium
3    * (Massachusetts Institute of Technology, Institut National de Recherche
4    *  en Informatique et en Automatique, Keio University).
5    * All Rights Reserved. http://www.w3.org/Consortium/Legal/
6    *
7    * The original version of this interface comes from SAX :
8    * http://www.megginson.com/SAX/
9    *
10   * $Id: Parser.java,v 1.1.1.1 2003/12/28 21:23:52 davidsch Exp $
11   */
12  package org.w3c.css.sac;
13  
14  import java.io.IOException  ;
15  import java.util.Locale  ;
16  
17  /**
18   * Basic interface for CSS (Simple API for CSS) parsers.
19   *
20   * <p>All CSS parsers must implement this basic interface: it allows
21   * applications to register handlers for different types of events
22   * and to initiate a parse from a URI, or a character stream.</p>
23   *
24   * <p>All CSS parsers must also implement a zero-argument constructor
25   * (though other constructors are also allowed).</p>
26   *
27   * <p>CSS parsers are reusable but not re-entrant: the application
28   * may reuse a parser object (possibly with a different input source)
29   * once the first parse has completed successfully, but it may not
30   * invoke the parse() methods recursively within a parse.</p>
31   *
32   * @version $Revision: 1.1.1.1 $
33   * @author  Philippe Le Hegaret
34   * @see DocumentHandler
35   * @see ErrorHandler
36   * @see InputSource
37   */
38  public interface Parser {
39      
40      /**
41       * Allow an application to request a locale for errors and warnings.
42       *
43       * <p>CSS parsers are not required to provide localisation for errors
44       * and warnings; if they cannot support the requested locale,
45       * however, they must throw a CSS exception.  Applications may
46       * not request a locale change in the middle of a parse.</p>
47       *
48       * @param locale A Java Locale object.
49       * @exception CSSException Throws an exception
50       *            (using the previous or default locale) if the 
51       *            requested locale is not supported.
52       * @see CSSException
53       * @see CSSParseException
54       */
55      public void setLocale(Locale   locale) throws CSSException;
56      
57      /**
58       * Allow an application to register a document event handler.
59       *
60       * <p>If the application does not register a document handler, all
61       * document events reported by the CSS parser will be silently
62       * ignored (this is the default behaviour implemented by
63       * HandlerBase).</p>
64       *
65       * <p>Applications may register a new or different handler in the
66       * middle of a parse, and the CSS parser must begin using the new
67       * handler immediately.</p>
68       *
69       * @param handler The document handler.
70       * @see DocumentHandler
71       */
72      public void setDocumentHandler(DocumentHandler handler);
73  
74      public void setSelectorFactory(SelectorFactory selectorFactory);
75      public void setConditionFactory(ConditionFactory conditionFactory);
76      
77      /**
78       * Allow an application to register an error event handler.
79       *
80       * <p>If the application does not register an error event handler,
81       * all error events reported by the CSS parser will be silently
82       * ignored, except for fatalError, which will throw a CSSException
83       * (this is the default behaviour implemented by HandlerBase).</p>
84       *
85       * <p>Applications may register a new or different handler in the
86       * middle of a parse, and the CSS parser must begin using the new
87       * handler immediately.</p>
88       *
89       * @param handler The error handler.
90       * @see ErrorHandler
91       * @see CSSException
92       */
93      public void setErrorHandler(ErrorHandler handler);
94      
95      /**
96       * Parse a CSS document.
97       *
98       * <p>The application can use this method to instruct the CSS parser
99       * to begin parsing an CSS document from any valid input
100      * source (a character stream, a byte stream, or a URI).</p>
101      *
102      * <p>Applications may not invoke this method while a parse is in
103      * progress (they should create a new Parser instead for each
104      * additional CSS document).  Once a parse is complete, an
105      * application may reuse the same Parser object, possibly with a
106      * different input source.</p>
107      *
108      * @param source The input source for the top-level of the
109      *        CSS document.
110      * @exception CSSException Any CSS exception, possibly
111      *            wrapping another exception.
112      * @exception java.io.IOException An IO exception from the parser,
113      *            possibly from a byte stream or character stream
114      *            supplied by the application.
115      * @see InputSource
116      * @see #parseStyleSheet(java.lang.String)
117      * @see #setDocumentHandler
118      * @see #setErrorHandler
119      */
120     public void parseStyleSheet(InputSource source) 
121     throws CSSException, IOException  ;
122     
123     
124     /**
125      * Parse a CSS document from a URI.
126      *
127      * <p>This method is a shortcut for the common case of reading a document
128      * from a URI.  It is the exact equivalent of the following:</p>
129      *
130      * <pre>
131      * parse(new InputSource(uri));
132      * </pre>
133      *
134      * <p>The URI must be fully resolved by the application before it is passed
135      * to the parser.</p>
136      *
137      * @param uri The URI.
138      * @exception CSSException Any CSS exception, possibly
139      *            wrapping another exception.
140      * @exception java.io.IOException An IO exception from the parser,
141      *            possibly from a byte stream or character stream
142      *            supplied by the application.
143      * @see #parseStyleSheet(InputSource) 
144      */
145     public void parseStyleSheet(String   uri) throws CSSException, IOException  ;
146 
147     /**
148      * Parse a CSS style declaration (without '{' and '}').
149      *
150      * @param styleValue The declaration.
151      * @exception CSSException Any CSS exception, possibly
152      *            wrapping another exception.
153      * @exception java.io.IOException An IO exception from the parser,
154      *            possibly from a byte stream or character stream
155      *            supplied by the application.
156      */
157     public void parseStyleDeclaration(InputSource source) 
158     throws CSSException, IOException  ;
159 
160 
161     /**
162      * Parse a CSS rule.
163      *
164      * @exception CSSException Any CSS exception, possibly
165      *            wrapping another exception.
166      * @exception java.io.IOException An IO exception from the parser,
167      *            possibly from a byte stream or character stream
168      *            supplied by the application.
169      */
170     public void parseRule(InputSource source) throws CSSException, IOException  ;
171 
172     /**
173      * Returns a string about which CSS language is supported by this
174      * parser. For CSS Level 1, it returns "http://www.w3.org/TR/REC-CSS1", for
175      * CSS Level 2, it returns "http://www.w3.org/TR/REC-CSS2". Note that a
176      * "CSSx" parser can return lexical unit other than those allowed by CSS
177      * Level x but this usage is not recommended.
178      */
179     public String   getParserVersion();
180     
181     /**
182      * Parse a comma separated list of selectors.
183      * 
184      * 
185      * @exception CSSException Any CSS exception, possibly
186      *            wrapping another exception.
187      * @exception java.io.IOException An IO exception from the parser,
188      *            possibly from a byte stream or character stream
189      *            supplied by the application.
190      */    
191     public SelectorList parseSelectors(InputSource source)
192         throws CSSException, IOException  ;
193 
194 
195     /**
196      * Parse a CSS property value.
197      * 
198      * 
199      * @exception CSSException Any CSS exception, possibly
200      *            wrapping another exception.
201      * @exception java.io.IOException An IO exception from the parser,
202      *            possibly from a byte stream or character stream
203      *            supplied by the application.
204      */    
205     public LexicalUnit parsePropertyValue(InputSource source)
206         throws CSSException, IOException  ;
207 
208     
209     /**
210      * Parse a CSS priority value (e.g. "!important").
211      * 
212      * 
213      * @exception CSSException Any CSS exception, possibly
214      *            wrapping another exception.
215      * @exception java.io.IOException An IO exception from the parser,
216      *            possibly from a byte stream or character stream
217      *            supplied by the application.
218      */    
219     public boolean parsePriority(InputSource source)
220         throws CSSException, IOException  ;
221 }
222
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags