SCDataStore Class Reference
Inherits from | NSObject |
Declared in | SCDataStore.h |
Overview
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.
Tasks
Creation and Initialization
Configuration
-
storeMode
property -
defaultDataDefinition
property -
supportsNilValues
property -
– addDataDefinition:
-
– definitionForObject:
Synchronous Data Access
-
– createNewObject
-
– createNewObjectWithDefinition:
-
– discardUninsertedObject:
-
– insertObject:
-
– insertObject:atOrder:
-
– changeOrderForObject:toOrder:subsetArray:
-
– updateObject:
-
– deleteObject:
-
– fetchObjectsWithOptions:
-
– valueForPropertyName:inObject:
-
– stringValueForPropertyName:inObject:separateValuesUsingDelimiter:
-
– setValue:forPropertyName:inObject:
Asynchronous Data Access
-
– asynchronousInsertObject:success:failure:noConnection:
-
– asynchronousUpdateObject:success:failure:noConnection:
-
– asynchronousDeleteObject:success:failure:noConnection:
-
– asynchronousFetchObjectsWithOptions:success:failure:noConnection:
Data Validation
-
– validateInsertForObject:
-
– validateUpdateForObject:
-
– validateDeleteForObject:
-
– validateOrderChangeForObject:
Data Management
Internal Properties & Methods (should only be used by the framework or when subclassing)
Properties
defaultDataDefinition
The data store’s default data definition. To add more data definitions (other than the default one), use addDataDefinition:.
@property (nonatomic, strong) SCDataDefinition *defaultDataDefinition
Declared In
SCDataStore.h
defaultsDictionary
Should be used by subclasses to store any default values needed.
@property (nonatomic, strong) NSDictionary *defaultsDictionary
Declared In
SCDataStore.h
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.
@property (nonatomic, readwrite) SCStoreMode storeMode
Declared In
SCDataStore.h
Class Methods
storeWithDefaultDataDefinition:
Allocated and returns an initialized SCDataStore given a default SCDataDefinition of the data stored.
+ (instancetype)storeWithDefaultDataDefinition:(SCDataDefinition *)definition
Declared In
SCDataStore.h
Instance Methods
addDataDefinition:
Adds a definition to dataDefinitions.
- (void)addDataDefinition:(SCDataDefinition *)definition
Declared In
SCDataStore.h
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.
- (void)applicationWillEnterForeground
Declared In
SCDataStore.h
asynchronousDeleteObject:success:failure:noConnection:
Asynchronously deletes the given object from the data store.
- (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.
SCDataStoreDeleteSuccess_Block syntax: { // Your code here }
- failure_block
The code block called in case the object could not be deleted.
SCDataStoreFailure_Block syntax: ^(NSError *error) { // Your code here }
- noConnection_Block
The code block called in case no connection could be established to data store.
SCNoConnection_Block syntax: ^BOOL() { // Return YES to try operation again when connection is established, otherwise return NO to call failure_block }
Declared In
SCDataStore.h
asynchronousFetchObjectsWithOptions:success:failure:noConnection:
Asynchronously fetches objects from the data store that satisfy the given fetch options.
- (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.
SCDataStoreFetchSuccess_Block syntax: ^(NSArray *results) { // Your code here } Where ‘results’ is the fetched data array.
- failure_block
The code block called in case the data could not be fetched.
SCDataStoreFailure_Block syntax: ^(NSError *error) { // Your code here }
- noConnection_Block
The code block called in case no connection could be established to data store.
SCNoConnection_Block syntax: ^BOOL() { // Return YES to try operation again when connection is established, otherwise return NO to call failure_block }
See Also
Declared In
SCDataStore.h
asynchronousInsertObject:success:failure:noConnection:
Asynchronously inserts the given object into the data store.
- (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.
SCDataStoreInsertSuccess_Block syntax: { // Your code here }
- failure_block
The code block called in case the object could not be inserted.
SCDataStoreFailure_Block syntax: ^(NSError *error) { // Your code here }
- noConnection_Block
The code block called in case no connection could be established to data store.
SCNoConnection_Block syntax: ^BOOL() { // Return YES to try operation again when connection is established, otherwise return NO to call failure_block }
Declared In
SCDataStore.h
asynchronousUpdateObject:success:failure:noConnection:
Asynchronously updates the given object into the data store.
- (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.
SCDataStoreUpdateSuccess_Block syntax: { // Your code here }
- failure_block
The code block called in case the object could not be updated.
SCDataStoreFailure_Block syntax: ^(NSError *error) { // Your code here }
- noConnection_Block
The code block called in case no connection could be established to data store.
SCNoConnection_Block syntax: ^BOOL() { // Return YES to try operation again when connection is established, otherwise return NO to call failure_block }
Declared In
SCDataStore.h
bindStoreToPropertyName:forObject:withDefinition:
Binds the store to a property name that will be used to fetch all the store’s data.
- (void)bindStoreToPropertyName:(NSString *)propertyName forObject:(NSObject *)object withDefinition:(SCDataDefinition *)definition
Discussion
Should only be used by the framework all must be implemented by all subclasses.
Declared In
SCDataStore.h
changeOrderForObject:toOrder:subsetArray:
Changes the order of the given object to the specified order.
- (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.
Discussion
Note: Only applicable for data stores that maintain ordered object storage.
Declared In
SCDataStore.h
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.
- (void)commitData
Declared In
SCDataStore.h
createNewObject
Returns a newly allocated and initialized object based on the store’s default data definition.
- (NSObject *)createNewObject
Return Value
The newly created object.
Discussion
Warning: Any newly created objects should be later either added to the data store using insertObject:, or discarded using discardUninsertedObject:.
Declared In
SCDataStore.h
createNewObjectWithDefinition:
Returns a newly allocated and initialized object based on the given data definition.
- (NSObject *)createNewObjectWithDefinition:(SCDataDefinition *)definition
Parameters
- definition
The data definition that describes the object to be created.
Return Value
The newly created object.
Discussion
Warning: Any newly created objects should be later either added to the data store using insertObject:, or discarded using discardUninsertedObject:.
Declared In
SCDataStore.h
definitionForObject:
Returns the data definition for the given object.
- (SCDataDefinition *)definitionForObject:(NSObject *)object
Declared In
SCDataStore.h
deleteObject:
Deletes the given object from the data store.
- (BOOL)deleteObject:(NSObject *)object
Parameters
- object
The object to be deleted.
Return Value
Returns TRUE if successful.
Declared In
SCDataStore.h
discardUninsertedObject:
Discards the given uninserted object.
- (BOOL)discardUninsertedObject:(NSObject *)object
Parameters
- object
The uninserted newly created object to be discarded.
Return Value
Returns TRUE if successful.
Discussion
Any object created with createNewObject: or createNewObjectWithDefinition: and not later inserted to the store using insertObject: must be discarded using this method.
Declared In
SCDataStore.h
fetchObjectsWithOptions:
Fetches objects from the data store that satisfy the given fetch options.
- (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.
See Also
Declared In
SCDataStore.h
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.
- (void)forceDiscardAllUnaddedObjects
Declared In
SCDataStore.h
initWithDefaultDataDefinition:
Returns an initialized SCDataStore given a default SCDataDefinition of the data stored.
- (instancetype)initWithDefaultDataDefinition:(SCDataDefinition *)definition
Declared In
SCDataStore.h
insertObject:
Inserts the given object into the data store.
- (BOOL)insertObject:(NSObject *)object
Parameters
- object
The object to be inserted.
Return Value
Returns TRUE if successful.
Declared In
SCDataStore.h
insertObject:atOrder:
Inserts the given object into the data store at the specified order.
- (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.
Discussion
Note: Only applicable for data stores that maintain ordered object storage.
Declared In
SCDataStore.h
setValue:forPropertyName:inObject:
Sets the value for the given property name in the given object.
- (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.
Declared In
SCDataStore.h
stringValueForPropertyName:inObject:separateValuesUsingDelimiter:
Returns the string value for the given property name in the given object.
- (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.
Declared In
SCDataStore.h
updateObject:
Updates the given object in the data store.
- (BOOL)updateObject:(NSObject *)object
Parameters
- object
The object to be updated.
Return Value
Returns TRUE if successful.
Declared In
SCDataStore.h
validateDeleteForObject:
Returns TRUE if the given object can be deleted from the data store, otherwise returns FALSE.
- (BOOL)validateDeleteForObject:(NSObject *)object
Declared In
SCDataStore.h
validateInsertForObject:
Returns TRUE if the given object can be inserted into the data store, otherwise returns FALSE.
- (BOOL)validateInsertForObject:(NSObject *)object
Declared In
SCDataStore.h
validateOrderChangeForObject:
Returns TRUE if the order of the given object can be changed in the data store, otherwise returns FALSE.
- (BOOL)validateOrderChangeForObject:(NSObject *)object
Declared In
SCDataStore.h
validateUpdateForObject:
Returns TRUE if the given object can be updated into the data store, otherwise returns FALSE.
- (BOOL)validateUpdateForObject:(NSObject *)object
Declared In
SCDataStore.h
valueForPropertyName:inObject:
Returns the value for the given property name in the given object.
- (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.
Declared In
SCDataStore.h