001: /* IXMLBuilder.java NanoXML/Java
002: *
003: * $Revision: 1421 $
004: * $Date: 2006-03-12 09:32:32 -0700 (Sun, 12 Mar 2006) $
005: * $Name$
006: *
007: * This file is part of NanoXML 2 for Java.
008: * Copyright (C) 2001 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:
033: /**
034: * NanoXML uses IXMLBuilder to construct the XML data structure it retrieved from its data source.
035: * You can supply your own builder or you can use the default builder of NanoXML.
036: *
037: * @see net.n3.nanoxml.IXMLParser
038: *
039: * @author Marc De Scheemaecker
040: * @version $Name$, $Revision: 1421 $
041: */
042: public interface IXMLBuilder {
043:
044: /**
045: * This method is called before the parser starts processing its input.
046: *
047: * @param systemID the system ID of the XML data source
048: * @param lineNr the line on which the parsing starts
049: *
050: * @throws java.lang.Exception If an exception occurred while processing the event.
051: */
052: public void startBuilding(String systemID, int lineNr)
053: throws Exception;
054:
055: /**
056: * This method is called when a processing instruction is encountered. PIs with target "xml" are
057: * handled by the parser.
058: *
059: * @param target the PI target
060: * @param reader to read the data from the PI
061: *
062: * @throws java.lang.Exception If an exception occurred while processing the event.
063: */
064: public void newProcessingInstruction(String target, Reader reader)
065: throws Exception;
066:
067: /**
068: * This method is called when a new XML element is encountered.
069: *
070: * @see #endElement
071: *
072: * @param name the name of the element
073: * @param nsPrefix the prefix used to identify the namespace
074: * @param nsSystemID the system ID associated with the namespace
075: * @param systemID the system ID of the XML data source
076: * @param lineNr the line in the source where the element starts
077: *
078: * @throws java.lang.Exception If an exception occurred while processing the event.
079: */
080: public void startElement(String name, String nsPrefix,
081: String nsSystemID, String systemID, int lineNr)
082: throws Exception;
083:
084: /**
085: * This method is called when a new attribute of an XML element is encountered.
086: *
087: * @param key the key (name) of the attribute
088: * @param nsPrefix the prefix used to identify the namespace
089: * @param nsSystemID the system ID associated with the namespace
090: * @param value the value of the attribute
091: * @param type the type of the attribute ("CDATA" if unknown)
092: *
093: * @throws java.lang.Exception If an exception occurred while processing the event.
094: */
095: public void addAttribute(String key, String nsPrefix,
096: String nsSystemID, String value, String type)
097: throws Exception;
098:
099: /**
100: * This method is called when the attributes of an XML element have been processed.
101: *
102: * @see #startElement
103: * @see #addAttribute
104: *
105: * @param name the name of the element
106: * @param nsPrefix the prefix used to identify the namespace
107: * @param nsSystemID the system ID associated with the namespace
108: *
109: * @throws java.lang.Exception If an exception occurred while processing the event.
110: */
111: public void elementAttributesProcessed(String name,
112: String nsPrefix, String nsSystemID) throws Exception;
113:
114: /**
115: * This method is called when the end of an XML elemnt is encountered.
116: *
117: * @see #startElement
118: *
119: * @param name the name of the element
120: * @param nsPrefix the prefix used to identify the namespace
121: * @param nsSystemID the system ID associated with the namespace
122: *
123: * @throws java.lang.Exception If an exception occurred while processing the event.
124: */
125: public void endElement(String name, String nsPrefix,
126: String nsSystemID) throws Exception;
127:
128: /**
129: * This method is called when a PCDATA element is encountered. A Java reader is supplied from
130: * which you can read the data. The reader will only read the data of the element. You don't
131: * need to check for boundaries. If you don't read the full element, the rest of the data is
132: * skipped. You also don't have to care about entities; they are resolved by the parser.
133: *
134: * @param reader the Java reader from which you can retrieve the data
135: * @param systemID the system ID of the XML data source
136: * @param lineNr the line in the source where the element starts
137: *
138: * @throws java.lang.Exception If an exception occurred while processing the event.
139: */
140: public void addPCData(Reader reader, String systemID, int lineNr)
141: throws Exception;
142:
143: /**
144: * Returns the result of the building process. This method is called just before the parse()
145: * method of IXMLParser returns.
146: *
147: * @see net.n3.nanoxml.IXMLParser#parse
148: *
149: * @return the result of the building process.
150: *
151: * @throws java.lang.Exception If an exception occurred while processing the event.
152: */
153: public Object getResult() throws Exception;
154:
155: }
|