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.

Constructor Summary

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

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

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

PropertiesConfigurator(java.util.Properties properties, java.lang.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.
java.io.File	getFile() Gets the file used for this configurator.
java.util.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.
void	setFile(java.io.File file) Sets the file used for this configurator.
void	setProperties(java.util.Properties properties) Sets the properties object used for this configurator.

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

getClassLoader, getException, getPeriodicity, setClassLoader, setPeriodicity, throwException

Methods inherited from class java.lang.Object

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

Constructor Detail

PropertiesConfigurator

public PropertiesConfigurator(java.util.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(java.util.Properties properties,
                              java.lang.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(java.io.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(java.io.File file,
                              java.lang.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 java.util.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(java.util.Properties properties)

Sets the properties object used for this configurator.

Parameters:

properties - Properties object

See Also:

getProperties()

getFile

public java.io.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(java.io.File file)

Sets the file used for this configurator.

Parameters:

file - File

Throws:

java.lang.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.

Overrides:

configure in class Configurator

initConfigure

public void initConfigure()
                   throws java.lang.IllegalArgumentException,
                          java.io.FileNotFoundException,
                          java.io.IOException,
                          java.lang.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:

java.lang.IllegalArgumentException - Null properties content

java.io.FileNotFoundException - Properties file(if specified) cannot be located

java.io.IOException - Problems reading properties file content