ByteDataAccessBase

java.lang.Object
- org.vishia.byteData.ByteDataAccessBase

All Implemented Interfaces:

InfoFormattedAppend

Direct Known Subclasses:

ByteDataAccessSimple, Field_Jc, InspcDatagram.Base, Inspcitem.Head, MemUnit, Object_Jc, RawDataAccess, SuperclassIfc_idxMtblJc_ByteDataAccess
```
public class ByteDataAccessBase
extends java.lang.Object
implements InfoFormattedAppend
```
This class is a base class to control the access to binary data. The binary data may typically used or produced from a part of software written in C or C++. Therewith the binary data are struct-constructs. Another example - build of datagram structures.
This class is a base class which should be derived for user's necessities. The methods getInt16(int) etc. are protected. That should prevent erratic free accesses to data on application level. A derived class of this class structures the software for byte data access.

It is able to support several kinds of structured data access:
- Simple C-like struct are adequate mapped with a simple derived class of this class, using the protected commonly access methods like _getLong(int, int) with predefined indexes in special methods like getValueXyz().
- Complex struct with nested struct inside are mapped with one derived class per struct, define one reference per nested struct
- Base struct inside a struct (inheritance in C) can be mapped with extra derived classes for the base struct and usind the assignCasted(ByteDataAccessBase, int, int)-method.
- A pack of data with several struct may be mapped using the addChild(ByteDataAccessBase)-method. Thereby a parent should be defined, and the structs of the pack are children of this parent. That structures need not be from the same type.
- packs of struct with parent are able to nesting, it is able to construct as a tree of pack of structures. The parent of the pack is the tree node. It is likewise a XML tree. The data may be also transformed to a XML data representation or the data structure may be explained with a XML tree, but they are not XML data straight.
This application possibilities show a capable of development system to access binary data. The other, hand made way was calculate with indices of the byte[idx] specially user programmed. This class helps to make such complex index calculation needlessly. One struct at C level corresponds with one derivated class of ByteDataAccessBase. But last also a generation of the java code from C/C++-header files containing the structs is able to. So the definition of byte positions are made only on one source. The C/C++ is primary thereby.
The UML structure of such an class in a environment may be shown with the followed object model diagram,
<+>---> is a composition, <>---> is a aggregation, <|---- is a inherition.
```
                      +-------------------------------+                 +----------+
                      | ByteDataAccessBase(sizeHead)  |----data-------->| byte[]   |
                      |-------------------------------|                 |          |
                      |- idxBegin:int                 |                 | d a t a  |
                      |- idxNextChild:int             |                 +----------+
  +-------------+     |- idxEnd:int                   |
  | derivated   |     |-------------------------------|<---------------+ a known parent
  | user        |---|>|+ addChild(child)              |---parent-------+ set in addChild()                
  | classes     |     |+ addChildFloat()              |
  +-------------+     |% getInt32()                   |----currChild---+
                      |                               |<---------------+
                      +-------------------------------+
 
```
This class is the base class for ByteDataAccess. It works without dynamic methods proper for C usage. All variables are package private because they should be changed only with methods of this class.

Initialization and instances
The root instance to access to data should be initialized with
```
 MyByteDataAccessRoot accessRoot = new MyByteDataAccessRoot(); 
   //... invokes super.ByteDataAccessBase(lengthHead);
 accessRoot.assign(myData, dataLength);
 
```
Any instances which represents a sub structure in data can be created as re-useable instances, which can be added as child of the root instance or as child of any already added child on demand:
```
 MySubStruct subStruct = new SubStruct();  //an instance for accessing 
   ....
   accessRoot.addChild(subStruct);         //adds on current position.
   int value = subStruct.getValuexyz();    //now can access the data.
   ....  //later on code:
   accessOther.addChild(subStruct);        //reuse the instance for access
   int value = subStruct.getValueAbc();    //access other data.
 
```
The instances of this derived class are helper to access to the data, they are not container for the data. The data are stored in a byte[]-array

children, currentChild, addChild
Children are used to evaluate or write different data structures after a known structure. The children may be from several derived types of this class. With children and children inside children a tree of different data can be built or evaluated.
- addChild(ByteDataAccessBase): adds a child with its head size
- addChild(ByteDataAccessBase, int): adds a child with a given length
- addChildEmpty(ByteDataAccessBase): adds a child with its head size for writing, set all data to 0.
- addChildEmpty(ByteDataAccessBase, int): same with given size of child.
- addChildFloat(float), addChildInteger(int, long): writes the value and increments the #ixChildEnd after it.
- addChildString(CharSequence), addChildString(CharSequence, String): writes the String.
- getChildFloat(), getChildDouble(), getChildInteger(int): reads the value at ixNextChild and increments the ixNextChild.
- getChildString(int) reads a String and increments the ixNextChild
- addChildAt(int, ByteDataAccessBase), addChildAt(int, ByteDataAccessBase, int): Used if the byte structure is known. Adds a child not at #ixNextChild but at the given position.
Mechanism and indices see addChild(ByteDataAccessBase, int).
Expand, check
If an instance is set for read or change, a given number of valid data bytes are known. The instance is marked as 'non expandable', see The data should be assigned with
- assign(byte[], int) with given length, not expandable
- assign(byte[], int, int) at a defined position in the data usefull for special cases. With the given length >= the sizehead of the ByteDataAccessBase(int) the internal flag bExpand is set to false.
If an instance is set for write, the maximal number of bytes is limited by the size of data (byte[]). The data should be assigned with:
- assignClear(byte[]) as empty instance, the data are cleared in its whole length.
- assign(byte[], int) with 0 as length argument as instance which only knows the head data, but the data are not cleared.
In both cases the internal flag bExpand is set to true. It means that the ixEnd() which is set initially to the sizeHead is increased if a child is added.

If an instance of this is set to non expandable, an exception is thrown if a children is added after the given length. If an instance is designated as 'expandable' the end index #ixEnd is increased by adding children till the length of data as its maximal value.

With the operations sufficingBytesForNextChild(int) or getMaxNrofBytes() it can be tested whether a child can be added with its known length.

Examples
See
- org.vishia.byteData.test.TestByteDataAccessBase
- org.vishia.byteData.test.ExampleStringOrInt

Nested Class Summary
- Nested classes/interfaces inherited from interface org.vishia.util.InfoFormattedAppend
  InfoFormattedAppend.PrepareToString

Field Summary

Fields
Modifier and Type	Field and Description
`protected boolean`	`bBigEndian` Flag is set or get data in big endian or little endian (if false)
`protected boolean`	`bExc` If false then never an exception is thrown, Instead the work is done as soon as possible.
`private boolean`	`bExpand` True if the `ixEnd` should not be set to the `sizeHead` on removing children.
`protected boolean`	`bLittleEndianBig2` Flag is set or get data in little endian but 2 Bytes as 16 bit word in big endian.
`private java.nio.charset.Charset`	`charset` The charset to build Strings.
`private ByteDataAccessBase`	`currChild` The last added child, null either if a child is not added or a child was added but the instance is used meanwhile otherwise.
`protected byte[]`	`data` The array containing the binary data.
`private int`	`ixBegin` Index of the beginning of the actual element in data
`private int`	`ixBeginLocal` Index of the beginning of the element inside the parent, relative to the parent.
`private int`	`ixEnd` Index of the end of the actual element in data.
`private int`	`ixNextChild` Index of the currents child end respectively the position of a new child.
`private ByteDataAccessBase`	`parent` The parent element, necessary especially for expand(), also for `removeChild(ByteDataAccessBase)` More as one children can refer the same parent.
`protected int`	`sizeHead` Number of Memory locations (usual bytes) for the head of this instance's Type.
`protected StringFormatter`	`toStringformatter` Use especially for test, only used in toString().
`static java.lang.String`	`version` The version, history and license.

Constructor Summary

Constructors
Modifier	Constructor and Description
	`ByteDataAccessBase(int sizeHead)` Any instance of ByteDataAccessBase is associated to a determined derived instance which has defined head size.
`protected`	`ByteDataAccessBase(int sizeHead, int sizeData)` Deprecated. Remark: Because `assign(byte[], int)` decides on the size of data, and `addChild(ByteDataAccessBase, int)` decides on the size of data of a child, this constructor makes no sense. Jchartmut 2015-04-12

Method Summary

All Methods Instance Methods Concrete Methods Deprecated Methods
Modifier and Type	Method and Description
`private void`	`_expand(int ixNextChildNew, int ixEndNew)` Increments the `ixNextChild` and/or increments the ixEnd of this and all parents.
`protected int`	`_getInt(int idxInChild, int nrofBytesAndSign)` Returns the content of 1 to 4 bytes inside the actual element as a int number, big- or little-endian depending on setBigEndian().
`protected long`	`_getLong(int idxInChild, int nrofBytesAndSign)` Returns the content of 1 to 8 bytes inside the actual element as a long number, big- or little-endian depending on setBigEndian().
`protected void`	`_setInt(int idx, int nrofBytes, int val)` sets the content of 1 to 4 bytes inside the actual element as a long number, big- or little-endian depending on setBigEndian().
`protected void`	`_setLong(int idx, int nrofBytes, long val)` sets the content of 1 to 8 bytes inside the actual element as a long number, big- or little-endian depending on setBigEndian().
`protected void`	`_setString(int idx, int nrofBytes, java.lang.String value, java.lang.String sEncoding, boolean preventCtrlChars)` sets the content inside the actual element with the character bytes from the given String.
`boolean`	`addChild(ByteDataAccessBase child)` Adds a child with its given head size without additional data space.
`boolean`	`addChild(ByteDataAccessBase child, int sizeChild)` Adds a child Element after the current child or as first child after head.
`void`	`addChildAt(int idxChild, ByteDataAccessBase child)` Adds a child at any position with its head size.
`void`	`addChildAt(int idxChild, ByteDataAccessBase child, int sizeChild)` Adds a child at any position.
`boolean`	`addChildEmpty(ByteDataAccessBase child)`
`boolean`	`addChildEmpty(ByteDataAccessBase child, int sizeChild)`
`boolean`	`addChildFloat(float value)` Adds a child for 1 float value without a child instance, and sets the value as float.
`boolean`	`addChildInt(int nrofBytes, int value)` Adds a child for 1 integer value without a child instance, and sets the value as integer.
`boolean`	`addChildInteger(int nrofBytes, long value)` Adds a child for 1 integer value without a child instance, and sets the value as integer.
`void`	`addChildString(java.lang.CharSequence value)` Adds a child with String value.
`boolean`	`addChildString(java.lang.CharSequence valueCs, java.lang.String sEncoding)` Adds a child with String value.
`boolean`	`addChildString(java.lang.String value, java.lang.String sEncoding, boolean preventCtrlChars)` Adds a child with String value.
`void`	`assign(byte[] dataP)` Assigns the given data with its given length to read the data.
`void`	`assign(byte[] data, int lengthData)` Assigns data with a given length.
`void`	`assign(byte[] dataP, int lengthData, int index)` Assigns new data to this element at given index in data.
`void`	`assignAt(int idxChildInParent, ByteDataAccessBase parent)` assigns the element to the given position of the parents data to present a child of the parent.
`void`	`assignAt(int idxChildInParent, int lengthChild, ByteDataAccessBase parent)` assigns the element to the given position of the parents data to present a child of the parent with a defined length.
`protected void`	`assignCasted(ByteDataAccessBase src, int offsetCastToInput, int lengthDst)` Deprecated. it is confuse. Use
`void`	`assignClear(byte[] data)` Initializes a top level instance, the data will be cleared, set to 0, overall.
`protected void`	`assignDataToFixChildren()` This method can be overridden by Java applications for derived instances which contains elements of this class assigned at defined positions in data.
`(package private) boolean`	`checkData()` Checks `data` == null and gets the data from parent if necessary.
`boolean`	`checkLengthElement(int size)` Checks whether a given size is possible as `setLengthElement(int)` for the given instance.
`void`	`clearData()` Sets all data of this element to 0.
`void`	`clearHead()` Sets all data of the head of this element to 0.
`void`	`copyData(int[] dst)` copies some data to a int[], primarily to debug a content.
`void`	`copyDataFrom(ByteDataAccessBase src)` copies the data from another references data into this data.
`private void`	`copyStdValues(ByteDataAccessBase src)`
`byte[]`	`data()` Returns the data buffer itself.
`void`	`detach()` Remove all connections.
`boolean`	`getBigEndian()`
`protected char`	`getChar(int idx)` Returns the content of 1 bytes as ASCII inside the actual element.
`double`	`getChildDouble()` Adds a child for 1 double value without a child instance, but returns the value as integer.
`float`	`getChildFloat()` Adds a child for 1 float value without a child instance, but returns the value as integer.
`int`	`getChildInt(int nrofBytes)` Adds a child for 1 integer value without a child instance and returns the value as 32-bit-integer.
`short`	`getChildInt16()` Adds a child for 1 short value without a child instance, returns the value as short.
`long`	`getChildInteger(int nrofBytes)` adds a child for 1 integer value without a child instance and returns the value as long integer.
`java.lang.String`	`getChildString(int nrofBytes)` Adds a child for a String value without a child instance, but returns the value as String.
`int`	`getChildUint16()` Adds a child for 1 short value without a child instance, returns the value as short.
`short`	`getChildUint8()` Adds a child for 1 short value without a child instance, returns the value as short.
`byte[]`	`getData()` Returns the data buffer itself.
`private byte[]`	`getData(int recursion)` Gets the data from parent if `data` == null
`protected double`	`getDouble(int idx)`
`protected float`	`getFloat(int idx)` Gets a float value from the content of 4 byte.
`protected float`	`getFloat(int idxBytes, int idxArray, int lengthArray)`
`protected short`	`getInt16(int idx)` Returns the content of 2 bytes as a positive nr between 0..65535 inside the actual element.
`protected int`	`getInt16(int idxBytes, int idxArray, int lengthArray)`
`protected int`	`getInt32(int idx)` Returns the content of 4 bytes inside the actual element as a integer number between -2147483648 and 2147483647, big- or little-endian depending on setBigEndian().
`protected int`	`getInt32(int idxBytes, int idxArray, int lengthArray)`
`protected long`	`getInt64(int idx)`
`protected byte`	`getInt8(int idx)` Returns the content of 1 bytes as a positive or negative nr between -128..127 inside the actual element.
`protected int`	`getInt8(int idxBytes, int idxArray, int lengthArray)`
`int`	`getLength()` Returns the length of the existing actual element.
`int`	`getLengthCurrent()` Returns the length of the element with all yet added children.
`int`	`getLengthHead()` Returns the length of the head.
`int`	`getLengthTotal()` Returns the length of the data.
`int`	`getMaxNrofBytes()` returns the number number of bytes there are max available from position of the current child
`int`	`getMaxNrofBytesForNextChild()` returns the maximal number of bytes which are available from position of a next current child.
`int`	`getPositionInBuffer()` Returns the position of the Element data in the assigned buffer.
`int`	`getPositionNextChildInBuffer()` Returns the position of a next child which can be added in the assigned buffer.
`protected java.lang.String`	`getString(int idx, int nrofBytes)` Returns a String from the given position inside the actual element .
`protected int`	`getUint16(int idx)` Returns the content of 2 bytes as a positive nr between 0..65535, big-endian inside the actual element.
`protected int`	`getUint16(int idxBytes, int idxArray, int lengthArray)`
`protected int`	`getUint32(int idx)`
`protected int`	`getUint32(int idxBytes, int idxArray, int lengthArray)`
`protected short`	`getUint8(int idx)` Returns the content of 1 bytes as a positive or negative nr between -128..127 inside the actual element.
`protected int`	`getUint8(int idxBytes, int idxArray, int lengthArray)`
`protected void`	`infoAppendHead(StringFormatter u, int bytesHex)` Appends information about the head of the given element.
`void`	`infoFormattedAppend(StringFormatter u)` Appends the information about the indices and the current Children.
`boolean`	`isCurrentChildInParent()`
`boolean`	`isExpandable()` Returns true if the instance is set as expandable, see `assign(byte[], int)`
`boolean`	`isInUse()`
`protected int`	`ixBegin()`
`protected int`	`ixEnd()`
`protected int`	`ixNextChild()`
`void`	`removeChild()` Removes the current child to assign another current child instead on the position of the current child.
`void`	`removeChild(ByteDataAccessBase child)` Shorten the evaluated content of the data to the position of the given child.
`void`	`removeChildren()` Remove all children.
`void`	`setBigEndian(boolean val)` Sets the big or little endian mode.
`void`	`setCharset(java.lang.String value)`
`protected void`	`setDouble(int idx, double value)` Set the content of 8 byte from a double variable.
`void`	`setException(boolean val)` Sets whether an exception should be thrown on adding a child or it should be return with false to continue as soon as possible without exception handling.
`protected void`	`setFloat(int idx, float value)` Set the content of 4 byte from a float variable.
`protected void`	`setFloat(int idxBytes, int idxArray, int lengthArray, float val)`
`private int`	`setIdxtoNextCurrentChild(int sizeChild)` Prepares a new child for this.
`protected void`	`setInt16(int idx, int value)` Set the content of 2 bytes from an integer between -32768..32768, or from an integer number between 0..65535.
`protected void`	`setInt16(int idxBytes, int idxArray, int lengthArray, int val)`
`protected void`	`setInt32(int idx, int value)` Set the content of 4 bytes as a integer number between -2147483648 and 2147483647, big- or little-endian depended from setBigEndian().
`protected void`	`setInt32(int idxBytes, int idxArray, int lengthArray, int val)`
`protected void`	`setInt8(int idx, int value)` Set the content of 1 bytes as a positive nr between 0..256.
`protected void`	`setInt8(int idxBytes, int idxArray, int lengthArray, int val)`
`void`	`setLengthElement(int length)` Sets the length of the element in this and all `parent` of this.
`void`	`setLittleEndianBig2()`
`protected int`	`setString(int idx, int nmax, java.lang.String ss)` Sets a String to the the given position inside the actual element .
`protected void`	`setUint16(int idx, int value)` Set the content of 2 bytes as a positive nr between 0..65535, big- or little-endian.
`protected void`	`setUint16(int idxBytes, int idxArray, int lengthArray, int val)`
`protected void`	`setUint32(int idxBytes, int idxArray, int lengthArray, int val)`
`protected void`	`setUint32(int idx, long value)` Set the content of 4 bytes as a positive nr between 0..2pow32-1, big- or little-endian.
`protected void`	`setUint8(int idx, int value)` Set the content of 1 bytes as a positive nr between 0..255, big- or little-endian.
`protected void`	`setUint8(int idxBytes, int idxArray, int lengthArray, int val)`
`int`	`sizeHead()` Returns the given head size, which is set on constructor respectively which is a determined value of an derived instance of this.
`boolean`	`sufficingBytesForNextChild(int nrofBytes)` returns true if the given number of bytes is sufficing in the data from position of next child.
`private void`	`throwexc(java.lang.String text, int idxArray)`
`java.lang.String`	`toString()` This method is especially usefully to debug in eclipse.
`protected void`	`upcast(ByteDataAccessBase src, int length)` This method is intend to use to change the view to the data from a firstly simple view (src) to the really type if the type is detected inside the (head) data of the firstly view.
`void`	`XXXrewind()` starts the calling loop of next().

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

- Field Detail
  - version
```
public static final java.lang.String version
```
    The version, history and license.
    - 2022-09-26 Hartmut new setLittleEndianBig2() necessary if there is little endian for data, but big endian only for 16 bit image.
    - 2018-12-27 Hartmut new upcast(ByteDataAccessBase, int) replaces the assignCasted(ByteDataAccessBase, int, int). Problems detect on usage of assignCasted: The cast of a child should influence the parent because the next addChild(ByteDataAccessBase) should regard the casting operation. The casting is regarded to the data in sum. It is not only a isolated view to data. Strategy of upcast is documented there.
    - 2018-09-18 Hartmut new ixBeginLocal stores the position inside the child, whereby ixBegin is global. TODO description of strategy of fix children. It may be proper if assignData(...) will be invoked only for the derived class which knows its fix children. The old concept of overridden methods here are not proper for simple C applications.
    - 2018-09-16 Hartmut chg: All access routines calls checkData(). The reason for checkData(): If a child (at an index) was not assigned with data, it gets the data from its parent now. With them it is possible to call assign(byte[]) for the parent only and it runs.
    - 2016-01-24 Hartmut chg: All addChild(ByteDataAccessBase) etc. returns false if setException(boolean) is false and the child cannot be added. If the user invokes setException(false) the user must check the return value of the add...() operations.
    - 2015-08-08 Hartmut chg: Change of concept: prevent Exception if the environment does not process it: Tested on setIdxtoNextCurrentChild(int): This routine can throw an Exception, but it can return -1 on error too, possible with an exception message. Therewith more operations can be disabled by quest of return value.
    - 2015-08-08 Hartmut chg: setLengthElement(int) should set the ixEnd of the child and the ixNextChild of the parent but does not influence the this.ixNextChild. See test cases (TODO). This is fixed and all usages of this class for org.vishia.insp* are tested well by testing the reflection access and GUI.
    - 2015-08-08 Hartmut new: getChildInt(int), _getInt(int, int) for 32 bit operation, _getLong(int, int) uses 64 bit. Used for in derived classes also. The 64-bit-operation is not proper for 32-bit embedded systems in C. TODO use it also if the size argument is <=4.
    - 2015-04-12 Hartmut docu and fineTuning:
    - 2015-03-08 Hartmut chg: ixChild removed, unnecessary, instead currChild, proper for debug.
    - 2014-09-05 Hartmut chg: Some problems fixed in C-Application. Runs in Java. Meaning of bExpand
    - 2014-09-05 Hartmut chg: Designation with some Java4C annotation.
    - 2014-09-05 Hartmut chg: now based on a charset of type Charset. In C it is a dummy yet. In Java the Charset can be used immediately, more simple.
    - 2014-09-05 Hartmut bugfix: Some references changed from ByteDataAccess to ByteDataAccessBase.
    - 2014-09-05 Hartmut chg: getString(int, int) now may contain 0-character. Only the 0-bytes on end are removed because they are fill-bytes for a 4-byte-alignment. _getString(int, int) removed because it was the same.
    - 2014-08-23 Hartmut chg: Member idxFirstChild removed, the information is contained in sizeHead.
    - 2014-08-23 Hartmut new: this class ByteDataAccessBase works without virtual methods (overrideable), it is proper for usage in C-language and it is not necessary. The sizeHead is set by construction. Only for the compatible now deprecated ByteDataAccess the sizeHead is able to set via the package-private #_setSizeHead(int).
    - 2014-01-12 Hartmut new: Java4C.inline for C-compilation.
    - 2013-12-08 Hartmut new: ByteDataAccessBase(int, int) as super constructor with given head and data size. addChild(ByteDataAccessBase) accepts an initialized not used child. Uses #kInitializedWithLength. That is the possibility to work without dynamic linked methods #specifyLengthElement() etc. for proper work especially for C usage. The overridden methods #specifyEmptyDefaultData(), #notifyAddChild() etc. are proper to use in C too with the concept of the dynamic linked methods, but there does not be necessary. It is an optimizing for C. Maybe in future the #specifyLengthElement() and #specifyLengthElementHead() may be depreciated because the new variant of initialized children is better to use, more simple for usage. But it should be compatible with older versions.
    - 2013-12-08 Hartmut chg: #reset(int, int) is protected now and has a second parameter. necessary public?
    - 2012-12-15 Hartmut chg: Some changes are done which cleans up this class. If any problem occurs, the ByteDataAccessOld can be used. It is compatible with the last version before this changes.
      
      The currentChild is not necessary. The only reason to have that association is: changes of size in parent force changes in the current child. But it is contrary: The changes should be done in the child and should affect the indices in all parents which should be known all in the child. If a child is added and it is never used furthermore then an unnecessary dangling reference exists. If the child instance is reused and detach is not called, mistakes are happen.
      the next() and rewind() are removed. It is an unused old concept.
    - 2012-04-07 Hartmut new: #reset(int), some comments.
    - 2012-03-00 Hartmut Note: compare it with java.nio.ByteBuffer. But a ByteBuffer is abstract.
    - 2010-12-20: Hartmut chg: remove the toString-method using StringFormatter, because it is too complex for C-usage. The toString was only able to use for debugging.
    - 2010-02-02: Hartmut new: getChildFloat(), getChildDouble().
    - 2010-01-16: Hartmut chg: setBigEndian in now public. It should be better because the same user data may be interpreted in both versions depending on a parameter.
    - 2005..2009: Hartmut: some changes
    - 2005 Hartmut 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 indent 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
  - sizeHead
```
protected final int sizeHead
```
    Number of Memory locations (usual bytes) for the head of this instance's Type. Set on construction.
  - data
```
protected byte[] data
```
    The array containing the binary data. Note this reference should be private, not protected because the kind of access may be changed or held more flexible for newer versions. The usage should not deal with this reference immediately. Use addChild etc. to adapt to data.
  - ixBegin
```
private int ixBegin
```
    Index of the beginning of the actual element in data
  - ixBeginLocal
```
private int ixBeginLocal
```
    Index of the beginning of the element inside the parent, relative to the parent.
  - ixNextChild
```
private int ixNextChild
```
    Index of the currents child end respectively the position of a new child. If no current child is known this index is equal ixBegin + sizeHead, it is the position after the head. If the length of the current child is not known, this index is <= -1. That is after addChild(ByteDataAccessBase, int) with lenght=-1.
  - ixEnd
```
private int ixEnd
```
    Index of the end of the actual element in data. If bExpand is set, this idxEnd and the idxEnd of all parents are increased if an child was added. If bExpand==false then this value is set via the addChild(ByteDataAccessBase, int) or addChildAt(int, ByteDataAccessBase, int).
  - bExpand
```
private boolean bExpand
```
    True if the ixEnd should not be set to the sizeHead on removing children.
  - bBigEndian
```
protected boolean bBigEndian
```
    Flag is set or get data in big endian or little endian (if false)
  - bLittleEndianBig2
```
protected boolean bLittleEndianBig2
```
    Flag is set or get data in little endian but 2 Bytes as 16 bit word in big endian.
  - bExc
```
protected boolean bExc
```
    If false then never an exception is thrown, Instead the work is done as soon as possible. See descriptions and return values of some methods.
  - parent
```
private ByteDataAccessBase parent
```
    The parent element, necessary especially for expand(), also for removeChild(ByteDataAccessBase) More as one children can refer the same parent. But this refers only the current child.
  - currChild
```
private ByteDataAccessBase currChild
```
    The last added child, null either if a child is not added or a child was added but the instance is used meanwhile otherwise. This reference is used in the productive code only for removeChild(). It is contained here especially for debugging. Therefore it is private to forbid other usage.
  - charset
```
private java.nio.charset.Charset charset
```
    The charset to build Strings.
  - toStringformatter
```
protected StringFormatter toStringformatter
```
    Use especially for test, only used in toString().
- Constructor Detail
  - ByteDataAccessBase
```
public ByteDataAccessBase(int sizeHead)
```
    Any instance of ByteDataAccessBase is associated to a determined derived instance which has defined head size. The sizeHead can be given with -1 only for derived instances of ByteDataAccess. That class defines a method ByteDataAccess.specifyLengthElementHead() to get the head's size.
    
    Parameters:
    
    sizeHead - The size of head data, it is the number of bytes.
  - ByteDataAccessBase
```
protected ByteDataAccessBase(int sizeHead,
                             int sizeData)
```
    Deprecated. Remark: Because assign(byte[], int) decides on the size of data, and addChild(ByteDataAccessBase, int) decides on the size of data of a child, this constructor makes no sense. Jchartmut 2015-04-12
    
    Constructs a new empty instance with a given head size and a given size for children. That instance is not expandable.
    
    Parameters:
    
    sizeHead - The size of head data, it is the number of bytes.
    
    sizeData - number of significant bytes in data for all children.
- Method Detail
  - setBigEndian
```
public final void setBigEndian(boolean val)
```
    Sets the big or little endian mode.
    
    Parameters:
    
    val - true if big endian, hi byte at lower adress, false if little endian.
  - setLittleEndianBig2
```
public final void setLittleEndianBig2()
```
  - setException
```
public final void setException(boolean val)
```
    Sets whether an exception should be thrown on adding a child or it should be return with false to continue as soon as possible without exception handling. This is especially for C programming if an exception handling is not desired. It is usefull in Java too depending on the user solution. The exception state is inherited to all added childs. It should be set only for the root instance.
    
    Parameters:
    
    val - true if addChild should throw an exception on error, false if addChild... operations should be return false on error. Because the default value for the exception is true, the user should set setException(false) usually.
  - setCharset
```
public final void setCharset(java.lang.String value)
```
  - _getLong
```
protected final long _getLong(int idxInChild,
                              int nrofBytesAndSign)
```
    Returns the content of 1 to 8 bytes inside the actual element as a long number, big- or little-endian depending on setBigEndian(). This method is protected because at user level its using is a prone to errors because the idx is free related.
    
    Parameters:
    
    idxInChild - The position of leading byte in the actual element, the data are taken from data[idxBegin+idx].
    
    nrofBytesAndSign - If positiv, than the method returns the unsigned interpretation of the bytes. If negative, than the return value is negative, if the last significant bit of the given number of bytes is set. The value represents the number of bytes to interprete as integer. It may be 1..8 respectively -1...-8.
    
    Returns:
    
    the long value in range adequate nrof bytes.
    
    Since:
    
    2009-09-30: regards negative nrofBytesAndSign. Prior Versions: returns a signed value always.
  - _getInt
```
protected final int _getInt(int idxInChild,
                            int nrofBytesAndSign)
```
    Returns the content of 1 to 4 bytes inside the actual element as a int number, big- or little-endian depending on setBigEndian(). This method is protected because at user level its using is a prone to errors because the idx is free related.
    
    Parameters:
    
    idxInChild - The position of leading byte in the actual element, the data are taken from data[idxBegin+idx].
    
    nrofBytesAndSign - If positiv, than the method returns the unsigned interpretation of the bytes. If negative, than the return value is negative, if the last significant bit of the given number of bytes is set. The value represents the number of bytes to interprete as integer. It may be 1..8 respectively -1...-8.
    
    Returns:
    
    the long value in range adequate nrof bytes.
    
    Since:
    
    2009-09-30: regards negative nrofBytesAndSign. Prior Versions: returns a signed value always.
  - _setLong
```
protected final void _setLong(int idx,
                              int nrofBytes,
                              long val)
```
    sets the content of 1 to 8 bytes inside the actual element as a long number, big- or little-endian depending on setBigEndian(). This method is protected because at user level its using is a prone to errors because the idx is free related.
    
    Parameters:
    
    idx - the position of leading byte in the actual element, the data are set to data[idxBegin+idx].
    
    nrofBytes - The number of bytes of the value.
    
    val - the long value in range adequate nrof bytes.
  - _setInt
```
protected final void _setInt(int idx,
                             int nrofBytes,
                             int val)
```
    sets the content of 1 to 4 bytes inside the actual element as a long number, big- or little-endian depending on setBigEndian(). This method is protected because at user level its using is a prone to errors because the idx is free related.
    
    Parameters:
    
    idx - the position of leading byte in the actual element, the data are set to data[idxBegin+idx].
    
    nrofBytes - The number of bytes of the value.
    
    val - the long value in range adequate nrof bytes.
  - _expand
```
private final void _expand(int ixNextChildNew,
                           int ixEndNew)
```
    Increments the ixNextChild and/or increments the ixEnd of this and all parents. It is called if a new child is added inside method addChild(child) and recursively to correct in all parents. It is called for setLengthElement(int)
    
    Parameters:
    
    ixNextChildNew - The possible set ixNextChild position, 0 if not to change.
    
    ixEndNew - The new end position, ixEnd is only changed if it is greater the current one.
  - assignDataToFixChildren
```
protected void assignDataToFixChildren()
```
    This method can be overridden by Java applications for derived instances which contains elements of this class assigned at defined positions in data. The method will be called automatically as overridden method for Java applications. For C applications this method will not supported because that would be the only one reason for virtual methods of this class. Keep it simple in C! For C applications the assignment to fix children should be done by special methods of the derived class.
  - assign
```
public final void assign(byte[] dataP,
                         int lengthData,
                         int index)
                  throws java.lang.IllegalArgumentException
```
    Assigns new data to this element at given index in data. This method should be used only for an root element. If the element was used before, its connection to an other parent is dissolved. The position of the next child ixNextChild is set always after the known head data of this derived type stored in the final sizeHead.
    Parameters:
    
    data - The dataP. The length of data may be greater as the number of the significant bytes.
    lengthData - absolute Number of significant bytes in data from start of data (index=0).
    
    If length is > data.length, an exception is thrown.
    If the length is < sizeHead (especially 0), then the access is expand-able. bExpand = true.
    If the length is >=sizeHead(), it defines the size of this access. Between the head and this length some children can be added to access that data. The access is not expanded. Adding a child after this given length throws an exception.
    index - Start position in data, often 0.
    
    Throws:
    
    java.lang.IllegalArgumentException
  - assign
```
public final void assign(byte[] data,
                         int lengthData)
```
    Assigns data with a given length. This method is used usual to read data. Writing as 'changing' is possible too. The expand flag is set to false if the given lengthData is >= the sizeHead(). This method should be used only for an root element respectively this is a root element after calling this method. If the element was used before, its connection to an other parent is dissolved.
    
    Parameters:
    
    data - The data which are accessed with this instance
    
    lengthData - The known length of data. If 0 then the instance is expandable, see isExpandable().
  - assign
```
public final void assign(byte[] dataP)
```
    Assigns the given data with its given length to read the data. This method is also usefully to detach() a current data buffer, call assign(null);.
    
    Parameters:
    
    dataP -
  - assignClear
```
public final void assignClear(byte[] data)
```
    Initializes a top level instance, the data will be cleared, set to 0, overall.
    If this instance is using before, its connection to an other parent is dissolved.
    
    Parameters:
    
    data - The data. It should be not null. The data are filled with 0 initial.
  - assignAt
```
public final void assignAt(int idxChildInParent,
                           int lengthChild,
                           ByteDataAccessBase parent)
                    throws java.lang.IllegalArgumentException
```
    assigns the element to the given position of the parents data to present a child of the parent with a defined length. The difference to addChild(ByteDataAccessBase) is: The position is given here directly, it should not be the current child but a free child.
    The data reference is copied, the idxBegin of this element is set to the idxChild given as parameter. All other indices are set calling specifyLengthElementHead(): idxChild and specifyLengthElement(): idxEnd.
    If the element was used before, its connection to an other parent is dissolved.
    
    Parameters:
    
    parent - The parent. It should reference data.
    
    lengthChild - Number of the bytes of the free child.
    
    idxChildInParent - The index of the free child in the data.
    
    Throws:
    
    java.lang.IllegalArgumentException - If the indices are wrong in respect to the data.
  - assignAt
```
public final void assignAt(int idxChildInParent,
                           ByteDataAccessBase parent)
                    throws java.lang.IllegalArgumentException
```
    assigns the element to the given position of the parents data to present a child of the parent. The length of the child is limited to TODO the length of head - or not limited.
    
    Parameters:
    
    parent - The parent. It should reference data.
    
    idxChildInParent - The index of the free child in the data.
    
    Throws:
    
    java.lang.IllegalArgumentException - If the indices are wrong in respect to the data.
  - assignCasted
```
@Deprecated
protected final void assignCasted(ByteDataAccessBase src,
                                               int offsetCastToInput,
                                               int lengthDst)
                                        throws java.lang.IllegalArgumentException
```
    Deprecated. it is confuse. Use
    
    Assigns this element to the same position in data, but it is another view. This method should be called inside a assignCasted() method if a inner head structure is known and the conclusion of this structure is possible. At result, both ByteDataAccessBase instances reference the same data, in different views.
    
    Parameters:
    
    src - The known data access
    
    offsetCastToInput - typical 0 if single inherition is used.
    
    lengthDst - it is the same like assign(byte[], int): If 0 then the child is set to expandable and its ixEnd() is set to the sizeHead(). If >= sizeHead then this instance is not expandable and this value determines the valid number of data which are able to access via it.
    
    Throws:
    
    java.lang.IllegalArgumentException - if a length of the new type is specified but the byte[]-data are shorter. The length of byte[] is tested.
  - copyStdValues
```
private final void copyStdValues(ByteDataAccessBase src)
```
  - upcast
```
protected final void upcast(ByteDataAccessBase src,
                            int length)
```
    This method is intend to use to change the view to the data from a firstly simple view (src) to the really type if the type is detected inside the (head) data of the firstly view. It is important that the change of view is done for the whole data, represented with the isCurrentChildInParent() relation.
    The operation is protected because it should be only used in an derived class to cast from the src instance to this derived instance
    This instance is filled with the data from src, but with other length. If src is the current child of src.parent then this becomes the current child of parent and the parent.ixNextChild is set proper to this: = this.ixBegin + length. That helps to step in parent via addChild(ByteDataAccessBase)
    
    Parameters:
    
    src - The firstly associated access instance to the data typically via addChild(ByteDataAccessBase), it remains unchanged but it is no more the child of the parent.
    
    length - if <= this.sizeHead, typically 0, then unused, the thissizeHead() is used instead. If > this.sizeHead then it determines the ixEnd() of this and the parent ixNextChild. In that case it is a longer value because this instance should access head and inner children.
  - isExpandable
```
public final boolean isExpandable()
```
    Returns true if the instance is set as expandable, see assign(byte[], int)
  - sizeHead
```
public final int sizeHead()
```
    Returns the given head size, which is set on constructor respectively which is a determined value of an derived instance of this.
    
    Returns:
    
    the number of head bytes defined by construction of ByteDataAccessBase(int).
  - getData
```
public final byte[] getData()
```
    Returns the data buffer itself. The actual total length is got with getLengthTotal().
    
    Returns:
    
    The number of bytes of the data in the buffer.
  - data
```
public final byte[] data()
```
    Returns the data buffer itself. The actual total length is got with getLengthTotal().
    
    Returns:
    
    The number of bytes of the data in the buffer.
  - getData
```
private final byte[] getData(int recursion)
```
    Gets the data from parent if data == null
    
    Parameters:
    
    recursion - if <0 ends and call throwexc(String, int)
    
    Returns:
    
    data, maybe null if all parents have null.
    
    Since:
    
    2018-09
  - XXXrewind
```
public final void XXXrewind()
```
    starts the calling loop of next(). The calling of next() after them supplies the first child element.
  - getLengthHead
```
public final int getLengthHead()
```
    Returns the length of the head. This method returns the size of the head given on construction The size of the head cannot changed for an existing instance.
  - getLengthCurrent
```
public final int getLengthCurrent()
```
    Returns the length of the element with all yet added children. It is the current used length of this element. Note that getLength() returns the length which may be not evaluated with children up to know but given with assign(byte[], int).
    
    Returns:
    
    index of the current child's end of this element relative to this start position.
  - getLength
```
public final int getLength()
```
    Returns the length of the existing actual element.
    
    Returns:
    
    The number of bytes of the actual element in the buffer. It is (idxEnd - idxBegin).
  - getLengthTotal
```
public final int getLengthTotal()
```
    Returns the length of the data.
    
    Returns:
    
    The number of bytes of data in the buffer. It is idxEnd.
  - getMaxNrofBytes
```
public final int getMaxNrofBytes()
```
    returns the number number of bytes there are max available from position of the current child. , the number of bytes to the end of buffer is returned.
    
    Returns:
    
    nrofBytes that should fitting in the given data range from current child position to the end of data determines by calling assingData(...) or by calling addChild() with a known size of child or setLengthElement() .
  - checkLengthElement
```
public final boolean checkLengthElement(int size)
```
    Checks whether a given size is possible as setLengthElement(int) for the given instance. size >= sizeHead. If this is set to expand it returns end <= data.length else it returns end <= ixEnd whereby end means the end position of the element ixNextChild which will be given after call of #setLengthElement(size). This method checks whether a calculated length is proper. If this method returns false and setLengthElement(int) is called notwithstanding the setLengthElement(int) throws an IllegalArgumentException. See getMaxNrofBytes(), this routine is used.
    
    Parameters:
    
    size -
    
    Returns:
  - getBigEndian
```
public final boolean getBigEndian()
```
  - setLengthElement
```
public final void setLengthElement(int length)
```
    Sets the length of the element in this and all parent of this. The ixEnd of this is set with the (this.ixBegin+length). This method sets this as not expandable, but does not change the expandable status of the parent. The ixNextChild of all parents are set to this index. So adding another child to the parent starts with that given position. A parent is expand if necessary.
    
    This routine is usefully for example if the length of a part of data is determined in the data itself.
    
    Parameters:
    
    length - The length of data of this current (last) child.
  - clearHead
```
public final void clearHead()
```
    Sets all data of the head of this element to 0. Note: If the element has not a head, this method does nothing.
  - clearData
```
public final void clearData()
```
    Sets all data of this element to 0. Note: The idxEnd should be set to the end of the element. This method is proper to use for a simple element only.
  - isInUse
```
public final boolean isInUse()
```
  - isCurrentChildInParent
```
public final boolean isCurrentChildInParent()
```
  - sufficingBytesForNextChild
```
public final boolean sufficingBytesForNextChild(int nrofBytes)
                                         throws java.lang.IllegalArgumentException
```
    returns true if the given number of bytes is sufficing in the data from position of next child.
    
    Parameters:
    
    nrofBytes - that should fitting in the given data range from current child position to the end of data determines by calling assingData(...) or by calling addChild() with a known size of child or setLengthElement() .
    
    Returns:
    
    true if it is okay, false if the nrofBytes are negative or to large.
    
    Throws:
    
    java.lang.IllegalArgumentException - see getMaxNrofBytesForNextChild()
  - getMaxNrofBytesForNextChild
```
public final int getMaxNrofBytesForNextChild()
                                      throws java.lang.IllegalArgumentException
```
    returns the maximal number of bytes which are available from position of a next current child. It returns (ixEnd - ixChildEnd) for non-expandable instances respectively data.length - ixChildEnd if this is expandable. With this information any child which head length is less or equal can be added to check whether it is matched to the data.
    
    Returns:
    
    nrofBytes that should fitting in the given data range from current child position to the end of data determines by calling assingData(...) or by calling addChild() with a known size of child or setLengthElement() .
    
    Throws:
    
    java.lang.IllegalArgumentException
  - addChild
```
public final boolean addChild(ByteDataAccessBase child,
                              int sizeChild)
                       throws java.lang.IllegalArgumentException
```
    Adds a child Element after the current child or as first child after head. With the aid of the child Element the data can be read or write structured.
    
    The child instance will be initialized newly. Any old usage of the child instance will be ignored. The child is a helper to get data and to manage the indices. The child can be used to add further children to build a tree of children for complex structured data.
    
    Some children can be added after a parent like following sample:
```
 ByteAccessDerivation child = new ByteAccessDerivation();  //empty and unassigned.
 ...
 parent.addChild(child);        //The byte[] data of parent are assigned, index after current child index of parent.
 child.addChild(grandchild);    //By adding a child to this child, also the parent's index is corrected.
 
```
    Indices in the parent and child:
    If no child is added yet, the indices have the following values:
    - ixNextChild == sizeHead
    - ixEnd == either given data length or sizeHead if bExpand == true.
    - currChild == null
    A call of addChild() or its adequate derived addChildXY() sets the indices after the given current child:
    - ixNextChild == the index after the child, either after its head data or after the given length.
    - ixEnd == either left unchanged if bExpand == false or incremented, maximum of added children
    - currChild == added child, used for debug view, #rewind() etc.
    The length of the current Child may be increased while evaluating the child's data. The user should call setLengthElement(int) with the child or add some more grand children.
    
    data, charset, expand: That properties are inherit from the parent (this).
    Parameters:
    
    child - The child will be assigned with the data of this at index after the current child's end-index. Note that the child's sizeHead should be set correctly.
    
    sizeChild - The number of bytes which are used from the child or 0. If it is 0, then the child's sizeHead is used to set the position of a possible next children ixNextChild, elsewhere ixNextChild is set using that value. The child itself does not use this value.
    
    Returns:
    
    true if success, false if the child cannot be added because there is no space for it and bExc is false.
    
    Throws:
    
    java.lang.IllegalArgumentException - if the length of the head of the new current child is to far for the data. It means, child.idxEnd > data.length.
  - addChild
```
public final boolean addChild(ByteDataAccessBase child)
```
    Adds a child with its given head size without additional data space. It calls addChild(ByteDataAccessBase, int).
    
    Parameters:
    
    child - The child will be initialized newly.
  - addChildEmpty
```
public final boolean addChildEmpty(ByteDataAccessBase child)
```
  - addChildEmpty
```
public final boolean addChildEmpty(ByteDataAccessBase child,
                                   int sizeChild)
```
  - addChildAt
```
public final void addChildAt(int idxChild,
                             ByteDataAccessBase child,
                             int sizeChild)
                      throws java.lang.IllegalArgumentException
```
    Adds a child at any position. This method is usefully if the data structure is known and specific elements should be accessed. The child can be used to detect data in a sub structure.
    
    Parameters:
    
    idxChild - The index from the position of this (from this.ixBegin). It is not the index inside the data. If ixBegin ==0 because this is the root ByteDataAccess instance, it is the index in data.
    
    child - An empty instance for a child with given child.sizeHead. Usual instances are re-used (especially in a C-environment). child will be filled completely. A content before is cleared except the child.sizeHead. This value should be known in the child.
    
    sizeChild - The size of the child. It may be 0, but >=0 (asserted)
    
    Throws:
    
    java.lang.IllegalArgumentException
  - addChildAt
```
public final void addChildAt(int idxChild,
                             ByteDataAccessBase child)
                      throws java.lang.IllegalArgumentException
```
    Adds a child at any position with its head size. This method is usefully if the data structure is known and specific elements should be accessed. The child can be used to detect data in a sub structure.
    
    Parameters:
    
    idxChild - The index from the position of this (from this.ixBegin). It is not the index inside the data. If ixBegin ==0 because this is the root ByteDataAccess instance, it is the index in data.
    
    child - An empty instance for a child with given child.sizeHead. Usual instances are re-used (especially in a C-environment). child will be filled completely. A content before is cleared except the child.sizeHead. This value should be known in the child.
    
    Throws:
    
    java.lang.IllegalArgumentException
    
    java.lang.IllegalArgumentException
  - addChildInt
```
public final boolean addChildInt(int nrofBytes,
                                 int value)
                          throws java.lang.IllegalArgumentException
```
    Adds a child for 1 integer value without a child instance, and sets the value as integer.
    
    Parameters:
    
    nrofBytes - of the integer
    
    Returns:
    
    value in long format, cast it to (int) if you read only 4 bytes etc.
    
    Throws:
    
    java.lang.IllegalArgumentException
  - addChildInteger
```
public final boolean addChildInteger(int nrofBytes,
                                     long value)
                              throws java.lang.IllegalArgumentException
```
    Adds a child for 1 integer value without a child instance, and sets the value as integer.
    
    Parameters:
    
    nrofBytes - of the integer
    
    Returns:
    
    value in long format, cast it to (int) if you read only 4 bytes etc.
    
    Throws:
    
    java.lang.IllegalArgumentException
  - addChildFloat
```
public final boolean addChildFloat(float value)
                            throws java.lang.IllegalArgumentException
```
    Adds a child for 1 float value without a child instance, and sets the value as float. The indices of this are incremented to the next child position after the added float value. The byte representation is the IEEE 754 floating-point "single format" bit layout, preserving Not-a-Number (NaN) values. See Float.floatToRawIntBits(float).
    
    Returns:
    
    value in long format, cast it to (int) if you read only 4 bytes etc.
    
    Throws:
    
    java.lang.IllegalArgumentException
  - addChildString
```
public final boolean addChildString(java.lang.String value,
                                    java.lang.String sEncoding,
                                    boolean preventCtrlChars)
                             throws java.lang.IllegalArgumentException,
                                    java.io.UnsupportedEncodingException
```
    Adds a child with String value.
    
    Parameters:
    
    value - String to add
    
    sEncoding - If null then use the standard encoding of the system-environment.
    
    preventCtrlChars - true then values < 0x20 are not set. If the String value contain a control character with code < 0x20, a '?' is written. This behavior guarantees, that byte-values < 0x20 can use to detect no-String elements, see getByteNextChild().
    
    Throws:
    
    java.lang.IllegalArgumentException
    
    java.io.UnsupportedEncodingException
  - addChildString
```
public final boolean addChildString(java.lang.CharSequence valueCs,
                                    java.lang.String sEncoding)
                             throws java.lang.IllegalArgumentException,
                                    java.io.UnsupportedEncodingException
```
    Adds a child with String value.
    
    Parameters:
    
    valueCs - String to add, @pjava2c=nonPersistent.
    
    sEncoding - String describes the encoding for translation from UTF16 to bytes.
    
    Throws:
    
    java.lang.IllegalArgumentException - XXX
    
    java.io.UnsupportedEncodingException
  - addChildString
```
public final void addChildString(java.lang.CharSequence value)
                          throws java.lang.IllegalArgumentException
```
    Adds a child with String value.
    
    Parameters:
    
    value - String to add, @pjava2c=nonPersistent.
    
    Throws:
    
    java.lang.IllegalArgumentException
  - getChildInt16
```
public final short getChildInt16()
```
    Adds a child for 1 short value without a child instance, returns the value as short.
    
    Returns:
    
    The value which is represented by the next bytes after the current child before call this routine.
  - getChildUint16
```
public final int getChildUint16()
```
    Adds a child for 1 short value without a child instance, returns the value as short.
    
    Returns:
    
    The value which is represented by the next bytes after the current child before call this routine.
  - getChildUint8
```
public final short getChildUint8()
```
    Adds a child for 1 short value without a child instance, returns the value as short.
    
    Returns:
    
    The value which is represented by the next bytes after the current child before call this routine.
  - getChildInteger
```
public final long getChildInteger(int nrofBytes)
                           throws java.lang.IllegalArgumentException
```
    adds a child for 1 integer value without a child instance and returns the value as long integer.
    
    Parameters:
    
    nrofBytes - of the integer, if negative then gets as signed integer, elsewhere as unsigned
    
    Returns:
    
    value in long format, cast it to (int) if you read only 4 bytes etc.
    
    Throws:
    
    java.lang.IllegalArgumentException - if not data has not enaught bytes.
  - getChildInt
```
public final int getChildInt(int nrofBytes)
                      throws java.lang.IllegalArgumentException
```
    Adds a child for 1 integer value without a child instance and returns the value as 32-bit-integer.
    
    Parameters:
    
    nrofBytes - of the integer, if negative then gets as signed integer, elsewhere as unsigned, Only till 4.
    
    Returns:
    
    value in int format.
    
    Throws:
    
    java.lang.IllegalArgumentException - if not data has not enaught bytes.
  - getChildFloat
```
public final float getChildFloat()
                          throws java.lang.IllegalArgumentException
```
    Adds a child for 1 float value without a child instance, but returns the value as integer.
    
    Returns:
    
    value in float format
    
    Throws:
    
    java.lang.IllegalArgumentException - if not data has not enaught bytes.
  - getChildDouble
```
public final double getChildDouble()
                            throws java.lang.IllegalArgumentException
```
    Adds a child for 1 double value without a child instance, but returns the value as integer.
    
    Returns:
    
    value in float format
    
    Throws:
    
    java.lang.IllegalArgumentException - if not data has not enaught bytes.
  - getChildString
```
public final java.lang.String getChildString(int nrofBytes)
```
    Adds a child for a String value without a child instance, but returns the value as String.
    
    Parameters:
    
    nrofBytes - of the String maybe with 0-bytes on end which will be removed (alignment).
    
    Returns:
    
    value as String
    
    Throws:
    
    java.lang.IllegalArgumentException - if not data has not enough bytes.
    
    java.io.UnsupportedEncodingException
  - removeChild
```
public final void removeChild()
                       throws java.lang.IllegalArgumentException
```
    Removes the current child to assign another current child instead on the position of the current child. This method is usefully if data are tested with several structures. See removeChild(ByteDataAccessBase).
    
    Parameters:
    
    child -
    
    Throws:
    
    java.lang.IllegalArgumentException
  - removeChild
```
public final void removeChild(ByteDataAccessBase child)
```
    Shorten the evaluated content of the data to the position of the given child. The given child is removed. See removeChild(). The ixEnd is set to ixNextChild if the expand mode is set. In expand mode the ixEnd is set to the ixNextChild, to the current child position. The content which was written before at following positions is not removed. It means a content can be written with one child type, and checked with another child type after them.
    
    Parameters:
    
    child - It should be a child of this. The parent of the child should be this.
  - removeChildren
```
public final void removeChildren()
```
    Remove all children. Let the head unchanged.
    
    Since:
    
    2010-11-16
  - detach
```
public final void detach()
```
    Remove all connections. Especially for children.
  - getPositionInBuffer
```
public final int getPositionInBuffer()
```
    Returns the position of the Element data in the assigned buffer.
    
    Returns:
    
    index of this element in the data buffer.
  - getPositionNextChildInBuffer
```
public final int getPositionNextChildInBuffer()
```
    Returns the position of a next child which can be added in the assigned buffer. See getLengthCurrent().
    
    Returns:
    
    index of the current child's end of this element in the data buffer.
  - copyDataFrom
```
public final void copyDataFrom(ByteDataAccessBase src)
                        throws java.lang.IllegalArgumentException
```
    copies the data from another references data into this data. The src is positioned to any child. That's data are copied in this data at the position of this child. The length of both children should be equal. If it is not so, the routines throws or copies the lesser length Note this method is never used in actual implementations of vishia. Check whether it is necessary.
    
    Throws:
    
    java.lang.IllegalArgumentException
  - copyData
```
public final void copyData(int[] dst)
```
    copies some data to a int[], primarily to debug a content.
    
    Parameters:
    
    dst - This array is field, but only from data of the current element between idxBegin and idxEnd
  - getString
```
protected final java.lang.String getString(int idx,
                                           int nrofBytes)
```
    Returns a String from the given position inside the actual element . The bytes are interpreted in the given encoding. 0-characters on end of the spread in child till idx + nrofBytes are not taken as String characters. They are 4-byte-alignment fill bytes usually. 0-bytes inside the String are taken as normal characters.
    
    Parameters:
    
    idx - The start position inside the child.
    
    nrofBytes - The number of bytes to build the String.
    
    Returns:
    
    The String representation of the bytes. Note: In C the String refers the bytes in data.
    
    Throws:
    
    java.lang.IndexOutOfBoundsException - if any index is faulty.
  - setString
```
protected final int setString(int idx,
                              int nmax,
                              java.lang.String ss)
```
    Sets a String to the the given position inside the actual element . The bytes are interpreted in the given encoding.
    
    Parameters:
    
    idx - The start position inside the child.
    
    nmax - Maximal number of bytes
    
    ss - The String representation of the bytes.
    
    Returns:
    
    Number of written chars.
    
    Throws:
  - _setString
```
protected final void _setString(int idx,
                                int nrofBytes,
                                java.lang.String value,
                                java.lang.String sEncoding,
                                boolean preventCtrlChars)
                         throws java.io.UnsupportedEncodingException
```
    sets the content inside the actual element with the character bytes from the given String. This method is protected because at user level its using is a prone to errors because the idx is free related.
    
    Parameters:
    
    idx - the position in the actual element, the data are set to data[idxBegin+idx].
    
    nrofBytes - The length of the byte[] area to set. If the String value is longer as nrofBytes, it will be truncated. No exception occurs. If the String is shorter as nrofBytes, the rest is filled with 0.
    
    value - The String value.
    
    sEncoding - The encoding of the String. null: Use standard encoding.
    
    preventCtrlChars - true then values < 0x20 are not set. If the String value contain a control character with code < 0x20, a '?' is written. This behavior guarantees, that byte-values < 0x20 can use to detect no-String elements, see getByteNextChild().
    
    Throws:
    
    java.io.UnsupportedEncodingException
  - getFloat
```
protected final float getFloat(int idx)
```
    Gets a float value from the content of 4 byte. The float value is red according to the IEEE 754 floating-point "single format" bit layout, preserving Not-a-Number (NaN) values, like converted from java.lang.Float.intBitsToFloat().
  - getDouble
```
protected final double getDouble(int idx)
```
  - getInt64
```
protected final long getInt64(int idx)
```
  - getInt32
```
protected final int getInt32(int idx)
```
    Returns the content of 4 bytes inside the actual element as a integer number between -2147483648 and 2147483647, big- or little-endian depending on setBigEndian().
    
    Parameters:
    
    idx - the position of leading byte in the actual element, the data are raken from data[idxBegin+idx]. This is not the absolute position in data, idxBegin is added.
    
    Returns:
    
    the integer value in range from -2147483648 and 2147483647
  - getUint32
```
protected final int getUint32(int idx)
```
  - getUint16
```
protected final int getUint16(int idx)
```
    Returns the content of 2 bytes as a positive nr between 0..65535, big-endian inside the actual element.
    
    Parameters:
    
    idx - the position of leading byte in the actual element, the data are raken from data[idxBegin+idx]. This is not the absolute position in data, idxBegin is added.
    
    Returns:
    
    the integer value in range from -32768 to 32767
  - getInt16
```
protected final short getInt16(int idx)
```
    Returns the content of 2 bytes as a positive nr between 0..65535 inside the actual element.
    
    Parameters:
    
    idx - the position of leading byte in the actual element, the data are raken from data[idxBegin+idx]. This is not the absolute position in data, idxBegin is added.
    
    Returns:
    
    the integer value in range from -32768 to 32767
  - getChar
```
protected final char getChar(int idx)
```
    Returns the content of 1 bytes as ASCII inside the actual element.
    
    Parameters:
    
    idx - the position of char in the actual element, the data are raken from data[idxBegin+idx]. This is not the absolute position in data, idxBegin is added.
    
    Returns:
    
    the ASCII value
  - getInt8
```
protected final byte getInt8(int idx)
```
    Returns the content of 1 bytes as a positive or negative nr between -128..127 inside the actual element.
    
    Parameters:
    
    idx - the position of leading byte in the actual element, the data are raken from data[idxBegin+idx]. This is not the absolute position in data, idxBegin is added.
    
    Returns:
    
    the integer value in range from -32768 to 32767
  - getUint8
```
protected final short getUint8(int idx)
```
    Returns the content of 1 bytes as a positive or negative nr between -128..127 inside the actual element.
    
    Parameters:
    
    idx - the position of leading byte in the actual element, the data are raken from data[idxBegin+idx]. This is not the absolute position in data, idxBegin is added.
    
    Returns:
    
    the integer value in range from -32768 to 32767
  - getUint32
```
protected final int getUint32(int idxBytes,
                              int idxArray,
                              int lengthArray)
```
  - getInt32
```
protected final int getInt32(int idxBytes,
                             int idxArray,
                             int lengthArray)
```
  - getInt16
```
protected final int getInt16(int idxBytes,
                             int idxArray,
                             int lengthArray)
```
  - getInt8
```
protected final int getInt8(int idxBytes,
                            int idxArray,
                            int lengthArray)
```
  - getUint16
```
protected final int getUint16(int idxBytes,
                              int idxArray,
                              int lengthArray)
```
  - getUint8
```
protected final int getUint8(int idxBytes,
                             int idxArray,
                             int lengthArray)
```
  - getFloat
```
protected final float getFloat(int idxBytes,
                               int idxArray,
                               int lengthArray)
```
  - setFloat
```
protected final void setFloat(int idx,
                              float value)
```
    Set the content of 4 byte from a float variable. The float value is stored according to the IEEE 754 floating-point "single format" bit layout, preserving Not-a-Number (NaN) values, like converted from java.lang.Float.floatToRawIntBits().
  - setDouble
```
protected final void setDouble(int idx,
                               double value)
```
    Set the content of 8 byte from a double variable. The double value is stored according to the IEEE 754 floating-point "double format" bit layout, preserving Not-a-Number (NaN) values, like converted from java.lang.Double.doubleToRawLongBits().
  - setInt32
```
protected final void setInt32(int idx,
                              int value)
```
    Set the content of 4 bytes as a integer number between -2147483648 and 2147483647, big- or little-endian depended from setBigEndian().
    
    Parameters:
    
    idx - The position of leading byte in the current elements data. This is not the absolute position in data, idxBegin is added.
    
    value - The value in range 0..65535. The value is taken modulo 0xffffffff.
  - setInt8
```
protected final void setInt8(int idx,
                             int value)
```
    Set the content of 1 bytes as a positive nr between 0..256.
    
    Parameters:
    
    idx - The position of leading byte in the current elements data. This is not the absolute position in data, idxBegin is added.
    
    value - The value in range 0..65535. The value is taken modulo 0xffff.
  - setUint8
```
protected final void setUint8(int idx,
                              int value)
```
    Set the content of 1 bytes as a positive nr between 0..255, big- or little-endian.
    
    Parameters:
    
    idx - The position of leading byte in the current elements data. This is not the absolute position in data, idxBegin is added.
    
    value - The value in range 0..65535. The value is taken modulo 0xff.
  - setUint32
```
protected final void setUint32(int idx,
                               long value)
```
    Set the content of 4 bytes as a positive nr between 0..2pow32-1, big- or little-endian.
    
    Parameters:
    
    idx - The position of leading byte in the current elements data. This is not the absolute position in data, idxBegin is added.
    
    value - The value as long. The value is taken modulo 0xffffffff.
  - setInt16
```
protected final void setInt16(int idx,
                              int value)
```
    Set the content of 2 bytes from an integer between -32768..32768, or from an integer number between 0..65535. The value is interpreted from the input parameter with modulo 0x10000. Big- or little-endian.
    
    Parameters:
    
    idx - The position of leading byte in the current elements data. This is not the absolute position in data, idxBegin is added.
    
    value - The value in range 0..65535. The value is taken modulo 0xffff.
  - setUint16
```
protected final void setUint16(int idx,
                               int value)
```
    Set the content of 2 bytes as a positive nr between 0..65535, big- or little-endian.
    
    Parameters:
    
    idx - The position of leading byte in the current elements data. This is not the absolute position in data, idxBegin is added.
    
    value - The value in range 0..65535. The value is taken modulo 0xffff.
  - throwexc
```
private final void throwexc(java.lang.String text,
                            int idxArray)
```
  - setUint32
```
protected final void setUint32(int idxBytes,
                               int idxArray,
                               int lengthArray,
                               int val)
```
  - setInt32
```
protected final void setInt32(int idxBytes,
                              int idxArray,
                              int lengthArray,
                              int val)
```
  - setInt16
```
protected final void setInt16(int idxBytes,
                              int idxArray,
                              int lengthArray,
                              int val)
```
  - setInt8
```
protected final void setInt8(int idxBytes,
                             int idxArray,
                             int lengthArray,
                             int val)
```
  - setUint16
```
protected final void setUint16(int idxBytes,
                               int idxArray,
                               int lengthArray,
                               int val)
```
  - setUint8
```
protected final void setUint8(int idxBytes,
                              int idxArray,
                              int lengthArray,
                              int val)
```
  - setFloat
```
protected final void setFloat(int idxBytes,
                              int idxArray,
                              int lengthArray,
                              float val)
```
  - setIdxtoNextCurrentChild
```
private final int setIdxtoNextCurrentChild(int sizeChild)
```
    Prepares a new child for this. It sets the this.ixNextChild to the end of the new child given by argument sizeChild. The size of the new child, at least its head size, should be known. It is given by the calling argument sizeChild.
    
    This method is called while addChild. The state before is:
    - ixChildEnd is the actual end index of the current Child, or the index of the first child (after head, may be also 0 if the head has 0 bytes), if no child was added before. ixChildEnd is always positive and should be valid.
    The state after is:
    - ixChildEnd is set to the ixChild + argument sizeChild.
    The size of the child may be increased later by calling addChild(ByteDataAccessBase) for an added child or by calling setLengthElement(int) for the child. Therefore an argument =0 is possible.
    
    The method is package private because it should not invoked from the user directly.
    Parameters:
    
    sizeChild - yet known size of the child to add. It have to be >=0.
    
    Returns:
    
    position in data of the current child, that is the ixNextChild() before this is processed. returns -1 if the child cannot be added.
  - ixBegin
```
protected final int ixBegin()
```
  - ixNextChild
```
protected final int ixNextChild()
```
  - ixEnd
```
protected final int ixEnd()
```
  - checkData
```
boolean checkData()
```
    Checks data == null and gets the data from parent if necessary. With them it is possible to call assign(byte[]) for the parent only and it runs. If the data remain null throwexc(String, int) is invoked. It may force an exeption if that is activated. Elsewhere it returns false, to force prevent access to data in the calling routine.
    
    Returns:
    
    false if data remain == null
    
    Since:
    
    2018-09
  - infoFormattedAppend
```
public void infoFormattedAppend(StringFormatter u)
```
    Appends the information about the indices and the current Children. For C it is excluded because it is only for test.
    
    Specified by:
    
    infoFormattedAppend in interface InfoFormattedAppend
    
    See Also:
    
    InfoFormattedAppend.infoFormattedAppend(org.vishia.util.StringFormatter)
  - infoAppendHead
```
protected void infoAppendHead(StringFormatter u,
                              int bytesHex)
```
    Appends information about the head of the given element.
    
    Parameters:
    
    u - The destination buffer
    
    bytesHex - Number of shown bytes of data as hexa line.
  - toString
```
public java.lang.String toString()
```
    This method is especially usefully to debug in eclipse. It shows the first bytes of head, the position of child and the first bytes of the child.
    
    Overrides:
    
    toString in class java.lang.Object

Class ByteDataAccessBase

Initialization and instances

children, currentChild, addChild

Expand, check

Examples

Nested Class Summary

Nested classes/interfaces inherited from interface org.vishia.util.InfoFormattedAppend

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

version

sizeHead

data

ixBegin

ixBeginLocal

ixNextChild

ixEnd

bExpand

bBigEndian

bLittleEndianBig2

bExc

parent

currChild

charset

toStringformatter

Constructor Detail

ByteDataAccessBase

ByteDataAccessBase

Method Detail

setBigEndian

setLittleEndianBig2

setException

setCharset

_getLong

_getInt

_setLong

_setInt

_expand

assignDataToFixChildren

assign

assign

assign

assignClear

assignAt

assignAt

assignCasted

copyStdValues

upcast

isExpandable

sizeHead

getData

data

getData

XXXrewind

getLengthHead

getLengthCurrent

getLength

getLengthTotal

getMaxNrofBytes

checkLengthElement

getBigEndian

setLengthElement

clearHead

clearData

isInUse

isCurrentChildInParent

sufficingBytesForNextChild

getMaxNrofBytesForNextChild

addChild

addChild

addChildEmpty

addChildEmpty

addChildAt

addChildAt

addChildInt

addChildInteger

addChildFloat

addChildString