001: package com.jclark.xml.output;
002:
003: import java.io.Writer;
004: import java.io.IOException;
005:
006: /**
007: * An extension of <code>Writer</code> for writing XML documents.
008: * The normal <code>write</code> methods write character data,
009: * automatically escaping markup characters.
010: * @version $Revision: 1.4 $ $Date: 1998/06/16 13:24:37 $
011: */
012:
013: public abstract class XMLWriter extends Writer {
014:
015: protected XMLWriter(Object lock) {
016: super (lock);
017: }
018:
019: /**
020: * Starts an element.
021: * This may be followed by zero or more calls to <code>attribute</code>.
022: * The start-tag will be closed by the first following call to any method
023: * other than <code>attribute</code>.
024: */
025: public abstract void startElement(String name) throws IOException;
026:
027: /**
028: * Writes an attribute.
029: * This is not legal if there have been calls to methods other than
030: * <code>attribute</code> since the last call to <code>startElement</code>,
031: * unless inside a <code>startAttribute</code>, <code>endAttribute</code>
032: * pair.
033: */
034: public abstract void attribute(String name, String value)
035: throws IOException;
036:
037: /**
038: * Starts an attribute.
039: * This writes the attribute name, <code>=</code> and the opening
040: * quote.
041: * This provides an alternative to <code>attribute</code>
042: * that allows markup to be included in the attribute value.
043: * The value of the attribute is written using the normal
044: * <code>write</code> methods;
045: * <code>endAttribute</code> must be called at the end
046: * of the attribute value.
047: * Entity and character references can be written using
048: * <code>entityReference</code> and <code>characterReference</code>.
049: */
050: public abstract void startAttribute(String name) throws IOException;
051:
052: /**
053: * Ends an attribute.
054: * This writes the closing quote of the attribute value.
055: */
056: public abstract void endAttribute() throws IOException;
057:
058: /**
059: * Ends an element.
060: * This may output an end-tag or close the current start-tag as an
061: * empty element.
062: */
063: public abstract void endElement(String name) throws IOException;
064:
065: /**
066: * Writes a processing instruction.
067: * If <code>data</code> is non-empty a space will be inserted automatically
068: * to separate it from the <code>target</code>.
069: */
070: public abstract void processingInstruction(String target,
071: String data) throws IOException;
072:
073: /**
074: * Writes a comment.
075: */
076: public abstract void comment(String body) throws IOException;
077:
078: /**
079: * Writes an entity reference.
080: */
081: public abstract void entityReference(boolean isParam, String name)
082: throws IOException;
083:
084: /**
085: * Writes a character reference.
086: */
087: public abstract void characterReference(int n) throws IOException;
088:
089: /**
090: * Writes a CDATA section.
091: */
092: public abstract void cdataSection(String content)
093: throws IOException;
094:
095: /**
096: * Starts the replacement text for an internal entity.
097: * The replacement text must be ended with
098: * <code>endReplacementText</code>.
099: * This enables an extra level of escaping that protects
100: * against the process of constructing an entity's replacement
101: * text from the literal entity value.
102: * See Section 4.5 of the XML Recommendation.
103: * Between a call to <code>startReplacementText</code>
104: * and <code>endReplacementText</code>, the argument to
105: * <code>markup</code> would specify entity replacement text;
106: * these would be escaped so that when processed as
107: * a literal entity value, the specified entity replacement text
108: * would be constructed.
109: * This call does not itself cause anything to be written.
110: */
111: public abstract void startReplacementText() throws IOException;
112:
113: /**
114: * Ends the replacement text for an internal entity.
115: * This disables the extra level of escaping enabled by
116: * <code>startReplacementText</code>.
117: * This call does not itself cause anything to be written.
118: */
119: public abstract void endReplacementText() throws IOException;
120:
121: /**
122: * Writes markup. The characters in the string will be written as is
123: * without being escaped (except for any escaping enabled by
124: * <code>startReplacementText</code>).
125: */
126: public abstract void markup(String str) throws IOException;
127: }
|