Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improve reference documentation #398

Merged
merged 2 commits into from
Jul 25, 2024
+65 −74
Merged

Improve reference documentation #398

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
51c46a9
Improve refenece documentation
stephen-webb Jul 24, 2024
b7dfb8e
How to name a thread
stephen-webb Jul 24, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
139 changes: 65 additions & 74 deletions src/main/include/log4cxx/spi/loggingevent.h
View file
Open in desktop
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
Loading