com.sap.tc.logging

Class PropertiesConfigurator

java.lang.Object
  com.sap.tc.logging.Configurator
      com.sap.tc.logging.PropertiesConfigurator

public class PropertiesConfigurator
extends Configurator

Configures the Logging API according to a set of properties. A single properties configurator is set to get its properties either from a specific properties object or read it from a specific properties file. The configuration call itself does not take arguments and can therefore be automatically repeated with a desired periodicity.

The syntax of keys in the properties specification follows the general syntax <Name>.<Attribute>, where <Name> is the name of a location or category, and <Attribute> is one of its attributes, for example severity. If you want to set the severity for a location named com.sap.tc.monitoring.Node to Severity.INFO you would write:

com.sap.tc.monitoring.Node.severity = INFO

If you would like to set a relative severity, for example for trace messages regarding object management, you use a kind of array element notation with the name of the corresponding category and write:

com.sap.tc.monitoring.Node.severity[/Objects/Management] = DEBUG

If you want to define logs for controllers or formatters for logs you often have to set additional attributes. In order to do this, you refer to these objects using variables. A variable uses an array element notation with the array name specifying the kind of object and the index giving the name of the variable. For example, with

log[Trace] = FileLog

you make a new FileLog object, and assign it to a log variable named Trace, which you then with

log[Trace].pattern = %t/std.trc

set the file name pattern attribute for. When you want to attach the file log to a location called com.sap.tc you write:

com.sap.tc.logs = + log[Trace]

The plus sign in front of the log variable tells the configurator to attach the log in addition to other logs already set for the controller. If you omit it, logs already present will be discarded. Care has to be taken for if a log with the same attributes is already present it will be kept and the new log not attached. This has the advantage that periodic evaluation of, at least in part, unchanged configuration files does not lead to loss of state of the attached objects. Removing all logs is also possible using an empty log list:

com.sap.tc.logs =

Please note that it is not sufficient to just omit the logs attribute, as the configurator leaves alone all attributes not mentioned in the properties.

To illustrate the use of formatter variables we want to configure a trace formatter with a custom pattern for the file log:

formatter[Trace]         = TraceFormatter
formatter[Trace].pattern = %24d: %m
log[Trace].formatter     = formatter[Trace]

Another typical application of log and formatter variables is to attach the same object to several other objects. For example, you first define a log variable refering to a console log, and then attach the log to several different controllers using the variable.

Sometimes you do not want to use a predefined class but one of your own to make an object. In rare cases, this might be your own log or formatter class but more often it is going to be a filter class for which there are no prefabricated implementations at all. You can do this by specifying the qualified name of this custom class:

log[Trace].filters = com.sap.tc.monitoring.Filter

However, for this to work the custom class needs to provide a no-argument constructor and either has to be installed in the class path or be part of your application. If not, the class loader to be used has to be set via the corresponding constructor, or later the call:

propertiesConfigurator.setClassLoader(classLoader)

You can set attributes of a custom class if inherited from a predefined class. For example, you can assign a value to the inherited attribute pattern of a custom log class derived from FileLog.

The sequence in which all the above settings occur does not matter. What is left is to tell the properties configurator where to find the properties described above. Most often, a properties file is used, and you tell the configurator so when you make it, so the call reads something like:

propertiesConfigurator = new PropertiesConfigurator(new File("logging.properties"));
   

The complete syntax in case of a properties specification in a file looks like this:

.

<Configuration>	=		<Entry>*.
<Entry>	=		<Key> '=' <Value>
		|	<Key> ':' <Value>
		|	<Key> <Value>.
<Key>	=		[<LogController> '.'] <LogControllerAttr>
		|	<Log> ['.' <LogAttr>]
		|	<Formatter> ['.' <FormatterAttr>].
<LogController>	=		<Location>
		|	<Category>.
<Location>	=		[<Identifier> ('.' <Identifier> ['(' <Types> ')'])*].
<Types>	=		[<Type> (',' <Type>)*].
<Type>	=		<Identifier> ('.' <Identifier>)* ('[' ']')*.
<Category>	=		'/' [<Identifier> ('/' <Identifier>)*].
<LogControllerAttr>	=		'severity' [<Relative>]
		|	'effSeverity' [<Relative>]
		|	'minSeverity' [<Relative>]
		|	'maxSeverity' [<Relative>]
		|	'logs'
		|	'localLogs'
		|	'privateLogs'
		|	'filters'
		|	'bundleName'.
<Relative>	=		'[' <LogController> ']'.
<Log>	=		'log' '[' <Identifier> ']'.
<LogAttr>	=		'severity'
		|	'effSeverity'
		|	'encoding'
		|	'filters'
		|	'formatter'
		|	'desc'
		|	'autoFlush'
		|	'append'
		|	'pattern'
		|	'limit'
		|	'cnt'.
<Formatter>	=		'formatter' '[' <Identifier> ']'.
<FormatterAttr>	=		'pattern'.
<Value>	=		<Severity>
		|	<Objects>
		|	<String>
		|	<Boolean>
		|	<Identifier>.
<Severity>	=		['Severity' '.'] ('NONE' | 'FATAL' |'ERROR' | 'WARNING' | 'INFO' | 'PATH' | 'DEBUG')
<Objects>	=		[['+'] <Object> (',' <Object>)*].
<Object>	=		<Class>
		|	<Log>
		|	<Formatter>.
<Class>	=		'FileLog'
		|	'ConsoleLog'
		|	'TraceFormatter'
		|	'ListFormatter'
		|	'XMLFormatter'
		|	<Identifier> ('.' <Identifier>)*.

In the above grammar, the words in quotes like 'logs' or 'XMLFormatter' are reserved. If you want to use such a word as an identifier, for example in a custom class name, escape it with single quotes, like in:

log[Trace] = com.sap.tc.'logs'.GreatLog
   

In case of a properties object, use the syntax rules of <Key> and <Value> for defining keys and values of properties, respectively.

Please find fundamental information about the principles of error handling in the package description. For this class, there are two cases where the methods Configurator.getException() and Configurator.throwException() are served. First, if you forgot to provide a properties object or a properties file you specified could not be found, constructors and setters leave a java.lang.IllegalArgumentException. Second, the method configure() hands over the same exception with different messages if syntactical or semantical errors are discovered in a properties specification. These errors are logged in even more detail to the category /System/Logging which in turn writes messages to the console. So if some properties do not quite work as you expected, have a look there to find out about misspelled attribute names and the like.

Field Summary

protected static String	INVALID_PROPS_FILE
protected static String	NO_CNT_MSG
protected static String	NO_LIMIT_MSG
protected static String	NO_PATTERN_MSG
protected static String	NO_PROPERTIES_EMSG
protected static String	SEMANTICS_ERR_EMSG
protected static String	SYNTAX_ERR_EMSG
protected static String	SYNTAX_ERR_IN_KEY_MSG
protected static String	SYNTAX_ERR_IN_VAL_MSG
protected static String	UNKNOWN_CLASS_MSG
protected static String	UNKNOWN_FORMATTER_MSG
protected static String	UNKNOWN_LOG_MSG

Constructor Summary

PropertiesConfigurator(File file)
Configures this properties configurator with a properties file and the class loader used for this class.

PropertiesConfigurator(File file, ClassLoader classLoader)
Configures this properties configurator with a properties file and a custom class loader.

PropertiesConfigurator(Properties properties)
Configures this properties configurator with a properties object and the class loader used for this class.

PropertiesConfigurator(Properties properties, ClassLoader classLoader)
Configures this properties configurator with a properties object and a custom class loader.

Method Summary

void	configure() Configures tracing and logging according to the settings of the configurator.
File	getFile() Gets the file used for this configurator.
Properties	getProperties() Gets the properties object used for this configurator.
void	initConfigure() To initialize configuration setting defined by user in the settings of the configurator.
protected com.sap.tc.logging.PropertiesConfigurator.BooleanVal	parseBoolean(String value, String forKey)
protected com.sap.tc.logging.PropertiesConfigurator.ClassVal	parseClass(com.sap.tc.logging.PropertiesConfigurator.PCTokenizer tokenizer, String forKey)
protected String	parseFormatter(com.sap.tc.logging.PropertiesConfigurator.PCTokenizer tokenizer, String forKey)
protected com.sap.tc.logging.PropertiesConfigurator.Attr	parseFormatterAttr(com.sap.tc.logging.PropertiesConfigurator.PCTokenizer tokenizer)
protected com.sap.tc.logging.PropertiesConfigurator.Key	parseKey(String key)
protected String	parseLog(com.sap.tc.logging.PropertiesConfigurator.PCTokenizer tokenizer, String forKey)
protected com.sap.tc.logging.PropertiesConfigurator.Attr	parseLogAttr(com.sap.tc.logging.PropertiesConfigurator.PCTokenizer tokenizer)
protected LogController	parseLogController(String name, String forKey)
protected com.sap.tc.logging.PropertiesConfigurator.Attr	parseLogControllerAttr(com.sap.tc.logging.PropertiesConfigurator.PCTokenizer tokenizer)
protected com.sap.tc.logging.PropertiesConfigurator.ObjectVal	parseObject(com.sap.tc.logging.PropertiesConfigurator.PCTokenizer tokenizer, String forKey)
protected com.sap.tc.logging.PropertiesConfigurator.ObjectsVal	parseObjectList(com.sap.tc.logging.PropertiesConfigurator.PCTokenizer tokenizer, String forKey)
protected com.sap.tc.logging.PropertiesConfigurator.ObjectsVal	parseObjects(String value, String forKey)
protected com.sap.tc.logging.PropertiesConfigurator.SeverityVal	parseSeverity(String value, String forKey)
void	setFile(File file) Sets the file used for this configurator.
void	setProperties(Properties properties) Sets the properties object used for this configurator.

Methods inherited from class com.sap.tc.logging.Configurator

getClassLoader, getException, getPeriodicity, handleException, resetException, setClassLoader, setPeriodicity, throwException

Methods inherited from class java.lang.Object

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

Field Detail

NO_PROPERTIES_EMSG

protected static final String NO_PROPERTIES_EMSG

See Also:

Constant Field Values

INVALID_PROPS_FILE

protected static final String INVALID_PROPS_FILE

See Also:

Constant Field Values

SYNTAX_ERR_EMSG

protected static final String SYNTAX_ERR_EMSG

See Also:

Constant Field Values

SEMANTICS_ERR_EMSG

protected static final String SEMANTICS_ERR_EMSG

See Also:

Constant Field Values

SYNTAX_ERR_IN_KEY_MSG

protected static final String SYNTAX_ERR_IN_KEY_MSG

See Also:

Constant Field Values

SYNTAX_ERR_IN_VAL_MSG

protected static final String SYNTAX_ERR_IN_VAL_MSG

See Also:

Constant Field Values

UNKNOWN_CLASS_MSG

protected static final String UNKNOWN_CLASS_MSG

See Also:

Constant Field Values

NO_PATTERN_MSG

protected static final String NO_PATTERN_MSG

See Also:

Constant Field Values

NO_LIMIT_MSG

protected static final String NO_LIMIT_MSG

See Also:

Constant Field Values

NO_CNT_MSG

protected static final String NO_CNT_MSG

See Also:

Constant Field Values

UNKNOWN_FORMATTER_MSG

protected static final String UNKNOWN_FORMATTER_MSG

See Also:

Constant Field Values

UNKNOWN_LOG_MSG

protected static final String UNKNOWN_LOG_MSG

See Also:

Constant Field Values

Constructor Detail

PropertiesConfigurator

public PropertiesConfigurator(Properties properties)

Configures this properties configurator with a properties object and the class loader used for this class.

Parameters:

properties - Properties object

See Also:

PropertiesConfigurator(java.util.Properties, java.lang.ClassLoader)

PropertiesConfigurator

public PropertiesConfigurator(Properties properties,
                              ClassLoader classLoader)

Configures this properties configurator with a properties object and a custom class loader.

Parameters:

properties - Properties object

classLoader - Custom class loader

See Also:

PropertiesConfigurator(java.util.Properties)

PropertiesConfigurator

public PropertiesConfigurator(File file)

Configures this properties configurator with a properties file and the class loader used for this class.

Parameters:

file - Properties file

See Also:

PropertiesConfigurator(java.io.File, java.lang.ClassLoader)

PropertiesConfigurator

public PropertiesConfigurator(File file,
                              ClassLoader classLoader)

Configures this properties configurator with a properties file and a custom class loader.

Parameters:

file - Properties file

classLoader - Custom class loader

See Also:

PropertiesConfigurator(java.io.File)

Method Detail

getProperties

public Properties getProperties()

Gets the properties object used for this configurator.

Returns:

Properties object, or null if there is none

See Also:

setProperties(java.util.Properties)

setProperties

public void setProperties(Properties properties)

Sets the properties object used for this configurator.

Parameters:

properties - Properties object

See Also:

getProperties()

getFile

public File getFile()

Gets the file used for this configurator.

Returns:

File, or null if there is none

See Also:

setFile(java.io.File)

setFile

public void setFile(File file)

Sets the file used for this configurator.

Parameters:

file - File

Throws:

IllegalArgumentException - No file

See Also:

getProperties()

configure

public void configure()

Description copied from class: Configurator

Configures tracing and logging according to the settings of the configurator.

Specified by:

configure in class Configurator

initConfigure

public void initConfigure()
                   throws IllegalArgumentException,
                          FileNotFoundException,
                          IOException,
                          Exception

To initialize configuration setting defined by user in the settings of the configurator. This is called and executed once and this method throws exception. Corresponding events will be fired after the configuration. For logging instrumentation, it is recommended to use configure() that is bundled with periodic feature.

Throws:

IllegalArgumentException - Null properties content

FileNotFoundException - Properties file(if specified) cannot be located

IOException - Problems reading properties file content

Exception

parseKey

protected com.sap.tc.logging.PropertiesConfigurator.Key parseKey(String key)

parseLogController

protected LogController parseLogController(String name,
                                           String forKey)

parseLogControllerAttr

protected com.sap.tc.logging.PropertiesConfigurator.Attr parseLogControllerAttr(com.sap.tc.logging.PropertiesConfigurator.PCTokenizer tokenizer)

parseLog

protected String parseLog(com.sap.tc.logging.PropertiesConfigurator.PCTokenizer tokenizer,
                          String forKey)

parseLogAttr

protected com.sap.tc.logging.PropertiesConfigurator.Attr parseLogAttr(com.sap.tc.logging.PropertiesConfigurator.PCTokenizer tokenizer)

parseFormatter

protected String parseFormatter(com.sap.tc.logging.PropertiesConfigurator.PCTokenizer tokenizer,
                                String forKey)

parseFormatterAttr

protected com.sap.tc.logging.PropertiesConfigurator.Attr parseFormatterAttr(com.sap.tc.logging.PropertiesConfigurator.PCTokenizer tokenizer)

parseSeverity

protected com.sap.tc.logging.PropertiesConfigurator.SeverityVal parseSeverity(String value,
                                                                              String forKey)

parseBoolean

protected com.sap.tc.logging.PropertiesConfigurator.BooleanVal parseBoolean(String value,
                                                                            String forKey)

parseObjects

protected com.sap.tc.logging.PropertiesConfigurator.ObjectsVal parseObjects(String value,
                                                                            String forKey)

parseObjectList

protected com.sap.tc.logging.PropertiesConfigurator.ObjectsVal parseObjectList(com.sap.tc.logging.PropertiesConfigurator.PCTokenizer tokenizer,
                                                                               String forKey)

parseObject

protected com.sap.tc.logging.PropertiesConfigurator.ObjectVal parseObject(com.sap.tc.logging.PropertiesConfigurator.PCTokenizer tokenizer,
                                                                          String forKey)

parseClass

protected com.sap.tc.logging.PropertiesConfigurator.ClassVal parseClass(com.sap.tc.logging.PropertiesConfigurator.PCTokenizer tokenizer,
                                                                        String forKey)

Access Rights

This class can be accessed from:

SC	DC
[sap.com] FRAMEWORK	[sap.com] tc/ddic/ddicruntime
[sap.com] ENGINEAPI	[sap.com] tc/logging
[sap.com] ENGFACADE	[sap.com] tc/bl/logging/api
[sap.com] CORE-TOOLS	[sap.com] com.sap.engine.client.lib
[sap.com] BRMS-FACADE	[sap.com] tc/brms/facade