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 static java.util.Map<java.lang.String,OutTextPreparer>`	`idxScript` Should be also static because the `OutTextPreparer.parse(Class, Map, Map)` should only be called one time for the static `otxCfgHead` and `otxNode` on first usage.
`private static OutTextPreparer`	`otxCfgHead` Control for `writeToText(File, LogMessage)` for the head of the text file.
`private static 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()
Constructor for empty instance.

XmlCfg(boolean readFromText)
Deprecated.
use XmlCfg().

Constructors
Constructor and Description
`XmlCfg()` Constructor for empty instance.
`XmlCfg(boolean readFromText)` Deprecated. use `XmlCfg()`.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`(package private) XmlCfg.XmlCfgNode`	`addSubTree(java.lang.CharSequence name)` Gets the root of a `subtrees` entry or adds an new created empty subtree and returns it.
`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 from XML.
`boolean`	`readCfgFile(java.io.File fText, LogMessage log)` Read the XmlCfg content from the textual representation file.
`boolean`	`readFromJar(java.lang.Class<?> clazz, java.lang.String pathInJarFromClazz, LogMessage log)` Read the XmlCfg content from the textual representation in a jar file.
`boolean`	`readFromText(StringPartScan sp, LogMessage log)` Read the XmlCfg content from the textual representation.
`private boolean`	`readFromTextNode(XmlCfg.XmlCfgNode node, StringPartScan sp, LogMessage log)` Read the configuration from the given text in StringPartScan already prepared.
`(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 which can be later read with `readCfgFile(File, LogMessage)` or with `readFromJar(Class, String, LogMessage)`.

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.
    - 2025-12-14: Now the textual syntax is changed but held compatible, see ...adoc
    - readFromTextNode(XmlCfgNode, StringPartScan, LogMessage)(...) read compatible, more variants.
    - otxNode: First write attributes necessary for NEW, then NEW and ADD, then only "=>SUBTREE" in the better explainable order. XmlCfg.XmlCfgNode.attribsForCheck correct filled, and new XmlCfg.XmlCfgNode.attribsArg and XmlCfg.XmlCfgNode.attribsSet set in XmlCfg.XmlCfgNode.addAttribStorePath(String, String) and used for otxNode pattern for write
    - 2025-12-11: addSubTree(CharSequence) and transferNamespaceAssignment(Map) now supports add for supplementing a given XmlCfg with new inputs by XmlJzAnalyzer.
    - 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
```
  - otxCfgHead
```
private static final OutTextPreparer otxCfgHead
```
    Control for writeToText(File, LogMessage) for the head of the text file.
  - readFromText
```
protected boolean readFromText
```
  - otxNode
```
private static final OutTextPreparer otxNode
```
    Control for writing a Node.
    - whatis := "SUBTREE" or empty.
    - indent := spaces from left.
    - node := the root or sub node
  - idxScript
```
private static java.util.Map<java.lang.String,OutTextPreparer> idxScript
```
    Should be also static because the OutTextPreparer.parse(Class, Map, Map) should only be called one time for the static otxCfgHead and otxNode on first usage. That is only in writeToText(File, LogMessage).
- Constructor Detail
  - XmlCfg
```
@Deprecated
public XmlCfg(boolean readFromText)
```
    Deprecated. use XmlCfg().
    
    Parameters:
    
    readFromText -
  - XmlCfg
```
public XmlCfg()
```
    Constructor for empty instance. Use readCfgFile(File, LogMessage) or adequate to set a configuration.
- Method Detail
  - newCfgCfg
```
static XmlCfg newCfgCfg()
```
    Creates the configuration to read a config.xml file from XML.
    
    Returns:
    
    instance
  - addSubTree
```
XmlCfg.XmlCfgNode addSubTree(java.lang.CharSequence name)
```
    Gets the root of a subtrees entry or adds an new created empty subtree and returns it.
    - This is invoked from XmlCfg.XmlCfgNode.addSubTree(CharSequence) while reading a XML configuration from a text file. The subtree is part of the XmlConfig, outside of the intrinsic given XmlCfgNode element where this is called.
    - The second reason to call is in XmlJzCfgAnalyzer.checkStructTree() if it is detected that a subtree entry is necessary.
    The name 'addSubtree' may be necessary because of symbolic reflection calling. Intrinsic it may be 'getCreateSubtree)...)'.
    Parameters:
    
    name -
    
    Returns:
    
    the existing subtree root node with this name or a new created node.
    
    Since:
    
    2025-12-11 look whether the node is existing, for supplement a given XmlCfg with new definitions.
  - 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(), 2025-12-11 does no more clean xmlnsAssign, able to add name spaces. This is used to supplement a given configuration with new results from XmlJzCfgAnalyzer.storeInCfg(XmlJzReader).
  - 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 file. Syntax adequate writeToText(File, LogMessage) It calls readFromText(StringPartScan, LogMessage).
    
    After reading this instance of XmlCfg is initialized as config file for XmlJzReader.setCfg(XmlCfg) to read a XML files with this configuration. 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 in a jar file. Syntax adequate writeToText(File, LogMessage) It calls readFromText(StringPartScan, LogMessage).
    
    After reading this instance of XmlCfg is initialized as config file for XmlJzReader.setCfg(XmlCfg) to read a XML files with this configuration.
    
    Parameters:
    
    clazz - Any class in the same directory as the text file to read inside the jar file
    
    pathInJarFromClazz - The relative path from the clazz to the text file
    
    log - output of errors
    
    Returns:
    
    true if ok.
    
    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)
```
    Read the configuration from the given text in StringPartScan already prepared. It is called recursively also for inner nodes. First call is in readFromText(StringPartScan, LogMessage) for the while file.
    
    Parameters:
    
    node -
    
    sp -
    
    log -
    
    Returns:
  - writeToText
```
public void writeToText(java.io.File fText,
                        LogMessage log)
```
    Writes the content of the config to a text file which can be later read with readCfgFile(File, LogMessage) or with readFromJar(Class, String, LogMessage). This operation is used especially after XmlJzCfgAnalyzer.analyzeXmlStruct(File) or XmlJzCfgAnalyzer#analyzeXmlStructZip(File, String) to write out the result.
    - Uses otxCfgHead for the head of the text, with the subtree definitioons and the <root>....</root>
    - Uses otxNode for all node contents,
    - Translates this script to executable commands on first usage (it is static). Translation is done if idxScript is set.
    - otxNode will be called recursively for all child nodes in the otxNode script itself:
    Parameters:
    
    fText - destination.
    
    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)
```

Class XmlCfg

Nested Class Summary

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

version

xmlnsAssign

subtrees

subtreeForward

rootNode

attribNameVale

otxCfgHead

readFromText

otxNode

idxScript

Constructor Detail

XmlCfg

XmlCfg

Method Detail

newCfgCfg

addSubTree

transferNamespaceAssignment

finishReadCfg

readCfgFile

readFromJar

readFromText

readFromTextNode

writeToText

writeSubNode

wrDataAccess

iterNamespace

checkCfg

checkCfg