001: /* IXMLBuilder.java NanoXML/Java
002: *
003: * $Revision: 1.3 $
004: * $Date: 2002/01/04 21:03:28 $
005: * $Name: RELEASE_2_2_1 $
006: *
007: * This file is part of NanoXML 2 for Java.
008: * Copyright (C) 2000-2002 Marc De Scheemaecker, All Rights Reserved.
009: *
010: * This software is provided 'as-is', without any express or implied warranty.
011: * In no event will the authors be held liable for any damages arising from the
012: * use of this software.
013: *
014: * Permission is granted to anyone to use this software for any purpose,
015: * including commercial applications, and to alter it and redistribute it
016: * freely, subject to the following restrictions:
017: *
018: * 1. The origin of this software must not be misrepresented; you must not
019: * claim that you wrote the original software. If you use this software in
020: * a product, an acknowledgment in the product documentation would be
021: * appreciated but is not required.
022: *
023: * 2. Altered source versions must be plainly marked as such, and must not be
024: * misrepresented as being the original software.
025: *
026: * 3. This notice may not be removed or altered from any source distribution.
027: */
028:
029: package net.n3.nanoxml;
030:
031: import java.io.Reader;
032: import java.io.IOException;
033:
034: /**
035: * NanoXML uses IXMLBuilder to construct the XML data structure it retrieved
036: * from its data source. You can supply your own builder or you can use the
037: * default builder of NanoXML.
038: * <P>
039: * If a method of the builder throws an exception, the parsing is aborted and
040: * {@link net.n3.nanoxml.IXMLParser#parse} throws an
041: * {@link net.n3.nanoxml.XMLException} which encasulates the original
042: * exception.
043: *
044: * @see net.n3.nanoxml.IXMLParser
045: *
046: * @author Marc De Scheemaecker
047: * @version $Name: RELEASE_2_2_1 $, $Revision: 1.3 $
048: */
049: public interface IXMLBuilder {
050:
051: /**
052: * This method is called before the parser starts processing its input.
053: *
054: * @param systemID the system ID of the XML data source.
055: * @param lineNr the line on which the parsing starts.
056: *
057: * @throws java.lang.Exception
058: * If an exception occurred while processing the event.
059: */
060: public void startBuilding(String systemID, int lineNr)
061: throws Exception;
062:
063: /**
064: * This method is called when a processing instruction is encountered.
065: * A PI with a reserved target ("xml" with any case) is never reported.
066: *
067: * @param target the processing instruction target.
068: * @param reader the method can retrieve the parameter of the PI from this
069: * reader. You may close the reader before reading all its
070: * data and you cannot read too much data.
071: *
072: * @throws java.lang.Exception
073: * If an exception occurred while processing the event.
074: */
075: public void newProcessingInstruction(String target, Reader reader)
076: throws Exception;
077:
078: /**
079: * This method is called when a new XML element is encountered.
080: *
081: * @see #endElement
082: *
083: * @param name the name of the element.
084: * @param nsPrefix the prefix used to identify the namespace. If no
085: * namespace has been specified, this parameter is null.
086: * @param nsURI the URI associated with the namespace. If no
087: * namespace has been specified, or no URI is
088: * associated with nsPrefix, this parameter is null.
089: * @param systemID the system ID of the XML data source.
090: * @param lineNr the line in the source where the element starts.
091: *
092: * @throws java.lang.Exception
093: * If an exception occurred while processing the event.
094: */
095: public void startElement(String name, String nsPrefix,
096: String nsURI, String systemID, int lineNr) throws Exception;
097:
098: /**
099: * This method is called when a new attribute of an XML element is
100: * encountered.
101: *
102: * @param key the key (name) of the attribute.
103: * @param nsPrefix the prefix used to identify the namespace. If no
104: * namespace has been specified, this parameter is null.
105: * @param nsURI the URI associated with the namespace. If no
106: * namespace has been specified, or no URI is
107: * associated with nsPrefix, this parameter is null.
108: * @param value the value of the attribute.
109: * @param type the type of the attribute. If no type is known,
110: * "CDATA" is returned.
111: *
112: * @throws java.lang.Exception
113: * If an exception occurred while processing the event.
114: */
115: public void addAttribute(String key, String nsPrefix, String nsURI,
116: String value, String type) throws Exception;
117:
118: /**
119: * This method is called when the attributes of an XML element have been
120: * processed.
121: *
122: * @see #startElement
123: * @see #addAttribute
124: *
125: * @param name the name of the element.
126: * @param nsPrefix the prefix used to identify the namespace. If no
127: * namespace has been specified, this parameter is null.
128: * @param nsURI the URI associated with the namespace. If no
129: * namespace has been specified, or no URI is
130: * associated with nsPrefix, this parameter is null.
131: *
132: * @throws java.lang.Exception
133: * If an exception occurred while processing the event.
134: */
135: public void elementAttributesProcessed(String name,
136: String nsPrefix, String nsURI) throws Exception;
137:
138: /**
139: * This method is called when the end of an XML elemnt is encountered.
140: *
141: * @see #startElement
142: *
143: * @param name the name of the element.
144: * @param nsPrefix the prefix used to identify the namespace. If no
145: * namespace has been specified, this parameter is null.
146: * @param nsURI the URI associated with the namespace. If no
147: * namespace has been specified, or no URI is
148: * associated with nsPrefix, this parameter is null.
149: *
150: * @throws java.lang.Exception
151: * If an exception occurred while processing the event.
152: */
153: public void endElement(String name, String nsPrefix, String nsURI)
154: throws Exception;
155:
156: /**
157: * This method is called when a PCDATA element is encountered. A Java
158: * reader is supplied from which you can read the data. The reader will
159: * only read the data of the element. You don't need to check for
160: * boundaries. If you don't read the full element, the rest of the data
161: * is skipped. You also don't have to care about entities: they are
162: * resolved by the parser.
163: *
164: * @param reader the method can retrieve the data from this reader. You
165: * may close the reader before reading all its data and you
166: * cannot read too much data.
167: * @param systemID the system ID of the XML data source.
168: * @param lineNr the line in the source where the element starts.
169: *
170: * @throws java.lang.Exception
171: * If an exception occurred while processing the event.
172: */
173: public void addPCData(Reader reader, String systemID, int lineNr)
174: throws Exception;
175:
176: /**
177: * Returns the result of the building process. This method is called just
178: * before the <I>parse</I> method of IXMLParser returns.
179: *
180: * @see net.n3.nanoxml.IXMLParser#parse
181: *
182: * @return the result of the building process.
183: *
184: * @throws java.lang.Exception
185: * If an exception occurred while processing the event.
186: */
187: public Object getResult() throws Exception;
188:
189: }
|