de.frame4j.xml

Class XMLdoc

java.lang.Object

de.frame4j.xml.XMLdoc

All Implemented Interfaces:

Serializable, Cloneable

@MinDoc(copyright="Copyright   2001 - 2005, 2009  A. Weinert",
        author="Albrecht Weinert",
        version="V.46",
        lastModified="11.05.2021",
        usage="use in XML / HTML applications",
        purpose="represents a XML document")
public class XMLdoc
extends Object
implements Cloneable, Serializable

An XML document (DOM).

Objects of this class contain or encapsulate a (DOM-) Document as well as properties and methods for input, manipulation and output. XMLdoc thereby facilitates the (partly laborious and restricted) handling of DOM (org.w3c.dom) documents.

The motive of going to JDom is hence mostly gone by this class, that (in the predecessor framework) had been a "come back from JDom enabler". Also, the serialisation, not supported by (DOM-) Document (but by JDom) is supported here — and is still for those historical reasons. In between this feature seems a bit questionable in the light of XML itself being a (the) serialisation format.

The org.w3c.dom.Document encapsulated in an object of this class is of the more common (parent) type Node, as a matter of fact. But it is settable or available just as Document, DocumentFragment or Element.

© Copyright 2001 - 2005, 2009 Albrecht Weinert

See Also:

Serialized Form

Field Summary

Fields

Modifier and Type	Field and Description
protected PrintWriter	log Writer (output) for error and warning reports.
static String	NO_CLOSE Output coding "UTF-8 without closing the output stream".
XMLconf	xmlConf Parser properties — plus some others.

Constructor Summary

Constructors

Constructor and Description
XMLdoc(App app) Make for an application (App inheritor).
XMLdoc(PrintWriter log) Make with standard settings.

Method Summary

Modifier and Type	Method and Description
boolean	applyTransforms() Apply the transformation.
XMLdoc	clone() A copy of this object.
static boolean	doc2xml(Node doc, OutputStream os, String encoding) Output (facsimile) a DOM tree as XML.
Node	getDocument() The document (contained).
ParseErrorHandler	getErrorHandler() rrorHandler for parsing..
static SAXException	getLastXml2docError() Fetch last XML error of xml2doc() call (if any).
String	getPublicId() The document's name (just for report and documentation).
static DocumentBuilder	getXMLInputer() Make a simple XML -> DOM input.
static Transformer	getXMLOutputer() Supply a DOM -> XML - output with no transformation.
boolean	isDocNode() The node (contained) is a document or a part.
static DocumentBuilder	makeBuilder(boolean valid, boolean nameSpace, PrintWriter log) Make a DOM parser.
void	parse(InputSource is) Parse from an input source.
void	parse(InputStream is) Parse from an input stream.
void	parse(String fileOrURL, String encoding) Parse from a file or URL.
void	readFrom(InputStream is) Get (in facsimile) from an input stream.
void	set(PropMap prop) Set the properties by a PropMap object.
void	setDocument(Node document) Set the document.
void	setErrorHanlder(ParseErrorHandler errorHandler) ErrorHandler for parsing.
void	setPublicId(String publicId) The document's name (just for report and documentation).
boolean	write(OutputStream os) Write (with transformations) to an output stream..
boolean	writeTo(OutputStream os) Write (in facsimile) to an output stream.
static Document	xml2doc(InputStream is) Input (facsimile) from XML to DOM tree.

Methods inherited from class java.lang.Object

equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

xmlConf

public final XMLconf xmlConf

Parser properties — plus some others.

All parser, input, output, transformer and else properties wanted / used for this XMLdoc object lie in this associated XMLconf object. It will be set on construction by XMLdoc(App) according to the Application's properties (app.prop).

See Also:

set(PropMap)

log

protected final PrintWriter log

Writer (output) for error and warning reports.

Is set finally on construction. It is never null; default is (decorated) System.out.

NO_CLOSE

public static final String NO_CLOSE

Output coding "UTF-8 without closing the output stream".

This (pseudo-) output encoding signalises to output methods like doc2xml(Node, OutputStream, String) or writeTo(OutputStream) to use UTF-8 and not close the output.

The rationale behind this somewhat exotic approach is the XML serialisation of many objects to one ObjectOutputStream.
N.B.: XMLdoc is serializable.
Value: "NO_CLOSE"

See Also:

Constant Field Values

Constructor Detail

XMLdoc

public XMLdoc(PrintWriter log)

Make with standard settings.

An XMLdoc object without a document with log output and all properties in default setting will be made.

As PrintStream log the parameter log is taken or, if null, the normal output (decorated System.out).

Parameters:

log - destination of reports

XMLdoc

public XMLdoc(App app)
       throws NullPointerException

Make for an application (App inheritor).

An XMLdoc object without a document will be made.

The log output and other properties will be taken from the application, the App inheritor, supplied.

Parameters:

app - the application get output streams and properties from

Throws:

NullPointerException - if app is null

See Also:

set(PropMap)

Method Detail

set

public void set(PropMap prop)
         throws IllegalArgumentException

Set the properties by a PropMap object.

Parameters:

prop - source of the properties to be used

Throws:

IllegalArgumentException - parameter value problems

See Also:

XMLconf.set(PropMap)

getDocument

public Node getDocument()

The document (contained).

It is of type Document, DocumentFragment or Element or it is null.

isDocNode

public final boolean isDocNode()

The node (contained) is a document or a part.

Returns true, if document is not null and of type Document, DocumentFragment or Element (that is it may have children nodes).

setDocument

public final void setDocument(Node document)
                       throws ClassCastException

Set the document.

Parameters:

document - the new document (DOM tree or null).
document has to be of type Document, DocumentFragment or Element

Throws:

ClassCastException - on wrong type;
this.document is null then

getPublicId

public final String getPublicId()

The document's name (just for report and documentation).

It is either not empty or it is null.

setPublicId

public void setPublicId(String publicId)

The document's name (just for report and documentation).

If publicId is not empty it is taken as new publicId. Otherwise that is set null.

clone

public XMLdoc clone()

A copy of this object.

This XMLdoc object is cloned deeply, including a deep clone of an associated document.

Overrides:

clone in class Object

setErrorHanlder

public void setErrorHanlder(ParseErrorHandler errorHandler)

ErrorHandler for parsing.

getErrorHandler

public ParseErrorHandler getErrorHandler()

rrorHandler for parsing..

parse

public void parse(InputStream is)
           throws IllegalArgumentException,
                  IOException,
                  SAXException,
                  FactoryConfigurationError,
                  ParserConfigurationException

Parse from an input stream.

Parameters:

is - the XML input stream to be parsed

Throws:

IllegalArgumentException - (forwarded)

IOException - stream problem

SAXException - (forwarded from parsing)

FactoryConfigurationError - XML problem

ParserConfigurationException - XML prolem

See Also:

parse(InputSource)

parse

public void parse(String fileOrURL,
                  String encoding)
           throws IllegalArgumentException,
                  IOException,
                  SAXException,
                  FactoryConfigurationError,
                  ParserConfigurationException

Parse from a file or URL.

Parameters:

fileOrURL - names a file or URL as XML input

encoding - the input's encoding (character set)

Throws:

IllegalArgumentException - (forwarded)

IOException - stream problem

SAXException - (forwarded from parsing)

FactoryConfigurationError - XML problem

ParserConfigurationException - XML problem

See Also:

parse(InputSource), XMLconf.setProxyPort(CharSequence), XMLconf.setProxyHost(CharSequence)

parse

public void parse(InputSource is)
           throws IOException,
                  SAXException,
                  IllegalArgumentException,
                  FactoryConfigurationError,
                  ParserConfigurationException

Parse from an input source.

All (DOM-) parse() methods allowing for other input types make an InputSource in the end (and delegate to here).

This method is either successful or throws an Exception, see also XMLconf.makeDocumentBuilder(ParseErrorHandler).

Parameters:

is - the XML input

Throws:

IllegalArgumentException - (forwarded)

IOException - stream problem

SAXException - (forwarded from parsing)

FactoryConfigurationError - XML problem

ParserConfigurationException - XML problem

readFrom

public void readFrom(InputStream is)
              throws IOException,
                     SAXException,
                     ClassNotFoundException

Get (in facsimile) from an input stream.

The DOM tree is fetched directly and without any validation from is.

Parameters:

is - the input stream to read the DOM from

Throws:

IOException - stream or file problems

SAXException - XML problems

ClassNotFoundException - no DOM could be made

See Also:

xml2doc()

writeTo

public boolean writeTo(OutputStream os)
                throws IOException

Write (in facsimile) to an output stream.


The DOM tree is written directly and without any special formating or transforming to the OutputStream os.

The only property influencing this simple proceeding is encoding.

Parameters:

os - the output stream to write the DOM as XML to

Returns:

false if nothing (no XML) could be written (e.g. due to wrong parameter values

Throws:

IOException - stream or file problems

See Also:

doc2xml(), write()

applyTransforms

public boolean applyTransforms()

Apply the transformation.

THe transformations defined by all transformation properties will be applied to the embedded DOM document.

Returns:

true if the transformations were applied successfully

See Also:

XMLconf.clearDefAtts, XMLconf.textNormalize, MLHelper.clearHTMLdefAtts(Element), Node.normalize()

write

public boolean write(OutputStream os)
              throws IOException,
                     TransformerException

Write (with transformations) to an output stream..

The DOM tree will be output to the stream os using all formating etc. specified by the output properties.

If the transformations are wanted and not yet done, applyTransforms() must be called before this method.
aufzurufen.

Parameters:

os - the stream to write to

Returns:

true if the XML was written successfully

Throws:

IOException - file or stream problems

TransformerException - errors while applying the transformations

See Also:

writeTo()

getXMLOutputer

public static Transformer getXMLOutputer()

Supply a DOM -> XML - output with no transformation.

This method returns always the same simple "one to one transformer".

That transformer is not threadsafe. The output properties of the last use remain set in each case.

The guaranteed usage in one thread only is OK. One may also (better) synchronise the proceeding with this object, that is for setOutputProperty(), etc. until transform() respectively doc2xml(). Other methods using this singleton object do this also.

Returns:

the simple (singleton) XML outputer = "one to one transformer"
null will only returne if the whole XML installation (JDK/JRE) is insufficient

doc2xml

public static boolean doc2xml(Node doc,
                              OutputStream os,
                              String encoding)
                       throws IOException

Output (facsimile) a DOM tree as XML.

The output will be closed by this method after work done. This will not happen if encoding is equal to "NO_CLOSE"; in that case the encoding is UTF-8.

Parameters:

doc - the DOM tree to output; it's the starting node and it has to be of type Document, DocumentFragment or Element

os - the destination, the output; it will be closed afterwards (except when ... see above)

encoding - the output encoding (default UTF-8); ISO-8859-1 and some others are possible too

Returns:

true on success

Throws:

IOException - on output problems with os

makeBuilder

public static DocumentBuilder makeBuilder(boolean valid,
                                          boolean nameSpace,
                                          PrintWriter log)

Make a DOM parser.

A DOM parser will be supplied; all its properties, except validating and namespace, will be set to its default in each case. If both parameters valid and namespace are false this will be the most simple or most direct (1 to 1) translation from XML input to DOM tree (compare doc2xml() and getXMLOutputer()).

Parameters:

valid - true: validating

nameSpace - true: namespace aware

log - Writer for error reports (if any); may be null

Returns:

a parser (on success, or null)

getXMLInputer

public static DocumentBuilder getXMLInputer()

Make a simple XML -> DOM input.

This method returns always the same simple "one to one parser" without validation, namespace awareness and the like schnick-schnack.

That parser is not threadsafe.
Usage in one thread is OK. Better is the synchronisation of the proceeding with the object. Other Frame4J methods using this singleton parser do this also.

Returns:

the simple 1-to-1 parser. null is returned on failure; that normally means an insufficient XML implementation in the JDK/JRE

getLastXml2docError

public static SAXException getLastXml2docError()

Fetch last XML error of xml2doc() call (if any).

This method is not threadsafe. It just returns the last Exception internally caught. If the whole input proceeding is synchronised by the xmlInputer the method will give the right answer within the synchronized block.

Returns:

den ggf. Fehler (SAXException) or null;

xml2doc

public static Document xml2doc(InputStream is)
                        throws IOException

Input (facsimile) from XML to DOM tree.

The InputStream is will be parsed without any validating, namespace awareness and the like and the DOM object made in the process is returned. This method is the complement to doc2xml().

Parameters:

is - the input

Returns:

the document or null on failure

Throws:

IOException - on input problems with is