Create some core infrastructure for backends (#2198)

* s/GDLLogClock/GDLClock/

This isn't a class of log clocks, it's a class of clocks.

* Create some core infrastructure to support backends and prioritization of logs.

* Docs and slight changes to the scorer API.

* Missing return statement

* Change 'score' terminology to 'prioritize'. Also style issues.

* Change the protocol being used for a prioritizer.

Author: mikehaney24

GoogleDataLogger/GoogleDataLogger/Classes/GDLLogClock.h renamed to GoogleDataLogger/GoogleDataLogger/Classes/GDLClock.h

@@ -31,7 +31,7 @@ typedef struct {
 } GDLLogClockSnapshot;
 
 /** This class manages the device clock and produces snapshots of the current time. */
-@interface GDLLogClock : NSObject
+@interface GDLClock : NSObject
 
 // TODO(mikehaney24): - (GDLLogClockSnapshot)snapshot;
 

GoogleDataLogger/GoogleDataLogger/Classes/GDLLogClock.m renamed to GoogleDataLogger/GoogleDataLogger/Classes/GDLClock.m

@@ -14,8 +14,8 @@
  * limitations under the License.
  */
 
-#import "GDLLogClock.h"
+#import "GDLClock.h"
 
-@implementation GDLLogClock
+@implementation GDLClock
 
 @end

GoogleDataLogger/GoogleDataLogger/Classes/GDLRegistrar.m

@@ -0,0 +1,39 @@
+/*
+ * Copyright 2018 Google
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#import "GDLRegistrar.h"
+
+@implementation GDLRegistrar
+
++ (instancetype)sharedInstance {
+  static GDLRegistrar *sharedInstance;
+  static dispatch_once_t onceToken;
+  dispatch_once(&onceToken, ^{
+    sharedInstance = [[GDLRegistrar alloc] init];
+  });
+  return sharedInstance;
+}
+
+- (void)registerBackend:(id<GDLLogBackend>)backend forLogTarget:(NSInteger)logTarget {
+  // TODO
+}
+
+- (void)registerLogPrioritizer:(id<GDLLogPrioritizer>)prioritizer
+                  forLogTarget:(NSInteger)logTarget {
+  // TODO
+}
+
+@end

GoogleDataLogger/GoogleDataLogger/Classes/Private/GDLLogEvent_Private.h

@@ -16,7 +16,7 @@
 
 #import "GDLLogEvent.h"
 
-#import "GDLLogClock.h"
+#import "GDLClock.h"
 
 NS_ASSUME_NONNULL_BEGIN
 

GoogleDataLogger/GoogleDataLogger/Classes/Private/GDLRegistrar_Private.h

@@ -0,0 +1,27 @@
+/*
+ * Copyright 2018 Google
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#import <GoogleDataLogger/GDLRegistrar.h>
+
+@interface GDLRegistrar ()
+
+/** A map of logTargets to backend implementations. */
+@property(nonatomic) NSDictionary<NSNumber *, id<GDLLogBackend>> *logTargetToBackend;
+
+/** A map of logTargets to prioritizer implementations. */
+@property(nonatomic) NSDictionary<NSNumber *, id<GDLLogPrioritizer>> *logTargetToPrioritizer;
+
+@end

GoogleDataLogger/GoogleDataLogger/Classes/Public/GDLLogBackend.h

@@ -0,0 +1,39 @@
+/*
+ * Copyright 2018 Google
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#import <Foundation/Foundation.h>
+
+/** A convenient typedef to define the block to be called upon completion of an upload to the
+ * backend.
+ */
+typedef void (^GDLBackendCompletionBlock)(NSSet<NSURL *> *successfulUploads,
+                                          NSSet<NSURL *> *unsuccessfulUploads);
+
+/** This protocol defines the common interface for logging backend implementations. */
+@protocol GDLLogBackend <NSObject>
+
+@required
+
+/** Uploads logs to the backend using this specific backend's chosen format.
+ *
+ * @param logFiles The set of log files to upload.
+ * @param onComplete A block to invoke upon completing the upload. Has two arguments:
+ *   - successfulUploads: The set of filenames uploaded successfully.
+ *   - unsuccessfulUploads: The set of filenames not uploaded successfully.
+ */
+- (void)uploadLogs:(NSSet<NSURL *> *)logFiles onComplete:(GDLBackendCompletionBlock)onComplete;
+
+@end

GoogleDataLogger/GoogleDataLogger/Classes/Public/GDLLogPrioritizer.h

@@ -0,0 +1,47 @@
+/*
+ * Copyright 2018 Google
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#import <Foundation/Foundation.h>
+
+@class GDLLogEvent;
+
+/** This protocol defines the common interface of a log prioritization. Log prioritizers are
+ * stateful objects that prioritize logs upon insertion into storage and remain prepared to return a
+ * set of log filenames to the storage system.
+ */
+@protocol GDLLogPrioritizer <NSObject>
+
+@required
+
+/** Accepts a logEvent and uses the log metadata to make choices on how to prioritize the log. This
+ *  method exists as a way to help prioritize which logs should be sent, which is dependent on the
+ *  request proto structure of your backend.
+ *
+ *  @note Three things: 1. the logEvent cannot be retained for longer than the execution time of
+ * this method. 2. The extension should be nil by this point and should not be used to prioritize
+ * logs. 3. You should retain the logEvent hashes, because those are returned in logsForNextUpload.
+ *
+ * @param logEvent The log event to prioritize.
+ */
+- (void)prioritizeLog:(GDLLogEvent *)logEvent;
+
+/** Returns a set of logs based on the logic of the prioritizer.
+ *
+ * @return A set of log hashes to upload, presumably based on the logs' priority.
+ */
+- (NSSet<NSNumber *> *)logsForNextUpload;
+
+@end

GoogleDataLogger/GoogleDataLogger/Classes/Public/GDLRegistrar.h

@@ -0,0 +1,49 @@
+/*
+ * Copyright 2018 Google
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#import <Foundation/Foundation.h>
+
+#import <GoogleDataLogger/GDLLogBackend.h>
+#import <GoogleDataLogger/GDLLogPrioritizer.h>
+
+NS_ASSUME_NONNULL_BEGIN
+
+/** Manages the registration of log targets with the logging SDK. */
+@interface GDLRegistrar : NSObject
+
+/** Creates and/or returns the singleton instance.
+ *
+ * @return The singleton instance of this class.
+ */
++ (instancetype)sharedInstance;
+
+/** Registers a backend implementation with the GoogleDataLogger infrastructure.
+ *
+ * @param backend The backend object to register.
+ * @param logTarget The logTarget this backend object will be responsible for.
+ */
+- (void)registerBackend:(id<GDLLogBackend>)backend forLogTarget:(NSInteger)logTarget;
+
+/** Registers a log prioritizer implementation with the GoogleDataLogger infrastructure.
+ *
+ * @param prioritizer The prioritizer object to register.
+ * @param logTarget The logTarget this prioritizer object will be responsible for.
+ */
+- (void)registerLogPrioritizer:(id<GDLLogPrioritizer>)prioritizer forLogTarget:(NSInteger)logTarget;
+
+@end
+
+NS_ASSUME_NONNULL_END

GoogleDataLogger/Tests/GDLRegistrarTest.m

@@ -0,0 +1,32 @@
+/*
+ * Copyright 2018 Google
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#import <XCTest/XCTest.h>
+
+#import <GoogleDataLogger/GDLRegistrar.h>
+
+@interface GDLRegistrarTest : XCTestCase
+
+@end
+
+@implementation GDLRegistrarTest
+
+/** Tests the default initializer. */
+- (void)testInit {
+  XCTAssertNotNil([[GDLRegistrarTest alloc] init]);
+}
+
+@end