AGStore protocol

gistfile1.m

/**
 * AGStore represents an abstraction layer for a storage system.
 */
@protocol AGStore <NSObject>

/**
 * Reads all the data from the underlying storage system.
 *
 * @param success A block object to be executed when the operation finishes successfully.
 * This block has no return value and takes one argument: A collection, containing all stored
 * objects.
 *
 * @param failure A block object to be executed when the operation finishes unsuccessfully.
 * This block has no return value and takes one argument: The `NSError` object describing
 * the error that occurred.
 */
-(void) readAll:(void (^)(id objects))success
        failure:(void (^)(NSError *error))failure;

/**
 * Reads a specific object/record from the underlying storage system.
 *
 * @param success A block object to be executed when the operation finishes successfully.
 * This block has no return value and takes one argument: The object (or nil) read from the
 * underlying storage.
 *
 * @param failure A block object to be executed when the operation finishes unsuccessfully.
 * This block has no return value and takes one argument: The `NSError` object describing
 * the error that occurred.
 */
-(void) read:(id) recordId
     success:(void (^)(id object))success
     failure:(void (^)(NSError *error))failure;

/**
 * Reads all, based on a filter, from the underlying storage system.
 *
 * @param success A block object to be executed when the operation finishes successfully.
 * This block has no return value and takes one argument: A collection, containing all stored
 * objects, matching the given filter. The argument is nil, if nothing matches the criteria.
 *
 * @param failure A block object to be executed when the operation finishes unsuccessfully.
 * This block has no return value and takes one argument: The `NSError` object describing
 * the error that occurred.
 */
-(void) filter:(id)filterObject
       success:(void (^)(id objects))success
       failure:(void (^)(NSError *error))failure;



/**
 * Saves the given object in the underlying storage system.
 *
 * @param success A block object to be executed when the operation finishes successfully.
 * This block has no return value and takes one argument: The object that has been stored.
 *
 * @param failure A block object to be executed when the operation finishes unsuccessfully.
 * This block has no return value and takes one argument: The `NSError` object describing
 * the error that occurred.
 */
-(void) save:(id) data
     success:(void (^)(id object))success
     failure:(void (^)(NSError *error))failure;



/**
 * Resets the entire storage system.
 *
 * @param success A block object to be executed when the operation finishes successfully.
 * This block has no return value and takes no argument.
 *
 * @param failure A block object to be executed when the operation finishes unsuccessfully.
 * This block has no return value and takes one argument: The `NSError` object describing
 * the error that occurred.
 */
-(void) reset:(void (^)())success
      failure:(void (^)(NSError *error))failure;


/**
 * Removes a specific object/record from the underlying storage system.
 *
 * @param success A block object to be executed when the operation finishes successfully.
 * This block has no return value and takes one argument: The object that has been removed.
 *
 * @param failure A block object to be executed when the operation finishes unsuccessfully.
 * This block has no return value and takes one argument: The `NSError` object describing
 * the error that occurred.
 */
-(void) remove:(id) recordId
       success:(void (^)(id object))success
       failure:(void (^)(NSError *error))failure;

// NOTE: a 'removeAll' method has been _deleted_
@end