XMLconf ( Frame4J -- the Java framework de.frame4j... )

java.lang.Object
- de.frame4j.xml.XMLconf

All Implemented Interfaces:

Cloneable
```
@MinDoc(copyright="Copyright   2005, 2009, 2016  A. Weinert",
        author="Albrecht Weinert",
        version="V.33",
        lastModified="27.03.2021",
        usage="use in XML applications",
        purpose="encapsulate the configuration")
public class XMLconf
extends Object
implements Cloneable
```
Configuration for XML parser, generator and such..

Objects of this class contain and handle commonly usable configuration settings especially for XML parsers. By connection to n PropMap respectively App.prop this class simplifies the usage of DOM (org.w3c.dom) and SAX parsers.

Hence this class' the respective methods deliver SAX parsers (as XMLReader), DOM builder (as DocumentBuilder) and XML inputs (as InputSource) all according to the properties set in this XMLconf object.

XML input objects made by makeInputSource(CharSequence) can be used for inputing XML in the narrower sense as as for inputing the transforming style sheets.

The class XMLdoc is build upon this class using an associated internal XMLconf object.

© Copyright 2005 Albrecht Weinert

Field Summary

Fields
Modifier and Type	Field and Description
`boolean`	`clearDefAtts` Delete HTML default attributes before output.
`boolean`	`coalescing` Unite character data in a text node.
`String`	`encoding` Coding of the XML text output.
`boolean`	`expandEmptyElements` Expand empty elements on the XML text output.
`boolean`	`expandEntityReferences` Replace references.
`boolean`	`ignoreComments` Delete comments.
`boolean`	`ignoreWhiteSpace` Ignore white space.
`String`	`impEncoding` Coding of the XML text input.
`boolean`	`namespaceAware` Parse XML with XML namespace support.
`boolean`	`newlines` Output line feeds with the XML text output.
`boolean`	`omitDeclaration` Declare XML coding in the XML output text.
`boolean`	`omitEncoding` Declare the coding with the XML text output.
`protected String`	`proxyHost` Name of the proxy server for fetching from URL.
`protected String`	`proxyPort` Port of the proxy server for fetching from URL.
`boolean`	`textNormalize` Compact the XML text output.
`boolean`	`useSchema` Parse XML validating with XML scheme en lieu de DTD.
`boolean`	`validating` Parse XML validating.

Constructor Summary

Constructors
Constructor and Description

XMLconf()
Make with standard settings.

XMLconf(PropMap prop)
Make with settings from a PropMap.

Constructors
Constructor and Description
`XMLconf()` Make with standard settings.
`XMLconf(PropMap prop)` Make with settings from a PropMap.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`StringBuilder`	`appendProxy(StringBuilder bastel)` Append host and port as text.
`String`	`getIndent()` Indentation of the XML text output.
`int`	`getIndentSize()` Indentation of the XML text output.
`String`	`getProxyHost()` Name of the proxy server for fetching from URL.
`String`	`getProxyPort()` Port of the proxy server for fetching from URL.
`String`	`getSchemaSource()` Name of a local schema.
`boolean`	`isProxySet()` Use a proxy server when fetching from URL.
`DocumentBuilder`	`makeDocumentBuilder(ParseErrorHandler dbeh)` Make a DocumentBuilder.
`InputSource`	`makeInputSource(CharSequence fileOrURL)` Make a XML input.
`StreamSource`	`makeStreamSource(CharSequence fileOrURL)` Make a XML input.
`Transformer`	`makeTransformer(Source transI)` Make a XML style sheet transformer.
`XMLReader`	`makeXMLReader(ContentHandler cnth, ErrorHandler dbeh)` Make a XML parser / reader.
`XMLReader`	`makeXMLReader(SAXHandler handler)` Make a XML reader / SAX parser.
`void`	`set(PropMap prop)` Set the properties by a PropMap object.
`void`	`setClearDefAtts(boolean clearDefAtts)` Standard setter for `clearDefAtts`.
`void`	`setCoalescing(boolean coalescing)` Standard setter for `coalescing`.
`void`	`setEncoding(String encoding)` Set the coding of the XML text (input and) output.
`void`	`setExpandEmptyElements(boolean expandEmptyElements)` Standard setter for `expandEmptyElements`.
`void`	`setExpandEntityReferences(boolean expandEntityReferences)` Standard setter for `expandEntityReferences`.
`void`	`setIgnoreComments(boolean ignoreComments)` Standard setter for `ignoreComments`.
`void`	`setIgnoreWhiteSpace(boolean ignoreWhiteSpace)` Set `ignoreWhiteSpace`.
`void`	`setImpEncoding(String impEncoding)` Set the coding of the XML text input.
`void`	`setIndent(String indent)` Set the indentation String.
`void`	`setIndentSize(int indentSize)` Set the indentation length.
`void`	`setNamespaceAware(boolean namespaceAware)` Standard setter for `namespaceAware`.
`void`	`setNewlines(boolean newlines)` Standard setter for `newlines`.
`void`	`setOmitDeclaration(boolean omitDeclaration)` Standard setter for `omitDeclaration`.
`void`	`setOmitEncoding(boolean omitEncoding)` Standard setter for `omitEncoding`.
`void`	`setProxyHost(CharSequence proxyHost)` Set the name of the proxy server for fetching from URL.
`void`	`setProxyPort(CharSequence proxyPort)` Set the port of the proxy server for fetching from URL.
`void`	`setProxySet(boolean proxySet)` Use a proxy server when fetching from URL.
`void`	`setSchemaSource(String schemaSource)` Set the name of a local schema.
`void`	`setTextNormalize(boolean textNormalize)` Standard setter for `textNormalize`.
`void`	`setUseSchema(boolean useSchema)` Set parse XML validating with XML scheme en lieu de DTD.
`void`	`setValidating(boolean validating)` Set validating XML parsing.
`void`	`simplifyInput()` Settings for simplified, non checking input.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - proxyHost
```
protected String proxyHost
```
    Name of the proxy server for fetching from URL.
    
    See Also:
    
    getProxyHost()
  - proxyPort
```
protected String proxyPort
```
    Port of the proxy server for fetching from URL.
    
    See Also:
    
    getProxyPort()
  - validating
```
public boolean validating
```
    Parse XML validating.
    
    If true a "valide" XML input will be required. Non valid inputs will lead to error reports, but will not in every case impede the generating of a DOM document.
    
    default: true
  - namespaceAware
```
public boolean namespaceAware
```
    Parse XML with XML namespace support.
    
    If true a XML parser with namespace support will be made and used.
    
    default: false
  - useSchema
```
public boolean useSchema
```
    Parse XML validating with XML scheme en lieu de DTD.
    
    default: false
  - ignoreWhiteSpace
```
public boolean ignoreWhiteSpace
```
    Ignore white space.
    
    DOM-Name: ignoringElementWhiteSpaceContent
    validating has to be true on most XML implementations if ignoreWhiteSpace respectively ignoringElementWhiteSpaceContent is true.
    
    default: false
  - expandEntityReferences
```
public boolean expandEntityReferences
```
    Replace references.
    
    default: false
  - coalescing
```
public boolean coalescing
```
    Unite character data in a text node.
    
    default: false
  - ignoreComments
```
public boolean ignoreComments
```
    Delete comments.
    
    default: false
  - clearDefAtts
```
public boolean clearDefAtts
```
    Delete HTML default attributes before output.
    
    In case of true the default attributes of some standard HTML elements like clear="none" for <br /> and others will be removed.
    
    The complete list and the rationale is given at the method clearHTMLdefAtts(Element).
    
    default: false
  - impEncoding
```
public String impEncoding
```
    Coding of the XML text input.
    
    The coding will be used for input.
    
    default: ISO-8859-1
  - encoding
```
public String encoding
```
    Coding of the XML text output.
    
    The coding will be used for the output and for a generated declaration of encoding (if omitEncoding is not true).
    
    default: ISO-8859-1
  - omitDeclaration
```
public boolean omitDeclaration
```
    Declare XML coding in the XML output text.
    
    In case of false a XML declaration will prepend the output.
    W3C calls this property omit-xml-declaration.
    
    default: false
  - newlines
```
public boolean newlines
```
    Output line feeds with the XML text output.
    
    In the case of false line feeds will not be output (compact output).
    
    default: true
  - omitEncoding
```
public boolean omitEncoding
```
    Declare the coding with the XML text output.
    
    In the case of false the coding will be declared at the beginning of a XML output.
    
    default: false
  - textNormalize
```
public boolean textNormalize
```
    Compact the XML text output.
    
    In case of true the XML output will get just one space for any sequence of consecutive white spaces.
    In case of false the white spaces in the input will be preserved.
    
    default: false
  - expandEmptyElements
```
public boolean expandEmptyElements
```
    Expand empty elements on the XML text output.
    
    In case of true the XML output will get a pair of tags (start and end tag) for every empty tag. In that case, for example, <br /> would become <br></br>.
    
    default: false
- Constructor Detail
  - XMLconf
```
public XMLconf()
```
    Make with standard settings.
    
    An XMLconf object with standard / default properties is made.
    
    See Also:
    
    XMLconf(PropMap), set(PropMap), simplifyInput()
  - XMLconf
```
public XMLconf(PropMap prop)
```
    Make with settings from a PropMap.
    
    An XMLconf object with properties set by prop is
    
    Parameters:
    
    prop - stating properties; null means default settings
    
    See Also:
    
    set(PropMap), simplifyInput()
- Method Detail
  - set
```
public void set(PropMap prop)
```
    Set the properties by a PropMap object.
    
    The properties and criteria of this XMLconf object will be set according to the PropMap object prop.
    Input- and parser properties:
    - proxyHost
    - proxyPort
    - proxySet (1)
    - validating
    - useSchema
    - schemaSource
    - namespaceAware
    - ignoreWhiteSpace respectively ignoringElementWhiteSpaceContent
    - expandEntityReferences
    - coalescing
    - ignoreComments
    - impEncoding
    Transformer properties:
    - clearDefAtts
    - textNormalize
    Output properties:
    - encoding
    - omitDeclaration respectively omit-xml-declaration
    - indentSize (2)
    - indent (3)
    - omitEncoding (4)
    - newlines (4)
    - expandEmptyElements (4)
    Is one of these properties not contained in prop nothing happens in each case.
    If more than two names are available for the same property they will be looked for in prop in the order given. The first name given above is the property name within XMLdoc.
    
    Remark (1): The proxy settings will be evaluated in the order shown (compare setProxySet()).
    Remark 2: methods of this class set the DOM filter property indent as indentSize > 0 ? yes : no.
    Remark 3: Setting the property indentSize (0..18) sets indent as String containing the respective number of space; setting the Strings indent to null or with a length in the range 0..18, sets indentSize accordingly.
    Parameters:
    
    prop - source of the properties to be used
    
    See Also:
    
    XMLconf(PropMap), simplifyInput()
  - simplifyInput
```
public void simplifyInput()
```
    Settings for simplified, non checking input.
    
    This method sets coalescing, ignoreComments as well as ignoreWhiteSpace true and sets namespaceAware and validating false.
    
    See Also:
    
    set(PropMap)
  - isProxySet
```
public boolean isProxySet()
```
    Use a proxy server when fetching from URL.
    
    If true a proxy will be used and the properties proxyHost and proxyHost are effective.
    
    Returns:
    
    true if a proxy is to be used (default: false)
  - setProxySet
```
public void setProxySet(boolean proxySet)
```
    Use a proxy server when fetching from URL.
    
    If true a proxy will be used and the properties proxyHost and proxyHost are effective.
    
    If this method changes the previous setting the respective system properties will be set accordingly.
    
    This method setProxySet() has to be called after setProyHost() and setProyPort(), to make the changes effective. (If using makeInputSource() one doesn't have to bother a this method does it right by itself.)
    
    Parameters:
    
    proxySet - true if a proxy is to be used.
  - getProxyHost
```
public String getProxyHost()
```
    Name of the proxy server for fetching from URL.
    
    default: "e;cache"e;
    
    Returns:
    
    the proxy server
    
    See Also:
    
    proxySet
  - setProxyHost
```
public void setProxyHost(CharSequence proxyHost)
```
    Set the name of the proxy server for fetching from URL.
    
    The parameter proxyHost will be stripped from surrounding white space; empty will be taken as null.
    
    A change of the property prooxyHost or proxyPort will only be effective after calling setProxySet(true).
    
    Parameters:
    
    proxyHost - the proxy server
    
    See Also:
    
    getProxyHost()
  - getProxyPort
```
public String getProxyPort()
```
    Port of the proxy server for fetching from URL.
    
    default: 8080
    
    Returns:
    
    the proxy port
    
    See Also:
    
    proxySet
  - setProxyPort
```
public void setProxyPort(CharSequence proxyPort)
```
    Set the port of the proxy server for fetching from URL.
    
    The parameter proxyPort will be stripped from surrounding white space; empty will be taken as null.
    
    A change of the property prooxyHost or proxyPort will only be effective after calling setProxySet(true).
    
    Parameters:
    
    proxyPort - the proxy port (a number as String)
    
    See Also:
    
    getProxyPort()
  - appendProxy
```
public StringBuilder appendProxy(StringBuilder bastel)
```
    Append host and port as text.
    
    According to the properties proxySet, proxyHost and proxyPort to bastel is appended either "no proxy" or "proxy host = cache, port = 8080" (e.g. the default).
    
    Parameters:
    
    bastel - the StringBuilder to append to; if null it will be made with starting capacity 80 character
    
    Returns:
    
    bastel
  - setValidating
```
public final void setValidating(boolean validating)
```
    Set validating XML parsing.
    
    Parameters:
    
    validating - true if XML parsing should be validating (requires schema or documentation type)
  - setUseSchema
```
public final void setUseSchema(boolean useSchema)
```
    Set parse XML validating with XML scheme en lieu de DTD.
    
    Parameters:
    
    useSchema - true means a schema and not a DTD is to be used for validating
  - getSchemaSource
```
public final String getSchemaSource()
```
    Name of a local schema.
    
    It is either not empty or null.
    In case of useSchema true it will be taken as the name of a local schema file for schema validation.
    
    Returns:
    
    a schema file name
  - setSchemaSource
```
public void setSchemaSource(String schemaSource)
```
    Set the name of a local schema.
    
    If schemaSource stripped from surrounding white space is not empty it will be used as new local source (file) of a schema. Otherwise the property schemaSource will be set null.
    
    Parameters:
    
    schemaSource - a schema file name
    
    See Also:
    
    TextHelper.trimUq(CharSequence, String)
  - setImpEncoding
```
public void setImpEncoding(String impEncoding)
```
    Set the coding of the XML text input.
    
    The parameter encoding will be stripped from surrounding white spaces and then used to set impEncoding.
    
    null or empty will be taken as ComVar.FILE_ENCODING.
    
    Parameters:
    
    impEncoding - the encoding for XML input
  - setEncoding
```
public void setEncoding(String encoding)
```
    Set the coding of the XML text (input and) output.
    
    The parameter encoding will be stripped from surrounding white spaces and then used to set encoding.
    
    null or empty will be taken as ISO-8859-1.
    
    Parameters:
    
    encoding - the encoding for XML input and output
  - getIndent
```
public String getIndent()
```
    Indentation of the XML text output.
    
    The String indent respectively indentSize spaces will be used for the indentation according to the block structure.
    
    Allowed: A String of length 0..18 or null
    default: null
    
    Returns:
    
    an indentation string or null
  - setIndent
```
public void setIndent(String indent)
```
    Set the indentation String.
    
    Parameters:
    
    indent - an indentation string or null
    
    See Also:
    
    getIndent(), getIndentSize()
  - getIndentSize
```
public int getIndentSize()
```
    Indentation of the XML text output.
    
    The String indent respectively indentSize spaces will be used for the indentation according to the block structure.
    
    Allowed range: 0..18
    default: 0
    
    Returns:
    
    the indentation size (number of spaces)
  - setIndentSize
```
public void setIndentSize(int indentSize)
```
    Set the indentation length.
    
    Parameters:
    
    indentSize - new indentation length 0..18;
    other values will not change the previous setting
    
    See Also:
    
    getIndent(), getIndentSize()
  - setClearDefAtts
```
public void setClearDefAtts(boolean clearDefAtts)
```
    Standard setter for clearDefAtts.
    
    Parameters:
    
    clearDefAtts - true means delete HTML default attributes before output
  - setExpandEmptyElements
```
public void setExpandEmptyElements(boolean expandEmptyElements)
```
    Standard setter for expandEmptyElements.
    
    Parameters:
    
    expandEmptyElements - true means expand respectively auto-close empty elements on the XML text output
  - setNamespaceAware
```
public void setNamespaceAware(boolean namespaceAware)
```
    Standard setter for namespaceAware.
    
    Parameters:
    
    namespaceAware - true means be aware of namespaces
  - setNewlines
```
public void setNewlines(boolean newlines)
```
    Standard setter for newlines.
    
    Parameters:
    
    newlines - true means output line feeds with the XML text output
  - setOmitDeclaration
```
public void setOmitDeclaration(boolean omitDeclaration)
```
    Standard setter for omitDeclaration.
    
    Parameters:
    
    omitDeclaration - false means a XML declaration will prepend the output
  - setOmitEncoding
```
public void setOmitEncoding(boolean omitEncoding)
```
    Standard setter for omitEncoding.
    
    Parameters:
    
    omitEncoding - true means declare the coding with the XML text output
  - setTextNormalize
```
public void setTextNormalize(boolean textNormalize)
```
    Standard setter for textNormalize.
    
    Parameters:
    
    textNormalize - true means make a compact XML text output
  - setCoalescing
```
public final void setCoalescing(boolean coalescing)
```
    Standard setter for coalescing.
    
    Parameters:
    
    coalescing - see coalescing
  - setExpandEntityReferences
```
public void setExpandEntityReferences(boolean expandEntityReferences)
```
    Standard setter for expandEntityReferences.
    
    Parameters:
    
    expandEntityReferences - expandEntityReferences
  - setIgnoreComments
```
public final void setIgnoreComments(boolean ignoreComments)
```
    Standard setter for ignoreComments.
    
    Parameters:
    
    ignoreComments - ignoreComments
  - setIgnoreWhiteSpace
```
public final void setIgnoreWhiteSpace(boolean ignoreWhiteSpace)
```
    Set ignoreWhiteSpace.
    
    Parameters:
    
    ignoreWhiteSpace - ignoreWhiteSpace
  - makeXMLReader
```
public XMLReader makeXMLReader(ContentHandler cnth,
                               ErrorHandler dbeh)
                        throws ParserConfigurationException,
                               SAXException,
                               SAXNotRecognizedException,
                               SAXNotSupportedException
```
    Make a XML parser / reader.
    
    Parameters:
    
    cnth - a ContentHandler if given; may here be null, but a SAX parser without ContentHandler makes no sense in most cases
    
    dbeh - ErrorHandler, for example a ParseErrorHandler object; may be null
    
    Returns:
    
    the SAXParser as XMLReader
    
    Throws:
    
    ParserConfigurationException - if a SAXparser with the basic properties (namespace, validating) set in this XMLconf object can't be made
    
    SAXException - the rest of the errors (its the enclosing type) while making the internal SAXParser or the XMLReader
    
    SAXNotRecognizedException - if the XMLReader made does not honour a property to be set, like for example MLHelper.JAXP_SCHEMA_LANGUAGE
    
    SAXNotSupportedException - if the XMLReader made does know / recognise a property to be set, but won't accept the value, like e.g. for MLHelper.W3C_XML_SCHEMA
  - makeXMLReader
```
public XMLReader makeXMLReader(SAXHandler handler)
                        throws ParserConfigurationException,
                               SAXException,
                               SAXNotRecognizedException,
                               SAXNotSupportedException
```
    Make a XML reader / SAX parser.
    
    The call is equivalent to
    makeXMLReader(handler, handler).
    
    Parameters:
    
    handler - ContentHandler and ErrorHandler in one object — supplied as an inheritor of SAXHandler; may be null, even if that does not make any sense in virtually all cases
    
    Returns:
    
    the SAXParser as XMLReader
    
    Throws:
    
    ParserConfigurationException - if a SAXparser with the basic properties (namespace, validating) set in this XMLconf object can't be made
    
    SAXException - the rest of the errors (its the enclosing type) while making the internal SAXParser or the XMLReader
    
    SAXNotRecognizedException - if the XMLReader made does not honour a property to be set, like for example MLHelper.JAXP_SCHEMA_LANGUAGE
    
    SAXNotSupportedException - if the XMLReader made does know / recognise a property to be set, but won't accept the value, like e.g. for MLHelper.W3C_XML_SCHEMA
  - makeDocumentBuilder
```
public DocumentBuilder makeDocumentBuilder(ParseErrorHandler dbeh)
                                    throws FactoryConfigurationError,
                                           IllegalArgumentException,
                                           ParserConfigurationException
```
    Make a DocumentBuilder.
    
    Parameters:
    
    dbeh - ErrorHandler, e.g. a ParseErrorHandler-Objekt; may be null
    
    Returns:
    
    the DocumentBuilder
    
    Throws:
    
    FactoryConfigurationError - forwarded
    
    ParserConfigurationException - if a DocumentBuilder with the basic properties (namespace, validating) set in this XMLconf object can't be made
    
    IllegalArgumentException - if a property to be set, that is not known by the SAX/DOM implementation, like for example MLHelper.JAXP_SCHEMA_LANGUAGE
  - makeStreamSource
```
public StreamSource makeStreamSource(CharSequence fileOrURL)
                              throws IllegalArgumentException,
                                     IOException
```
    Make a XML input.
    
    Relevant e properties: impEncoding, proxySet, proxyHost and proxyPort.
    
    Parameters:
    
    fileOrURL - denotation of the input
    
    Returns:
    
    XML input object as a Source
    
    Throws:
    
    IllegalArgumentException - if fileOrURL null or empty
    
    IOException - on problems making the Source
  - makeInputSource
```
public InputSource makeInputSource(CharSequence fileOrURL)
                            throws IllegalArgumentException,
                                   IOException
```
    Make a XML input.
    
    Relevant e properties: impEncoding, proxySet, proxyHost and proxyPort.
    
    Parameters:
    
    fileOrURL - denotation of the input
    
    Returns:
    
    XML input object as an InputSource object
    
    Throws:
    
    IllegalArgumentException - if fileOrURL null or empty
    
    IOException - on problems making the Input
  - makeTransformer
```
public Transformer makeTransformer(Source transI)
                            throws IllegalArgumentException,
                                   TransformerConfigurationException
```
    Make a XML style sheet transformer.
    
    Relevant properties: encoding, indentSize >0, omitDeclaration
    
    Parameters:
    
    transI - input source, like for example one made by makeInputSource(CharSequence)
    
    Returns:
    
    XML style sheet transformer
    
    Throws:
    
    IllegalArgumentException - if transI is null
    
    TransformerConfigurationException - on problems setting relevant properties

Class XMLconf

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

proxyHost

proxyPort

validating

namespaceAware

useSchema

ignoreWhiteSpace

expandEntityReferences

coalescing

ignoreComments

clearDefAtts

impEncoding

encoding

omitDeclaration

newlines

omitEncoding

textNormalize

expandEmptyElements

Constructor Detail

XMLconf

XMLconf

Method Detail

set

simplifyInput

isProxySet

setProxySet

getProxyHost

setProxyHost

getProxyPort

setProxyPort

appendProxy

setValidating

setUseSchema

getSchemaSource

setSchemaSource

setImpEncoding

setEncoding

getIndent

setIndent

getIndentSize

setIndentSize

setClearDefAtts

setExpandEmptyElements

setNamespaceAware

setNewlines

setOmitDeclaration

setOmitEncoding

setTextNormalize

setCoalescing

setExpandEntityReferences

setIgnoreComments

setIgnoreWhiteSpace

makeXMLReader

makeXMLReader

makeDocumentBuilder

makeStreamSource

makeInputSource

makeTransformer