ORKDataLogger Class Reference

Inherits from	NSObject
Declared in	ORKDataLogger.h

The ORKDataLogger class is an internal component used by some ORKRecorder subclasses for writing data to disk during tasks. An ORKDataLogger object manages one log as a set of files in a directory.

The current log file is at directory/logName. Historic log files are at directory/logName-(timestamp)-(count) where timestamp is of the form YYYYMMddHHmmss (Zulu) and indicates the time the log finished (that is, was rolled over). If more than one rollover occurs within one second, additional log files may be created with increasing count.

The user is responsible for managing the historic log files, but the ORKDataLogger class provides tools for enumerating them (in sorted order).

The data logger contains a concept of whether a file has been uploaded, which is tracked using file attributes. This feature can facilitate a workflow in which log files are archived and queued for upload before actually sending them to a server. When archived and ready for upload, the files could be marked uploaded by the ORKDataLogger. When the upload is complete and the data has been handed off downstream, the files can then be deleted. If the upload fails, the uploaded files can have that flag cleared, to indicate that they should be included in the next archiving attempt.

Other Methods

`+ JSONDataLoggerWithDirectory:logName:delegate:`

Returns a data logger with an ORKJSONLogFormatter.

+ (ORKDataLogger *)JSONDataLoggerWithDirectory:(NSURL *)url logName:(NSString *)logName delegate:(nullable id<ORKDataLoggerDelegate>)delegate

Parameters

`url`	The URL of the directory in which to place log files.
`logName`	The prefix on the log file name in an ASCII string. Note that the string must not contain the hyphen character (“-”), because a hyphen is used as a separator in the log naming scheme.
`delegate`	The initial delegate. May be `nil`.

Declared In

ORKDataLogger.h

`– initWithDirectory:logName:formatter:delegate:`

Returns an initialized data logger using the specified URL, log name, formatter, and delegate.

- (instancetype)initWithDirectory:(NSURL *)url logName:(NSString *)logName formatter:(ORKLogFormatter *)formatter delegate:(nullable id<ORKDataLoggerDelegate>)delegate

Parameters

`url`	The URL of the directory in which to place log files
`logName`	The prefix on the log file name in an ASCII string. Note that the string must not contain the hyphen character (“-”), because a hyphen is used as a separator in the log naming scheme.
`formatter`	The type of formatter to use for the log, such as `ORKJSONLogFormatter`.
`delegate`	The initial delegate. May be `nil`.

Return Value

An initialized data logger.

Declared In

ORKDataLogger.h

`delegate`

The delegate to be notified when file sizes change or the log rolls over.

@property (weak, nullable) id<ORKDataLoggerDelegate> delegate

Declared In

ORKDataLogger.h

`logFormatter`

The log formatter being used.

@property (strong, readonly) ORKLogFormatter *logFormatter

Declared In

ORKDataLogger.h

`maximumCurrentLogFileSize`

The maximum current log file size.

@property size_t maximumCurrentLogFileSize

Discussion

When the current log reaches this size, it is automatically rolled over.

Declared In

ORKDataLogger.h

`maximumCurrentLogFileLifetime`

The maximum current log file lifetime.

@property NSTimeInterval maximumCurrentLogFileLifetime

Discussion

When the current log file has been active this long, it is rolled over.

Declared In

ORKDataLogger.h

`pendingBytes`

The number of bytes of log data that are not marked uploaded, excluding the current file. This value is lazily updated.

@property unsigned long long pendingBytes

Declared In

ORKDataLogger.h

`uploadedBytes`

The number of bytes of log data that are marked uploaded. This value is lazily updated.

@property unsigned long long uploadedBytes

Declared In

ORKDataLogger.h

`fileProtectionMode`

The file protection mode to use for newly created files.

@property (assign) ORKFileProtectionMode fileProtectionMode

Declared In

ORKDataLogger.h

`logName`

The prefix on the log file names.

@property (copy, readonly) NSString *logName

Declared In

ORKDataLogger.h

`– finishCurrentLog`

Forces a roll-over now.

- (void)finishCurrentLog

Declared In

ORKDataLogger.h

`– currentLogFileURL`

The current log file’s location.

- (NSURL *)currentLogFileURL

Declared In

ORKDataLogger.h

`– enumerateLogs:error:`

Enumerates the URLs of completed log files, sorted to put the oldest first.

- (BOOL)enumerateLogs:(void ( ^ ) ( NSURL *logFileUrl , BOOL *stop ))block error:(NSError *_Nullable *)error

Parameters

`block`	The block to call during enumeration.
`error`	Any error detected during the enumeration.

Return Value

YES if the enumeration was successful; otherwise, NO.

Discussion

Takes a snapshot of the current directory’s relevant files, sorts them, and enumerates them. Errors can occur if changes are being made to the filesystem other than through this object.

Declared In

ORKDataLogger.h

`– enumerateLogsNeedingUpload:error:`

Enumerates the URLs of completed log files not yet marked uploaded, sorted to put the oldest first.

- (BOOL)enumerateLogsNeedingUpload:(void ( ^ ) ( NSURL *logFileUrl , BOOL *stop ))block error:(NSError *_Nullable *)error

Parameters

`block`	The block to call during enumeration.
`error`	Any error detected during the enumeration.

Return Value

YES if the enumeration was successful; otherwise, NO.

Discussion

This method takes a snapshot of the current directory’s completed nonuploaded log files, sorts them, and then enumerates them. Errors can occur if changes are being made to the filesystem other than through this object.

Declared In

ORKDataLogger.h

`– enumerateLogsAlreadyUploaded:error:`

Enumerates the URLs of completed log files not already marked uploaded, sorted to put the oldest first.

- (BOOL)enumerateLogsAlreadyUploaded:(void ( ^ ) ( NSURL *logFileUrl , BOOL *stop ))block error:(NSError *_Nullable *)error

Parameters

`block`	The block to call during enumeration.
`error`	Any error detected during the enumeration.

Return Value

YES if the enumeration was successful; otherwise, NO.

Discussion

Takes a snapshot of the current directory’s completed uploaded log files, sorts them, and then enumerates them. Errors can occur if changes are being made to the filesystem other than through this object.

Declared In

ORKDataLogger.h

`– append:error:`

Appends an object to the log file, which is formatted with logFormatter.

- (BOOL)append:(id)object error:(NSError *_Nullable *)error

Parameters

`object`	Should be an object of a class that is accepted by the logFormatter.
`error`	Error output, if the append fails.

Return Value

YES if appending succeeds; otherwise, NO.

Discussion

The default log formatter expects NSData; call canAcceptLogObjectOfClass: on logFormatter to determine if it will accept this object.

Note that the current log file is created and opened lazily when a request to log data is made. If an attempt is made to log data and there is no access due to file protection, the log is immediately rolled over and a new file created.

Declared In

ORKDataLogger.h

`– appendObjects:error:`

Appends multiple objects to the log file.

- (BOOL)appendObjects:(NSArray *)objects error:(NSError *_Nullable *)error

Parameters

`objects`	An array of objects of a class that is accepted by the logFormatter.
`error`	Error output, if the append fails.

Return Value

YES if appending succeeds; otherwise, NO.

Discussion

This method formats and appends all the objects at once. Using this method may have efficiency and atomicity gains for error handling, compared to making multiple calls to append:error.

Declared In

ORKDataLogger.h

`– isFileUploadedAtURL:`

Checks whether a file has been marked as uploaded.

- (BOOL)isFileUploadedAtURL:(NSURL *)url

Parameters

`url`	The URL to check.

Return Value

YES if the uploaded attribute has been set on the file and the file exists; otherwise, NO.

Declared In

ORKDataLogger.h

`– markFileUploaded:atURL:error:`

Marks or unmarks a file as uploaded.

- (BOOL)markFileUploaded:(BOOL)uploaded atURL:(NSURL *)url error:(NSError *_Nullable *)error

Parameters

`uploaded`	A Boolean value that indicates whether to mark the file uploaded or not uploaded.
`url`	The URL to mark.
`error`	The error that occurred, if the operation fails.

Return Value

YES if adding or removing the attribute succeeded; otherwise, NO.

Discussion

This method uses an extended attribute on the filesystem to mark a file as uploaded. This is intended for book-keeping use only and to track which files have already been attached to a pending upload. When the upload is sufficiently complete, the file should be removed.

Declared In

ORKDataLogger.h

`– removeUploadedFiles:withError:`

Removes files if they are marked uploaded.

- (BOOL)removeUploadedFiles:(NSArray<NSURL*> *)fileURLs withError:(NSError *_Nullable *)error

Parameters

`fileURLs`	The array of files that should be removed.
`error`	The error that occurred, if the operation fails.

Return Value

YES if removing the files succeeded; otherwise, NO.

Discussion

If a file is in the list, but is no longer marked uploaded, this method does not remove the file. This workflow lets you unmark files selectively if they could not be added to the archive, and later call removeUploadedFiles:withError: to remove only the files that are still marked uploaded.

Declared In

ORKDataLogger.h

`– removeAllFilesWithError:`

Removes all files managed by this logger (files that have the logName prefix).

- (BOOL)removeAllFilesWithError:(NSError *_Nullable *)error

Parameters

`error`	The error that occurred, if operation fails.

Return Value

YES if removing the files succeeded.; otherwise, NO.

Declared In

ORKDataLogger.h

Tests Methods

`– fileHandle`

The file handle to which to write

- (nullable NSFileHandle *)fileHandle

Declared In

ORKDataLogger.h