com.sap.tc.logging

Class Log

java.lang.Object
  com.sap.tc.logging.ExceptionHandling
      com.sap.tc.logging.Log

All Implemented Interfaces:

ILog, IObjectInfo, Cloneable

Direct Known Subclasses:

StreamLog

public abstract class Log
extends com.sap.tc.logging.ExceptionHandling
implements ILog

Writes log records to destinations. Writing log records is done on behalf of log controllers. On logging calls, records are written to the destination associated with the log in the format dictated by the formatter registered with the log, if the severity and the filters set for the log do not veto.

Please find fundamental information about the principles of error handling in the package description. For this class, there are two cases where the methods ExceptionHandling.getException() and ExceptionHandling.throwException() are served. First, methods dealing with severities pass over a java.lang.IllegalArgumentException if a value is out of range. Second, output methods encountering problems leave the corresponding java.io.IOException. Some of these problems are also logged to the category /System/Logging which in turn writes messages to the console.

See Also:

LogController, Severity, Filter, Formatter, LogRecord

Field Summary

static int	LOG_ACCESSABILITY_TYPE_LOCAL_LOG Inheritance is allowed, but with additional condition: final discretion of message printing lies with the original parent object.
static int	LOG_ACCESSABILITY_TYPE_NORMAL_LOG This type of Log allows regular inheritance; this log will become available to all descendants of the parent object.
static int	LOG_ACCESSABILITY_TYPE_PRIVATE_LOG This type of Log completely disables inheritance.
static int	STATUS_CLOSED
static int	STATUS_INVALID
static int	STATUS_OPENED

Fields inherited from class com.sap.tc.logging.ExceptionHandling

EX_NO_FILTER_EMSG, EX_NO_FORMATTER_EMSG, EX_NO_INSTANCE_EMSG

Constructor Summary

protected	Log()
protected	Log(Formatter formatter)

Method Summary

void	addFilter(Filter filter) Adds another filter that controls writing of messages via this log.
protected void	addOwner(String owner)
boolean	beGroup() Deprecated. Not supported anymore. Always return False!
boolean	beLogged(int severity) Checks whether a message with the specified severity would be written via this log.
protected Object	clone()
void	close() Closes output of this log object.
protected void	closeInt() Closes output of this log object.
protected void	finalize()
void	flush() Flushes buffered records in this log object.
protected void	flushInt() Flushes buffered records in this log object.
String	getDescription() Gets the description for this log.
int	getEffectiveSeverity() Gets the current effective severity of this log.
abstract String	getEncoding() Gets the canonical name of the character encoding that is used for this log.
Collection	getFilters() Gets the filters that control writing of messages via this log.
String	getFooter() Sets the footer text of this log.
Formatter	getFormatter() Gets the formatter that dictates the format of log records in this log.
String	getHeader() Gets the header text of this log.
protected LogController	getLocalLogOwner()
int	getLoggedCount()
String	getLogName() Deprecated. @see {#getName()}.
int	getLogTypeAccessibility() Gets the current accessibility type of this log.
String	getName() Gets the name for this log.
int	getNumberOfLogRecordsWritten() This method returns the number that indicates how many LogRecords have been written so far.
List	getOwners()
LogRecord	getRecord() Deprecated. - Not supported anymore - always return null
String	getVerInUse() Gets the version of API.
boolean	isAutoFlush() Checks whether this log flushes its output stream after each log message.
boolean	isClosed() Check is this log closed.
boolean	isFiltersAgreeing(LogRecord rec) Checks whether all filters associated with this log controller agree with writing a log record.
protected boolean	isHeaderWritten()
boolean	isOpened() Check is this log opened.
boolean	isSuppressing()
void	open() open output of this log object.
protected void	openInt() Open output of this log object.
void	removeFilter(Filter filter) Removes a filter so that it no longer controls writing of messages via this log.
void	removeFilters() Removes all filters associated with this log.
protected void	removeOwner(String owner)
void	reset() Reset all current Log settings and starts from beginning Current file
protected void	resetInt() Reset all current FileLog settings and starts from beginning Current file
void	resetLoggedCount()
void	setAutoFlush(boolean autoFlush) Configures this log to flush the output stream after each log message.
void	setDescription(String value) Sets a description for this log.
void	setEffectiveSeverity(int severity) Sets the effective severity of this log.
abstract void	setEncoding(String enc) Sets the named character encoding to be used for this log.
protected void	setFooter(String value)
void	setFormatter(Formatter formatter) Sets the formatter that dictates the format of log records in this log.
protected void	setHeader(String value)
protected void	setHeaderWritten(boolean headerWritten)
protected void	setLocalLogOwner(LogController owner)
void	setLogName(String name) Deprecated. @see {#setName(String name)}.
void	setLogTypeAccessibility(int value) Sets the accessibility level for this log.
void	setName(String name) Sets a name for this log.
protected void	setSize(long value)
protected void	setStatus(int status)
void	setSuppressing(boolean suppressing)
protected void	setVerInUse(String value)
long	size() Current size of the log.
int	status() Status of this log object.
LogRecord	write(LogRecord rec) Deprecated. not supported anymore
protected String	writeInt(LogRecord rec) Writes a log record to this log.
protected void	writeInt(String s) Writes a log message string to this log.
protected void	writeLogFooter() Writes a log footer to this log.
protected void	writeLogHeader() Writes a log header to this log.

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

getException, getExceptions, handleException, handleException, resetException, throwException

Methods inherited from class java.lang.Object

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

Field Detail

STATUS_INVALID

public static final int STATUS_INVALID

See Also:

Constant Field Values

STATUS_CLOSED

public static final int STATUS_CLOSED

See Also:

Constant Field Values

STATUS_OPENED

public static final int STATUS_OPENED

See Also:

Constant Field Values

LOG_ACCESSABILITY_TYPE_NORMAL_LOG

public static final int LOG_ACCESSABILITY_TYPE_NORMAL_LOG

This type of Log allows regular inheritance; this log will become available to all descendants of the parent object. The corresponding API is: static final Location parent = Location.getLocation("com.sap"), Location child = Location.getLocation("com.sap.foo"); parent.addLog(new ConsoleLog()); parent.setEffectiveSeverity(Severity.NONE); child.setEffectiveSeverity(Severity.INFO); child.fatalT("A fatal message from children"); This is an unconditional inheritance. As long as the message passes the evaluation of severity and filter of the child object, it will be printed out via the inherited log, in this case, ConsoleLog.

See Also:

Constant Field Values

LOG_ACCESSABILITY_TYPE_LOCAL_LOG

public static final int LOG_ACCESSABILITY_TYPE_LOCAL_LOG

Inheritance is allowed, but with additional condition: final discretion of message printing lies with the original parent object. The log is local, in the sense that it is not available for the descendants if the child message does not pass the severity and filter test of the parent object. static final Location parent = Location.getLocation("com.sap") Location child = Location.getLocation("com.sap.foo"); parent.addLocalLog(new ConsoleLog()); parent.setEffectiveSeverity(Severity.NONE); child.setEffectiveSeverity(Severity.INFO); child.fatalT("A fatal message from children"); Contrary to the NORMAL Log example, the child message will not be printed because it does not pass the severity test of the parent.

See Also:

Constant Field Values

LOG_ACCESSABILITY_TYPE_PRIVATE_LOG

public static final int LOG_ACCESSABILITY_TYPE_PRIVATE_LOG

This type of Log completely disables inheritance. Log assignment is private: only effective for the parent source object. static final Location parent = Location.getLocation("com.sap"), Location child = Location.getLocation("com.sap.foo"); parent.addPrivateLog(new ConsoleLog()); child.setEffectiveSeverity(Severity.INFO); child.fatalT("A fatal message from children"); In this case, child object does not inherit any destination log at all. Nothing will be printed even the message passes all the severity and filter tests.

See Also:

Constant Field Values

Constructor Detail

Log

protected Log()

Log

protected Log(Formatter formatter)

Method Detail

finalize

protected void finalize()
                 throws Throwable

Overrides:

finalize in class Object

Throws:

Throwable

getName

public String getName()

Gets the name for this log. Can be null.

Specified by:

getName in interface IObjectInfo

setName

public void setName(String name)

Sets a name for this log. An optional courtesy feature for user to easily refer to a log. Highly recommended if logviewer tool will be used to browse the output messages. If no name is specified, nothing will be set and the value is null.

getDescription

public String getDescription()

Gets the description for this log. Can be null.

Specified by:

getDescription in interface IObjectInfo

setDescription

public void setDescription(String value)

Sets a description for this log. An optional courtesy feature for user to easily refer to a log. Highly recommended if logviewer tool will be used to browse the output messages. If no name is specified, nothing will be set and the value is null.

getVerInUse

public String getVerInUse()

Gets the version of API.

Specified by:

getVerInUse in interface IObjectInfo

status

public int status()

Status of this log object. STATUS_CLOSE == 1 STATUS_OPEN == 2

Specified by:

status in interface ILog

getHeader

public String getHeader()

Gets the header text of this log.

Specified by:

getHeader in interface ILog

Returns:

Text which represent header of this log.

See Also:

setHeader(java.lang.String)

getFooter

public String getFooter()

Sets the footer text of this log.

Specified by:

getFooter in interface ILog

Returns:

Text which represent footer of this log.

See Also:

setHeader(java.lang.String)

getEffectiveSeverity

public int getEffectiveSeverity()

Gets the current effective severity of this log.

Specified by:

getEffectiveSeverity in interface ILog

Returns:

Effective severity

setEffectiveSeverity

public void setEffectiveSeverity(int severity)

Sets the effective severity of this log.

Specified by:

setEffectiveSeverity in interface ILog

Parameters:

severity - New effective severity

getLogTypeAccessibility

public int getLogTypeAccessibility()

Gets the current accessibility type of this log. Default = LOG_ACCESSABILITY_TYPE_NORMAL_LOG

Specified by:

getLogTypeAccessibility in interface ILog

Returns:

Accessibility type. LOG_ACCESSABILITY_TYPE_NORMAL_LOG LOG_ACCESSABILITY_TYPE_LOCAL_LOG LOG_ACCESSABILITY_TYPE_PRIVATE_LOG.

setLogTypeAccessibility

public void setLogTypeAccessibility(int value)

Sets the accessibility level for this log. Note: If you specified value which is not recognized, the accessibility type will be set to PRIVATE.

Specified by:

setLogTypeAccessibility in interface ILog

Parameters:

new - accessibility type LOG_ACCESSABILITY_TYPE_NORMAL_LOG LOG_ACCESSABILITY_TYPE_LOCAL_LOG LOG_ACCESSABILITY_TYPE_PRIVATE_LOG.

getFormatter

public Formatter getFormatter()

Gets the formatter that dictates the format of log records in this log.

Specified by:

getFormatter in interface ILog

Returns:

Formatter

See Also:

setFormatter(Formatter)

setFormatter

public void setFormatter(Formatter formatter)

Sets the formatter that dictates the format of log records in this log. Note: If you send a null like argument the default formater (ListFormatter), will be created.

Specified by:

setFormatter in interface ILog

See Also:

getFormatter()

getNumberOfLogRecordsWritten

public int getNumberOfLogRecordsWritten()

This method returns the number that indicates how many LogRecords have been written so far. This does not take into account how many LogRecords were there in the file before the current session has started. Therefore, please note that this number deals with the number of LogRecords that have been written in the current session.

Specified by:

getNumberOfLogRecordsWritten in interface ILog

Returns:

int Number of LogRecords written so far in the current session.

size

public long size()

Current size of the log.

Returns:

long size of the log.

getEncoding

public abstract String getEncoding()

Gets the canonical name of the character encoding that is used for this log. If no character encoding is set the default character encoding of the platform is used.

Specified by:

getEncoding in interface ILog

Returns:

Name of character encoding

See Also:

setEncoding(java.lang.String)

setEncoding

public abstract void setEncoding(String enc)

Sets the named character encoding to be used for this log. If no character encoding is set the default character encoding is used.

Specified by:

setEncoding in interface ILog

Parameters:

enc - Name of character encoding

See Also:

getEncoding()

isFiltersAgreeing

public boolean isFiltersAgreeing(LogRecord rec)

Checks whether all filters associated with this log controller agree with writing a log record.

Parameters:

rec - Log record to be written

Returns:

No filter vetoes writing

getFilters

public Collection getFilters()

Gets the filters that control writing of messages via this log.

Specified by:

getFilters in interface ILog

Returns:

Unmodifiable collection of filters associated with this log

addFilter

public void addFilter(Filter filter)

Adds another filter that controls writing of messages via this log. The results of all filters for a given message are logically anded to determine whether a message is to be written.

Specified by:

addFilter in interface ILog

Parameters:

filter - New filter

removeFilter

public void removeFilter(Filter filter)

Removes a filter so that it no longer controls writing of messages via this log.

Specified by:

removeFilter in interface ILog

Parameters:

filter - Filter to be removed

removeFilters

public void removeFilters()

Removes all filters associated with this log.

Specified by:

removeFilters in interface ILog

beLogged

public boolean beLogged(int severity)

Checks whether a message with the specified severity would be written via this log. The purpose of this method is to avoid evaluating the arguments of a logging call, which is expensive and would be superfluous if a message is not written because of its insufficient severity. The result returned is necessary but not sufficient for writing log messages, that is if the method returns false the message is not going to be written but not vice versa. To this end, the method checks whether the specified severity is equal to or higher than the effective severity of the log. It does not take into account filters associated with the log.

Specified by:

beLogged in interface ILog

Parameters:

severity - Severity of message to be written

write

public LogRecord write(LogRecord rec)

Deprecated. not supported anymore

Writes a log record to this log if no filter vetoes.

Parameters:

rec - Record to be written

flush

public void flush()

Flushes buffered records in this log object.

Specified by:

flush in interface ILog

isAutoFlush

public boolean isAutoFlush()

Checks whether this log flushes its output stream after each log message. Automatic flushing is switched on in a new log.

Specified by:

isAutoFlush in interface ILog

Returns:

true if and only if this log flushes its output stream after each log message

See Also:

setAutoFlush(boolean)

setAutoFlush

public void setAutoFlush(boolean autoFlush)

Configures this log to flush the output stream after each log message. Automatic flushing is switched on in a new log.

Specified by:

setAutoFlush in interface ILog

Parameters:

autoFlush -

See Also:

isAutoFlush()

open

public void open()

open output of this log object.

Specified by:

open in interface ILog

close

public void close()

Closes output of this log object.

Specified by:

close in interface ILog

isClosed

public boolean isClosed()

Check is this log closed. Helper method. Same like: status() == STATUS_CLOSED

Specified by:

isClosed in interface ILog

isOpened

public boolean isOpened()

Check is this log opened. Helper method. Same like: status() == STATUS_OPENED

Specified by:

isOpened in interface ILog

reset

public void reset()

Reset all current Log settings and starts from beginning Current file

isSuppressing

public boolean isSuppressing()

setSuppressing

public void setSuppressing(boolean suppressing)

getLoggedCount

public int getLoggedCount()

resetLoggedCount

public void resetLoggedCount()

getOwners

public List getOwners()

setSize

protected void setSize(long value)

setStatus

protected void setStatus(int status)

setHeader

protected void setHeader(String value)

setFooter

protected void setFooter(String value)

setVerInUse

protected void setVerInUse(String value)

clone

protected Object clone()
                throws CloneNotSupportedException

Overrides:

clone in class Object

Throws:

CloneNotSupportedException

writeInt

protected void writeInt(String s)
                 throws Exception

Writes a log message string to this log. This method is meant as the standard way of implementing the fashion in which a log message is written to its destination. Note that this method is called inside a synchronized statement that locks this log, in order to avoid deadlocks.

If you need access to the log record to be written you should override writeInt(java.lang.String). Note that, nevertheless, even in this case it is usually necessary to reimplement this method.

Throws:

IOException - Exception from writing messages to the destination

Exception

flushInt

protected void flushInt()
                 throws IOException

Flushes buffered records in this log object. This method is meant for overriding the fashion in which buffered log records are flushed. You should not call this method from the outside because you would ignore common actions that have to take place for each flush.

Throws:

IOException - Exception from flushing records to the destination

closeInt

protected void closeInt()
                 throws IOException

Closes output of this log object. This method is meant for overriding the fashion in which the log is closed. You should not call this method from the outside because you would ignore common actions that have to take place for each close, for example writing the footer defined by the formatter.

Throws:

IOException - Exception from closing the destination

openInt

protected void openInt()
                throws IOException

Open output of this log object. This method is meant for overriding the fashion in which the log is open. You should not call this method from the outside because you would ignore common actions that have to take place for each open, for example writing the header defined by the formatter.

Throws:

IOException - Exception from opening the destination

resetInt

protected void resetInt()
                 throws Exception

Reset all current FileLog settings and starts from beginning Current file

Throws:

Exception

writeInt

protected String writeInt(LogRecord rec)
                   throws Exception

Writes a log record to this log. This method is meant for overriding if you need access to the log record to be written. You should not call this method from the outside because you would ignore the checks for severities and filters done in write(LogRecord). There are three basic use cases in which to reimplement this method.

• You want to do something with the record before writing it in the standard fashion. In that case, do what is needed and then call return super.writeInt(rec) as the last statement.
• Second, you want to do your own special formatting of the record prior to writing. In that case, consider to write your own formatter as this is probably a much cleaner way to do so. If for some unforeseeable reason you cannot achieve the effect you are after, do the log record formatting into a string and then call writeInt(java.lang.String) to write it. Finally, return the string to the caller.
• Third, you do not want to write the log record as a string at all but, for example, into a structure such as a database table. In that case, put the corresponding code into your overriding method and do not call writeInt(String). Return null to the caller.

Note that this method is called inside a synchronized statement that locks this log, in order to avoid deadlocks.

If you want to override where to write a formatted string to, do not override this method at all but instead reimplement writeInt(String). Note that the first and second use case usually also necessitate this reimplementation.

Throws:

IOException - Exception from writing records to the destination

Exception

See Also:

writeInt(java.lang.String)

isHeaderWritten

protected boolean isHeaderWritten()

setHeaderWritten

protected void setHeaderWritten(boolean headerWritten)

addOwner

protected void addOwner(String owner)

removeOwner

protected void removeOwner(String owner)

setLocalLogOwner

protected void setLocalLogOwner(LogController owner)

getLocalLogOwner

protected LogController getLocalLogOwner()

writeLogHeader

protected void writeLogHeader()

Writes a log header to this log.

writeLogFooter

protected void writeLogFooter()

Writes a log footer to this log.

getRecord

public LogRecord getRecord()

Deprecated. - Not supported anymore - always return null

beGroup

public boolean beGroup()

Deprecated. Not supported anymore. Always return False!

See Also:

#LogController.beGroup()

getLogName

public String getLogName()

Deprecated. @see {#getName()}.

setLogName

public void setLogName(String name)

Deprecated. @see {#setName(String name)}.

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