[#BloombergLP-ball-FileObserver2]
= xref:BloombergLP.adoc[BloombergLP]::xref:BloombergLP/ball.adoc[ball]::FileObserver2
:relfileprefix: ../../
:mrdocs:

This class implements the `Observer` protocol. The `publish` method of this class outputs the log records that it receives to a user‐specified file. This class is thread‐safe; different threads can operate on an object concurrently. This class is exception‐neutral with no guarantee of rollback. In no event is memory leaked.

== Synopsis

Declared in `<ball_fileobserver2.h>`

[source,cpp,subs="verbatim,replacements,macros,-callouts"]
----
class FileObserver2
    : public xref:BloombergLP/ball/Observer.adoc[Observer]
----

== Base Classes

[cols="1,4"]
|===
| Name| Description
| `xref:BloombergLP/ball/Observer.adoc[Observer]`
| This class provides a protocol for receiving and processing log record output.
|===

== Type Aliases

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/ball/FileObserver2/LogRecordFunctor.adoc[`LogRecordFunctor`] 
| `LogRecordFunctor` is an alias for the type of the functor used for formatting log records to a stream.
| xref:BloombergLP/ball/FileObserver2/OnFileRotationCallback.adoc[`OnFileRotationCallback`] 
| `OnFileRotationCallback` is an alias for a user‐supplied callback function that is invoked after the file observer attempts to rotate its log file. The callback takes two arguments: (1) an integer status value where 0 indicates a new log file was successfully created and a non‐zero value indicates an error occurred during rotation, and (2) a string that provides the name of the rotated log file if the rotation was successful. E.g.: ` void onLogFileRotation(int rotationStatus, const bsl::string& rotatedLogFileName); `
| xref:BloombergLP/ball/FileObserver2/RecordFormatter.adoc[`RecordFormatter`] 
| `RecordFormatter` is an alias for the type of the functor used for formatting log records to a stream.
|===


== Member Functions

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/ball/FileObserver2/2constructor.adoc[`FileObserver2`]         [.small]#[constructor]#
| Create a file observer with file logging initially disabled. Optionally specify a `basicAllocator` used to supply memory. If `basicAllocator` is 0, the currently installed default allocator is used. Note that `isPublishInLocalTimeEnabled` returns `false` following construction indicating that the timestamp attribute of published records will be written in UTC time (see `enablePublishInLocalTime`). Also note that a default record format is in effect for file logging (see `setLogFileFunctor`).
| xref:BloombergLP/ball/FileObserver2/2destructor.adoc[`~FileObserver2`] [.small]#[destructor]# [.small]#[virtual]#
| Close the log file of this file observer if file logging is enabled, and destroy this file observer.
| xref:BloombergLP/ball/FileObserver2/disableFileLogging.adoc[`disableFileLogging`] 
| Disable file logging for this file observer. This method has no effect if file logging is not enabled. Note that records subsequently received through the `publish` method will be dropped until file logging is re‐enabled.
| xref:BloombergLP/ball/FileObserver2/disableLifetimeRotation.adoc[`disableLifetimeRotation`] 
| Disable log file rotation based on a periodic time interval for this file observer. This method has no effect if rotation‐on‐time‐interval is not enabled.
| xref:BloombergLP/ball/FileObserver2/disablePublishInLocalTime.adoc[`disablePublishInLocalTime`] 
| Disable publishing of the timestamp attribute of records in local time by this file observer; henceforth, timestamps will be in UTC time. This method has no effect if publishing in local time is not enabled. Note that this method also affects log filenames (see {Log Filename Patterns}).
| xref:BloombergLP/ball/FileObserver2/disableSizeRotation.adoc[`disableSizeRotation`] 
| Disable log file rotation based on log file size for this file observer. This method has no effect if rotation‐on‐size is not enabled.
| xref:BloombergLP/ball/FileObserver2/disableTimeIntervalRotation.adoc[`disableTimeIntervalRotation`] 
| Disable log file rotation based on a periodic time interval for this file observer. This method has no effect if rotation‐on‐time‐interval is not enabled.
| xref:BloombergLP/ball/FileObserver2/enableFileLogging-0b.adoc[`enableFileLogging`] 
| `enableFileLogging` overloads
| xref:BloombergLP/ball/FileObserver2/enablePublishInLocalTime.adoc[`enablePublishInLocalTime`] 
| Enable publishing of the timestamp attribute of records in local time by this file observer. This method has no effect if publishing in local time is already enabled. Note that this method also affects log filenames (see {Log Filename Patterns}).
| xref:BloombergLP/ball/FileObserver2/forceRotation.adoc[`forceRotation`] 
| Forcefully perform a log file rotation by this file observer. Close the current log file, rename the log file if necessary, and open a new log file. This method has no effect if file logging is not enabled. See {Rotated File Naming} for details on filenames of rotated log files.
| xref:BloombergLP/ball/FileObserver2/getFormat.adoc[`getFormat`] 
| Return the format config of the last successful `setFormat` call.
| xref:BloombergLP/ball/FileObserver2/isFileLoggingEnabled-00.adoc[`isFileLoggingEnabled`] 
| `isFileLoggingEnabled` overloads
| xref:BloombergLP/ball/FileObserver2/isPublishInLocalTimeEnabled.adoc[`isPublishInLocalTimeEnabled`] 
| Return `true` if this file observer writes the timestamp attribute of records that it publishes in local time, and `false` otherwise (in which case timestamps are written in UTC time). Note that the value returned by this method also affects log filenames (see {Log Filename Patterns}).
| xref:BloombergLP/ball/FileObserver2/isSuppressUniqueFileNameOnRotation.adoc[`isSuppressUniqueFileNameOnRotation`] 
| Return `true` if the log filename uniqueness check on rotation is suppressed, and false otherwise.
| xref:BloombergLP/ball/FileObserver2/localTimeOffset.adoc[`localTimeOffset`] 
| Return the difference between the local time and UTC time in effect when this file observer was constructed. Note that this value remains unchanged during the lifetime of this object and therefore may become incorrect when the difference between the local time and UTC time changes (e.g., when transitioning into or out of daylight savings time).
| xref:BloombergLP/ball/FileObserver2/publish-09.adoc[`publish`] 
| `publish` overloads
| xref:BloombergLP/ball/FileObserver2/releaseRecords.adoc[`releaseRecords`]  [.small]#[virtual]#
| Discard any shared references to `Record` objects that were supplied to the `publish` method, and are held by this observer. Note that this operation should be called if resources underlying the previously provided shared pointers must be released.
| xref:BloombergLP/ball/FileObserver2/rotateOnLifetime.adoc[`rotateOnLifetime`] 
| Set this file observer to perform a periodic log file rotation at multiples of the specified `timeInterval`. This rule replaces any rotation‐on‐time‐interval rule currently in effect. The behavior is undefined unless `0 < timeInterval.totalMilliseconds()`.
| xref:BloombergLP/ball/FileObserver2/rotateOnSize.adoc[`rotateOnSize`] 
| Set this file observer to perform log file rotation when the size of the file exceeds the specified `size` (in kilobytes). This rule replaces any rotation‐on‐size rule currently in effect. The behavior is undefined unless `size > 0`.
| xref:BloombergLP/ball/FileObserver2/rotateOnTimeInterval-0b.adoc[`rotateOnTimeInterval`] 
| `rotateOnTimeInterval` overloads
| xref:BloombergLP/ball/FileObserver2/rotationLifetime.adoc[`rotationLifetime`] 
| Return the lifetime of the log file that will trigger a file rotation by this file observer if rotation‐on‐lifetime is in effect, and a 0 time interval otherwise.
| xref:BloombergLP/ball/FileObserver2/rotationSize.adoc[`rotationSize`] 
| Return the size (in kilobytes) of the log file that will trigger a file rotation by this file observer if rotation‐on‐size is in effect, and 0 otherwise.
| xref:BloombergLP/ball/FileObserver2/setFormat.adoc[`setFormat`] 
| Set the formatting functor used when writing records to the log file of this file observer to a log file functor created according to the specified, possibly URI‐like scheme tagged, `format`. Return zero if the setup with the specified arguments was successful and also save the `format` to be later retrievable using `getFormat`. Otherwise (if no matching scheme could be found or the configuration is invalid) return a non‐zero value and do not change the log record formatter used by this object. Note that a default format ("n%d %p:%t %s %f:%l %c %m %un") is in effect until this method or `setLogFileFunctor` is called. Also, notice that the observer emits newline characters at the beginning and at the end of a log record by default, so the user needs to add them explicitly to (text) format strings to preserve that behavior.
| xref:BloombergLP/ball/FileObserver2/setLogFileFunctor.adoc[`setLogFileFunctor`] 
| Set the formatting functor used when writing records to the log file of this file observer to the specified `logFileFunctor`. Note that a default format ("n%d %p:%t %s %f:%l %c %m %un") is in effect until this method or `setFormat` is called. Also, notice that the observer emits newline characters at the beginning and at the end of a log record by default, so the user needs to add them explicitly to (text) format strings to preserve that behavior. Note that this method exists for backwards compatibility and new code is highly encouraged to make use of `setFormat` with the URI‐scheme‐like tags to create different formatters. (Currently string and JSON output format is supported.)
| xref:BloombergLP/ball/FileObserver2/setOnFileRotationCallback.adoc[`setOnFileRotationCallback`] 
| Set the specified `onRotationCallback` to be invoked after each time this file observer attempts to perform a log file rotation. The behavior is undefined if the supplied function calls either `setOnFileRotationCallback`, `forceRotation`, or `publish` on this file observer (i.e., the supplied callback should _not_ attempt to write to the `ball` log).
| xref:BloombergLP/ball/FileObserver2/suppressUniqueFileNameOnRotation.adoc[`suppressUniqueFileNameOnRotation`] 
| Suppress generating a unique log file name upon rotation if the specified `suppress` is `true`, and generate a unique filename otherwise. See {Rotated File Naming} for details.
| xref:BloombergLP/ball/FileObserver2/2conversion.adoc[`operator BloombergLP::bslmf::NestedTraitDeclaration<FileObserver2, UsesBslmaAllocator>`] 
| Declare that this type uses a `bslma` allocator.
|===



[.small]#Created with https://www.mrdocs.com[MrDocs]#