SCDataStore

@interface SCDataStore : NSObject {
  SCStoreMode _storeMode;
  NSObject *_storedData;
  SCDataDefinition *_defaultDataDefinition;
  NSMutableDictionary *_dataDefinitions;
  NSMutableArray *_uninsertedObjects;
  NSObject *_boundObject;
  NSString *_boundPropertyName;
  SCDataDefinition *_boundObjectDefinition;
  NSDictionary *_defaultsDictionary;
}

SCDataStore is an abstract base class that can encapsulate any kind of data storage, providing means for the SC framework to communicate with this storage to fetch, add, update and remove data.

Several SCDataStore subclasses have been implemented to enable the SC framework to communicate with Core Data, web services, iCloud storage, and even NSUserDefaults storage. Feel free to subclass SCDataStore to enable any kind of data storage not currently implemented by framework.

Sample use: // Display all the TaskEntity objects SCCoreDataStore *coreDataStore = [SCCoreDataStore storeWithManagedObjectContext:context defaultEntityDefinition:TaskEntityDef]; SCArrayOfObjectsSection *tasksSection = [SCArrayOfObjectsSection sectionWithHeaderTitle:@“Task Objects” dataStore:coreDataStore]; [self.tableViewModel addSection:tasksSection];

See also: SCArrayStore, SCCoreDataStore, SCWebServiceStore, SCiCloudStore, SCUserDefaultsStore

Note

At initialization time, SCDataStore must be assigned at least one default SCDataDefinition that fully defines its stored data objects.

Warning

SCDataStore is an abstract base class and should not be directly instantiated.

Show on GitHub

_storeMode
Undocumented
Declaration
Objective-C

SCStoreMode _storeMode
Show on GitHub
_storedData
Undocumented
Declaration
Objective-C

NSObject *_storedData
Show on GitHub
_defaultDataDefinition
Undocumented
Declaration
Objective-C

SCDataDefinition *_defaultDataDefinition
Show on GitHub
_dataDefinitions
Undocumented
Declaration
Objective-C

NSMutableDictionary *_dataDefinitions
Show on GitHub
_uninsertedObjects
Undocumented
Declaration
Objective-C

NSMutableArray *_uninsertedObjects
Show on GitHub
_boundObject
Undocumented
Declaration
Objective-C

NSObject *_boundObject
Show on GitHub
_boundPropertyName
Undocumented
Declaration
Objective-C

NSString *_boundPropertyName
Show on GitHub
_boundObjectDefinition
Undocumented
Declaration
Objective-C

SCDataDefinition *_boundObjectDefinition
Show on GitHub
_defaultsDictionary
Undocumented
Declaration
Objective-C

NSDictionary *_defaultsDictionary
Show on GitHub

Creation and Initialization

+storeWithDefaultDataDefinition:
Allocated and returns an initialized SCDataStore given a default SCDataDefinition of the data stored.
Declaration
Objective-C

+ (instancetype)storeWithDefaultDataDefinition:(SCDataDefinition *)definition;
Show on GitHub
-initWithDefaultDataDefinition:
Returns an initialized SCDataStore given a default SCDataDefinition of the data stored.
Declaration
Objective-C

- (instancetype)initWithDefaultDataDefinition:(SCDataDefinition *)definition;
Show on GitHub

Configuration

storeMode
Specifies the mode that the SC framework should use to communicate with the store. Set to SCStoreModeSynchronous to have the framework communicate synchronously, otherwise set to SCStoreModeAsynchronous for asynchronous communication.
Declaration
Objective-C

@property (nonatomic) SCStoreMode storeMode;
Show on GitHub
defaultDataDefinition
The data store’s default data definition. To add more data definitions (other than the default one), use addDataDefinition:.
Declaration
Objective-C

@property (nonatomic, strong) SCDataDefinition *defaultDataDefinition;
Show on GitHub
supportsNilValues
Whether the data store supports nil values. Default: YES.
Declaration
Objective-C

@property (nonatomic) BOOL supportsNilValues;
Show on GitHub
-addDataDefinition:
Adds a definition to dataDefinitions.
Declaration
Objective-C

- (void)addDataDefinition:(SCDataDefinition *)definition;
Show on GitHub
-definitionForObject:
Returns the data definition for the given object.
Declaration
Objective-C

- (SCDataDefinition *)definitionForObject:(NSObject *)object;
Show on GitHub

Synchronous Data Access

-createNewObject
Returns a newly allocated and initialized object based on the store’s default data definition.

Warning
Any newly created objects should be later either added to the data store using insertObject:, or discarded using discardUninsertedObject:.
Declaration
Objective-C

- (NSObject *)createNewObject;
Return Value

The newly created object.

Show on GitHub


                    
                    
                    -createNewObjectWithDefinition:

Returns a newly allocated and initialized object based on the given data definition.

Warning

Any newly created objects should be later either added to the data store using insertObject:, or discarded using discardUninsertedObject:.

Declaration

Objective-C

- (NSObject *)createNewObjectWithDefinition:(SCDataDefinition *)definition;

Parameters


                                definition

The data definition that describes the object to be created.

Return Value

The newly created object.

Show on GitHub


                    
                    
                    -discardUninsertedObject:

Discards the given uninserted object.

Any object created with createNewObject: or createNewObjectWithDefinition: and not later inserted to the store using insertObject: must be discarded using this method.

Declaration

Objective-C

- (BOOL)discardUninsertedObject:(NSObject *)object;

Parameters


                                object

The uninserted newly created object to be discarded.

Return Value

Returns TRUE if successful.

Show on GitHub


                    
                    
                    -insertObject:

Inserts the given object into the data store.

Declaration

Objective-C

- (BOOL)insertObject:(NSObject *)object;

Parameters


                                object

The object to be inserted.

Return Value

Returns TRUE if successful.

Show on GitHub


                    
                    
                    -insertObject:atOrder:

Inserts the given object into the data store at the specified order.

Note

Only applicable for data stores that maintain ordered object storage.

Declaration

Objective-C

- (BOOL)insertObject:(NSObject *)object atOrder:(NSUInteger)order;

Parameters

`object`	The object to be inserted.
`order`	The order index that the object should be inserted at.

Return Value

Returns TRUE if successful.

Show on GitHub


                    
                    
                    -changeOrderForObject:toOrder:subsetArray:

Changes the order of the given object to the specified order.

Note

Only applicable for data stores that maintain ordered object storage.

Declaration

Objective-C

- (BOOL)changeOrderForObject:(NSObject *)object
                     toOrder:(NSUInteger)toOrder
                 subsetArray:(NSArray *)subsetArray;

Parameters

`object`	The object that the order of will change.
`toOrder`	The new order index of the object.

Return Value

Returns TRUE if successful.

Show on GitHub


                    
                    
                    -updateObject:

Updates the given object in the data store.

Declaration

Objective-C

- (BOOL)updateObject:(NSObject *)object;

Parameters


                                object

The object to be updated.

Return Value

Returns TRUE if successful.

Show on GitHub


                    
                    
                    -deleteObject:

Deletes the given object from the data store.

Declaration

Objective-C

- (BOOL)deleteObject:(NSObject *)object;

Parameters


                                object

The object to be deleted.

Return Value

Returns TRUE if successful.

Show on GitHub


                    
                    
                    -fetchObjectsWithOptions:

Fetches objects from the data store that satisfy the given fetch options.

See

SCDataFetchOptions

Declaration

Objective-C

- (NSArray *)fetchObjectsWithOptions:(SCDataFetchOptions *)fetchOptions;

Parameters


                                fetchOptions

The fetch options that the data store must satisfy when returning the objects.

Return Value

An array of the fetched objects.

Show on GitHub


                    
                    
                    -valueForPropertyName:inObject:

Returns the value for the given property name in the given object.

Declaration

Objective-C

- (NSObject *)valueForPropertyName:(NSString *)propertyName
                          inObject:(NSObject *)object;

Parameters

`propertyName`	The name of the property.
`object`	The object containing propertyName.

Return Value

The value for the given propertyName.

Show on GitHub


                    
                    
                    -stringValueForPropertyName:inObject:separateValuesUsingDelimiter:

Returns the string value for the given property name in the given object.

Declaration

Objective-C

- (NSString *)stringValueForPropertyName:(NSString *)propertyName
                                inObject:(NSObject *)object
            separateValuesUsingDelimiter:(NSString *)delimiter;

Parameters

`propertyName`	The name of the property.
`object`	The object containing propertyName.
`delimiter`	If the property returns more than one value, this delimiter is used to separate the values in the returned string.

Return Value

The value for the given propertyName.

Show on GitHub


                    
                    
                    -setValue:forPropertyName:inObject:

Sets the value for the given property name in the given object.

Declaration

Objective-C

- (void)setValue:(NSObject *)value
    forPropertyName:(NSString *)propertyName
           inObject:(NSObject *)object;

Parameters

`value`	The value of the property.
`propertyName`	The name of the property.
`object`	The object containing propertyName.

Show on GitHub

Asynchronous Data Access


                    
                    
                    -asynchronousInsertObject:success:failure:noConnection:

Asynchronously inserts the given object into the data store.

SCDataStoreInsertSuccess_Block syntax: ^() { // Your code here }

SCDataStoreFailure_Block syntax: ^(NSError *error) { // Your code here }

SCNoConnection_Block syntax: ^BOOL() { // Return YES to try operation again when connection is established, otherwise return NO to call failure_block }

Declaration

Objective-C

- (void)asynchronousInsertObject:(NSObject *)object
                         success:(SCDataStoreInsertSuccess_Block)success_block
                         failure:(SCDataStoreFailure_Block)failure_block
                    noConnection:(SCNoConnection_Block)noConnection_block;

Parameters

`object`	The object to be inserted.
`success_block`	The code block called after the object has been successfully inserted.
`failure_block`	The code block called in case the object could not be inserted.
`noConnection_block`	The code block called in case no connection could be established to data store.

Show on GitHub


                    
                    
                    -asynchronousUpdateObject:success:failure:noConnection:

Asynchronously updates the given object into the data store.

SCDataStoreUpdateSuccess_Block syntax: ^() { // Your code here }

SCDataStoreFailure_Block syntax: ^(NSError *error) { // Your code here }

SCNoConnection_Block syntax: ^BOOL() { // Return YES to try operation again when connection is established, otherwise return NO to call failure_block }

Declaration

Objective-C

- (void)asynchronousUpdateObject:(NSObject *)object
                         success:(SCDataStoreUpdateSuccess_Block)success_block
                         failure:(SCDataStoreFailure_Block)failure_block
                    noConnection:(SCNoConnection_Block)noConnection_block;

Parameters

`object`	The object to be updated.
`success_block`	The code block called after the object has been successfully updated.
`failure_block`	The code block called in case the object could not be updated.
`noConnection_block`	The code block called in case no connection could be established to data store.

Show on GitHub


                    
                    
                    -asynchronousDeleteObject:success:failure:noConnection:

Asynchronously deletes the given object from the data store.

SCDataStoreDeleteSuccess_Block syntax: ^() { // Your code here }

SCDataStoreFailure_Block syntax: ^(NSError *error) { // Your code here }

SCNoConnection_Block syntax: ^BOOL() { // Return YES to try operation again when connection is established, otherwise return NO to call failure_block }

Declaration

Objective-C

- (void)asynchronousDeleteObject:(NSObject *)object
                         success:(SCDataStoreDeleteSuccess_Block)success_block
                         failure:(SCDataStoreFailure_Block)failure_block
                    noConnection:(SCNoConnection_Block)noConnection_block;

Parameters

`object`	The object to be deleted.
`success_block`	The code block called after the object has been successfully deleted.
`failure_block`	The code block called in case the object could not be deleted.
`noConnection_block`	The code block called in case no connection could be established to data store.

Show on GitHub


                    
                    
                    -asynchronousFetchObjectsWithOptions:success:failure:noConnection:

Asynchronously fetches objects from the data store that satisfy the given fetch options.

SCDataStoreFetchSuccess_Block syntax: ^(NSArray *results) { // Your code here } Where ‘results’ is the fetched data array.

SCDataStoreFailure_Block syntax: ^(NSError *error) { // Your code here }

SCNoConnection_Block syntax: ^BOOL() { // Return YES to try operation again when connection is established, otherwise return NO to call failure_block }

See

SCDataFetchOptions

Declaration

Objective-C

- (void)
    asynchronousFetchObjectsWithOptions:(SCDataFetchOptions *)fetchOptions
                                success:
                                    (SCDataStoreFetchSuccess_Block)success_block
                                failure:(SCDataStoreFailure_Block)failure_block
                           noConnection:
                               (SCNoConnection_Block)noConnection_block;

Parameters

`fetchOptions`	The fetch options that the data store must satisfy when returning the objects.
`success_block`	The code block called after the data has been successfully fetched.
`failure_block`	The code block called in case the data could not be fetched.
`noConnection_block`	The code block called in case no connection could be established to data store.

Show on GitHub


                    
                    
                    postAsynchronousFetchObjectsAction

Action gets called right after asynchronousFetchObjectsWithOptions has successfully finished.

This action is typically used to asynchronously load further objects or data in addition to the ones fetched in asynchronousFetchObjectsWithOptions.

Example:

// Objective-C
myDataStore.postAsynchronousFetchObjectsAction = ^(NSArray *results, SCPostFetchAsyncronousCompletionHandler_Block completionHandler)
{
    // ... load your data here asynchronously ...

    NSError *error = nil;
    completionHandler(myUpdatedResultsArray, error);
};

// Swift
myDataStore.postAsynchronousFetchObjectsAction =
{
    (results, completionHandler) in

    // ... load your data here asynchronously ...

    let error : NSError = nil
    completionHandler(myUpdatedResultsArray, error);
}

Declaration

Objective-C

@property (nonatomic, copy) SCPostFetchAsyncronousAction_Block postAsynchronousFetchObjectsAction;

Return Value

Return The updated array of objects.

Show on GitHub

Data Validation

-validateInsertForObject:
Returns TRUE if the given object can be inserted into the data store, otherwise returns FALSE.
Declaration
Objective-C

- (BOOL)validateInsertForObject:(NSObject *)object;
Show on GitHub
-validateUpdateForObject:
Returns TRUE if the given object can be updated into the data store, otherwise returns FALSE.
Declaration
Objective-C

- (BOOL)validateUpdateForObject:(NSObject *)object;
Show on GitHub
-validateDeleteForObject:
Returns TRUE if the given object can be deleted from the data store, otherwise returns FALSE.
Declaration
Objective-C

- (BOOL)validateDeleteForObject:(NSObject *)object;
Show on GitHub
-validateOrderChangeForObject:
Returns TRUE if the order of the given object can be changed in the data store, otherwise returns FALSE.
Declaration
Objective-C

- (BOOL)validateOrderChangeForObject:(NSObject *)object;
Show on GitHub

Data Management

-commitData
Commits the data store objects to the persistent store. This method is only applicable to data stores that store their objects in memory before persisting them to a permenant persistant storage.
Declaration
Objective-C

- (void)commitData;
Show on GitHub

Internal Properties & Methods (should only be used by the framework or when subclassing)

storedData
Should be used by subclasses to store their data when heap memory storage is needed.
Declaration
Objective-C

@property (nonatomic, strong) NSObject *storedData;
Show on GitHub
defaultsDictionary
Should be used by subclasses to store any default values needed.
Declaration
Objective-C

@property (nonatomic, strong) NSDictionary *defaultsDictionary;
Show on GitHub
-bindStoreToPropertyName:forObject:withDefinition:
Binds the store to a property name that will be used to fetch all the store’s data.

Should only be used by the framework all must be implemented by all subclasses.
Declaration
Objective-C

- (void)bindStoreToPropertyName:(NSString *)propertyName forObject:(NSObject *)object withDefinition:(SCDataDefinition *)definition;
Show on GitHub
-forceDiscardAllUnaddedObjects
This method is typically called internally by the framework when all unadded objects must be discarded. The method will issue the ‘SCDataStoreWillDiscardAllUnaddedObjectsNotification’ notification to inform all classes using the store that this will happen.
Declaration
Objective-C

- (void)forceDiscardAllUnaddedObjects;
Show on GitHub
-applicationWillEnterForeground
Method called when the application is about to leave the background state. Subclasses should override this method when any initialization is needed at this point.
Declaration
Objective-C

- (void)applicationWillEnterForeground;
Show on GitHub


                    
                    
                    -fetchObjectsSuccessful:successBlock:failure:

Undocumented

Declaration

Objective-C

- (void)fetchObjectsSuccessful:(NSArray *)objects successBlock:(SCDataStoreFetchSuccess_Block)success_block failure:(SCDataStoreFailure_Block)failure_block;

Show on GitHub