001: /*
002: * Copyright (c) 1999 World Wide Web Consortium
003: * (Massachusetts Institute of Technology, Institut National de Recherche
004: * en Informatique et en Automatique, Keio University).
005: * All Rights Reserved. http://www.w3.org/Consortium/Legal/
006: *
007: * The original version of this interface comes from SAX :
008: * http://www.megginson.com/SAX/
009: *
010: * $Id$
011: */
012: package org.w3c.css.sac;
013:
014: import java.io.IOException;
015: import java.util.Locale;
016:
017: /**
018: * Basic interface for CSS (Simple API for CSS) parsers.
019: *
020: * <p>All CSS parsers must implement this basic interface: it allows
021: * applications to register handlers for different types of events
022: * and to initiate a parse from a URI, or a character stream.</p>
023: *
024: * <p>All CSS parsers must also implement a zero-argument constructor
025: * (though other constructors are also allowed).</p>
026: *
027: * <p>CSS parsers are reusable but not re-entrant: the application
028: * may reuse a parser object (possibly with a different input source)
029: * once the first parse has completed successfully, but it may not
030: * invoke the parse() methods recursively within a parse.</p>
031: *
032: * @version $Revision$
033: * @author Philippe Le Hegaret
034: * @see DocumentHandler
035: * @see ErrorHandler
036: * @see InputSource
037: */
038: public interface Parser {
039:
040: /**
041: * Allow an application to request a locale for errors and warnings.
042: *
043: * <p>CSS parsers are not required to provide localisation for errors
044: * and warnings; if they cannot support the requested locale,
045: * however, they must throw a CSS exception. Applications may
046: * not request a locale change in the middle of a parse.</p>
047: *
048: * @param locale A Java Locale object.
049: * @exception CSSException Throws an exception
050: * (using the previous or default locale) if the
051: * requested locale is not supported.
052: * @see CSSException
053: * @see CSSParseException
054: */
055: public void setLocale(Locale locale) throws CSSException;
056:
057: /**
058: * Allow an application to register a document event handler.
059: *
060: * <p>If the application does not register a document handler, all
061: * document events reported by the CSS parser will be silently
062: * ignored (this is the default behaviour implemented by
063: * HandlerBase).</p>
064: *
065: * <p>Applications may register a new or different handler in the
066: * middle of a parse, and the CSS parser must begin using the new
067: * handler immediately.</p>
068: *
069: * @param handler The document handler.
070: * @see DocumentHandler
071: */
072: public void setDocumentHandler(DocumentHandler handler);
073:
074: public void setSelectorFactory(SelectorFactory selectorFactory);
075:
076: public void setConditionFactory(ConditionFactory conditionFactory);
077:
078: /**
079: * Allow an application to register an error event handler.
080: *
081: * <p>If the application does not register an error event handler,
082: * all error events reported by the CSS parser will be silently
083: * ignored, except for fatalError, which will throw a CSSException
084: * (this is the default behaviour implemented by HandlerBase).</p>
085: *
086: * <p>Applications may register a new or different handler in the
087: * middle of a parse, and the CSS parser must begin using the new
088: * handler immediately.</p>
089: *
090: * @param handler The error handler.
091: * @see ErrorHandler
092: * @see CSSException
093: */
094: public void setErrorHandler(ErrorHandler handler);
095:
096: /**
097: * Parse a CSS document.
098: *
099: * <p>The application can use this method to instruct the CSS parser
100: * to begin parsing an CSS document from any valid input
101: * source (a character stream, a byte stream, or a URI).</p>
102: *
103: * <p>Applications may not invoke this method while a parse is in
104: * progress (they should create a new Parser instead for each
105: * additional CSS document). Once a parse is complete, an
106: * application may reuse the same Parser object, possibly with a
107: * different input source.</p>
108: *
109: * @param source The input source for the top-level of the
110: * CSS document.
111: * @exception CSSException Any CSS exception, possibly
112: * wrapping another exception.
113: * @exception java.io.IOException An IO exception from the parser,
114: * possibly from a byte stream or character stream
115: * supplied by the application.
116: * @see InputSource
117: * @see #parseStyleSheet(java.lang.String)
118: * @see #setDocumentHandler
119: * @see #setErrorHandler
120: */
121: public void parseStyleSheet(InputSource source)
122: throws CSSException, IOException;
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,
146: IOException;
147:
148: /**
149: * Parse a CSS style declaration (without '{' and '}').
150: *
151: * @param styleValue The declaration.
152: * @exception CSSException Any CSS exception, possibly
153: * wrapping another exception.
154: * @exception java.io.IOException An IO exception from the parser,
155: * possibly from a byte stream or character stream
156: * supplied by the application.
157: */
158: public void parseStyleDeclaration(InputSource source)
159: throws CSSException, IOException;
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,
171: IOException;
172:
173: /**
174: * Returns a string about which CSS language is supported by this
175: * parser. For CSS Level 1, it returns "CSS1", for CSS Level 2, it returns
176: * "CSS2". For CSS Level 3, it returns "CSS3", etc. Note that a "CSSx"
177: * parser can return lexical unit other than those allowed by CSS Level x
178: * but this usage is not recommended.
179: */
180: public String getParserVersion();
181:
182: /**
183: * Parse a comma separated list of selectors.
184: *
185: *
186: * @exception CSSException Any CSS exception, possibly
187: * wrapping another exception.
188: * @exception java.io.IOException An IO exception from the parser,
189: * possibly from a byte stream or character stream
190: * supplied by the application.
191: */
192: public SelectorList parseSelectors(InputSource source)
193: throws CSSException, IOException;
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: * Parse a CSS priority value (e.g. "!important").
210: *
211: *
212: * @exception CSSException Any CSS exception, possibly
213: * wrapping another exception.
214: * @exception java.io.IOException An IO exception from the parser,
215: * possibly from a byte stream or character stream
216: * supplied by the application.
217: */
218: public boolean parsePriority(InputSource source)
219: throws CSSException, IOException;
220: }
|