API change: renamed method: unregisterExtension: -> unregisterExtensi…

…onWithName:
yapstudios · Jun 30, 2014 · 628e3b2 · 628e3b2
1 parent 4712ed9
commit 628e3b2
Show file tree

Hide file tree

Showing 4 changed files with 121 additions and 34 deletions.
diff --git a/Testing/UnitTesting/TestYapDatabaseFilteredView.m b/Testing/UnitTesting/TestYapDatabaseFilteredView.m
@@ -574,7 +574,7 @@ - (void)_testUnregistration_withPath:(NSString *)databasePath options:(YapDataba
 
 	// Now unregister the view, and make sure it automatically unregisters the filteredView too.
 
-	[database unregisterExtension:@"order"];
+	[database unregisterExtensionWithName:@"order"];
 
 	[connection readWithBlock:^(YapDatabaseReadTransaction *transaction) {
 
@@ -707,7 +707,7 @@ - (void)_testDoubleUnregistration_withPath:(NSString *)databasePath options:(Yap
 
 	// Now unregister the view, and make sure it automatically unregisters both filteredViews too.
 
-	[database unregisterExtension:@"order"];
+	[database unregisterExtensionWithName:@"order"];
 
 	[connection readWithBlock:^(YapDatabaseReadTransaction *transaction) {
 
@@ -1503,8 +1503,8 @@ - (void)_testEmptyFilterMappings_withPath:(NSString *)databasePath options:(YapD
 
     [[NSNotificationCenter defaultCenter] removeObserver:observer];
 
-    [database unregisterExtension:@"order"];
-//	[database unregisterExtension:@"filter"]; // <- will get automatically unregistered with order (b/c of dependency)
+    [database unregisterExtensionWithName:@"order"];
+	// The @"filter" extension will get automatically unregistered with order (b/c of dependency)
 }
 
 @end
diff --git a/Testing/UnitTesting/TestYapDatabaseView.m b/Testing/UnitTesting/TestYapDatabaseView.m
@@ -2525,7 +2525,7 @@ - (void)_testDropView_withPath:(NSString *)databasePath options:(YapDatabaseView
 
 	// Now drop the view
 
-	[database unregisterExtension:@"order"];
+	[database unregisterExtensionWithName:@"order"];
 
 	// Now make sure it's gone
 

diff --git a/YapDatabase/YapDatabase.h b/YapDatabase/YapDatabase.h
@@ -459,21 +459,25 @@ extern NSString *const YapDatabaseAllKeysRemovedKey;
  * The associated underlying tables will be dropped from the database.
  * 
  * Note 1:
- * You can unregister an extension that was hasn't been registered. For example,
- * you've previously registered an extension (in previous app launches), but you no longer need the extension.
- * You don't have to bother creating and registering the unneeded extension,
- * just so you can unregister it and have the associated tables dropped.
- * The database persists information about registered extensions, including the associated class of an extension.
- * So you can simply pass the name of the extension, and the database system will use the associated class to
- * drop the appropriate tables.
- *
- * Note:
- * You don't have to worry about unregistering extensions that you no longer need.
+ *   You don't need to re-register an extension in order to unregister it. For example,
+ *   you've previously registered an extension (in previous app launches), but you no longer need the extension.
+ *   You don't have to bother creating and registering the unneeded extension,
+ *   just so you can unregister it and have the associated tables dropped.
+ *   The database persists information about registered extensions, including the associated class of an extension.
+ *   So you can simply pass the name of the extension, and the database system will use the associated class to
+ *   drop the appropriate tables.
+ *
+ * Note 2:
+ *   In fact, you don't even have to worry about unregistering extensions that you no longer need.
+ *   That database system will automatically handle it for you.
+ *   That is, upon completion of the first readWrite transaction (that makes changes), the database system will
+ *   check to see if there are any "orphaned" extensions. Previously registered extensions that are no longer in use.
+ *   And it will automatically unregister these orhpaned extensions for you.
  *       
- * @see asyncUnregisterExtension:completionBlock:
- * @see asyncUnregisterExtension:completionBlock:completionQueue:
+ * @see asyncUnregisterExtensionWithName:completionBlock:
+ * @see asyncUnregisterExtensionWithName:completionBlock:completionQueue:
 **/
-- (void)unregisterExtension:(NSString *)extensionName;
+- (void)unregisterExtensionWithName:(NSString *)extensionName;
 
 /**
  * Asynchronoulsy starts the extension unregistration process.
@@ -486,8 +490,8 @@ extern NSString *const YapDatabaseAllKeysRemovedKey;
  * 
  * The completionBlock will be invoked on the main thread (dispatch_get_main_queue()).
 **/
-- (void)asyncUnregisterExtension:(NSString *)extensionName
-                 completionBlock:(dispatch_block_t)completionBlock;
+- (void)asyncUnregisterExtensionWithName:(NSString *)extensionName
+                         completionBlock:(dispatch_block_t)completionBlock;
 
 /**
  * Asynchronoulsy starts the extension unregistration process.
@@ -501,9 +505,25 @@ extern NSString *const YapDatabaseAllKeysRemovedKey;
  * Additionally the dispatch_queue to invoke the completion block may also be specified.
  * If NULL, dispatch_get_main_queue() is automatically used.
 **/
+- (void)asyncUnregisterExtensionWithName:(NSString *)extensionName
+                         completionBlock:(dispatch_block_t)completionBlock
+                         completionQueue:(dispatch_queue_t)completionQueue;
+
+
+/**
+ * DEPRECATED in v2.5
+**/
+- (void)unregisterExtension:(NSString *)extensionName
+__attribute((deprecated("Use method unregisterExtensionWithName: instead")));
+
+- (void)asyncUnregisterExtension:(NSString *)extensionName
+                 completionBlock:(dispatch_block_t)completionBlock
+__attribute((deprecated("Use method asyncUnregisterExtensionWithName:completionBlock: instead")));
+
 - (void)asyncUnregisterExtension:(NSString *)extensionName
                  completionBlock:(dispatch_block_t)completionBlock
-                 completionQueue:(dispatch_queue_t)completionQueue;
+                 completionQueue:(dispatch_queue_t)completionQueue
+__attribute((deprecated("Use method asyncUnregisterExtensionWithName:completionBlock:completionQueue: instead")));
 
 /**
  * Returns the registered extension with the given name.

diff --git a/YapDatabase/YapDatabase.m b/YapDatabase/YapDatabase.m
@@ -1404,34 +1404,65 @@ - (void)asyncRegisterExtension:(YapDatabaseExtension *)extension
 }
 
 /**
+ * This method unregisters an extension with the given name.
+ * The associated underlying tables will be dropped from the database.
  *
+ * Note 1:
+ *   You don't need to re-register an extension in order to unregister it. For example,
+ *   you've previously registered an extension (in previous app launches), but you no longer need the extension.
+ *   You don't have to bother creating and registering the unneeded extension,
+ *   just so you can unregister it and have the associated tables dropped.
+ *   The database persists information about registered extensions, including the associated class of an extension.
+ *   So you can simply pass the name of the extension, and the database system will use the associated class to
+ *   drop the appropriate tables.
+ *
+ * Note 2:
+ *   In fact, you don't even have to worry about unregistering extensions that you no longer need.
+ *   That database system will automatically handle it for you.
+ *   That is, upon completion of the first readWrite transaction (that makes changes), the database system will
+ *   check to see if there are any "orphaned" extensions. Previously registered extensions that are no longer in use.
+ *   And it will automatically unregister these orhpaned extensions for you.
+ *
+ * @see asyncUnregisterExtensionWithName:completionBlock:
+ * @see asyncUnregisterExtensionWithName:completionBlock:completionQueue:
 **/
-- (void)unregisterExtension:(NSString *)extensionName
+- (void)unregisterExtensionWithName:(NSString *)extensionName
 {
 	dispatch_sync(writeQueue, ^{ @autoreleasepool {
 
-		[self _unregisterExtension:extensionName];
+		[self _unregisterExtensionWithName:extensionName];
 	}});
 }
 
-- (void)asyncUnregisterExtension:(NSString *)extensionName
-                 completionBlock:(dispatch_block_t)completionBlock
+/**
+ * Asynchronoulsy starts the extension unregistration process.
+ *
+ * The unregistration process is equivalent to a readwrite transaction.
+ * It involves deleting various information about the extension from the database,
+ * as well as possibly dropping related tables the extension may have been using.
+ *
+ * An optional completion block may be used.
+ *
+ * The completionBlock will be invoked on the main thread (dispatch_get_main_queue()).
+**/
+- (void)asyncUnregisterExtensionWithName:(NSString *)extensionName
+                         completionBlock:(dispatch_block_t)completionBlock
 {
-	[self asyncUnregisterExtension:extensionName
-	               completionBlock:completionBlock
-	               completionQueue:NULL];
+	[self asyncUnregisterExtensionWithName:extensionName
+	                       completionBlock:completionBlock
+	                       completionQueue:NULL];
 }
 
-- (void)asyncUnregisterExtension:(NSString *)extensionName
-                 completionBlock:(dispatch_block_t)completionBlock
-                 completionQueue:(dispatch_queue_t)completionQueue
+- (void)asyncUnregisterExtensionWithName:(NSString *)extensionName
+                         completionBlock:(dispatch_block_t)completionBlock
+                         completionQueue:(dispatch_queue_t)completionQueue
 {
 	if (completionQueue == NULL && completionBlock != NULL)
 		completionQueue = dispatch_get_main_queue();
 
 	dispatch_async(writeQueue, ^{ @autoreleasepool {
 
-		[self _unregisterExtension:extensionName];
+		[self _unregisterExtensionWithName:extensionName];
 
 		if (completionBlock)
 		{
@@ -1448,7 +1479,7 @@ - (void)asyncUnregisterExtension:(NSString *)extensionName
  * Handles lazy creation and destruction of short-lived registrationConnection instance.
  * 
  * @see _registerExtension:withName:
- * @see _unregisterExtension:
+ * @see _unregisterExtensionWithName:
 **/
 - (YapDatabaseConnection *)registrationConnection
 {
@@ -1523,7 +1554,7 @@ - (BOOL)_registerExtension:(YapDatabaseExtension *)extension withName:(NSString
  * Internal method that handles extension unregistration.
  * This method must be invoked on the writeQueue.
 **/
-- (void)_unregisterExtension:(NSString *)extensionName
+- (void)_unregisterExtensionWithName:(NSString *)extensionName
 {
 	NSAssert(dispatch_get_specific(IsOnWriteQueueKey), @"Must go through writeQueue.");
 
@@ -1536,6 +1567,42 @@ - (void)_unregisterExtension:(NSString *)extensionName
 	[[self registrationConnection] unregisterExtensionWithName:extensionName];
 }
 
+/**
+ * DEPRECATED in v2.5
+ * 
+ * Use unregisterExtensionWithName: instead.
+**/
+- (void)unregisterExtension:(NSString *)extensionName
+{
+	[self unregisterExtensionWithName:extensionName];
+}
+
+/**
+ * DEPRECATED in v2.5
+ * 
+ * Use asyncUnregisterExtensionWithName:completionBlock: instead.
+**/
+- (void)asyncUnregisterExtension:(NSString *)extensionName
+                 completionBlock:(dispatch_block_t)completionBlock
+{
+	[self asyncUnregisterExtensionWithName:extensionName
+	                       completionBlock:completionBlock];
+}
+
+/**
+ * DEPRECATED in v2.5
+ * 
+ * Use asyncUnregisterExtensionWithName:completionBlock:completionQueue: instead.
+**/
+- (void)asyncUnregisterExtension:(NSString *)extensionName
+                 completionBlock:(dispatch_block_t)completionBlock
+                 completionQueue:(dispatch_queue_t)completionQueue
+{
+	[self asyncUnregisterExtensionWithName:extensionName
+	                       completionBlock:completionBlock
+	                       completionQueue:completionQueue];
+}
+
 /**
  * Returns the registered extension with the given name.
 **/