org.vishia.util

Class DataAccess

java.lang.Object

org.vishia.util.DataAccess

Direct Known Subclasses:

DataAccess.DataAccessSet

public class DataAccess
extends java.lang.Object

This class contains methods to access and set data and invoke methods with symbolic access using reflection mechanism. The class is helpful to deal with reflection. Some methods are offered to make it simply. This class is independent of other classes else Assert and TreeNodeBase. The last one is checked whether it is used as container. It is not necessary to work with.

All methods throws the proper exception if anything is not correct. The user should catch it if necessary.

• Simple access to fields, also to super and enclosing instances
• Access to referred instance in one method.
• access to container with a name as key similar to fields.
• Support a datapool using variables
• Invocation of methods and creation of instances (Constructor)
• Working with additional ClassLoader

public static methods:

• #getDataFromField(String, Object, boolean): Data from one instance, also from super and enclosing. Enhances Class.getField(String) and Field.get(Object)
• #getData(String, Object, boolean, boolean): Data from one instance. If the instance is a Map it accessed to an element of this container. Elsewhere it tries to get from a field. Invokes #getDataFromField(String, Object, boolean).
• invokeNew(DatapathElement) creates an instance by symbolic name maybe with parameters, maybe with another ClassLoader (from additional jar files etc.). Enhances Class.newInstance() and Constructor.newInstance(java.lang.Object...).
• #invokeMethod(DatapathElement, Class, Object, boolean, boolean) invokes a static method by symbolic name maybe with parameters, maybe with another ClassLoader (from additional jar files etc.). Enhances Class.getMethod(String, Class...) and Method.invoke(Object, Object...).
• #access(List, Object, Map, boolean, boolean, boolean, Dst) Data from a complex referenced instance maybe with method invocations and creation of instances. It uses a List< DataAccess.DatapathElement> to access, it uses method arguments. Static methods and creation of instances can invoked too. See DataAccess.DatapathElement.
• #access(CharSequence, Object, Map, boolean, boolean, boolean, Dst): Path String given.
• #storeValue(List, Map, Object, boolean) stores instead accesses
• #setVariable(Map, String, Object), getVariable(Map, String, boolean): Deal with variables.
• getEnclosingInstance(Object): Gets the enclosing instance
• getStringFromObject(Object, String), getInt(Object), getFloat(Object): access to simple data, conversions.
• setBit(int, int, boolean) Helper to deal with bits
• getInt(Object), getFloat(Object) etc.

This class can hold a datapath, see add_datapathElement(DatapathElement) and can access with this path using the non-static method #access(Map, boolean, boolean).

Datapath elements are stored in DataAccess.DatapathElement and DataAccess.DatapathElementClass.

A DataAccess.Variable is a wrapper for any Object which is used and regarded. Sometimes the Variable is returned which's content can be changed: DataAccess.Variable.setValue(Object). A Variable is helpfully if the content of referenced instances should be changed without changing all references:

      any_instance---------------->|
      other_instance-------------->|
                              Variable
                                   |--value------->references_somewhat
                                       ^   \
                                       |    ------>other_reference
                                     is changed:  
 

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
private static interface	DataAccess.Conversion Interface to convert between data.
private static class	DataAccess.Conversions This inner class contains all possible automatic special conversions.
static class	DataAccess.DataAccessSet This class extends its outer class and provides the capability to set the data path especially from a ZBNF parser result.
static class	DataAccess.DatapathElement Class holds one element for access to data.
static class	DataAccess.DatapathElementClass Variant of a DatapathElement which can contain a ClassLoader for a new Java class or a static method invocation or a Class which's field, method or constructor should access.
static class	DataAccess.Dst Result of an DataAccess#access(List, Object, Map, boolean, boolean, boolean, Dst) to store a value.
static class	DataAccess.IntegerIx Wrapper around the index as integer.
static class	DataAccess.ObjMethod
static class	DataAccess.SetDatapathElement This class extends a DataAccess.DatapathElement and provides the capability to set the data path especially from a ZBNF parser result, see ZbnfJavaOutput.
static class	DataAccess.Test
static class	DataAccess.Variable<T> This class wraps any Object which is used for a variable.

Field Summary

Fields

Modifier and Type	Field and Description
protected java.util.List<DataAccess.DatapathElement>	datapath The description of the path to any data if the script-element refers data.
private static java.lang.String	debugIdent Can be set immediately for debug approach.
private static java.lang.String	debugMethod
private static java.util.Map<java.lang.String,DataAccess.Conversion>	idxConversions
static java.lang.String	sVersion Version, history and license.

Constructor Summary

Constructors

Constructor and Description
DataAccess() Empty constructor.
DataAccess(java.lang.String path) Creates a Datapath with given String.
DataAccess(java.lang.String path, char cTypeNewVariable) Creates a Datapath with given String.
DataAccess(StringPartScan sp, java.util.Map<java.lang.String,DataAccess.IntegerIx> nameVariables, java.lang.Class<?> reflData, char cTypeNewVariable) Creates a Datapath with given StringPartScan.

Method Summary

Modifier and Type	Method and Description
static java.lang.Object	access(java.lang.CharSequence datapathArg, java.lang.Object dataRoot, boolean accessPrivate, boolean bContainer, boolean bVariable, DataAccess.Dst dst) Accesses data with a String given path.
static java.lang.Object	access(DataAccess.DatapathElement element, java.lang.Object data1, boolean accessPrivate, boolean bContainer, java.util.Map<java.lang.String,DataAccess.IntegerIx> nameVariables, java.lang.Object[] varValues, boolean bVariable, DataAccess.Dst dst) Access to the given element, used internally, also able to use for one element form extern.
static java.lang.Object	access(java.util.List<DataAccess.DatapathElement> datapathArg, java.lang.Object dataRoot, boolean accessPrivate, boolean bContainer, java.util.Map<java.lang.String,DataAccess.IntegerIx> nameVariables, java.lang.Object[] varValues, boolean bVariable, DataAccess.Dst dst) Universal method to accesses data.
java.lang.Object	access(java.lang.Object dataRoot, boolean accessPrivate, boolean bContainer, java.util.Map<java.lang.String,DataAccess.IntegerIx> nameVariables, java.lang.Object[] varValues) Searches the Object maybe invoking some methods which is referred with this instances, datapath.
void	add_datapathElement(DataAccess.DatapathElement item) Sets the datapath while adding one element after another.
protected static java.lang.Object[]	checkAndConvertArgTypes(java.lang.Object[] providedArgs, java.lang.Class<?>[] argTypes) Checks whether the given arguments matches to the necessary arguments of a method or constructor invocation.
static DataAccess.Conversion	checkArgTypes(java.lang.Class<?> argType, java.lang.Class<?> actType, java.lang.Object arg) Checks whether the given actType with its value arg matches to the given argType.
private static DataAccess.Conversion	checkIfcTypes(java.lang.Class<?> argType, java.lang.Class<?> ifcType, java.lang.Object arg)
static DataAccess.Conversion	checkTypes(java.lang.Class<?> argType, java.lang.Class<?> actType, java.lang.Object arg) Checks whether a given type with its value can be converted to a destination type.
static DataAccess.Variable<java.lang.Object>	createOrReplaceVariable(java.util.Map<java.lang.String,DataAccess.Variable<java.lang.Object>> map, java.lang.String name, char type, java.lang.Object content, boolean isConst) Creates or replaces a variable with a simple name in the given container.
java.util.List<DataAccess.DatapathElement>	datapath() Returns the datapath of this access to check details.
protected static void	debug() Set a breakpoint here to edit a debugIdent(String)
static void	debugIdent(java.lang.String ident) A debug helper: Set this ident to any String, which is expected for access.
static void	debugMethod(java.lang.String ident) A debug helper: Set this identifier to any String, which is expected for invocation of a method.
static java.util.List<DataAccess.DatapathElement>	expandElements(java.lang.CharSequence path, char whatisit) Splits a String given path to elements.
static java.lang.Object	getArrayElement(java.lang.Object data, int... ixArray) Gets the indexed element of the given array.
private static java.lang.Class<?>	getClass(java.lang.String name)
private static java.lang.ClassLoader	getClassLoader(DataAccess.DatapathElement element)
static java.lang.Object	getData(java.lang.String name, java.lang.Object instance, boolean accessPrivate, boolean bContainer, boolean bVariable, DataAccess.Dst dst) Gets data from a field or from an indexed container.
private static java.lang.Object	getDataFromField(java.lang.String name, java.lang.Object obj, boolean accessPrivate, java.lang.Class<?> clazz, DataAccess.Dst dst, int recursiveCt) Core method to get data from a field, static or non static
static java.lang.Object	getDataFromField(java.lang.String name, java.lang.Object obj, boolean accessPrivate, DataAccess.Dst dst) Returns the data which are stored in the named field of the given instance.
private static java.lang.Object	getDataPriv(java.lang.String name, java.lang.Object instance, boolean accessPrivate, boolean bContainer, boolean bVariable, DataAccess.Dst dst) It does not resolve the instance if it is a Variable
private static java.lang.Object	getEnclosingInstance(int recurs, java.lang.Object obj)
static java.lang.Object	getEnclosingInstance(java.lang.Object obj) Returns the enclosing instance (outer class) of an instance which is type of any inner non-static class.
static float	getFloat(java.lang.Object val) Gets the float value from any Object.
static int	getInt(java.lang.Object val) Gets the int value from any Object.
static int	getLengthOfArray(java.lang.Object data) Checks whether data is an array and returns the current number of elements.
protected static java.lang.Object	getStaticValue(DataAccess.DatapathElement element) Invokes the static method which is described with the element.
static java.lang.String	getStringFromObject(java.lang.Object content, java.lang.String format) Returns a string representation of the object.
static DataAccess.Variable<java.lang.Object>	getVariable(java.util.Map<java.lang.String,DataAccess.Variable<java.lang.Object>> map, java.lang.String name, boolean strict) Searches the variale in the container and returns it.
java.lang.CharSequence	idents() Returns a CharSequence with the idents of the path separated with "."
(package private) static java.util.Map<java.lang.String,DataAccess.Conversion>	initConversion() This method initializes the internal conversion index.
int	intFromUnsignedShort(short val) Converts a value in a short to a unsigned value, which can be stored in a int in Java.
static java.lang.Object	invokeMethod(DataAccess.DatapathElement element, java.lang.Class<?> clazz, java.lang.Object obj, boolean accessPrivate, boolean bNoExceptionifNotFound, java.lang.Object[] args) Invokes the method which is described with the element with given immediately calling arguments.
static java.lang.Object	invokeMethod(DataAccess.DatapathElement element, java.lang.Class<?> clazz, java.lang.Object obj, boolean accessPrivate, java.lang.Object[] varValues, boolean bNoExceptionifNotFound) Prepares firstly the arguments of the method and invokes the method.
protected static java.lang.Object	invokeNew(DataAccess.DatapathElement element) Invokes the static method which is described with the element.
protected static java.lang.Object	invokeStaticMethod(DataAccess.DatapathElement element) Invokes the static method which is described with the element.
static boolean	isOrExtends(java.lang.Class<?> thisclazz, java.lang.Class<?> cmpclazz) Check whether a given class is type of another class.
static boolean	isReferenceToEnclosing(java.lang.reflect.Field ref) Checks whether a given Field is the reference to the enclosing respectively outer class.
static boolean	istypeof(java.lang.Object obj, java.lang.Class type) Checks whether the given obj is type of the given type.
static boolean	istypeof(java.lang.Object obj, java.lang.String sType) Checks whether the given obj is type of the given type.
static int	setBit(int value, int mask, boolean set) Sets a bit in a int word
static void	setVariable(java.util.Map<java.lang.String,DataAccess.Variable<java.lang.Object>> map, DataAccess.Variable<java.lang.Object> ref) Set or replaces a variable with a simple name in the given container.
short	shortFromUnsignedByte(byte val) Converts a value in a byte to a unsigned value, which can be stored in a short in Java.
static void	storeValue(DataAccess.DatapathElement path, java.lang.Object data, java.lang.Object value, boolean bAccessPrivate) Stores a value in the given field or with the given method into the data instance.
static void	storeValue(java.util.List<DataAccess.DatapathElement> path, java.lang.Object dataRoot, java.lang.Object value, boolean bAccessPrivate) Stores the given value in the element determined by the data path, maybe create a new Variable therewith.
void	storeValue(java.lang.Object dataRoot, java.lang.Object value, boolean bAccessPrivate) Stores the value in the given path.
java.lang.String	toString() Should be used only for debug to view what is it.
void	writeStruct(java.lang.Appendable out)

Methods inherited from class java.lang.Object

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

Field Detail

sVersion

public static final java.lang.String sVersion

Version, history and license.

• 2023-05-21: istypeof(Object, Class) now also can detect the class Object itself. More universal.
• 2023-05-05: Hartmut improved error message on method not found / argument mismatch, in invokeMethod(DatapathElement, Class, Object, boolean, boolean, Object[])
• 2021-12-30: Hartmut: access(CharSequence, Object, boolean, boolean, boolean, Dst) now regards a "%..." path for static access.
• 2019-08-20: some operations throws ParseException on syntax errors.
• 2019-08-23 Hartmut new: Supports now &(path) as indirect access, access to variable with gotten name in path. Therefore the operations access(Object, boolean, boolean, Map, Object[]) etc. needs the variableNames.
• 2019-08-19 Hartmut chg: error msg on throw improved on non found operation etc, line feed for better read ability.
• 2019-08-10 Hartmut new / chg: Usage of variable-values in a Object[] array:
  • DataAccess(StringPartScan, Map, Class, char) has a new 2. and 3. argument nameVariables and , as well as DataAccess.DatapathElement#DatapathElement(StringPartScan, Map, Class). If given this map is used to search the first identifier there. If found
  • The operations #access(Object, boolean, boolean, Object[]), #access(List, Object, boolean, boolean, Object[], boolean, Dst), #access(DatapathElement, Object, boolean, boolean, Object[], boolean, Dst) invokeMethod(DatapathElement, Class, Object, boolean, Object[], boolean) gets a new argument varValues to access the variable given on ctor and set operations.
  • The routine invokeMethod(DatapathElement, Class, Object, boolean, Object[], boolean) calculates the arguments of the method with the given calculation rule in DataAccess.DatapathElement.args. This approach is used in, see next
  • The operation invokeMethod(DatapathElement, Class, Object, boolean, Object[], boolean) calculates the arguments due to given algorithm in DataAccess.DatapathElement.args using the varValues which corresponds to the nameVariables argument on setting the expression.
  • The DataAccess.DatapathElement has the new field args, instead argNames and argExpr are removed.
• 2019-08-10 Hartmut chg: Some operations, all which parses, throws an ParseException on parsing errors. Hence the request to handle it is forced.
• 2019-06-18 Hartmut new ctor: #DataAccess(StringPartScan, char) and DatapathElement#set(StringPartScan) used in parsing pattern in CalculatorExpr.
• 2019-06-18 Hartmut new ctor: DatapathElement#XXXargExpr to calculate more complex arguments with given expression outside JZtxtcmd
• 2019-05-30 Hartmut gardening for C#-translation: The Conversion#key() may be a better documentation for the conversion classes. It is experience, not used yet.
• 2018-12-18 Hartmut improve: rename DataAccess.DatapathElement.operation_, private and setter and getter. The JzTxtCmd invokes the set_operation() without changes. It is set now on any operation. Used via DataAccess.DatapathElement.isOperation() in the org.vishia.xmlReader.XmlZzReader
• 2018-09-28 Hartmut improve: An dataAccess element now knows DatapathElement#operation. If that is not set and there are no fnArgs then a field (static) is accessed. That were missing. Used for JzTxtCmd.
• 2018-09-28 Hartmut improve: initConversion() accepts boolean from Boolean, important for JzTxtCmd
• 2017-12-20 Hartmut improve: #invokeMethod(DatapathElement, Class, Object, boolean, boolean): Show used class on error.
• 2017-08-30 Hartmut new: istypeof(Object, String) with String argument, based on istypeof(Object, Class).
• 2017-07-02 Hartmut new: debugMethod(String) can be invoked with "". Then it invokes debug() on the next found method and removes the settings after them. It is usual in a JZtxtcmd Script to stop on the next method.
• 2016-10-01 Hartmut new: storeValue(DatapathElement, Object, Object, boolean) and #access(DatapathElement, Object, boolean, boolean, boolean, Dst) only with an datapath element, more simple.
• 2016-10-01 Hartmut new: invokeMethod(DatapathElement, Class, Object, boolean, boolean, Object[]) with the arguments of the method. The DatapathElement#argNames contains names of the arguments which are given with DataAccess.DatapathElement.set(String). With that concept it is possible to define a method call in a script with control which values in the script are used as parameters. It is used for the XmlJzReader.
• 2016-01-17 Hartmut new: Now an element can be an array, which is accessed with indices: DataAccess.SetDatapathElement.set_index(int) and DataAccess.DatapathElement.indices. Syntax for JZcmd adapted (JZtxtcmdSyntax).
• 2016-01-09 Hartmut bugfix: access(CharSequence, Object, boolean, boolean, boolean, Dst) has dissolved a DataAccess.Variable twice, problem if a variable contains a Variable as value. The access <&myVariable.name> was faulty. Not it works.
• 2015-05-17 Hartmut new: conversion routines shortFromUnsignedByte(byte) and intFromUnsignedShort(short).
• 2015-05-17 Hartmut chg: Messages if methods not found.
• 2014-10-19 Hartmut bugfix: invokeStaticMethod(DatapathElement) with variable argument list but only 1 argument has not worked. TODO okay if no argument?
• 2014-10-19 Hartmut new: isReferenceToEnclosing(Field) and isOrExtends(Class, Class)
• 2014-06-15 Hartmut chg: #access(List, Object, boolean, boolean, boolean, Dst) and access(CharSequence, Object, boolean, boolean, boolean, Dst) now with only one dataRoot. Not differenced between a Map2014-06-15 Hartmut new: DataAccess.Variable.type() to check whether the type of value is correct. It is not ready yet. Idea: Parameter Class on creation of variables. JZcmd feature.
• 2014-06-10 Hartmut new: DataAccess.Conversions.list2array: If a List is provided as argument and an array is expected and the first element matches, it is used. It is assumed that all arguments matches. TODO special handling for main(String[]) with List argument is not necessary then.
• 2014-06-01 Hartmut new: DataAccess.DatapathElementClass.clazz with a given class. Used on invokeNew(DatapathElement) and invokeStaticMethod(DatapathElement)
• 2014-06-01 Hartmut new: DataAccess.DatapathElementClass.loader: static Methods and #invokeMethod(DatapathElement, Class, Object, boolean, boolean) with an special ClassLoader.
• 2014-05-28 Hartmut new: some conversions added, especially for main(String[] args): compatible with some CharSequence arguments. Automatic conversion from String to File removed.
• 2014-05-25 Hartmut new: access(...): gets static data. It is essential for example for Math.PI
• 2014-05-18 Hartmut new: #expandElements(String, char) for String-given elements. The first only one element of #access(List, Object, Map, boolean, boolean, boolean, Dst) can contain "path.subpath..." #access(CharSequence, Object, Map, boolean, boolean, boolean, Dst) for String given elements.
• 2014-05-18 Hartmut new: DataAccess.ObjMethod for invocation of an method described with reflection, not used yet but prepared.
• 2014-04-25 Hartmut chg: #invokeMethod(DatapathElement, Class, Object, boolean, boolean) with Class as parameter. #access(List, Object, Map, boolean, boolean, boolean, Dst) checks whether the obj is stored in an DataAccess.Variable with type 'C' and value instanceof Class. Then the static method of this Class type is searched and invoked. That feature is used in conclusion with JZcmd Class myClass = package.path.Class;
• 2014-03-08 Hartmut new: debugIdent(String) sets an identifier on which debug() was called, to set manual breakpoint while debugging.
• 2014-01-26 Hartmut chg: The element fnArgsExpr of DataAccess.DatapathElement is removed from here. It is now located in JZtxtcmdScript.JZcmdDatapathElement because it is necessary only for the JZcmd usage. This class is more simple in its functionality.
• 2014-01-25 Hartmut chg: some methods of DataAccess.DataAccessSet are final now. Nobody overrides.
• 2013-12-26 Hartmut chg: createOrReplaceVariable(Map, String, char, Object, boolean) instead setVariable(...) with type argument.
• 2013-12-26 Hartmut chg: getData(String, Object, boolean, boolean, boolean, Dst) returns the variable if the argument bVariable is set.
• 2013-11-03 Hartmut chg: rename getData(...) to #access(List, Object, Map, boolean, boolean, boolean, Dst), return value Dst for setting. The #storeValue(List, Map, Object, boolean) may be obsolte now.
• 2013-11-03 Hartmut chg: Handling of variable in #getData(List, Object, Map, boolean, boolean, boolean)
• 2013-10-27 Hartmut chg: Definition of a String name [= value] in JZcmd is handled like assign. Stored with DataAccess#storeValue(List, Map, Object, boolean) with special designation in DataAccess.DatapathElement.whatisit with 'new Variable' designation.
• 2013-10-20 Hartmut new/chg: The start-variables are all of type DataAccess.Variable up to now. This concept is changed in JZtxtcmdExecuter originally. Any other application of this class have to wrapped its data in such an instance DataAccess.Variable, it is a low-cost effort.
• 2013-10-09 Hartmut new: #storeValue(List, Map, Object, boolean) put in a map, replaces the value.
• 2013-09-14 Hartmut new: support of null as Argument.
• 2013-08-18 Hartmut new: This class now contains the List of datapath as only one attribute. Now this class can be used instead a List as bundled instance.
• 2013-08-18 Hartmut new: DataAccess.DataAccessSet is moved from the org.vishia.zbatch.ZbatchGenScript because it is more universal.
• 2013-07-28 Hartmut chg: improvement of conversion of method arguments.
• 2013-07-14 Hartmut chg: #checkAndConvertArgTypes(List, Class[]) now checks super classes and interfaces,
• 2013-07-14 Hartmut chg: Exception handling for invoked methods.
• 2013-06-23 Hartmut new: invokeNew(DatapathElement).
• 2013-03-26 Hartnut improved: #getData(String, DataAccess.Variable, boolean, boolean) Now accesses to all elements, also to enclosing and super classes.
• 2013-03-26 Hartmut new: #getDataFromField(String, DataAccess.Variable, boolean)
• 2013-03-26 Hartmut new: getEnclosingInstance(Object)
• 2013-03-26 Hartmut bugfix: #getData(String, DataAccess.Variable, boolean, boolean) has thrown an Exception if a existing element has a null-value. Instead it should return null. Exception only if the field is not found.
• 2013-03-23 Hartmut chg: #checkAndConvertArgTypes(List, Class[]): Now supports a (String[]) arg which is typical for a main(String[]) routine. General: The last formal argument can be an array, then all further non-array arguments are tried to build the element of it.
• 2013-03-10 Hartmut new: Now supports access to elements of the super class (TODO: outer classes).
• 2013-01-13 Hartmut chg: #getData(List, Object, Map, boolean, boolean) can be invoked with null for dataPool to invoke new or static methods.
• 2013-01-12 Hartmut new: #checkAndConvertArgTypes(List, Class[]) improved, new #invokeStaticMethod(DatapathElement, Object, boolean, boolean)
• 2013-01-05 Hartmut new: reads $$ENV_VAR.
• 2013-01-02 Hartmut new: Supports access to methods whith parameter with automatic cast from CharSequence to String and to File. Uses the DataAccess.DatapathElement.fnArgs and #getData(List, Object, Map, boolean, boolean).
• 2012-12-23 Hartmut chg, new: getStringFromObject(Object, String) now uses a format string.
• 2012-12-22 Hartmut new: DatapathElement#constValue as general possibility, usual for the first element of a path.
• 2012-12-08 Hartmut new: #getData(String, Object, boolean) as subroutine in #getData(List, Object, Map, boolean, boolean) and able to use to get with non treed path, only direct but with all facilities to get from Map etc..
• 2012-11-24 Hartmut new: DataAccess.DatapathElement for describing more complex path for access.
• 2012-11-18 Hartmut new: setBit(int, int, boolean) as little universal routine.
• 2012-11-16 Hartmut new: getInt(Object), getFloat(Object) from ObjectValue, last one is deprecated now.
• 2012-11-04 Hartmut chg: parameter bContainer in getData(...): Sometimes a container is ispected to iterate though only one element is found, sometimes only a simple element is expected though a container is addressed maybe with one element.
• 2012-10-21 Hartmut created. Some algorithm are copied from org.vishia.zbatch.ZbatchExecuter in this class. That algorithm are able to use independent in some applications.

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

idxConversions

private static java.util.Map<java.lang.String,DataAccess.Conversion> idxConversions

debugIdent

private static java.lang.String debugIdent

Can be set immediately for debug approach. Set debug break on usage!

debugMethod

private static java.lang.String debugMethod

datapath

protected java.util.List<DataAccess.DatapathElement> datapath

The description of the path to any data if the script-element refers data. It is null if the script element does not refer data. If it is filled, the instances are of type ZbnfDataPathElement. If it is used in DataAccess, its base class DataAccess.DatapathElement are used. The difference are the handling of actual values for method calls. See ZbnfDataPathElement#actualArguments.

Constructor Detail

DataAccess

public DataAccess(java.lang.String path)
           throws java.text.ParseException

Creates a Datapath with given String. The first character of an element determines the type, see DataAccess.DatapathElement.set(String).

• If the path does not start with $+%! then it is separated in path elements, the separator is the dot.
• If the path starts with $ it is an access to an environment variable.
• + new
• % ! static method.

For example for a simple local variable in the datapool write "@name".

Parameters:

path -

Throws:

java.text.ParseException

DataAccess

public DataAccess(java.lang.String path,
                  char cTypeNewVariable)
           throws java.text.ParseException

Creates a Datapath with given String. The first character of an element determines the type, see DataAccess.DatapathElement.set(String).

• If the path does not start with $+%! then it is separated in path elements, the separator is the dot.
• If the path starts with $ it is an access to an environment variable.
• + new
• % ! static method.

For example for a simple local variable in the datapool write "@name".

Parameters:

path -

cTypeNewVariable - if A...Z then the last element will be designated with it. Then a new variable should be created in the parent's container with the access.

Throws:

java.text.ParseException

DataAccess

public DataAccess(StringPartScan sp,
                  java.util.Map<java.lang.String,DataAccess.IntegerIx> nameVariables,
                  java.lang.Class<?> reflData,
                  char cTypeNewVariable)
           throws java.text.ParseException

Creates a Datapath with given StringPartScan. The first character of an element determines the type, see DataAccess.DatapathElement.set(String).

• If the path does not start with $+%! then it is separated in path elements, the separator is the dot.
• If the path starts with $ it is an access to an environment variable.
• + new
• % ! static method.

For example for a simple local variable in the datapool write "@name".

Parameters:

path -

nameVariables - if not null then the argument names can start with this given names. The first identifier is searched here. If it is not found, firstly reflData are used to find it as static variable. If it is not possible then the identifier is added to the nameVariables map. Hence used names are documented to outside and can be evaluate on invocation before #access(Object, boolean, boolean, Object[]). This feature is introduced with OutTextPreparer to support simple expressions in a fast way. If null then the arguments are parsed as DataAccess.

reflData - type wich can contain a static member with the required name in sDatapath if the name is not found in variables If nameVariables are given and this argument is not null, then an identifier will be searched in this reflData to get its Access routine. This feature is introduced with OutTextPreparer to support simple expressions in a fast way.

cTypeNewVariable - if A...Z then the last element will be designated with it. Then a new variable should be created in the parent's container with the access.

Throws:

java.text.ParseException - on errors on sp, on not found variables too.

DataAccess

public DataAccess()

Empty constructor. Use add_datapathElement(DatapathElement) to determine the datapath.

Method Detail

datapath

public final java.util.List<DataAccess.DatapathElement> datapath()

Returns the datapath of this access to check details.

add_datapathElement

public void add_datapathElement(DataAccess.DatapathElement item)

Sets the datapath while adding one element after another. More elements are necessary if the datapath has references.

Parameters:

item -

See Also:

DatapathElement}

access

public java.lang.Object access(java.lang.Object dataRoot,
                               boolean accessPrivate,
                               boolean bContainer,
                               java.util.Map<java.lang.String,DataAccess.IntegerIx> nameVariables,
                               java.lang.Object[] varValues)
                        throws java.lang.Exception

Searches the Object maybe invoking some methods which is referred with this instances, datapath.

Parameters:

dataRoot - Either a Map or any other Object which is the root for access. it is the object where the path starts from. A Map which's key is not a String is not admissible.

bContainer - true then returns a found container or build one.

varValues - maybe null or array of some variables which are sorted by parameter idxVariables in DataAccess(StringPartScan, Map, Class, char)

Returns:

Maybe null only if the last reference refers null.

Throws:

java.lang.Exception - on any not found or etc.

storeValue

public static void storeValue(java.util.List<DataAccess.DatapathElement> path,
                              java.lang.Object dataRoot,
                              java.lang.Object value,
                              boolean bAccessPrivate)
                       throws java.lang.Exception

Stores the given value in the element determined by the data path, maybe create a new Variable therewith.

• If the last or only one element of the path is designated with 'A'...'Z' in its DataAccess.DatapathElement.whatisit DataAccess.Variable.type(), this variable is created newly. The destination before, that is either the param variables or the result of the path before, have to be a Map< String, DataAccess.Variables>.
• If the path exists and refers to a DataAccess.Variable then the value of the variable is replaced.
• If the destination referred by the path exists and it is a List or a Appendable, then the value is added respectively appended to it.
• If the destination referred by the path exists, and the path before is a Map, then the element of the map is replaced.
• If the destination referred by the path does not exists, and the path before is a Map, then the element of the map is put.
• If the path consists of more as one element and any parent element does not exists too, it is added only if its parent is of type Map with a String as key.
• The parent of the first element is the variables container. It is of type Map.
• If the path consists of only one element and this element is a new one, it is created as a new variable in the variables container.
• If the path consists of some elements and all of them are Map or one of them does not exist, a Tree of Maps is build in variable.

Parameters:

path -

dataRoot - Either a Map or any other Object which is the root for access. it is the object where the path starts from. A Map which's key is not a String is not admissible.

value -

Throws:

java.lang.IllegalAccessException

java.io.IOException - if append fails.

java.lang.IllegalAccessException - if a field exists but can't access. Note that private members can be accessed.

java.lang.Exception

storeValue

public static void storeValue(DataAccess.DatapathElement path,
                              java.lang.Object data,
                              java.lang.Object value,
                              boolean bAccessPrivate)
                       throws java.lang.Exception

Stores a value in the given field or with the given method into the data instance.

• If the destination is instanceof DataAccess.Variable its value will be changed.
• If the destination is a field inside data, the value will set to the field.

Parameters:

path - describes a field or method of data. It is the 'destination'.

data - instance where path is found.

value - value

bAccessPrivate -

Throws:

java.lang.Exception - any exception is possible because faulty path, faulty data types etc.

storeValue

public void storeValue(java.lang.Object dataRoot,
                       java.lang.Object value,
                       boolean bAccessPrivate)
                throws java.lang.Exception

Stores the value in the given path. See #storeValue(List, Map, Object, boolean).

Parameters:

dataRoot - Either a Map or any other Object which is the root for access. it is the object where the path starts from. A Map which's key is not a String is not admissible.

value -

bAccessPrivate -

Throws:

java.lang.Exception

initConversion

static java.util.Map<java.lang.String,DataAccess.Conversion> initConversion()

This method initializes the internal conversion index. It is only public to document which conversions are possible. One can invoke the method and view the result. The keys in the map describe possible conversions fromType:toType.

Returns:

An index table for conversion. Used internal.

getClass

private static final java.lang.Class<?> getClass(java.lang.String name)

expandElements

public static java.util.List<DataAccess.DatapathElement> expandElements(java.lang.CharSequence path,
                                                                        char whatisit)
                                                                 throws java.text.ParseException

Splits a String given path to elements.

Parameters:

path - If starts with "&@$" it is the type.

whatisit - only used if path does not start with type.

Returns:

list.

Throws:

java.text.ParseException

access

public static java.lang.Object access(java.lang.CharSequence datapathArg,
                                      java.lang.Object dataRoot,
                                      boolean accessPrivate,
                                      boolean bContainer,
                                      boolean bVariable,
                                      DataAccess.Dst dst)
                               throws java.lang.Exception

Accesses data with a String given path. The path can contain more elements separated with dot. A first char can define from what to read: For example

• "$ENV": From an environment variable
• "@variable.element": Read start instance form dataPool
• "%java.package.Class.operation()": invokes a static method.
• "element": read from dataRoot. Read via get(element) if dataRoot is a Map
• "reference.element": read from dataRoot, referenced instance.

Parameters:

datapathArg -

dataRoot - Either a Map or any other Object which is the root for access. it is the object where the path starts from. A Map which's key is not a String is not admissible.

accessPrivate -

bContainer -

bVariable -

dst -

Returns:

Throws:

java.lang.Exception

access

public static java.lang.Object access(java.util.List<DataAccess.DatapathElement> datapathArg,
                                      java.lang.Object dataRoot,
                                      boolean accessPrivate,
                                      boolean bContainer,
                                      java.util.Map<java.lang.String,DataAccess.IntegerIx> nameVariables,
                                      java.lang.Object[] varValues,
                                      boolean bVariable,
                                      DataAccess.Dst dst)
                               throws java.lang.Exception

Universal method to accesses data. The argument datapathArg contains elements, which describes the access path.

The DataAccess.DatapathElement.whatisit is used like:

• The elements of datapath describe the access to data. Any element before supplies a reference for the path of the next element.
• $: The datapath can start with an element designated with DataAccess.DatapathElement.whatisit == '$'. It describes an access to an environment variable. The the variable is searched first in the given dataPool with an additional '$' on start of identifier. Note that the name of the variable (DataAccess.DatapathElement.ident) does not start with that '$' itself. If it is found, the dataPool contains this environment variable, it is prior. If the environment variable is not found in the datapool (a normal case), then the variable is searched in the environment variables of the operation system. Its String representation is returned. If the environment variable is not found, null is returned. The datapath should contain only this one element. Only this first element of the datapath is used.
• @ or .: A variable, DataAccess.DatapathElement.ident contains the name of the field. It is searched as a Field in the given instance of the parent level, firstly in dataRoot.
• @ or .: and DataAccess.DatapathElement.ident == "[]" It should be the last element of the path. Then the length of the array of the path before is returned, or the size of a container.
• A..Z a..z: If the only one first element or the last element is designated with DataAccess.DatapathElement.whatisit == 'A' .. 'Z' or 'a' ...'z' a new Variable will be created in the given datapool. The character 'A'...'Z' describes the type. If lower case is written then the variable is created as const.
• +: The only one first element with DataAccess.DatapathElement.whatisit == '+' is the creation of instance maybe with or without arguments in DataAccess.DatapathElement.fnArgs
• %: The only one first element with DataAccess.DatapathElement.whatisit == '%' is a call of a static routine maybe with or without arguments in DataAccess.DatapathElement.fnArgs
• (: An element with DataAccess.DatapathElement.whatisit == '(' is a method invocation maybe with or without arguments. in DataAccess.DatapathElement.fnArgs
• If the instance of the parent level is instanceof Map then the element is searched by name as member of this map. The key of the map should be instanceof String.
• If an element is not found a NoSuchFieldException or NoSuchMethodException is returned.
• If any method is invoked and this method throws an Exception, a InvocationTargetException is thrown.

Examples

• datapath = [myField:.]: The content respectively referenced instance of the field myField inside the dataRoot instance is returned.
• datapath = [myReference:., myField:.]: The content respectively referenced instance of the field myReference inside the dataRoot instance is read. From that instance the myField content of referenced instance is returned.

Variable:
DataAccess.Variable are designated especially for referencing from one or more Map. If the value should be changed, the value is changed inside the DataAccess.Variable.value(). Therewith all references sees the new value. This method can deal especially with Variable in Map-container additionally to any other accesses.

If an element of the 'datapath' argument is designated with DataAccess.DatapathElement.whatisit = 'A' .. 'Z', then a new variable is created in the context. The context should be a Map.

Access with an element with DataAccess.DatapathElement.whatisit == '.':
The DataAccess.DatapathElement.ident may determine a field of the current data reference or it may be a key for a indexed container. The #getData(String, DataAccess.Variable, boolean, boolean) is invoked, see there for further explanation.

Calculation of arguments:
This routine calculates all method's arguments it an expression is given in the datapathElement in DatapathElement#addArgumentExpression(CalculatorExpr). before the method is called. The expression to calculate is stored in DatapathElement#fnArgsExpr whereby the calculated results is stored in DataAccess.DatapathElement.fnArgs.

Assignment of arguments of methods or constructor:
If the method or class is found per name, all methods with this name respectively all constructors are tested whether they match to the DataAccess.DatapathElement.fnArgs. The number of args should match and the types should be compatibel. See #checkAndConvertArgTypes(List, Class[]).

Parameters:

dataRoot - Either a Map or any other Object which is the root for access. it is the object where the path starts from. A Map which's key is not a String is not admissible.

accessPrivate - if true then private data are accessed too. The accessing of private data may be helpfully for debugging. It is not recommended for general purpose! The access mechanism is given with AccessibleObject.setAccessible(boolean).

bVariable - if true then return the found DataAccess.Variable and not its content. If false then return the DataAccess.Variable.value() if a variable is the last element.

bContainer - If the element is a container, returns it. Elsewhere build a List to return a container for iteration with only the found element. A container is any object implementing java.util.Map or java.util.Iterable or an Array.

nameVariables - necessary on indirect access to variable via String, construct such as <&&(path)> can be null if not used, should be null especially if varValues == null

varValues - maybe null or array of some variables which are sorted by parameter idxVariables in DataAccess(StringPartScan, Map, Class, char)

dst - If not null then fill the last Field and the associated Object in the dst. It can be used to set the field with a new value.

Returns:

Any data object addressed by the path. Returns null if the last datapath element refers null.

• null: returns null
• Variable: bVariable = true: returns it
• Variable: bVariable = false: access to its DataAccess.Variable.value(), then the other rules.
• Iterable: returns it
• Map: returns it
• any Object: bContainer = true: returns a List with this Object as member.
• any Object: bContainer = false: returns it
• Not found: throws an NoSuchFieldException or NoSuchMethodException
• Any Exception while invocation of methods: throws it.

Throws:

java.lang.ReflectiveOperationException

java.lang.Throwable

java.lang.IllegalArgumentException - if the datapath does not address an element. The exception message contains a String as hint which part does not match.

java.lang.Exception

access

public static java.lang.Object access(DataAccess.DatapathElement element,
                                      java.lang.Object data1,
                                      boolean accessPrivate,
                                      boolean bContainer,
                                      java.util.Map<java.lang.String,DataAccess.IntegerIx> nameVariables,
                                      java.lang.Object[] varValues,
                                      boolean bVariable,
                                      DataAccess.Dst dst)
                               throws java.lang.Exception

Access to the given element, used internally, also able to use for one element form extern.

Parameters:

element - describes the access, can be a field, operation, environment variable or all possibilities

data1 - If it is instanceof Class, then static access. Can be null for instance access, then output null.

accessPrivate -

bContainer -

nameVariables -

varValues -

bVariable -

dst -

Returns:

The accessed content.

Throws:

java.lang.Exception

invokeNew

protected static java.lang.Object invokeNew(DataAccess.DatapathElement element)
                                     throws java.lang.Exception

Invokes the static method which is described with the element.

Parameters:

element - its DataAccess.DatapathElement.whatisit == '%'. The DatapathElement#identArgJbat should contain the full qualified "packagepath.Class.methodname" separated by dot.

Returns:

the return value of the method

Throws:

java.lang.NoSuchMethodException

java.lang.Exception

invokeMethod

public static java.lang.Object invokeMethod(DataAccess.DatapathElement element,
                                            java.lang.Class<?> clazz,
                                            java.lang.Object obj,
                                            boolean accessPrivate,
                                            java.lang.Object[] varValues,
                                            boolean bNoExceptionifNotFound)
                                     throws java.lang.reflect.InvocationTargetException,
                                            java.lang.NoSuchMethodException,
                                            java.lang.Exception

Prepares firstly the arguments of the method and invokes the method. The arguments of the method comes from access to 'varValues' maybe with sub elements or access to elements from obj due to the given DataAccess.DatapathElement.args which contains the access algorithm. The association to the arguments of the operation in argument 'args' is done here before invokeMethod(DatapathElement, Class, Object, boolean, boolean, Object[]) is called.

Parameters:

element - its DataAccess.DatapathElement.whatisit == '('. The DataAccess.DatapathElement.ident is the "methodname".

clazz - the Class instance where the method should be found. For non-static methods the relation obj instanceof clazz should be valid, elsewhere an exception is thrown.

obj - The instance which is the instance of the method. The obj is used as first argument of Method.invoke(Object, Object...). For static methods obj is not used. It may be null.

accessPrivate - true then uses private methods too

varValues - maybe null or array of some variables which are sorted by parameter idxVariables in DataAccess(StringPartScan, Map, Class, char)

bNoExceptionifNotFound - if the then does not a NochSuchMethodException if the method was not found. This is a special flag if the method is optional.

Returns:

the return value of the method

Throws:

java.lang.reflect.InvocationTargetException

java.lang.NoSuchMethodException

java.lang.Exception

invokeMethod

public static java.lang.Object invokeMethod(DataAccess.DatapathElement element,
                                            java.lang.Class<?> clazz,
                                            java.lang.Object obj,
                                            boolean accessPrivate,
                                            boolean bNoExceptionifNotFound,
                                            java.lang.Object[] args)
                                     throws java.lang.reflect.InvocationTargetException,
                                            java.lang.NoSuchMethodException,
                                            java.lang.Exception

Invokes the method which is described with the element with given immediately calling arguments.

Parameters:

element - its DataAccess.DatapathElement.whatisit == '('. The DataAccess.DatapathElement.ident is the "methodname".

clazz - the Class instance where the method should be found. For non-static methods the relation obj instanceof clazz should be valid, elsewhere an exception is thrown.

obj - The instance which is the instance of the method. The obj is used as first argument of Method.invoke(Object, Object...). For static methods obj is not used. It may be null.

accessPrivate -

bNoExceptionifNotFound -

args - if not null then this arguments are used prior to element DataAccess.DatapathElement.fnArgs.

Returns:

see #invokeMethod(DatapathElement, Class, Object, boolean, boolean)

Throws:

java.lang.reflect.InvocationTargetException

java.lang.NoSuchMethodException

java.lang.Exception

invokeStaticMethod

protected static java.lang.Object invokeStaticMethod(DataAccess.DatapathElement element)
                                              throws java.lang.Exception

Invokes the static method which is described with the element.

Parameters:

element - its DataAccess.DatapathElement.whatisit == '%'. The DatapathElement#identArgJbat should contain the full qualified "packagepath.Class.methodname" separated by dot.

Returns:

the return value of the method

Throws:

java.lang.Throwable

java.lang.Exception

getStaticValue

protected static java.lang.Object getStaticValue(DataAccess.DatapathElement element)
                                          throws java.lang.Exception

Invokes the static method which is described with the element.

Parameters:

element - its DataAccess.DatapathElement.whatisit == '%'. The DatapathElement#identArgJbat should contain the full qualified "packagepath.Class.methodname" separated by dot.

Returns:

the return value of the method

Throws:

java.lang.Throwable

java.lang.Exception

getClassLoader

private static java.lang.ClassLoader getClassLoader(DataAccess.DatapathElement element)

checkAndConvertArgTypes

protected static java.lang.Object[] checkAndConvertArgTypes(java.lang.Object[] providedArgs,
                                                            java.lang.Class<?>[] argTypes)

Checks whether the given arguments matches to the necessary arguments of a method or constructor invocation. Converts the arguments if possible and necessary:

• same type of providedArg and argType: use providedArg without conversion
• argType is String[]: check providedArgs. If all of them are CharSequence, return String[] of this CharSequences. Convert the CharSequences toString().
• provideArg instanceof -> argType: conversion
• CharSequence -> CharSequence: arg
• CharSequence -> String: arg.toString()
• CharSequence -> File : new File(arg)

Parameters:

providedArgs - Given arguments

argTypes - requested argument types

Returns:

actArgs This array will be filled with converted parameter if all parameter matches.
If the number of args is 0, then Object[0] is returned.
null if the number of argtypes is not equal to the number of providedArgs or if the providedArgs and argTypes does not match. The array have to be created with the size proper to

checkArgTypes

public static DataAccess.Conversion checkArgTypes(java.lang.Class<?> argType,
                                                  java.lang.Class<?> actType,
                                                  java.lang.Object arg)

Checks whether the given actType with its value arg matches to the given argType. It checks all its super and interface types and searches a possible conversion, see initConversion(). If actType is an interface, all super interfaces are checked after them. If actType is a class, all interfaces are checked but not the superclass. This routine will be called recursively for the interfaces. To get the interfaces of a class and all super interfaces of an interface, the routine Class.getInterfaces() is called. Last not least the checkTypes(Class, Class, Object) is called for a possible conversion.

Parameters:

argType - Requested type

actType - Given type, it may be a super class, an interface or a conversion may exists.

arg - The argument itself to check value ranges for conversion using Conversion#canConvert(Object).

Returns:

null if it does not match, elsewhere a conversion routine for conversion. If it is an super or interface type, the Conversion routine does return the instance itself.

checkIfcTypes

private static DataAccess.Conversion checkIfcTypes(java.lang.Class<?> argType,
                                                   java.lang.Class<?> ifcType,
                                                   java.lang.Object arg)

checkTypes

public static DataAccess.Conversion checkTypes(java.lang.Class<?> argType,
                                               java.lang.Class<?> actType,
                                               java.lang.Object arg)

Checks whether a given type with its value can be converted to a destination type.

Parameters:

argType - The destination type.

actType - The given type.

arg - The value

Returns:

null if conversion is not possible, elsewhere the conversion.

istypeof

public static final boolean istypeof(java.lang.Object obj,
                                     java.lang.String sType)
                              throws java.lang.ClassNotFoundException

Checks whether the given obj is type of the given type. It gets the type with Class.forName(sType) and invokes istypeof(Object, Class)

Parameters:

obj - any instance

type - String given type

Returns:

true if type matches

Throws:

java.lang.ClassNotFoundException

istypeof

public static final boolean istypeof(java.lang.Object obj,
                                     java.lang.Class type)

Checks whether the given obj is type of the given type.

Parameters:

obj - any instance

type - can be a base type or an interface type

Returns:

true if type matches

getData

public static java.lang.Object getData(java.lang.String name,
                                       java.lang.Object instance,
                                       boolean accessPrivate,
                                       boolean bContainer,
                                       boolean bVariable,
                                       DataAccess.Dst dst)
                                throws java.lang.NoSuchFieldException,
                                       java.lang.IllegalAccessException

Gets data from a field or from an indexed container.

• If the instance is typeof DataAccess.Variable then its value is used.
• If the actual instance is instanceof Map with String-key, then the next object is gotten from the map with the name used as key.
• If the name is "[]" and the instance is an array, its length is gotten and returned. If the instance is instance of an Container or Map, then the size() is returned. This property can be used especially for #access(Object, boolean, boolean) as last element.
• Elsewhere a field with ident as name is searched.
• If the instance is instanceof TreeNodeBase and the field identifier is not found in this instance, a child node with the given name is searched. The TreeNodeBase is the super class of XmlNodeSimple which is used to present a ZBNF parse result. Therewith the ZbnfParser.getResultTree() can be used as data input. The tag names of that result tree follow the semantic in the string given Syntax script.
• If the field is not found in this class, it is try to get from the super classes.
• If the found instance is of type DataAccess.Variable and bContainer = false, then the value of the Variable is returned.

Parameters:

name - Name of the field or key in the container

instance - The instance where the field or element is searched.

accessPrivate - true than accesses also private data.

bContainer - only used for a TreeNodeBase: If true then returns the List of children as container, If false returns the first child with that name.

bVariable - returns the variable if it is found. if false then returns the value inside a variable.

Returns:

The reference described by name.

Throws:

java.lang.NoSuchFieldException - If not found.

java.lang.IllegalAccessException

getDataPriv

private static java.lang.Object getDataPriv(java.lang.String name,
                                            java.lang.Object instance,
                                            boolean accessPrivate,
                                            boolean bContainer,
                                            boolean bVariable,
                                            DataAccess.Dst dst)
                                     throws java.lang.NoSuchFieldException,
                                            java.lang.IllegalAccessException

It does not resolve the instance if it is a Variable

Parameters:

name -

instance -

accessPrivate -

bContainer -

bVariable -

dst -

Returns:

Throws:

java.lang.NoSuchFieldException

java.lang.IllegalAccessException

getDataFromField

public static java.lang.Object getDataFromField(java.lang.String name,
                                                java.lang.Object obj,
                                                boolean accessPrivate,
                                                DataAccess.Dst dst)
                                         throws java.lang.NoSuchFieldException,
                                                java.lang.IllegalAccessException

Returns the data which are stored in the named field of the given instance. The method searches the field in the super class hierarchy and in all enclosing classes of each super classes starting with the last super class. If a field is defined in the enclosing class and in the super class or an outer class of the super class twice, it is searched firstly in the super hierarchy. It means it meets the field in the outer class of any super class instead of its own outer class.

Parameters:

name - The name of the field.

obj - The instance where the field are searched.

accessPrivate - true then read from private or protected fields, false then the access to such fields throws the IllegalAccessException

Returns:

the data of the field. Maybe null if the field contains a null pointer.

Throws:

java.lang.NoSuchFieldException - If the field does not exist in the obj

java.lang.IllegalAccessException - if the field exists but is not accessible.

getDataFromField

private static java.lang.Object getDataFromField(java.lang.String name,
                                                 java.lang.Object obj,
                                                 boolean accessPrivate,
                                                 java.lang.Class<?> clazz,
                                                 DataAccess.Dst dst,
                                                 int recursiveCt)
                                          throws java.lang.NoSuchFieldException,
                                                 java.lang.IllegalAccessException

Core method to get data from a field, static or non static

Parameters:

name - of the field

obj - null if static fields should be accessed.

accessPrivate - also search private fields

clazz - Should be match to obj if obj !=null

dst -

recursiveCt - 0 on user call, max. 100 recursions for sub classes and outer classes

Returns:

The data which are referred with the field in the given obj or with the static field.

Throws:

java.lang.NoSuchFieldException - If the field was not found in clazz

java.lang.IllegalAccessException - If the field cannot be accessed in obj

getEnclosingInstance

public static java.lang.Object getEnclosingInstance(java.lang.Object obj)

Returns the enclosing instance (outer class) of an instance which is type of any inner non-static class. Returns null if the instance is not type of an inner class. The access searches the internal field "this$0" and returns its reference. Not that an inner non-static class aggregates the instance which is given on construction of the inner instance. On source level all elements of the enclosing instance are visible without additional designation or with the "Enclosingclass.this" construction. On run level it is that aggregation.

Parameters:

obj - The instance

Returns:

the enclosing instance or null.

getEnclosingInstance

private static java.lang.Object getEnclosingInstance(int recurs,
                                                     java.lang.Object obj)

isReferenceToEnclosing

public static boolean isReferenceToEnclosing(java.lang.reflect.Field ref)

Checks whether a given Field is the reference to the enclosing respectively outer class. Such an reference is not visible in the souce code often. In source code it should be written with

  EnclosingType.this 

but it can be omitted. The internal name of the field is

 this$99

whereby 99 is a number, this$0 for the immediate enclosing instance. Note that a enclosing instance is accessible immediately, but it is a referenced object.

Parameters:

ref - the Field

Returns:

true if the name of the field starts with this$

isOrExtends

public static boolean isOrExtends(java.lang.Class<?> thisclazz,
                                  java.lang.Class<?> cmpclazz)

Check whether a given class is type of another class. This method does not check interfaces, only the extends-path. Example:

 MyClass myInstance = new MyClass();  //MyClass extends MySuperclass.
 ...
 if(DataAcess.isOrExtends(myInstance.getClass(), MySuperclass.class)) { ...
 

This method is similar like

   myInstance instanceof MySuperclass
 

. The difference is: It checks classes.

Parameters:

thisclazz - Class to test, usual build with myInstance.getClass()

cmpclazz - A Class to check, usual build with Classtype.class

Returns:

true if thisclazz is of type cmpclazz. Note: It does not check interfaces.

getStringFromObject

public static java.lang.String getStringFromObject(java.lang.Object content,
                                                   java.lang.String format)

Returns a string representation of the object.

• content == null returns an empty string.
• content is a numerical type, returns a formatted string from it.
• else return content.toString().

Parameters:

content - any object

format - may be null, if not null it is used with String.format(String, Object...).

Returns:

A string which represents content.

getInt

public static int getInt(java.lang.Object val)

Gets the int value from any Object. If the Object can represent a int val, convert and returns it. Elsewhere it returns 0. TODO return int from a String (CharSequence) with conversion.

Parameters:

val - The Object. An int value is returned from all numerical wrappers: Byte, ... Float, Double.

Returns:

the value.

getFloat

public static float getFloat(java.lang.Object val)

Gets the float value from any Object. If the Object can represent a float val, convert and returns it. Elsewhere it returns 0. TODO return int from a String (CharSequence) with conversion.

Parameters:

val - The Object. An float value is returned from all numerical wrappers: Byte, ... Float, Double.

Returns:

the value.

getLengthOfArray

public static int getLengthOfArray(java.lang.Object data)

Checks whether data is an array and returns the current number of elements.
Note: Use data.getClass(): Class.isArray() to check whether it is an array

Parameters:

data - any data

Returns:

-1 if it is not an array. The current number of elements if it is an array.

getArrayElement

public static java.lang.Object getArrayElement(java.lang.Object data,
                                               int... ixArray)

Gets the indexed element of the given array.

Parameters:

data - Should be an array with the expected number of dimensions, elsewhere see throws

ixArray - The indices, maybe missed or lesser than array depth, then data or an element as array is returned. if ixArray contains more indices than necessary, there are ignored.

Returns:

the array element

Throws:

java.lang.IndexOutOfBoundsException - on faulty ixArray

Since:

2016-01-17 for primitive types too.

setBit

public static int setBit(int value,
                         int mask,
                         boolean set)

Sets a bit in a int word

Parameters:

value - The actual value of the word

mask - Designation of bits to change. Usual only one bit. Tip: Use symbolic names.

set - true: set this bits to 1, false: reset the bits to 0.

Returns:

The new value of the word. You should invoke: myBitword = setBit(myBitword, ....);

createOrReplaceVariable

public static DataAccess.Variable<java.lang.Object> createOrReplaceVariable(java.util.Map<java.lang.String,DataAccess.Variable<java.lang.Object>> map,
                                                                            java.lang.String name,
                                                                            char type,
                                                                            java.lang.Object content,
                                                                            boolean isConst)
                                                                     throws java.lang.IllegalAccessException

Creates or replaces a variable with a simple name in the given container. If the variable exists, its content will be replaced by the new definition.

Parameters:

map - The container for variables.

name - The name of the variable in the container.

type - one of A O Q J S U L M V E C = Appendable, Object, Boolean, Long, String, StringBuilder, ListContainer, Map, VariableTree, EnvironmentVariable, Class

content - The new value

isConst - true then create a const variable, or change content of a constant variable. A const variable is designated by DataAccess.Variable.isConst boolean element. A const variable can change its content by setting another const value with this param, but not by assign without this const param flag.

Throws:

java.lang.IllegalAccessException - if a const variable is attempt to modify without isConst argument.

setVariable

public static void setVariable(java.util.Map<java.lang.String,DataAccess.Variable<java.lang.Object>> map,
                               DataAccess.Variable<java.lang.Object> ref)

Set or replaces a variable with a simple name in the given container. If the variable exists, its content will be replaced by the new definition. In opposite to createOrReplaceVariable(Map, String, char, Object, boolean) the container will contain the original given ref.

Parameters:

map - The container for variables.

ref - Initialized variable with or without value.

getVariable

public static DataAccess.Variable<java.lang.Object> getVariable(java.util.Map<java.lang.String,DataAccess.Variable<java.lang.Object>> map,
                                                                java.lang.String name,
                                                                boolean strict)
                                                         throws java.lang.NoSuchFieldException

Searches the variale in the container and returns it.

Parameters:

map - The container

name - name of the variable in the container

strict - true then throws an NoSuchFieldException if not found.

Returns:

null if strict = false and the variable was not found.

Throws:

java.lang.NoSuchFieldException

toString

public java.lang.String toString()

Should be used only for debug to view what is it.

Overrides:

toString in class java.lang.Object

See Also:

Object.toString()

idents

public java.lang.CharSequence idents()

Returns a CharSequence with the idents of the path separated with "."

Returns:

null if datapath is empty.

debugIdent

public static void debugIdent(java.lang.String ident)

A debug helper: Set this ident to any String, which is expected for access. Then a breakpoint may be used. Set the breakpoint in the routine debug() in any IDE (Eclipse...)

Parameters:

ident - The ident to break;

debugMethod

public static void debugMethod(java.lang.String ident)

A debug helper: Set this identifier to any String, which is expected for invocation of a method. Then a breakpoint may be used. Set the breakpoint in the routine debug() in any IDE (Eclipse...)

Parameters:

ident - The identifier to break;

debug

protected static void debug()

Set a breakpoint here to edit a debugIdent(String)

writeStruct

public void writeStruct(java.lang.Appendable out)
                 throws java.io.IOException

Throws:

java.io.IOException

shortFromUnsignedByte

public short shortFromUnsignedByte(byte val)

Converts a value in a byte to a unsigned value, which can be stored in a short in Java. Note that unsigned values are often used in C, and stored in a less memory location such as a byte if possible. For algorithm which are used in C too (tranlated with Java2C), this feature may be necessary.

Parameters:

val - a byte value in range -128..0..127

Returns:

unsigned value of the byte, -128..-1 is presented by 128..255

intFromUnsignedShort

public int intFromUnsignedShort(short val)

Converts a value in a short to a unsigned value, which can be stored in a int in Java. Note that unsigned values are often used in C, and stored in a less memory location such as a byte if possible. For algorithm which are used in C too (tranlated with Java2C), this feature may be necessary.

Parameters:

val - a short value in range -32768..0..32767

Returns:

unsigned value of the byte, -32768..-1 is presented by 32768..65535