Skip to content

Commit

Permalink
Improve reference documentation (#398)
Browse files Browse the repository at this point in the history
  • Loading branch information
swebb2066 authored Jul 25, 2024
1 parent d925a2e commit 824563d
Showing 1 changed file with 65 additions and 74 deletions.
139 changes: 65 additions & 74 deletions src/main/include/log4cxx/spi/loggingevent.h
Original file line number Diff line number Diff line change
Expand Up @@ -29,20 +29,16 @@

namespace LOG4CXX_NS
{
namespace helpers
{
class ObjectOutputStream;
}

namespace spi
{
LOG4CXX_LIST_DEF(KeySet, LogString);

/**
The internal representation of logging events. When an affirmative
decision is made to log then a <code>LoggingEvent</code> instance
is created. This instance is passed around to the different log4cxx
components.
The data recorded for each logging request.
Each logging request instantiates a <code>LoggingEvent</code> instance,
which Log4cxx provides to [filters](@ref log4cxx.spi.Filter),
[layouts](@ref log4cxx.Layout) and [appenders](@ref log4cxx.Appender).
<p>This class is of concern to those wishing to extend log4cxx.
*/
Expand All @@ -57,150 +53,145 @@ class LOG4CXX_EXPORT LoggingEvent :

typedef spi::KeySet KeySet;

/** For serialization only
/** An empty event.
*/
LoggingEvent();

/**
Instantiate a LoggingEvent from the supplied parameters.
An event composed using the supplied parameters.
<p>Except timeStamp all the other fields of
<code>LoggingEvent</code> are filled when actually needed.
<p>
@param logger The logger of this event.
@param level The level of this event.
@param logger The logger used to make the logging request.
@param level The severity of this event.
@param location The source code location of the logging request.
@param message The text to add to this event.
*/
LoggingEvent
( const LogString& logger
, const LevelPtr& level
, const spi::LocationInfo& location
, const LocationInfo& location
, LogString&& message
);

/**
Instantiate a LoggingEvent from the supplied parameters.
An event composed using the supplied parameters.
<p>Except timeStamp all the other fields of
<code>LoggingEvent</code> are filled when actually needed.
<p>
@param logger The logger of this event.
@param level The level of this event.
@param logger The logger used to make the logging request.
@param level The severity of this event.
@param message The text to add to this event.
@param location The source code location of the logging request.
*/
LoggingEvent(const LogString& logger,
const LevelPtr& level, const LogString& message,
const LOG4CXX_NS::spi::LocationInfo& location);
LoggingEvent
( const LogString& logger
, const LevelPtr& level
, const LogString& message
, const LocationInfo& location
);

~LoggingEvent();

/** Return the level of this event. */
/** The severity level of the logging request that generated this event. */
const LevelPtr& getLevel() const;

/** Return the name of the logger. */
/** The name of the logger used to make the logging request. */
const LogString& getLoggerName() const;

/** Return the message for this logging event. */
/** The message provided in the logging request. */
const LogString& getMessage() const;

/** Return the message for this logging event. */
/** The message provided in the logging request. */
const LogString& getRenderedMessage() const;

/**Returns the time when the application started,
in microseconds elapsed since 01.01.1970.
*/
/** The number of microseconds elapsed since 1970-01-01
* at the time the application started.
*/
static log4cxx_time_t getStartTime();

/** Return the threadName of this event. */
/** The identity of the thread in which this logging event was created. */
const LogString& getThreadName() const;

/**
* Get the user name of the thread. The default name is (noname) if
* Log4cxx is unable to retrieve the name using a platform-specific call.
* The name you gave to the thread in which this logging event was created.
* You can create a named thread using log4cxx::helpers::ThreadUtility::createThread.
* If Log4cxx is unable to retrieve the thread name using a platform-specific call,
* the value is the same as the thread identity.
*/
const LogString& getThreadUserName() const;

/** The number of microseconds elapsed from 01.01.1970 until logging event
was created. */
/** The number of microseconds elapsed since 1970-01-01
* at the time this logging event was created.
*/
log4cxx_time_t getTimeStamp() const;

/** The value of the system clock at the time this logging event was created.
*/
std::chrono::time_point<std::chrono::system_clock> getChronoTimeStamp() const;

/* Return the file where this log statement was written. */
const LOG4CXX_NS::spi::LocationInfo& getLocationInformation() const;
/** The source code location where the logging request was made. */
const LocationInfo& getLocationInformation() const;

/**
* This method appends the NDC for this event to passed string. It will return the
* correct content even if the event was generated in a different
* thread or even on a different machine. The NDC#get method
* should <em>never</em> be called directly.
* Add the current nested diagnostic context to the end of \c dest.
* The diagnostic context must have been loaded into this LoggingEvent using LoadDC,
* to obtain the correct content if the event was generated in a different thread.
*
* @param dest destination for NDC, unchanged if NDC is not set.
* @return true if NDC is set.
* @param dest the string to be added to.
* @return true if \c dest is changed.
*/
bool getNDC(LogString& dest) const;

/**
* Appends the the context corresponding to the <code>key</code> parameter.
* If there is a local MDC copy, possibly because we are in a logging
* server or running inside AsyncAppender, then we search for the key in
* MDC copy, if a value is found it is returned. Otherwise, if the search
* in MDC copy returns an empty result, then the current thread's
* <code>MDC</code> is used.
* Add the value associated with \c key to the end of \c dest.
* The diagnostic context must have been loaded into this LoggingEvent using LoadDC,
* to obtain the correct content if the event was generated in a different thread.
*
* <p>
* Note that <em>both</em> the local MDC copy and the current thread's MDC
* are searched.
* </p>
* @param key key.
* @param dest string to which value, if any, is appended.
* @return true if key had a corresponding value.
* @param key mapped diagnostic context key value.
* @param dest the string to be added to.
* @return true if \c dest is changed.
*/
bool getMDC(const LogString& key, LogString& dest) const;

/**
* Returns the set of of the key values in the MDC for the event.
* The returned set is unmodifiable by the caller.
* The keys in the mapped diagnostic context for the event.
*
* @return Set an unmodifiable set of the MDC keys.
* @return the mapped diagnostic context keys.
*
*/
KeySet getMDCKeySet() const;

#if LOG4CXX_ABI_VERSION <= 15
/**
Obtain a copy of this thread's MDC prior to serialization
or asynchronous logging.
Obtain a copy of the current thread's diagnostic context data.
*/
[[ deprecated( "Use LoadDC instead" ) ]]
void getMDCCopy() const;
#endif

/**
Obtain a copy of this thread's diagnostic context prior to serialization
or asynchronous logging.
* Obtain a copy of the current thread's diagnostic context data.
* The diagnostic context must be loaded to ensure the
* correct diagnostic context data is available
* when the event is stored for later use
* (for example, when the appender uses a different thread to process this event).
*/
void LoadDC() const;

/**
* Return a previously set property.
* @param key key.
* @param dest string to which value, if any, is appended.
* @return true if key had a corresponding value.
* Append onto \c dest the value associated with the property \c key.
* @param key the property name.
* @param dest the string onto which to associated value is appended.
* @return true if \c dest was changed.
*/
bool getProperty(const LogString& key, LogString& dest) const;

/**
* Returns the set of of the key values in the properties
* for the event. The returned set is unmodifiable by the caller.
*
* @return Set an unmodifiable set of the property keys.
* The set of of the key values in the properties
* for the event.
* @return the keys from properties in this event.
*/
KeySet getPropertyKeySet() const;

/**
* Set a string property using a key and a string value. since 1.3
* Associate \c value with the property \c key.
*/
void setProperty(const LogString& key, const LogString& value);

Expand Down

0 comments on commit 824563d

Please sign in to comment.