de.frame4j.util

Class Prop

java.lang.Object

java.util.AbstractMap<CharSequence,String>

de.frame4j.util.PropMap

de.frame4j.util.Prop

All Implemented Interfaces:

Serializable, Cloneable, ConcurrentMap<CharSequence,String>, Map<CharSequence,String>

@MinDoc(copyright="Copyright 1999 - 2009, 2016, 2021  A. Weinert",
        author="Albrecht Weinert",
        version="V.50",
        lastModified="4.06.2021",
        usage="3 phase: make, populate, use (preferably not further modified)",
        purpose="extended capabilities of PropMap for applications, App, ...")
public class Prop
extends PropMap

Properties, extended to support App based and other applications.

Content

Fundamentals
Prop (erties) load and (inter) nationalise
The J V M and start parameter
de.frame4j.util.Prop and start parameter
Copyright, version and so on


Fundamentals

Properties in JavaBeans' sense are part of the visible state of an object. In the classes' Map, AbstractMap and de.frame4j.util.PropMap sense properties are set of key-value-pairs.

This class Prop unites both these aspects. Prop extends PropMap by an ample bundle of utility functions for applications of all kinds. Among others these are:

• comfortable evaluation of properties,
• effortless setting of properties,
• evaluating a String array for property settings using a "grammar" (rules and default values) contained in the properties (self),
• quite simple (inter) nationalising of properties,
• the setting of an objects variables / state by fittingly named properties either by
  • calling the appropriate public setter methods (according to Beans conventions)
    or by
  • writing the variables.

Most of this class' constructors generate (by using the constructor Prop() a Prop object containing the (basic) properties for the parameter evaluation mentioned above; see there. This enables all utilising applications to evaluate start respectively initialisation parameters with little to null programming effort.

Prop (erties) load and internationalise

Properties and PropMap entries can be loaded from text files (streams) obeying a quite primitive syntax rules. Some of the constructors and methods load files and resources of that kind, using a simple name and some suffixes

• name.properties
• name_language.properties
• name_language_region.properties

That loading is done / tried from

1. the actual directory (the applications starting directory),
2. the JVM's jre\lib directory,
3. the deployment archive (.jar file) should the application have been loaded from that (that would include all applications and tools deployed as installed extensions prior Java 9), or
4. on base of an URL (if given)

(tried in the named sequence).

"name" here is in most cases the (pure) name of the application (see also App and Prop(App, CharSequence)).
"language" here means the lower case two letter language denotation (like de, fr, en or it, according to http->.ISO 639-2).
"region" here means the short two upper case country denotation (DE, GB, US).
Some constructors and methods search and or put these denotations in the Prop object's properties named (keyed) "language" and "region". Some methods, like nationalise(CharSequence, CharSequence, CharSequence) allow a direct setting of language and / or region. This supports easy nationalising of applications without re-starting (or worse re-building).

The class AppLangMap supports these tasks further; in co-operation with this class even a very basic Prop (the name.properties above) object has multilingual stereotypical expressions and output patterns; see also PropMap.valueLang(CharSequence, String).

The J V M and start parameter

Java forwards an appliation's start parameter (as a undue reverence to C) as a String array to the started class' static main method (greetings by C again).

As values for constructing this parameter array the JVM (java.exe or javaw.exe in the case of Windows) takes all start (command line) parameters that follow the parameter denoting the start class or the .jar file.

This class Prop widely simplifies (especially when extending de.frame4j.util.App) the handling and evaluation of those start parameters (s.u.). See also some helpers in the class de.frame4j.text.TextHelper for preparing start parameters for sub processes, applications or plug-ins.

Hint: When preparing start parameters all known versions of SUN's JVM / JRE for Windows show a feature that closer consideration debunks as dangerous bug:
If one of the original parameters contains at least one wildcard character (One or more * asterisk or ? question mark), this original will be replaced by as many matching file names as will be found in the actual directory, forwarding more parameters to the application (main(String[])) as are seen on the command line e.g.
If there are no such files (or directories) the parameter containing question mark (?) or asterisk (*) is forwarded unchanged.
This behaviour is (of course) totally unwanted if changing the number and hence sequence of parameters spoils their parsing or if the parameter's semantic has nothing to to with files. But even if files or directories are meant the application might want to keep the control over the evaluation of wild card expressions.
The unwanted and often dangerous behaviour can only be stopped by surrounding the parameter by quotes. This and other Frame4J's classes allow substituting a plus + (as wildcard) for the * as a often suitable alternative.

de.frame4j.util.Prop and start parameter

An application should use this class Prop to evaluate its (String[]) start parameters; this is supported among others by the methods parse() and setFields(). An application extending de.frame4j.util.App — a good choice instead of starting on empty ground — gets all this by just using one of the inherited methods go(String[]...) for starting.

Evaluating start parameters by Prop provides many advantages in flexibility and in self documentation, as the evaluating rules (the "grammar") are defined as properties that are human readable and writable put in the basic .property file or resource. See among others the examples Era.properties and SVNkeys.properties of the tools Era (source) and SVNkeys.

Hint: Direct Applet support was removed August 2016.


Copyright, version and so on

© Copyright 1999 - 2004, 2006, 2016 Albrecht Weinert.


To the table of content.

Version:

50 (4.06.2021)

Author:

Albrecht Weinert

See Also:

PropMap, AppLangMap, AppHelper, App, parse(String[], CharSequence, boolean), parse(String[], CharSequence), setFields(Object), PropMapHelper.setField(Object, String, String), Serialized Form

Nested Class Summary

Nested classes/interfaces inherited from class de.frame4j.util.PropMap

PropMap.EntrySet, PropMap.KeySet<S>

Nested classes/interfaces inherited from class java.util.AbstractMap

AbstractMap.SimpleEntry<K,V>, AbstractMap.SimpleImmutableEntry<K,V>

Nested classes/interfaces inherited from interface java.util.Map

Map.Entry<K,V>

Field Summary

Fields

Modifier and Type	Field and Description
protected Class<?>	baseClass A base class.
protected URL	baseURL A base URL.

Fields inherited from class de.frame4j.util.PropMap

entries, FILE_LIST_LEN, hashMissMax, hashMissSum, internalEntrySet, internalKeySet, keyStringMld, language, region, reHashes, rLock, valStringMld, VL_CL, wLock

Constructor Summary

Constructors

Constructor and Description
Prop() Constructor with basic presettings for applications.
Prop(App app, CharSequence commBeg) Constructor with presettings by an application (App object).
Prop(char se) Constructor with basic pre-settings for web services.
Prop(CharSequence fileName, CharSequence encoding) Constructor with presettings from a file (by name).
Prop(Class<?> cl, String shortClassName, boolean allowNoPropFile, String extraProp) Constructor with presettings related to a class.
Prop(Map<CharSequence,String> preset) Constructor with presettings by a Map.
Prop(URL baseURL, String fileName, CharSequence encoding) Constructor with presettings from a file with a base URL.

Method Summary

Modifier and Type	Method and Description
Object	changeProperty(CharSequence keyValue) Change an existing property.
AppLangMap	getAppLangMap() Fitting language object.
InputStream	getAsFileStream(CharSequence fileName) Get an input stream for a file name.
InputStream	getAsResourceStream(String fileName) Get an input stream for a file name as resource.
InputStream	getAsStream(String fileName, String ext) Get an input stream for a file name as file or as resource.
boolean	getBoolean(CharSequence name, int num, boolean def) Fetching a "numbered" property as boolean with default.
String	getHelpText(String def) Fetching the property "helpText" nationalised.
int	getInt(String name, int num, int def) Fetching a "numbered" property as int with default.
String	getProperty(CharSequence key, int num) Fetching a "numbered" or indexed property as non empty String.
String	getResString(CharSequence key, String def) Fetching a property also indirectly from a resource — nationalised.
String	getString(String name, int num, String def) Fetching a "numbered" or indexed property as non empty String.
String	getText(CharSequence key) Fetching a property as (non null) text.
StringBuilder	list() List all properties as StringBuilder .
void	list(PrintStream out) Output all properties to a PrintStream .
void	list(PrintWriter out) Output all properties to a PrintWriter .
boolean	load(CharSequence fName, CharSequence encoding) Loading of properties from a .properties text file.
boolean	load1(Class<?> cl, CharSequence fileName, CharSequence encoding) Loading of properties from a text file; class related.
boolean	load1(URL url, CharSequence fileName, CharSequence encoding) Loading of properties from a text file; URL related.
boolean	nationalise(CharSequence fileName, CharSequence lang, CharSequence reg) Nationalising the properties.
void	parse(String[] args, CharSequence commSt) Evaluate or parse a sequence of parameters.
void	parse(String[] args, CharSequence commSt, boolean partial) Evaluate or parse a sequence of parameters.
String	percReplace(String val) Replace references to properties by their values.
int	setFields(Object obj) Setting an object's fields (beans properties).
protected PropMapHelper.Entry	substLang(String key, String lang, String regio, String def) Get a substitute entry for a key — nationalised.
String	valueLang(CharSequence key) Fetching a value preferably in user language.

Methods inherited from class de.frame4j.util.PropMap

add, asProperties, clear, clear, clone, containsKey, containsValue, deepIt, entry, entrySet, equals, get, getBoolean, getBoolean, getInt, getLanguage, getLong, getProperty, getProperty, getProperty, getProperty, getRegion, getString, getString, hashCode, hashQuality, indexOfKey, isEmpty, keySet, load, load1, put, put, putAll, putIfAbsent, putImpl, putNewImpl, putNewImut, rehash, rehash, remove, remove, remove, replace, replace, setLanguage, setNewProperty, setNewProperty, setProperty, setProperty, setProperty, setRegion, size, sortedKeys, sortedList, store, subSet, toString, value, valueLang

Methods inherited from class java.util.AbstractMap

values

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface java.util.concurrent.ConcurrentMap

compute, computeIfAbsent, computeIfPresent, forEach, getOrDefault, merge, replaceAll

Methods inherited from interface java.util.Map

values

Field Detail

baseURL

protected URL baseURL

A base URL.

The base URL is set by some constructors.

If not null, it is used as base to search for .properties files by some of the load() methods.

default: null

baseClass

protected Class<?> baseClass

A base class.

The base class is set by some constructors.

If not null, it is used as base to search for .properties files by some of the load() methods extending the search into the .jar file from which the application class may have been loaded.

default: null

Constructor Detail

Prop

public Prop()

Constructor with basic presettings for applications.

A Prop object with some basic properties for applications will be made. The new Prop already has those properties:

• verbosity=normal *)
• help = false *)
• option-v= verbosity = verbose
• option-verbose= verbosity = verbose
• option-silent= verbosity = silent
• option-normal= verbosity = normal
• option-debug= verbosity = debug
• option-test= verbosity = test
• option-a= outMode=append
• option-o= outMode=overwrite
• option-c= outMode=create
• option-askGraf= askGraf=true
• option-askCons= askGraf=false
• option-log= logDat
• option-?= help=true
• option-help= help=true
  
• source=
• outMode=ask
• askGraf=!ComVar.NOT_WINDOWS **)
• codePages=
• dest=
• logDat=
  
• outDat=
  
• language= <wie user.language or ComVar.UL>
• region= <wie user.region bzw. ComVar.UR>
• option-de= language=de ## region=DE
• option-deDE= language=de ## region=DE
• option-deCH= language=de ## region=CH
• option-en= language=en ## region=GB
• option-enGB= language=en ## region=GB
• option-fr= language=fr ## region=FR
• option-frFR= language=fr ## region=FR
• option-frCH= language=fr ## region=CH
• option-frBE= language=fr ## region=BE
• option-it= language=it ## region=IT
• option-itIT= language=it ## region=IT
• option-itCH= language=it ## region=CH
• option-es= language=es ## region=ES
• option-da= language=da ## region=DK
• option-nl= language=nl ## region=NL
• option-pt= language=pt ## region=PT
  
• option-lang= language
  
• option-regio= region
  
• thoseDirs=
• omitDirs=
• thoseFiles=
• omitFiles=
• days=nosetting
• daysOld=nosetting
• since=
• til=
  
• ignoreCase= !ComVar.NOT_WINDOWS
• option-cs= ignoreCase=false
• option-case= ignoreCase=false
• option-ncs= ignoreCase=true
• option-nocase= ignoreCase=true

These are the basic properties including the basic syntax for evaluating start parameters as well as as base for often used file and directory criteria.

Remark *): If constructed with an App (inheritor) object (see e.g. Prop(App, CharSequence)), that in not the base application (that is usually the one started with the JVM) but is an "App plug in") of another suitable "mother application", then some properties are copied from there: help and verbosity.

Hint: A new totally empty Prop object can be made by new Prop((Map)null). In that case, ask the question, if not a PropMap is the thing meant.

Internal implementation hint: The description of the common basic properties set here with respect to start parameters is provided as property "hlpfwopt" in at least German and English in AppLangMap.properties. Changes here must at once be mirrored there, otherwise the help output of most tools and applications (inserting this by %hlpfwopt% its help texts) would get misleading.

See Also:

load(), Prop(Class, String, boolean, String), Prop(URL, String, CharSequence)

Prop

public Prop(char se)

Constructor with basic pre-settings for web services.

A Prop object with some basic properties for Applets and Servlets will be made. These are a small subset of those made for applications respectively programs (by other constructors or factory methods). If neither Servlet (S) nor Applet (A) is specified (only) this constructor returns an empty Prop object (capacity 271).

The new Prop for a Servlet or an Applet has those properties:

• verbosity=normal
• help = false
• language= <like user.language respectively ComVar.UL>
• region= <like user.region respectively ComVar.UR>
• ignoreCase set true for Windows (but not if Servlet)

If a Servlet, you get additionally

• option-v= verbosity = verbose
• option-verbose= verbosity = verbose
• option-silent= verbosity = silent
• option-normal= verbosity = normal
• option-debug= verbosity = debug
• option-test= verbosity = test
  
• option-de= language=de ## region=DE
• option-deDE= language=de ## region=DE
• option-deCH= language=de ## region=CH
• option-en= language=en ## region=GB
• option-enGB= language=en ## region=GB
• option-fr= language=fr ## region=FR
• option-frFR= language=fr ## region=FR
• option-frCH= language=fr ## region=CH
• option-frBE= language=fr ## region=BE
• option-it= language=it ## region=IT
• option-itIT= language=it ## region=IT
• option-itCH= language=it ## region=CH
• option-es= language=es ## region=ES
• option-da= language=da ## region=DK
• option-nl= language=nl ## region=NL
• option-pt= language=pt ## region=PT

This features the base properties usual for web services without the file and directory criteria for (most) applications (by Prop()).

Parameters:

se - S, s: Servlet; A, a: Applet; else: empty.

See Also:

load(), Prop(), Prop(URL, String, CharSequence)

Prop

public Prop(CharSequence fileName,
            CharSequence encoding)
     throws FileNotFoundException

Constructor with presettings from a file (by name).

A Prop object without any basic properties as set by the other constructors is made. Using load(fileName, encoding) a preset by the content of text file (in Java/SUN properties syntax) is tried (if fileName is not empty).

If this fails, a FileNotFoundException is thrown. If more than one file shall be tried it's better to call this constructor with null and handle the (trial) loads one by one.
Calling this constructor with null, returns a (totally) empty Prop().

Parameters:

fileName - the name of properties text file

Throws:

FileNotFoundException - if file fileName is nor readable.

See Also:

load(CharSequence, CharSequence), Prop(Class, String, boolean, String), Prop(URL, String, CharSequence), Prop()

Prop

public Prop(URL baseURL,
            String fileName,
            CharSequence encoding)
     throws FileNotFoundException

Constructor with presettings from a file with a base URL.

A Prop object preset like by Prop() is made and (by load(CharSequence, CharSequence)) additionally set by a file specified by fileName + Basis-URL.

If this fails, a FileNotFoundException is thrown.
If fileName is null the effect is like Prop() plus (if given) the setting of a baseURL.

Parameters:

fileName - the name of properties text file

Throws:

FileNotFoundException - if no such file readable

See Also:

load(CharSequence, CharSequence), Prop(Class, String, boolean, String), Prop(CharSequence, CharSequence), Prop()

Prop

public Prop(Map<CharSequence,String> preset)

Constructor with presettings by a Map.

A Prop object will be constructed that will contain all entries of the Map preset that fulfil PropMap's conditions on key-value-pairs.

If preset is null (or empty), the newly made Properties object is empty. It will also not contain any standard or default entries made by other constructors like Prop().

See Also:

Prop(Class, String, boolean, String), Prop(CharSequence, CharSequence), Prop()

Prop

public Prop(Class<?> cl,
            String shortClassName,
            boolean allowNoPropFile,
            String extraProp)
     throws FileNotFoundException

Constructor with presettings related to a class.

A Prop object will be made with all standard / default entries as made by the parameterless constructor Prop(). Then, using load(CharSequence, CharSequence) all properties from the file className+".properties" are added. Used therefore is the pure (short) class name of the class cl, that means without packages and else.

If the reading of the file in the actual directory meets with no success the directory java.home\lib is tried. If that fails reading a resource from the applications (deployment) .jar file is tried. If all that fails a FileNotFoundException is thrown.

After loading the file / resource nationalising the Prop object made will be tried by
nationalise(className, null, null).

A speciality for direct and and indirect de.frame4j inheritors:
If cl is an inheritor of a tool of a de.frame4j application its .properties file (from the .jar file) will be loaded first. For that the "total" name de/frame4j/parentApp will be used. The effect is that fitting properties of the base application don't have to be repeated in the inheriting applications .properties file.

Parameters:

allowNoPropFile - if true the absence of an own .properties file will be allowed; otherwise an exception would be thrown

extraProp - if not null or empty, the name of extra properties to be loaded before the class related ones

Throws:

FileNotFoundException - if the base .properties file is not readable and allowNoPropFile is false

See Also:

load(), Prop(CharSequence, CharSequence)

Prop

public Prop(App app,
            CharSequence commBeg)
     throws FileNotFoundException

Constructor with presettings by an application (App object).

This is the most powerful and most comfortable constructor for Java applications extending de.frame4j.util.App and fulfilling its contract. This constructor does all the evaluating of start arguments, the nationalising according to all available .properties files for that application.

The Prop object is made by Prop(Class, String, boolean, String). If the App object app has a mother application the properties help and verbosity take its values as defaults (instead of false and NORMAL.

After that a file named "ClassName.properties" will be searched and loaded to this Prop object. Then other .properties files with names generated according to the (system) properties user.language and user.region are used to nationalise it.

The .properties files will be searched for in the actual directory, in java.home\lib and as resource in the application's deployment .jar (in that sequence). If all fails for base .properties file a FileNotFoundException will be thrown.

Afterwards the application's start arguments will be evaluated (using parse()).

If after that one of the properties language or region have a value different from the system properties user.language respectively user.region, this Prop object will be nationalised (again) using those new values.

And at last the variables (fields) of the App object app will be set by setFields().

Throws:

FileNotFoundException - if no base .properties file for app can be found and read, except the application explicitly allows that omission; see App.allowNoPropertiesFile()

NullPointerException - if app is null

IllegalArgumentException - on parsing exception and if a called set(..) method raises an exception like IllegalArgumentException or an PropertyVetoException. The message of that exception will be transfered to the new IllegalArgumentException

See Also:

parse(), setFields(), getText(), Prop(CharSequence, CharSequence), Prop(Class, String, boolean, String)

Method Detail

load1

public boolean load1(URL url,
                     CharSequence fileName,
                     CharSequence encoding)

Loading of properties from a text file; URL related.

The file denoted by fileName related to the provided url or this Prop's baseURL will be loaded into this Prop object. For the text file's syntax see Properties.load().

If that succeeds true is returned. In this case this Prop object's properties are usually modified or added to.
If this fails or the file handling leads to exceptions false is returned.

Parameters:

url - the (base) URL. If null, the base URL set by some constructors is used instead. If that is null too, false is returned.

fileName - the URL related file name. \ will be replaced by / .

Returns:

true on successful load

See Also:

load1(Class, CharSequence, CharSequence), PropMap.load1(CharSequence, CharSequence), load(CharSequence, CharSequence)

load1

public boolean load1(Class<?> cl,
                     CharSequence fileName,
                     CharSequence encoding)
              throws ClassCastException,
                     UnsupportedOperationException,
                     UnsupportedOperationException

Loading of properties from a text file; class related.

The file denoted by fileName related to the class cl or to a baseClass set by some constructors will be loaded into this Prop object. For the text file's syntax see Properties.load().

If that succeeds, true is returned. In this case this Prop object's properties are usually modified or added to.
If this fails or the file handling leads to exceptions false is returned.

This method just delegates to PropMap's method PropMap.load1(Class, CharSequence, CharSequence). The differences are the mentioned substituting of cl == null by baseClass and encoding == null by ComVar.JAR_ENCODING.

Overrides:

load1 in class PropMap

Parameters:

cl - the (base) class. If null, the base class set by some constructors is used instead. If that is null too, false is returned.

fileName - the class related file name. \ will be replaced by / .

encoding - the resource / file encoding. null or empty will get JAR_ENCODING

Returns:

true on successful load

Throws:

IllegalArgumentException - if put(String, String) will be so rejected

UnsupportedOperationException - if put(String, String) will be so rejected

ClassCastException - if a key violates PropMap' contract

ClassCastException - a key violates PropMap' contract

See Also:

load1(URL, CharSequence, CharSequence), PropMap.load1(CharSequence, CharSequence), load(CharSequence, CharSequence)

load

public boolean load(CharSequence fName,
                    CharSequence encoding)

Loading of properties from a .properties text file.

Into this Prop object properties from the file denoted by fileName will be loaded. true is returned on success. For the text file's syntax see Properties.load().

If fileName contains no path (no \ or /), it ends with .properties and if baseClass is not null, it will be tried to read the file as class (loader) related resource. For frame4j base classes it will be tried to find the .properties file under de.frame4j first. For that .jar encoding (usually UTF8) will be used, no matter, what encoding says. If the resource loading succeeds or not direct file loading is tried next.

If that fails fileName will be suffixed by ".properties" if not yet ending so, and the trial will be repeated.

If that file loading fails also the following is done:

• If fileName contains no path (not even .\) the trial is repeated in the jre\lib directory (ComVar.JRL).
• If that fails and if the first resource loading from a jar had failed and if a base URL (baseURL) is set the trial is repeated as URL related load.

If all toils lead to no properties load false is returned.

If an input stream could be made and the properties loading leads to an exceptions (due to key or value / contract violations)b all further work ends and that exception is passed on.

Returns:

true if loading from a file, resource or URL succeeded

See Also:

PropMap.load1(CharSequence, CharSequence), load1(URL, CharSequence, CharSequence), load1(URL, CharSequence, CharSequence), ComVar.JRL

nationalise

public boolean nationalise(CharSequence fileName,
                           CharSequence lang,
                           CharSequence reg)

Nationalising the properties.

This Properties will be nationalised according to language and region given as parameters. null or empty will default to the properties language and region. These, if not otherwise set explicitly, are given by ComVar.UL and ComVar.UR.

A missing fileName is substituted by the first (originally) loaded file for this Prop.

For nationalising two versions

• filename_lang.properties and
• filename_lang_reg.properties.

based on fileName are tried to be loaded from the class files resource and in case of a pure file name on base of ComVar.JRL and ComVar.UD by load(CharSequence, CharSequence).

If at least one of the loads is successful, true is returned.

If the call just repeats previous calls for the same effective language and region, nothing is done and false is returned.

substLang

protected PropMapHelper.Entry substLang(String key,
                                        String lang,
                                        String regio,
                                        String def)

Get a substitute entry for a key — nationalised.

For the (already worked on) case of not having found an entry for

• language_region.key
• language.key

this method tries to find a substitute entry in the following order:

1. an entry of an AppLangMap fitting lang
2. key
3. en.key (only if lang is not en)
4. en_GB.key (only if lang is not en and if regio is not GB)
5. de.key (only if lang is not de
6. an entry of an AppLangMap fitting user language, but not fitting lang

Steps 2 .. 5 are like in the overridden PropMap.substLang().
If none is found, null is returned.
This method changes the behaviour of the (final) inherited method PropMap.valueLang(CharSequence, String).

Overrides:

substLang in class PropMap

Parameters:

key - non empty

lang - two letter lower case language code

regio - two letter upper case region or country code or ComVar.EMPTY_STRING if no region to be used

def - the default value; ignored in this implementation

getAppLangMap

public AppLangMap getAppLangMap()

Fitting language object.

valueLang

public final String valueLang(CharSequence key)

Fetching a value preferably in user language.

The call is equivalent to
valueLang(key, null).

Since:

V.02.37 (13.12.2004)

See Also:

AppLangMap.valueUL(CharSequence)

getAsFileStream

public InputStream getAsFileStream(CharSequence fileName)

Get an input stream for a file name.

It will be tried to make and return an InputStream for the given file name fileN. In case of success the source is registered in the list of opened / used file resources. No success returns null.

Returns:

an input stream in case of success

See Also:

PropMap.load1(CharSequence, CharSequence), getAsStream(String, String)

getAsResourceStream

public InputStream getAsResourceStream(String fileName)

Get an input stream for a file name as resource.

It will be tried to determine an input stream (InputStream)from the fileName provided, that must contain no path (not even .\).

The following will be tried:

• a baseClass related resource. (This would in effect be a file within the deployment .jar),
• a file or archive resource Datei related to the base URL (baseURL) if set.

Returns:

an input stream in case of success

See Also:

load(CharSequence, CharSequence), ComVar.JRL, getAsFileStream(String), getAsStream(String, String)

getAsStream

public InputStream getAsStream(String fileName,
                               String ext)

Get an input stream for a file name as file or as resource.

In a vast variety of way it will be tried to determine an input stream (InputStream) for the fileName provided. If that succeeds that InputStream will be returned and the fileName entered to the list of loaded files. If all fails, null is returned.

The first trial is for files named fileName and fileName suffixed ext if fileName is not yet ending so.

If that fails an fileName contains no path (not even .\), the following is tried (with and without ext):

• a file in the jre\lib directory (ComVar.JRL),
• a resource related to the base class' (baseClass) loader (this would in effect be a file within the deployment .jar),
• a file or archive resource Datei related to the base URL (baseURL) if set.

Returns:

an input stream in case of (any) success

See Also:

load(CharSequence, CharSequence), ComVar.JRL, getAsFileStream(String), getAsResourceStream(String)

changeProperty

public Object changeProperty(CharSequence keyValue)

Change an existing property.

This method is effectively like PropMap.setProperty(CharSequence) with the difference of only changing an existing property (key value pair) and not creating a new one.

If the key ends with one or more decimal digits (and is not consisting of digits only), like e.g. butTarget18, a property beginning with allowIndexed- and ending with the key name is searched; in the example that would be allowIndexed-butTarget. If this property has a integer interpretable value that is >= that of the ending digits, than this new property is considered as pre-existing and added to this Prop object. Returned is the empty String ComVar.EMPTY_STRING in this case.

Parameters:

keyValue - key-value pair

Returns:

the old value or ComVar.EMPTY_STRING if a) null before or b) allowed as new "indexed property"
null in case of failures or if rejected

parse

public void parse(String[] args,
                  CharSequence commSt)
           throws IllegalArgumentException

Evaluate or parse a sequence of parameters.

An array of String parameters (String[]) args will be worked on from start to end or the first occurrence of the character sequence commSt. This is accompanied by a strict syntax check: parameters the usage of with is not defined in this Prop object throw an exception. By using the similar but less strict method parse(String[],CharSequence,false) this strictness can be partly switched off (for applications that will rework the parameters).

The parameters fall in three categories:

• Option's parameters
  They start with a minus sign (-), Case does not not matter with option parameters.
• Set parameters
  They contain an equals sign (=), but no question mark (?) or colon (:) before it.
• Property file parameters
  They start with the ape sign (@).
• Standard parameters
  That are all that don't fall in one of the above categories.

Option parameters
For an option parameter a property named option-parameter (in all lower case) is searched in this Prop object. If it does not exist or has an empty value an exception is raised.

If this property has a value in the form "key=value" (with an equals sign) the property key is set to value.

If this property has a value in the form "key" (without an equals sign) the property key is set to the next parameter in the array args as it is. If there is no next parameters (before commSt) an exception is raised.

Multiple entries defining the effect of the option can be put into one such property separated by "##". Example:
option-floor1 = logDat=floor1.log ## language=de ## alertLevel=9
In case of space problems continuation lines are available.

Set parameters

For a set parameter, having the form "key=value" (with an equals sign) an existing property key will be set to the new value. If this property does not exist an exception is raised. A set parameter may not (!) define a non existing property.
The only exception are indexed properties in the form "butHref17=otto", the definition of which may be allowed by a special property "allowIndexed-butHref=19" (all examples) in the range butHref0 respectively butHref00 to butHref19.

Property file parameter

For a property file parameter @filXY (e.g) the properties of a file named filXY (in the example, without the leading @) or filxy.properties will be loaded and if possible its nationalised versions by nationalise()). If no such file exists an exception is raised.
Attention: If the properties language or region were changed, nationalised versions of the base .properties (named according to application class in most cases) file will be loaded as last step in that proceeding.

Standard parameters

For the first found standard parameter a property named word-0 or is searched for; for the second word-1 and so on. If this property does not exist an exception is raised. Otherwise its value is taken as the name of the property to be set by the standard parameter.

Word numbers in the range 0 to 9 may be given as two digit letters with a leading zero, as word-00 to word-09.

Hint Minus sign handling: To begin a standard parameter with a minus sign double it. Example: -otto is option parameter otto and --otto is the standard parameter -otto. The same applies for numbers: to have a negative one as parameter use --1. (Otherwise it would be option 1 requiring an existing property option-1 .

Hint on null: A String supplied by the JVM to the application's method main() is never null. It may be empty, but if not, no String contained is null (and very seldom empty). The methods parse(String[], CharSequence) and parse(String[], CharSequence, boolean) rely on the supplied String[] fulfilling the same contract as JVM to main(String[]) to do useful work. If not they do just nothing.

This method just calls parse(args, commSt, false).

Parameters:

args - the (start) parameters / arguments to parse

commSt - if not empty a comment start within args and hence its effective end for this methods work

Throws:

IllegalArgumentException - on the contract violations named

See Also:

setProperty(), changeProperty(), load(), setFields()

parse

public void parse(String[] args,
                  CharSequence commSt,
                  boolean partial)
           throws IllegalArgumentException

Evaluate or parse a sequence of parameters.

This method is like exactly like parse(String[], CharSequence) if the parameter partial is false.
When partial is true there are the following differences:

1. Parameter beginning with @ are not interpreted as order to load another .properties file but as standard parameter, except when a property load@prop is true (by "load@prop = on" in the base .properties file e.g.).
2. Standard parameters don't throw exceptions if the related property word-0, word-1 ... etc. does not exist.
3. For option parameters a property option-name and also a property option+name is looked for (all in lower case). If both don't exist an exception is thrown.
4. An option defined by a "+ property" (see point 3) is considered as only relevant for the following parameters / arguments in their sequence.
   It will not be set null in args and may be (sequence dependent re-) evaluated by the application code.
   Therefore it is allowed to define an option with no effect for this method by the form "option+dummy=" or "option+dummy= ##" without raising an exception. If the option value stars with # (as in the second example) the count of word parameters will be set to 30 if less.
   The effect is that unsatisfied word-0, word-1 etc. options won't get one of the word parameters to follow, hence, keeping them for later evaluation by application code.
5. An option (-xyz) defined by a "minus property", like option-xyz=effect, is considered as effective for the application as whole and independent of parameter sequence. The related parameter(s) will be set null in args after evaluation.
6. A standard parameter used by the preceding option or by a word-0, word-1 etc. definition will be set null in args.
7. If a comment start defined by commSt all parameters thereafter will be set null or shortened accordingly.

This method is (called with partial=true) made for applications who want a comfortable and powerful basic evaluation of the start arguments by Prop, but want to re-evaluate the (remaining) arguments in their sequence. Points 5 to 7 facilitate this proceeding by eliminating all evaluated global parameters as well as a parameter (command line) comment. An example for this is the tool Era (source Era.java, .properties file Era.properties).

Parameters:

partial - if true behaviour other than parse(String[], CharSequence) if false see description there

Throws:

IllegalArgumentException - on the contract violations described

See Also:

parse(String[], CharSequence)

getString

public String getString(String name,
                        int num,
                        String def)

Fetching a "numbered" or indexed property as non empty String.

This method returns a non empty String if and only if in this Prop object contains a property named "name" + num according to the rules of the method getProperty(name, num), the value of which is a non empty String also after removing surrounding white space.

This non empty String is returned or def otherwise.

Parameters:

name - the searched for property's name

num - its number or index

def - the substitute value if no non empty value is found

Returns:

the non empty value for key(name, number) or def

See Also:

getString(String,String), getInt(), getBoolean(), setProperty(), changeProperty()

getProperty

public String getProperty(CharSequence key,
                          int num)

Fetching a "numbered" or indexed property as non empty String.

If key is null or empty or if num is < 0, null is returned.

If this Prop object contains a property key + num in the variants described its value is returned even if empty.

If num is in the range 0 to 9 and no such property (like e.g. "name7") was found the trial is repeated with a leading zero (hence "name07" in the example).

If no such property exists the trial is repeated using index brackets in for the property's name, like "name[7]" in the example.

If also this fails and if num is 0 the property key without any number is looked for.

Otherwise null is returned. This is done for key null or num < 0.

Parameters:

key - the key (without number) to the property

num - the number (>= 0)

getResString

public String getResString(CharSequence key,
                           String def)

Fetching a property also indirectly from a resource — nationalised.

If this Prop object contains a property named <key>File (key being the parameter}, may be language prefixed in the form .de, .en .fr and so on, its non empty value, if given, will be taken as the name of a file or resource. It is tried to read its content by using getAsStream(keyFile, null). If this succeeds the read content is returned as String.

If this indirect fetching fails or if the mentioned auxiliary property <key>File is not given valueLanguage(key, def) is returned.

Hint: The resolution via <key>File including a default resource name without language prefix has priority over a possibly existing property lang.key fitting the language. This is to keep in mind if both possibilities are mixed.

Hint 2: This method's look up proceeding is not quite cheap (which is partly the source of its comfort for the application programmer). Contrary to PropMap.valueLang(CharSequence, String) this method does no caching. So this method should be called only once per language dependent property or file / resource. If the value is needed multiple times it should be stored / cashed by the application.

Parameters:

key - the searched property's name

def - a substitute value (may be null)

Returns:

the property's value or def

See Also:

valueLang(CharSequence), getAsStream(String, String)

getText

public String getText(CharSequence key)

Fetching a property as (non null) text.

This method fetches the value of the property key or the empty String ComVar.EMPTY_STRING.

If in the property value fetched other properties's keys are embedded embraced in two percent (%) signs, such an entry (that spot) will be replaced by the named property's value.
%% will be escaped to %.

Parameters:

key - the searched property's name

Returns:

key's value as String, may be with the substitutions described

See Also:

PropMap.getString(CharSequence), PropMap.getString(CharSequence, String), PropMap.getInt(CharSequence, int), PropMap.getBoolean(CharSequence), setProperty(), changeProperty()

percReplace

public String percReplace(String val)

Replace references to properties by their values.

The sequence val will be searched for names enclosed by two percent signs %, without enclosing a space. In "xxxyyy%nameX% hhh" for example nameX would be recognised as such a name, but not in the case of "xxxyyy%name % hhh".

All spots found in this way ("%nameX%") will be replaced by the value of the property so named, the value being evaluated by valueLang(name). The replacement is hence nationalised.

If no replacement value can be found the spot remains unchanged including the surrounding percents %.

%% is replaced by %.

If val is null ComVar.EMPTY_STRING is returned.

Parameters:

val - the sequence to work on

Returns:

val, may be with replacements; never null

getHelpText

public final String getHelpText(String def)

Fetching the property "helpText" nationalised.

The property's "helpText" will be nationalised (by valueLang("helpText", def)) and with possible replacements (compare percReplace() and returned.

Parameters:

def - substitute text if the property helpText respectively de.helpText, en.HelpText etc. does not exist

Returns:

the nationalised help text with may be some replacements

getBoolean

public boolean getBoolean(CharSequence name,
                          int num,
                          boolean def)

Fetching a "numbered" property as boolean with default.

This method determines by the rules of the method getProperty(name, num) the (indexed) property specified. If no such property exists def is returned.

Otherwise it is tried to interpret the value of the property as boolean by asBoolean(value, def). The result is returned.

Overrides:

getBoolean in class PropMap

Parameters:

name - the searched property's name

def - a substitute value (may be null)

num - the property's index / number (>=0)

Returns:

the boolean value of the property or def

See Also:




getInt

public int getInt(String name,
                  int num,
                  int def)

Fetching a "numbered" property as int with default.

This method determines by the rules of the method getProperty(name, num) the (indexed) property specified. If no such property exists def is returned.

Otherwise it is tried to interpret the value of the property as int. If possible that value is returned otherwise def.

Overrides:

getInt in class PropMap

Parameters:

name - the searched property's name

def - a substitute value

num - the property's index / number (>=0)

Returns:

the int value of the property or def

See Also:

PropMap.getInt(CharSequence, int), TextHelper.asInt(CharSequence, int), getLong(), TextHelper.asInt(CharSequence, int)

setFields

public int setFields(Object obj)
              throws SecurityException,
                     IllegalArgumentException

Setting an object's fields (beans properties).

The fields (variables) respectively the Java Beans properties of the object obj will be set by this Prop object's properties of the same name. Keys containing dot (.), minus (-) or plus (+) can't be variable's names and are not considered in the proceeding (see below).

For every possible key property a property "lang.property" is looked for (lang being the result of PropMap.getLanguage()). If it exists its value is taken otherwise that of property.

The setting of the variable "property" is either done directly by setting the public object variable or preferably by a fitting setter method named setProperty(...). Thereby this method uses the methods PropMapHelper.setField(Object, String, String) and searches in the sequence described there setters and at last the direct access to the public (not inherited) variable.

This method uses "introspection" of obj to call methods or set variables the existence of which this method can by no means know beforehand, of course.

Hint: The proceeding described prefers on language English (e.g.) a property en.helpText (e.g.) over helpText even if helpText was nationalised (English) by a loaded language specific .properties file (loaded by nationalise(CharSequence, CharSequence, CharSequence)). Hence multilingual values in one .properties file should not be combined with extra nationalised .properties files for the same key.

Parameters:

obj - the object the field of which shall be modified

Returns:

the number of fields / variables changed

Throws:

SecurityException - if the necessary introspection is forbidden

IllegalArgumentException - if a set method called throws an exception (e.g. an IllegalArgumentException or a PropertyVetoException. The exception's message is put into the (new) IllegalArgumentException

See Also:

PropMap.getString(CharSequence), getInt(), getBoolean(), parse(), PropMapHelper.setField(Object, String, String)

list

public void list(PrintStream out)

Output all properties to a PrintStream .

See Also:

list()

list

public void list(PrintWriter out)

Output all properties to a PrintWriter .

See Also:

list()

list

public StringBuilder list()

List all properties as StringBuilder .

This method is useful for tests.

After a headline comes the list of all loaded files or resources. Thereafter all properties contained are listed in (key) alphabetical order (one line per property).

If the value is interpretable as number or as boolean value (by getInt() respectively by getBoolean()) this interpretation is appended after <<.

keys (not allowed, can not happen) and values beginning or ending by white space will be set in quotes.

See Also:

PropMap.sortedKeys(), list(PrinWriter/PrintStream)