de.frame4j.util

Class PropMapHelper

java.lang.Object

de.frame4j.util.PropMapHelper

@MinDoc(copyright="Copyright  2009  A. Weinert",
        author="Albrecht Weinert",
        version="V.56",
        lastModified="28.06.2021",
        usage="import",
        purpose="common map and properties utilities")
public abstract class PropMapHelper
extends Object

Helpers for maps and properties.

This class has static (helper) methods for Maps and properties especially for AbstractMap<CharSequence, String>, used among others in PropMap, Prop and AppLangMap.

© Copyright 2009 Albrecht Weinert

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	PropMapHelper.Entry An entry: key value pair for (Prop)Maps.
static class	PropMapHelper.Indexed Designation of an indexed property.

Field Summary

Fields

Modifier and Type	Field and Description
protected static String	lastSuccReadEnco Last successful file encoding for reading or default.
static int	PUSTFI Modifier public static final.
static String	specialCharsToEscape Characters to be transformed into backslash (\) escape sequences.

Method Summary

Modifier and Type	Method and Description
static String	doEscape(CharSequence sequ, boolean escapeSurSpace) Converting special and control characters to backslash escape sequences.
static Method	getMethod(Class<?> cl, String name, Class<?>... parTypes) Get a method by signature for a class.
static int	gtPrim(int val) A next prime number.
static void	load(InputStream input, CharSequence encoding, Map<CharSequence,String> map) Read a list of properties from a stream.
static boolean	oddEndSlashs(CharSequence line) A character sequence ends with a odd number of (\) backslashes.
static int	posHash(String key) Positive hash code.
static boolean	setField(Object obj, String key, String value) Setting an object's field (beans property).
static void	store(Map<?,?> map, OutputStream output, CharSequence startComment, CharSequence encoding) Put a list of properties to an output stream.
static String	unEscape(CharSequence sequ) Convert backslash escape sequences to the character.

Methods inherited from class java.lang.Object

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

Field Detail

specialCharsToEscape

public static final String specialCharsToEscape

Characters to be transformed into backslash (\) escape sequences.

A short string containing the characters, which within keys and values have to be transformed into backslash escape sequences for external text representations. It's necessary because of their syntactic meaning to the parsing process.

Contains = : # ! as well as tabulator, return, line feed and form feed.

See Also:

Constant Field Values

PUSTFI

public static final int PUSTFI

Modifier public static final.

Value: 25

See Also:

Modifier, Constant Field Values

lastSuccReadEnco

protected static volatile String lastSuccReadEnco

Last successful file encoding for reading or default.

default / start value: ComVar.FILE_ENCODING

Method Detail

load

public static void load(InputStream input,
                        CharSequence encoding,
                        Map<CharSequence,String> map)
                 throws IOException,
                        NullPointerException

Read a list of properties from a stream.

This method reads an input stream line by line. Using the standard rules for .properties files key value pairs are extracted from the text input by the parsing process.

These key value pairs are used as arguments to the method Map.put(key, value) of the Map<CharSequence, String> map passed as parameter.

The whole operation is synchronised with map.

The mentioned syntactic rules are documented and (with one tiny bug) implemented by Properties.load(InputStream).
Hint / warning: Those java.util.Properties rules are not fully implemented by the Eclipse .properties plug-in distributed 2008. Do NOT use it.

One little addition to the mentioned rules by this method is

• A single (lonely) key in one input line ( uhu ) gets the value null.
• A key in a line followed by a key value separator sign, but no explicit value (uhu = ) gets the empty String (ComVar.EMPTY_STRING) as value.

This addition was made as some applications need the distinction between no value set as initial default (null) and no value set afterwards explicitly (ComVar.EMPTY_STRING) by parameter parsing.

encoding is stripped from surrounding white space. If null or (then) empty ComVar.FILE_ENCODING is used. If this or the given encoding fails ISO-8859-1 is used.

Parameters:

input - the stream to read the properties from

encoding - the inputs encoding (or character set)

map - the map to put the properties in

Throws:

IOException - when problems reading the input

NullPointerException - when input or map are null

UnsupportedOperationException - if a put is rejected by map, the reason the often being the changing of an immutable entry's value.

IllegalArgumentException - if put(String, String) is so rejected by map.

unEscape

public static String unEscape(CharSequence sequ)

Convert backslash escape sequences to the character.

In the input sequence sequ the backslash escape sequences, namely \t, \r, \n, \f will be converted to the corresponding control character.

\uxxxx expects xxxx as four digit hex number; and that six character sequence is converted to the corresponding unicode character.

All other characters after the backslash \ (especially a second \) will be left unchanged.

Parameters:

sequ - sequence to convert

Returns:

result as String

Throws:

IllegalArgumentException - if \uxxxx - syntactical faults

NullPointerException - sequ == null

store

public static void store(Map<?,?> map,
                         OutputStream output,
                         CharSequence startComment,
                         CharSequence encoding)
                  throws IOException

Put a list of properties to an output stream.

This method stores all key value pairs contained in the passed Map map using the syntactical rules documented with Properties.store(OutputStream, String) and load(InputStream, CharSequence, Map).

Hint: Properties.store(OutputStream, String) respectively an internal helper do (at least did) faultily not act as there documented.

The output is preceded by two comment lines beginning by a sharp #. The first one is the content of the parameters startComment; the second one giving the actual date by TimeHelper.TimeHelper.format(CharSequence, java.time.ZonedDateTime).

The key value pairs are extracted via Map.entrySet() and Set.toArray(). (This operation is synchronised with map.) Every non null entry in that array will be output in the text form key = value . Special characters are converted before by the method doEscape((CharSequence, true)) to backslash escape sequences.

encoding is stripped from surrounding white space. If null or (then) empty ComVar.FILE_ENCODING is used. If this or the given encoding fails ISO-8859-1 is used.

Hint: A null startComment will be substituted by a raw hint to the syntax "Map: key = value". If startComment is multi line, each line except the first one must start by # or "smuggle in" a key value pair, strictly obeying the syntax. This is NOT checked in this method.

Parameters:

map - the properties

output - the stream to write the properties to

startComment - a describing comment to put at the begin

encoding - the streams encoding (character set)

Throws:

IOException - when output problems

NullPointerException - when output or map are null

doEscape

public static String doEscape(CharSequence sequ,
                              boolean escapeSurSpace)

Converting special and control characters to backslash escape sequences.

If escapeSurSpace is true, a given leading and / trailing space in sequ are replaced by "\ ".

All following character values are converted to backslash escape sequences:
\, tab, form feed, line feed and return as well as = # : and ! will be converted to
\\, \t, \f, \n, \r respectively \=, \# and so on.

The perhaps astonishing "escaping" of =, #, : and ! is compelled by the syntax of reading properties, see load(InputStream, CharSequence, Map).

characters with a (uni) code less then 0x0020, grater than 0x00FD as well as between 0x007F and 0x00A0 will be coded as \uxxxx, xxxx being the four digit hexadecimal Unicode number (see. TextHelper.fourDigitHex(Appendable, int).

Parameters:

sequ - the sequence to convert

escapeSurSpace - true: convert starting and trailing blank (if there) to "\ "

Returns:

converted sequence as String (may be empty but never null)

posHash

public static final int posHash(String key)

Positive hash code.

Returns the String.String.hashCode() of key made non negative by cutting the (31st) sign bit off.

The reason of being is Java's strange modulo (%) implementation having disastrous effects when naively — using the text book's algorithm — converting a hash value to a first try index by modulo length.

Parameters:

key - may be empty but never null

Returns:

a positive hash value

oddEndSlashs

public static boolean oddEndSlashs(CharSequence line)

A character sequence ends with a odd number of (\) backslashes.

This method returns true if the character sequence line ends with one or a higher odd number of sequential \ backslashes.

The reason of being is a syntax considering two consecutive backslashes as an escaped "e;real" one and one trailing \ backslash as an order for a continuation line.

This method implements this "to be continued" condition.

Parameters:

line - sequence to be considered

Returns:

true: to be continued

Throws:

NullPointerException - if line is null

gtPrim

public static int gtPrim(int val)

A next prime number.

This method chooses out of a sparsely populated list of prime numbers the smallest >= the parameter val. One usage is getting the next about double prime size, when enlarging / rehashing a container.

The returned value is in the range 71 .. 479.001.599 and will be in average the double of the parameter value. Larger parameter values will get a -1.

Returns:

prime number >= val in the range <=479.001.599; -1 without

getMethod

public static Method getMethod(Class<?> cl,
                               String name,
                               Class<?>... parTypes)

Get a method by signature for a class.


This method is the equivalent of cl.getMethod(name, parTypes) except returning null instead of raising exceptions when no method object could be delivered.

Parameters:

cl - the class having the method searched for (hopefully)

name - the name of the method

parTypes - the parameter types

Returns:

a fitting method or null

setField

public static boolean setField(Object obj,
                               String key,
                               String value)
                        throws SecurityException,
                               IllegalArgumentException

Setting an object's field (beans property).

If obj or key is null, nothing will happen except returning false.

Otherwise this method (heavily) utilises introspection of the object obj to set its property named key by the value value.
The only case, where no (expensive) introspection is used is if

• obj is of type AttrSettable and
• AttrSettable.setAttribute(key, value does not return NO_KNOWN_ATTRIBUTE.

In all other cases the following (introspection) steps are taken:
If the platform or runtime forbids introspection into obj a SecurityException will happen.

The setting of obj's property named key by the value is effected either by accessing a public object variable or by using a public method named setKey().

In determining the setter method it is additionally evaluated, if the parameter key may designate an indexed property according to the rules of PropMapHelper.Indexed.make(key). If this is the case, with the key shortened by the index two parameter set methods setKey(int index, ..) are searched for.

The setKey method is searched with the following signatures in this sequence:.

• setKey(String) and afterwards setKey(CharSequence).
  Does one of this (public) methods exist, it is called as setKey(null) if value is null.
• If key designates possibly an indexed property, setKey(int, String) and afterwards setKey(int, CharSequence).
  Does one of this (public) methods exist, it is called as setKey(index, null) if value is null.
• setKey(int) and afterwards setKey(int, int).
  These methods are only searched if value is decodable as int by (TextHelper.asIntObj(CharSequence).
• setKey(boolean) and afterwards setKey(int, boolean).
  These methods are only searched if value is decodable as a binary ("truth") value by TextHelper.asBoolObj(CharSequence).
• setKey(Color) and afterwards setKey(int, Color).
  Is one of these methods found, it is now tried to interpret value as colour by ColorHelper.getColor(CharSequence)). Is that impossible an IllegalArgumentException is thrown, otherwise of cause the setter is called.

Implementation hint: The rationale behind the last "colour" point is a) the assumption of searching one method or if possible indexed two methods by introspection is cheaper than the multi language colour interpretation trials. And b) the assumption, that if a class provides a setter for Color the property has to be either a colour or is wrong. Hence the IllegalArgumentException before the search for public variables.

For the corresponding method setKey() the first letter after "set" is always made upper case according to beans and set/get method conventions. As a consequence two properties named (keyed) otto and Otto would both take the same setters setOtto(..). But they would not both succeed with AttrSettable.setAttribute(key, value; see above.

The called setter may itself throw exceptions — may be because of detesting the passed value. This case if forwarded by this method as an IllegalArgumentException, too.

If all described toils found no fitting setter method the direct access to a variable named key is tried. Preconditions:

• The object variable is declared in the class of the object obj and not inherited.
  Note: The public setters mentioned above may very well be inherited.
• The variable's type boolean, int or String (explicitly excluding CharSequence is gladly accepted for setters).
• The variable is public and neither static nor final.

The (found) variable remains unchanged, if value is null or not interpretable according to the variable's (int or boolean) type. No exception is raised due to non fitting types or values.
Please note that the String or CharSequence setters would have been called with null value and that all setters might react to values unwanted by throwing exceptions.

Hint: If key contains white spaces or otherwise does not comply to Java's rules for variable names, with all described efforts nothing will be effected. To avoid these waste of resources and time a filtering of keys before or while looping over all properties should be done by the caller. The method Prop.setFields(Object) which uses this method, tries to avoid those wasteful calls.

Parameters:

obj - the object, whose property key might be changed

key - name of the property

value - new value of the property

Returns:

true if the property key could be set

Throws:

SecurityException - if the runtime forbids introspection into obj

IllegalArgumentException - if a called setter throws itself an exception , like for example IllegalArgumentException or a PropertyVetoException. The exception's message is forwarded via the new IllegalArgumentException

See Also:

Prop.setFields(Object)