org.vishia.xmlReader

Class XmlCfg

java.lang.Object

org.vishia.xmlReader.XmlCfg

public class XmlCfg
extends java.lang.Object

This class contains the configuration data to assign xml elements to Java data. It is filled with the XmlJzReader.readCfg(java.io.File) from a given xml file.
The configuration xml file (config.xml) should have the same structure as the type of xml files to parse (user.xml).

• Basic rule: Any possible element in the user.xml should present as pattern (template) one time in the config.xml. Instead the value of attributes or instead the text in xml nodes a proper data path should be written. The attribute or content value should be start with "!...", after "!" the data path is given. The data path is the reflection access path to the current output instance.

     <tag attr="!storepath" xmlinput:data="!getOrCreateCurrentOutputPath()">!contentStorePath(text) ... <subelements ....
     

• The data path is processed via DataAccess.DataPathElement with invocation of DataAccess.storeValue(org.vishia.util.DataAccess.DatapathElement, Object, Object, boolean) or DataAccess#invokeMethod(org.vishia.util.DataAccess.DatapathElement, Class, Object, boolean, boolean, Object[]).
• If any tag or attribute is found in the user.xml, it is checked whether this tag or attribute is contained in the config.xml. Then the information in the config.xml are used to store the data from the user.xml
• The special attribute xmlinput:data contains the path to get or create the output instance for this element based on the current output instance.
• Whole structure of the config.xml:

    <?xml version="1.0" encoding="utf-8"?>
    <xmlinput:root xmlns:xmlinput="www.vishia.org/XmlReader-xmlinput">
    <xmlinput:subtree xmlinput:name="NAMESUBTREE">
       .....
    <xmlinput:cfg>
       ......   
    

  • Elements <xmlinput:subtree ... contains some templates of sub trees which should be parsed in the user.xml. Typically they are recursively sub trees.
  • The part <xmlinput:cfg ... contains the configuration from the root node of the user.xml.
• Use attribute values for arguments in the store path:

     <tag attr="!@attr" .... xmlinput:data="!newInstance(attr)" >!storeText(text, attr)
     

  If the store path starts with !@ then the attribute value of a given attr is locally stored with a name (key) following after "!@...". It may be usual the same as the attribute name. That stored attribute value can be used for the datapath-routine as argument to create the instance to store the data, or to invoke the store routine for the text of the element. If attribute values should be used as arguments for the xmlinput:data routine, then no attribute values should be stored with a storePath (attr="!storePath). Both approaches are exclusively.
• Attribute as key: If an attribute plays a role as key in the user.xml, it should written in the following form:

     <tag attr="!CHECK"/>
     <tag attr="key1">!invoke1()
     <tag attr="key2">!invoke2()
     

  The first <tag ...ATTR="!CHECK" ...> designates this attribute to check it, use its value as key. Any following <tag ...ATTR="..." ...> builds a key with the tag, the attribute and the value to search the proper config node with given data in user.xml. So they are different entries for the same tag but with different attribute values. The key for this element is internally build with tag@attr="key1"@anotherAttr="itsKey"
• sub tree:

     <subtreeTag xmlinput:subtree="subtreeTag" xmlinput:data="!addmodule()"/>
     

  If a node <subtreeTag ... was found in the user.xml, then via xmlinput:subtree="subtreeTag" the named <xmlinput:subtree .... is searched in the config file. That is used for sub nodes from this position. Typically this is proper to use for recursively content in the user.xml. Then the sub tree contains a link to the same sub tree itself. The config node above itself can contain more attributes but no content.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	XmlCfg.AttribDstCheck An instance of this class describes for any attribute how to proceed-
static class	XmlCfg.XmlCfgNode This class describes one node as pattern how the content of a parsed xml file should be stored.

Field Summary

Fields

Modifier and Type	Field and Description
(package private) java.util.Map<java.lang.String,DataAccess.IntegerIx>	attribNameVale
private OutTextPreparer	otxCfgHead Control for writeToText(File, LogMessage) for the head of the text file.
private OutTextPreparer	otxNode Control for writing a Node.
protected boolean	readFromText
(package private) XmlCfg.XmlCfgNode	rootNode
(package private) java.util.Map<java.lang.String,java.util.List<XmlCfg.XmlCfgNode>>	subtreeForward entries of usage of subtree instances which are defined later in the text.
(package private) java.util.Map<java.lang.String,XmlCfg.XmlCfgNode>	subtrees Configuration for subtrees which can occur anywhere in the XML file.
static java.lang.String	version Version, License and History: See XmlJzReader.
(package private) java.util.Map<java.lang.String,java.lang.String>	xmlnsAssign Assignment between nameSpace-value and nameSpace-alias gotten from the xmlns:ns="value" declaration in the read cfg.XML file.

Constructor Summary

Constructors

Constructor and Description
XmlCfg(boolean readFromText)

Method Summary

Modifier and Type	Method and Description
(package private) XmlCfg.XmlCfgNode	addSubTree(java.lang.CharSequence name) Invoked from XmlCfg.XmlCfgNode.addSubTree(CharSequence) to execute for the whole configuration.
void	checkCfg(LogMessage log) Detect different entries in sub node and node via sub tree to clarify it.
private void	checkCfg(XmlCfg.XmlCfgNode node, LogMessage log, java.util.HashMap<XmlCfg.XmlCfgNode,XmlCfg.XmlCfgNode> nodesChecked, int recursively)
(package private) void	finishReadCfg() TODO this operation may be non sensible, change XmlJzReader, TODO It transfers the subtrees content to the real sub trees of nodes.
java.lang.Iterable<java.util.Map.Entry<java.lang.String,java.lang.String>>	iterNamespace() Returns an iterator over all internal name space assignments.
(package private) static XmlCfg	newCfgCfg() Creates the configuration to read a config.xml file.
boolean	readCfgFile(java.io.File fText, LogMessage log) Read the XmlCfg content from the textual representation.
boolean	readFromJar(java.lang.Class<?> clazz, java.lang.String pathInJarFromClazz, LogMessage log) Read the XmlCfg content from the textual representation.
boolean	readFromText(StringPartScan sp, LogMessage log) Read the XmlCfg content from the textual representation.
private boolean	readFromTextNode(XmlCfg.XmlCfgNode node, StringPartScan sp, LogMessage log)
(package private) void	transferNamespaceAssignment(java.util.Map<java.lang.String,java.lang.String> src) Transfer the nameSpace assignments read from XmlJzReader stored there in XmlJzReader.namespaces in backward direction in the xmlnsAssign.
protected static void	wrDataAccess(java.lang.Appendable wr, DataAccess.DatapathElement dacc) Writes the data access path, called inside otxNode from script via <:exec:wrDataAccess(
protected void	writeSubNode(java.lang.Appendable wr, java.lang.String indent, XmlCfg.XmlCfgNode node)
void	writeToText(java.io.File fText, LogMessage log) writes the content of the config to a text file.

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: See XmlJzReader.

• 2024-05-21 new: readCfgFile(File, LogMessage), readFromJar(Class, String, LogMessage), readFromText(StringPartScan, LogMessage) Now the representation can be better editable as normal syntactical tet.
• 2024-05-17 chg: transferNamespaceAssignment(Map) does no more call src.clean(), instead it is called outside. The clean is not a task of this operation. Clean() is necessary before read a new Xml file in XmlJzReader instead. The solution before was dirty.
• 2024-05-17 chg: new writeToText(File, LogMessage) as new concept starting but not finished in 2022.
• 2022-06-25 new: newCfgCfg() also setContentStorePath(...) for the xmlinput:subtree node itself. it is a special case, hence first not regarded, but possible and necessary. Some sorting and comments there.
• 2022-06-06 new: regards "xmlinput:finish" for a set operation. It is now the same concept as for ZbnfData:
  • 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.
• 2021-10-07 new: XmlCfg.XmlCfgNode.nameSpaceDef to store namespace definitions in user data.
• 2021-10-07 formally change: General using TreeMap (java.util) instead the specific IndexMultiTable, same functionality
• 2019-08-16 XmlCfg.XmlCfgNode.allArgNames gets initial name, value, tag and text as unified for ReadCfgCfg and the used cfg
• 2019-08-15 Changes in respect of DataAccess usage of variables.
• 2019-03-13 new XmlCfgNode#addFromSubtree(XmlCfgNode) copies only not defined attributes from the subtree block definition. hence the definition of an attribute in the call subtree line is prior to the attribute defined in the subtree.
• 2019-03-13 new subtreeForward. It is possible that a definition in a subtree uses another subtree which is declared below. The information from the subtree will be copied on end of reading config. #finishReadCfg(Map) (moved from XmlJzReader) does it.
• 2018-08-15 element subNodeUnspec removed, instead store key="?" in XmlCfg.XmlCfgNode.subnodes.
• 2018-08-15 newCfgCfg() more simple. Don't use the root node as config for root node.
• 2018-08-15 #newCfgReadStruct() accepts all XML structures, stores the structure of the nodes and attributes.
• 2017-06 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

xmlnsAssign

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

Assignment between nameSpace-value and nameSpace-alias gotten from the xmlns:ns="value" declaration in the read cfg.XML file. If this table is null than the config file is read yet.

subtrees

java.util.Map<java.lang.String,XmlCfg.XmlCfgNode> subtrees

Configuration for subtrees which can occur anywhere in the XML file. A subtree have to be determined by a tag name of its root element. With them it can be found here.

subtreeForward

java.util.Map<java.lang.String,java.util.List<XmlCfg.XmlCfgNode>> subtreeForward

entries of usage of subtree instances which are defined later in the text. This element is only used for reading the config. It is used and set to null after #finishReadCfg(Map).

rootNode

XmlCfg.XmlCfgNode rootNode

attribNameVale

java.util.Map<java.lang.String,DataAccess.IntegerIx> attribNameVale

readFromText

protected final boolean readFromText

otxCfgHead

private OutTextPreparer otxCfgHead

Control for writeToText(File, LogMessage) for the head of the text file.

otxNode

private OutTextPreparer otxNode

Control for writing a Node.

• whatis := "SUBTREE" or empty.
• indent := spaces from left.
• node := the root or sub node

Constructor Detail

XmlCfg

public XmlCfg(boolean readFromText)

Method Detail

newCfgCfg

static XmlCfg newCfgCfg()

Creates the configuration to read a config.xml file.

Returns:

instance

addSubTree

XmlCfg.XmlCfgNode addSubTree(java.lang.CharSequence name)

Invoked from XmlCfg.XmlCfgNode.addSubTree(CharSequence) to execute for the whole configuration.

Parameters:

name -

Returns:

transferNamespaceAssignment

void transferNamespaceAssignment(java.util.Map<java.lang.String,java.lang.String> src)

Transfer the nameSpace assignments read from XmlJzReader stored there in XmlJzReader.namespaces in backward direction in the xmlnsAssign. Backward means, from the path to the namespace key. This is necessary because a read XML file uses the same nameSpace string but maybe different namespace keys. The simple thinking it, it's the same. Then this operation or field xmlnsAssign would not be necessary. But this thinking is consequently worse. Follow the nameSpace concept in XML:

<... xmlns:keyXY="nameSpace/string" ....
    <keyXY:element

In an XML file instance the keyXY is only a locally valid. The real used value is the "nameSpace/string" To search the element here in cfg this nameSpace string is used, not the short nameSpace alias.

 String aliasInCfg = xmlnsAssign.get("nameSpace/String");  // value from the read XML file
 

And this aliasInCfg is then used to search in cfg. It is not systematically but often given that both alias nameSpace keys are equal.

Parameters:

src -

Since:

2024-05 does no more invoke src.clean()

finishReadCfg

void finishReadCfg()

TODO this operation may be non sensible, change XmlJzReader, TODO It transfers the subtrees content to the real sub trees of nodes. Better search in subtrees while parsing XML.

Since:

2024-05-17 does not call transferNamespaceAssignment(Map), should be called outside.

readCfgFile

public boolean readCfgFile(java.io.File fText,
                           LogMessage log)
                    throws java.nio.charset.IllegalCharsetNameException,
                           java.nio.charset.UnsupportedCharsetException,
                           java.io.FileNotFoundException,
                           java.io.IOException

Read the XmlCfg content from the textual representation. Syntax adequate writeToText(File, LogMessage) It calls readFromText(StringPartScan, LogMessage).

Parameters:

fText - The file

log - log on error

Returns:

true if all ok, false if any syntax error.

Throws:

java.nio.charset.IllegalCharsetNameException

java.nio.charset.UnsupportedCharsetException

java.io.FileNotFoundException

java.io.IOException

readFromJar

public boolean readFromJar(java.lang.Class<?> clazz,
                           java.lang.String pathInJarFromClazz,
                           LogMessage log)
                    throws java.nio.charset.IllegalCharsetNameException,
                           java.nio.charset.UnsupportedCharsetException,
                           java.io.FileNotFoundException,
                           java.io.IOException

Read the XmlCfg content from the textual representation. Syntax adequate writeToText(File, LogMessage) It calls readFromText(StringPartScan, LogMessage).

Parameters:

fText - The file

log - log on error

Returns:

true if all ok, false if any syntax error.

Throws:

java.nio.charset.IllegalCharsetNameException

java.nio.charset.UnsupportedCharsetException

java.io.FileNotFoundException

java.io.IOException

readFromText

public boolean readFromText(StringPartScan sp,
                            LogMessage log)

Read the XmlCfg content from the textual representation. Syntax adequate writeToText(File, LogMessage)

Parameters:

sp - should be initialized with the text

log - log on error

Returns:

true if all ok, false if any syntax error.

readFromTextNode

private boolean readFromTextNode(XmlCfg.XmlCfgNode node,
                                 StringPartScan sp,
                                 LogMessage log)

writeToText

public void writeToText(java.io.File fText,
                        LogMessage log)

writes the content of the config to a text file.

Parameters:

fText -

log -

Since:

2024-05-17

writeSubNode

protected void writeSubNode(java.lang.Appendable wr,
                            java.lang.String indent,
                            XmlCfg.XmlCfgNode node)
                     throws java.io.IOException

Throws:

java.io.IOException

wrDataAccess

protected static void wrDataAccess(java.lang.Appendable wr,
                                   DataAccess.DatapathElement dacc)
                            throws java.io.IOException

Writes the data access path, called inside otxNode from script via <:exec:wrDataAccess(...)>

Parameters:

wr -

dacc -

Throws:

java.io.IOException

iterNamespace

public java.lang.Iterable<java.util.Map.Entry<java.lang.String,java.lang.String>> iterNamespace()

Returns an iterator over all internal name space assignments. Note: It encapsulates the content of the internal xmlnsAssign container, prevent for change.

Returns:

checkCfg

public void checkCfg(LogMessage log)

Detect different entries in sub node and node via sub tree to clarify it.

Parameters:

log -

checkCfg

private void checkCfg(XmlCfg.XmlCfgNode node,
                      LogMessage log,
                      java.util.HashMap<XmlCfg.XmlCfgNode,XmlCfg.XmlCfgNode> nodesChecked,
                      int recursively)