org.vishia.xmlReader

Class XmlJzReader

java.lang.Object

org.vishia.xmlReader.XmlJzReader

public class XmlJzReader
extends java.lang.Object

This is the main class to read an XML file with a given configuration file, store data in a Java instance via reflection paths given in the config.xml. A configuration file, written in XML too, contains the data path for the XML elements which should be stored in Java data. A main method does not exists because it is only proper to invoke the read routine inside a Java application.
Application example:

 XmlJzReader xmlReader = new XmlJzReader(); //instance to work, more as one file one after another
 xmlJzReader.readCfg(cfgFile);             //configuration for next xmlRead()
 AnyClass data = new AnyClass();        //a proper output instance matching to the cfg
 xmlReader.readXml(xmlInputFile, data); //reads the xml file and stores read data.
 

The configuration file contains the template of the xml file with paths to store the content in a proper user instance The paths is processed with DataAccess.DatapathElement. The configuration is hold in an instance of XmlCfg. Detail description of the config file see XmlCfg.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
(package private) static class	XmlJzReader.AttribToStore

Field Summary

Fields

Modifier and Type	Field and Description
(package private) XmlCfg	cfg To store the last used configuration, for parsing with the same config.
(package private) XmlCfg	cfgCfg Configuration to read a config file.
(package private) int	debugStopLine
(package private) java.lang.String	debugTag
(package private) java.util.Map<java.lang.String,java.lang.String>	namespaces Assignment between nameSpace-alias and nameSpace-value gotten from the xmlns:ns="value" declaration in the read XML file.
private java.util.Map<java.lang.String,java.lang.String>	replaceChars
(package private) int	sizeBuffer Size of the buffer to hold a part of the xml input file.
static java.lang.String	version Version, License and History: 2023-05-23: Now all text content parts are stored immediately after its parsing, and NOT as a whole.
(package private) XmlSequWriter	xmlTestWriter

Constructor Summary

Constructors

Constructor and Description
XmlJzReader()

Method Summary

Modifier and Type	Method and Description
private void	errMsg(int nr, StringPartScan inp, java.lang.CharSequence... txt)
(package private) void	finishElement(java.lang.Object parent, java.lang.Object element, DataAccess.DatapathElement elementStorePath) This op is called on finishing of parsing a element with its sub content.
(package private) java.lang.Object	getDataForTheElement(java.lang.Object output, DataAccess.DatapathElement elementStorePath, java.lang.String[] attribValues) Invokes the associated method to get/create the appropriate data instance for the element.
void	openXmlTestOut(java.io.File fout) Writes the parsed content without processing in this file.
private java.lang.CharSequence	parseAttributes(StringPartScan inp, java.lang.CharSequence tag, XmlCfg.XmlCfgNode cfgNode, java.util.List<XmlJzReader.AttribToStore>[] attribsToStore, java.util.List<XmlJzReader.AttribToStore>[] namespacesToStore, java.util.Map<java.lang.String,DataAccess.IntegerIx>[] attribNames, java.lang.String[] attribValues)
private java.lang.CharSequence	parseContent(StringPartScan inp, java.lang.StringBuilder buffer) Reads the textual content of an element.
private void	parseElement(StringPartScan inp, java.lang.Object output, XmlCfg.XmlCfgNode cfgNode) Parse a whole element with all inner content
XmlCfg	readCfg(java.io.File file) Read the configuration file for this instance.
XmlCfg	readCfgFromJar(java.lang.Class<?> clazz, java.lang.String pathInJarFromClazz) Read from a resource (file inside jar archive).
java.lang.String	readXml(java.io.File file, java.lang.Object dst)
java.lang.String	readXml(java.io.File input, java.lang.Object output, XmlCfg xmlCfg) Reads an xml file with a given config.
java.lang.String	readXml(java.io.InputStream stream, java.lang.String sInputPath, java.lang.Object dst)
java.lang.String	readXml(java.io.InputStream input, java.lang.String sInputPath, java.lang.Object output, XmlCfg xmlCfg) Reads the xml content from an opened stream.
java.lang.String	readXml(java.io.Reader stream, java.lang.String sInputPath, java.lang.Object dst)
java.lang.String	readXml(java.io.Reader input, java.lang.String sInputPath, java.lang.Object output, XmlCfg xmlCfg) Reads the xml content from an opened stream.
void	readXml(StringPartScan input, java.lang.Object output) Reads the xml content from an StringPart.
void	readXml(StringPartScan inp, java.lang.Object output, XmlCfg xmlCfg) Core routine to read in whole XML stream.
java.lang.String	readZipXml(java.io.File zipInput, java.lang.String pathInZip, java.lang.Object output) Reads an xml File from a zipfile.
private java.lang.CharSequence	replaceSpecialCharsInText(java.lang.CharSequence src) Replaces the basic sequences &lt; etc. and the UTF 16 <#xaaaa; and replaces line feed with indent with one space.
void	setCfg(XmlCfg cfg) Set the CmlCfg with a Java-given structure, especially for config reading.
void	setDebugStop(int line) Only for internal debug.
void	setDebugStopTag(java.lang.String stag)
void	setNamespaceEntry(java.lang.String key, java.lang.String url) This operation is only necessary if a name space declaration is missing in the xml file to read.
(package private) void	storeAttrData(StringPartScan inp, java.lang.Object output, DataAccess.DatapathElement dstPath, java.util.Map<java.lang.String,DataAccess.IntegerIx> attribNames, java.lang.CharSequence sAttrName, java.lang.CharSequence sAttrValue, java.lang.String sTag) Invokes the associated method to store the attribute value.
private static void	storeContent(java.lang.StringBuilder buffer, XmlCfg.XmlCfgNode cfgNode, java.lang.Object output, java.util.Map<java.lang.String,DataAccess.IntegerIx>[] attribs, java.lang.String[] attribValues)

Methods inherited from class java.lang.Object

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

Field Detail

version

public static final java.lang.String version

Version, License and History:

• 2023-05-23: Now all text content parts are stored immediately after its parsing, and NOT as a whole. The last one is faulty if the text is mixed with some more order relevant content. Especially formatted text. This is detected and used while parsing Libre Office files (odg).
• 2023-05-23: same as newline characters now also in parseContent(StringPartScan, StringBuilder)
• 2023-05-02: chg: newline characters after and before text: Then all white spaces after and before text are removed. If a newline char does not appear, nothing is removed. spaces on start or end are admissible. Then the XML file should not do beautification and should not contain newline characters there. If a newline character is necessary in text content, the etc. should be used. Changed in storeContent(StringBuilder, org.vishia.xmlReader.XmlCfg.XmlCfgNode, Object, Map[], String[]).
• 2022-06-25: chg: in storeContent(StringBuilder, org.vishia.xmlReader.XmlCfg.XmlCfgNode, Object, Map[], String[]): the DataAccess.invokeMethod(org.vishia.util.DataAccess.DatapathElement, Class, Object, boolean, Object[], boolean) was called with true for non exception, that is faulty. To detect writing errors in the xmlcfg file, exceptions are necessary.
• 2022-06-23: "xmlinput:finish" regarded, see finishElement(Object, Object, org.vishia.util.DataAccess.DatapathElement)
• 2022-06-06: new setNamespaceEntry(String, String)
• 2021-12-16 documentation and fine tuning of storeAttrData(..). Now usage of value is not tested. If the operation for an attribute in cfg returns a #Field then the value is stored in this return field independent whether it is used also as argument. This can be helpfully and it is a special condition lesser.
• 2021-10-18 new: in storeAttrData(StringPartScan, Object, org.vishia.util.DataAccess.DatapathElement, Map, CharSequence, CharSequence, String) In the Xmlcfg file now you can use "tag" as attribute value for a xmlinput:data="!CREATE_OPER(..., tag, ...) now. Additionally: If the attr="!OPERATION(?)" does not use "value" as argument and it returns a java.lang.reflect.Field then this field is used to store the attribute value, as also for a simple expression.
• 2021-10-18 improved: The readCfg(File) and readCfgFromJar(Class, String) produces now a new instance of XmlCfg data. Before the read cfg data are written in the given instance of cfg which means, immediately able to use, but the older instance was destroyed. This new version is compatible with the old one (both activates updates the cfg), but now the reference to a older read config remain valid and can be reused for the now public readXml(File, Object, XmlCfg). It means some XmlCfg can be present and use for different reading approaches with the same XmlJzReader. You can switch between config. This change was done primary because the older implementation was not really good able to document. The older approach was firstly done to save memory space (prevent new instances). But this is not true because the Garbage Collector does its work if necessary.
• 2021-10-07 new storeAttrData(StringPartScan, Object, org.vishia.util.DataAccess.DatapathElement, Map, CharSequence, CharSequence, String) gets inp as info only for a better error msg.
• 2021-10-07 new in parseElement(StringPartScan, Object, org.vishia.xmlReader.XmlCfg.XmlCfgNode) stores also a namespace definition in user data if required. See cfg.
• 2021-10-07 new errMsg(int, StringPartScan, CharSequence...) as central routine if problems occur.
• 2021-10-07 formally change: General using TreeMap (java.util) instead the specific IndexMultiTable, same functionality
• 2020-06-28 Hartmut new now supports <![CDATA[ ... ]]>
• 2020-02-12 Hartmut new readXml(Reader, String, Object) and readXml(StringPartScan, Object)
• 2020-01-15 Hartmut Improve handling of &#code characters.
• 2020-01-01 Hartmut Exception on file errors.
• 2019-12-30 Hartmut Using XmlSequWriter for Test output the read content, if openXmlTestOut(File) is invoked. .
• 2019-08-19 Hartmut full support of text special sequences.
• 2019-08-10 Hartmut refactoring of DataAccess, handling of arguments on access routines changed.
• 2019-05-29 Now skips over <!DOCTYPE....>
• 2018-09-09 Renamed from XmlReader to XmlJzReader, because: It is a special reader. It stores Data to Java (J) and works with a configfile which has a semantic (z as reverse 's').
• 2017-12-25 first version which can be used.
• 2017-01 created.

Copyright/Copyleft: For this source the LGPL Lesser General Public License, published by the Free Software Foundation is valid. It means:

1. You can use this source without any restriction for any desired purpose.
2. You can redistribute copies of this source to everybody.
3. Every user of this source, also the user of redistribute copies with or without payment, must accept this license for further using.
4. But the LPGL is not appropriate for a whole software product, if this source is only a part of them. It means, the user must publish this part of source, but don't need to publish the whole source of the own product.
5. You can study and modify (improve) this source for own using or for redistribution, but you have to license the modified sources likewise under this LGPL Lesser General Public License. You mustn't delete this Copyright/Copyleft inscription in this source file.

If you are intent to use this sources without publishing its usage, you can get a second license subscribing a special contract with the author.

See Also:

Constant Field Values

cfg

XmlCfg cfg

To store the last used configuration, for parsing with the same config.

cfgCfg

final XmlCfg cfgCfg

Configuration to read a config file.

sizeBuffer

int sizeBuffer

Size of the buffer to hold a part of the xml input file. It should be enough large to hold 1 element with attributes (without content). On 2/3 of the buffer it is reloaded. It means the most length of an attribute should be < sizeBuffer/3. Note that sometimes attributes are very long. Maximum size is 16 MByte.

debugStopLine

int debugStopLine

debugTag

java.lang.String debugTag

namespaces

java.util.Map<java.lang.String,java.lang.String> namespaces

Assignment between nameSpace-alias and nameSpace-value gotten from the xmlns:ns="value" declaration in the read XML file.

replaceChars

private final java.util.Map<java.lang.String,java.lang.String> replaceChars

xmlTestWriter

XmlSequWriter xmlTestWriter

Constructor Detail

XmlJzReader

public XmlJzReader()

Method Detail

setDebugStop

public void setDebugStop(int line)

Only for internal debug. See implementation. There is a possibility to set a break point if the parser reaches the line.

Parameters:

line -

setDebugStopTag

public void setDebugStopTag(java.lang.String stag)

openXmlTestOut

public void openXmlTestOut(java.io.File fout)
                    throws java.io.IOException

Writes the parsed content without processing in this file. The writing regards indents for any node, so that a beautification is gotten for the content. That is the important application of this functionality. The call of this operation opens the xmlTestWriter. It is closed on end of JZtxtReader. It means this operation should be called immediately before call of readXml(File, Object) or also readCfg(File) and all its abbreviations. It should not be called without a read Xml invocation because otherwise the resource remains open.

Parameters:

fout - File to write

Throws:

java.io.IOException - if open fails

setNamespaceEntry

public void setNamespaceEntry(java.lang.String key,
                              java.lang.String url)

This operation is only necessary if a name space declaration is missing in the xml file to read. It should be called before reading.

Parameters:

key -

url -

readXml

public java.lang.String readXml(java.io.File input,
                                java.lang.Object output,
                                XmlCfg xmlCfg)
                         throws java.io.IOException

Reads an xml file with a given config. It does not change the stored config which is gotten by readCfg(File) or #readCfgFromJar(String). This operation is used internally in for all read operations too. It is the common entry to read.

Parameters:

input - The xml file

output - The empty data where the first operation is called or the first data are stored via reflection.

xmlCfg - Already read XmlCfg from a file using {readCfg(File)} or readCfgFromJar(Class, String) or alternatively a immediate prepared XmlCfg.

• For reading the config file itself it is XmlCfg.newCfgCfg().
• For storing to a XmlNodeSimple it is
• Also a user can prepare a XmlCfg by himself.

Returns:

Throws:

java.io.IOException

readZipXml

public java.lang.String readZipXml(java.io.File zipInput,
                                   java.lang.String pathInZip,
                                   java.lang.Object output)

Reads an xml File from a zipfile. It uses the given config. Either #readXmlCfg(File) was invoked before or the config will be read itself (with cfgCfg as configuration).

Parameters:

zipInput - The zipfile itself

pathInZip - The path of a file inside the zip file

output - destination data

Returns:

readXml

public java.lang.String readXml(java.io.InputStream input,
                                java.lang.String sInputPath,
                                java.lang.Object output,
                                XmlCfg xmlCfg)

Reads the xml content from an opened stream. The stream is firstly tested whether the first line contains a encoding hint. This is obligate in XML. Then the input is read into a character buffer using the StringPartScan class. The StringPartScan scans the XML syntax.
The xmlCfg determines which elements, attributes and textual content is transferred to the output data. See Description of XmlJzReader.

Parameters:

input - any opened InputStream. Typically it is an FileInputStream or InputStream from a ZipEntry.

sInputPath - The path to the input stream, used for error hints while parsing.

output - Any output data. The structure should match to the xmlCfg.

xmlCfg - A configuration. It can be gotten via readCfg(File).

Returns:

null if no error. Elsewhere an error message, instead of throwing.

readXml

public void readXml(StringPartScan input,
                    java.lang.Object output)
             throws java.lang.Exception

Reads the xml content from an StringPart. The stream is firstly tested whether the first line contains a encoding hint. This is obligate in XML. Then the input is read into a character buffer using the StringPartScan class. The StringPartScan scans the XML syntax.
The xmlCfg determines which elements, attributes and textual content is transferred to the output data. See Description of XmlJzReader.

Parameters:

input - any opened InputStream. Typically it is an FileInputStream or InputStream from a ZipEntry.

sInputPath - The path to the input stream, used for error hints while parsing.

output - Any output data. The structure should match to the xmlCfg.

xmlCfg - A configuration. It can be gotten via readCfg(File).

Throws:

java.lang.Exception

readXml

public java.lang.String readXml(java.io.Reader input,
                                java.lang.String sInputPath,
                                java.lang.Object output,
                                XmlCfg xmlCfg)

Reads the xml content from an opened stream. The stream is firstly tested whether the first line contains a encoding hint. This is obligate in XML. Then the input is read into a character buffer using the StringPartScan class. The StringPartScan scans the XML syntax.
The xmlCfg determines which elements, attributes and textual content is transferred to the output data. See Description of XmlJzReader.

Parameters:

input - any opened InputStream. Typically it is an FileInputStream or InputStream from a ZipEntry.

sInputPath - The path to the input stream, used for error hints while parsing.

output - Any output data. The structure should match to the xmlCfg.

xmlCfg - A configuration. It can be gotten via readCfg(File).

Returns:

null if no error. Elsewhere an error message, instead of throwing.

readXml

public void readXml(StringPartScan inp,
                    java.lang.Object output,
                    XmlCfg xmlCfg)
             throws java.lang.Exception

Core routine to read in whole XML stream.

Parameters:

inp - A StringPartScan can be built from a String too, using StringPart.assign(CharSequence). for file reading the constructor StringPartFromFileLines.StringPartFromFileLines(File) is used.

output - the data to store the read content. Should match to the root instance in the cfg file.

xmlCfg - The used configuration (it does not access the cfg if the instance, may call with cfg.

Throws:

java.lang.Exception

parseElement

private void parseElement(StringPartScan inp,
                          java.lang.Object output,
                          XmlCfg.XmlCfgNode cfgNode)
                   throws java.lang.Exception

Parse a whole element with all inner content

Parameters:

inp - scanOk-Position after the "<" before the identifier.

output -

cfg1 -

Throws:

java.lang.Exception

parseAttributes

private java.lang.CharSequence parseAttributes(StringPartScan inp,
                                               java.lang.CharSequence tag,
                                               XmlCfg.XmlCfgNode cfgNode,
                                               java.util.List<XmlJzReader.AttribToStore>[] attribsToStore,
                                               java.util.List<XmlJzReader.AttribToStore>[] namespacesToStore,
                                               java.util.Map<java.lang.String,DataAccess.IntegerIx>[] attribNames,
                                               java.lang.String[] attribValues)
                                        throws java.lang.Exception

Parameters:

inp -

tag -

cfgNode -

attribsToStore - [0] maybe given or may be created. If an attribute is found which's XmlCfg.AttribDstCheck.daccess is set, then the attribute with the daccess is stored in [0] to write it in the new created node if this was created after this operation.

namespacesToStore -

attribNames -

attribValues -

Returns:

Throws:

java.lang.Exception

getDataForTheElement

java.lang.Object getDataForTheElement(java.lang.Object output,
                                      DataAccess.DatapathElement elementStorePath,
                                      java.lang.String[] attribValues)

Invokes the associated method to get/create the appropriate data instance for the element.

Parameters:

output - The current output in the parent context

elementStorePath - if null, returns output. Else: The storePath in the XmlCfg.XmlCfgNode

attribValues -

subCfgNode - The cfgNode for the found element

sTag - it is the keyResearch maybe assembled with attribute values, not only the tag name.

Returns:

output if elementStorePath is null, either result of an invoked method via DataAccess or accessed data

Throws:

java.lang.Exception

finishElement

void finishElement(java.lang.Object parent,
                   java.lang.Object element,
                   DataAccess.DatapathElement elementStorePath)

This op is called on finishing of parsing a element with its sub content.

• The "xmlinput:data" delivers the data storage, but need not insert the data storage for this element in the whole data tree.
• The "xmlinput:finish" inserts the data storage (via reference, hold stack local till now) in the whole data tree. Depending from the finish operation the data can be post prepared in any kind. For ZBNF data storage this is the set... operation. It should be named set_... also here.
• If the data does not need to be post-prepared, it is also possible that this operation is not given or empty. But then the "xmlinput:data" should set the reference in the whole data tree already for the new created data. That is the approach till now, furthermore supported.

Parameters:

parent - The element where the content is to insert as sub content.

element - to insert

elementStorePath - rule where to insert: It contains:

• DataAccess.DatapathElement#ident Immediately the name of the variable of operation to call in parent
• DataAccess.DatapathElement#args Arguments, whereas the argument for finish should be usual "value", which is the [1] element in the immediately argument list for the internal called DataAccess.invokeMethod(org.vishia.util.DataAccess.DatapathElement, Class, Object, boolean, Object[], boolean) for the "varValues".

storeAttrData

void storeAttrData(StringPartScan inp,
                   java.lang.Object output,
                   DataAccess.DatapathElement dstPath,
                   java.util.Map<java.lang.String,DataAccess.IntegerIx> attribNames,
                   java.lang.CharSequence sAttrName,
                   java.lang.CharSequence sAttrValue,
                   java.lang.String sTag)

Invokes the associated method to store the attribute value.

• This method is invoked while reading the cfg.xml to store the attribute value with XmlNode#addAttributeStorePath().
• This method is invoked while reading the user.xml to store the users attribute value in the users data.

Parameters:

output - It is an instance of XmlCfgNode while reading the cfg.xml, it is an user instance while reading the user.xml

dstPath - The dataAccess which should be executed.

sAttrNsName -

sAttrValue -

parseContent

private java.lang.CharSequence parseContent(StringPartScan inp,
                                            java.lang.StringBuilder buffer)
                                     throws java.io.IOException,
                                            java.text.ParseException

Reads the textual content of an element. leading and trailing whitespaces are not part of the content. If the content contains a hard coded line feed with &#xa; etc. all textual line feeds and following indents are removed from the text. See replaceSpecialCharsInText(CharSequence)

Parameters:

inp -

buffer - maybe null then ignore content.

Throws:

java.text.ParseException

java.io.IOException

storeContent

private static void storeContent(java.lang.StringBuilder buffer,
                                 XmlCfg.XmlCfgNode cfgNode,
                                 java.lang.Object output,
                                 java.util.Map<java.lang.String,DataAccess.IntegerIx>[] attribs,
                                 java.lang.String[] attribValues)

replaceSpecialCharsInText

private java.lang.CharSequence replaceSpecialCharsInText(java.lang.CharSequence src)
                                                  throws java.text.ParseException

Replaces the basic sequences &lt; etc. and the UTF 16 <#xaaaa; and replaces line feed with indent with one space. Before call of this routine the leading and trailing white spaces are removed alread.

Parameters:

src -

Returns:

src if no such sequences found

Throws:

java.text.ParseException

errMsg

private void errMsg(int nr,
                    StringPartScan inp,
                    java.lang.CharSequence... txt)

readCfg

public XmlCfg readCfg(java.io.File file)
               throws java.io.IOException

Read the configuration file for this instance. The configuration contains how elements of a read xml file are processed and stored.

Parameters:

file - from this file

Returns:

A new XmlCfg instance which is automatically set as referenced and used in cfg. But you can store this reference and used for readXml(File, Object, XmlCfg) later too.

Throws:

java.io.IOException

setCfg

public void setCfg(XmlCfg cfg)

Set the CmlCfg with a Java-given structure, especially for config reading.

Parameters:

cfg -

readCfgFromJar

public XmlCfg readCfgFromJar(java.lang.Class<?> clazz,
                             java.lang.String pathInJarFromClazz)
                      throws java.io.IOException

Read from a resource (file inside jar archive).

Parameters:

clazz - A class in any jar, from there the relative path to the pathInJar is built. Often the clazz should be the output data clazz.

pathInJar - relative Path from clazz. Usually the cfg should be in the same directory as the output data class. Then this is only the file name.

Returns:

A new XmlCfg instance which is automatically set as referenced and used in cfg. But you can store this reference and used for readXml(File, Object, XmlCfg) later too.

Throws:

java.io.IOException

readXml

public java.lang.String readXml(java.io.File file,
                                java.lang.Object dst)
                         throws java.io.IOException

Throws:

java.io.IOException

readXml

public java.lang.String readXml(java.io.InputStream stream,
                                java.lang.String sInputPath,
                                java.lang.Object dst)

readXml

public java.lang.String readXml(java.io.Reader stream,
                                java.lang.String sInputPath,
                                java.lang.Object dst)