KV storage

Introduction

In many scenarios, Key-Value storage can meet the client-side storage requirements quite well. NSUserDefaults is often used, but it does not support encryption and is slow in data persistence.

The Key-Value storage of Datacenter provides interfaces for storing: PList objects of such data types as NSInteger, long long (the same as NSInteger in 64-bit environment), BOOL, double and NSString, objects supporting NSCoding, and Objective-C objects that can be converted to JSON objects through reflection, greatly reducing the complexity of persistent objects in the client.

For instructions on most of the interfaces of Key-Value storage, see the method description in the header file APSharedPreferences.h.

Store basic types of objects

Datacenter provides the following interfaces for storing the basic types of objects:

- (NSInteger)integerForKey:(NSString*)key business:(NSString*)business;
- (NSInteger)integerForKey:(NSString*)key business:(NSString*)business defaultValue:(NSInteger)defaultValue; // Return default value when the data don’t exist
- (void)setInteger:(NSInteger)value forKey:(NSString*)key business:(NSString*)business;

- (long long)longLongForKey:(NSString*)key business:(NSString*)business;
- (long long)longLongForKey:(NSString*)key business:(NSString*)business defaultValue:(long long)defaultValue; // Return default value when the data don’t exist
- (void)setLongLong:(long long)value forKey:(NSString*)key business:(NSString*)business;

- (BOOL)boolForKey:(NSString*)key business:(NSString*)business;
- (BOOL)boolForKey:(NSString*)key business:(NSString*)business defaultValue:(BOOL)defaultValue; // Return default value when the data don’t exist
- (void)setBool:(BOOL)value forKey:(NSString*)key business:(NSString*)business;

- (double)doubleForKey:(NSString*)key business:(NSString*)business;
- (double)doubleForKey:(NSString*)key business:(NSString*)business defaultValue:(double)defaultValue; // Return default value when the data don’t exist
- (void)setDouble:(double)value forKey:(NSString*)key business:(NSString*)business;

The parameter defaultValue is the default value returned when the data don’t exist.

Store Objective-C objects

Interface instruction

Datacenter provides the following interfaces for storing the Objective-C objects:

- (NSString*)stringForKey:(NSString*)key business:(NSString*)business;
- (NSString*)stringForKey:(NSString*)key business:(NSString*)business extension:(APDataCrypt*)extension;
- (void)setString:(NSString*)string forKey:(NSString*)key business:(NSString*)business;
- (void)setString:(NSString*)string forKey:(NSString*)key business:(NSString*)business extension:(APDataCrypt*)extension;

- (id)objectForKey:(NSString*)key business:(NSString*)business;
- (id)objectForKey:(NSString*)key business:(NSString*)business extension:(APDataCrypt*)extension;

- (void)setObject:(id)object forKey:(NSString*)key business:(NSString*)business;
- (void)setObject:(id)object forKey:(NSString*)key business:(NSString*)business extension:(APDataCrypt*)extension;
- (BOOL)setObject:(id)object forKey:(NSString*)key business:(NSString*)business extension:(APDataCrypt*)extension options:(APDataOptions)options;

- (void)archiveObject:(id)object forKey:(NSString*)key business:(NSString*)business;
- (void)archiveObject:(id)object forKey:(NSString*)key business:(NSString*)business extension:(APDataCrypt*)extension;
- (BOOL)archiveObject:(id)object forKey:(NSString*)key business:(NSString*)business extension:(APDataCrypt*)extension options:(APDataOptions)options;

- (void)saveJsonObject:(id)object forKey:(NSString*)key business:(NSString*)business;
- (void)saveJsonObject:(id)object forKey:(NSString*)key business:(NSString*)business extension:(APDataCrypt*)extension;
- (BOOL)saveJsonObject:(id)object forKey:(NSString*)key business:(NSString*)business extension:(APDataCrypt*)extension options:(APDataOptions)options;

setString & stringForKey

The setString and stringForKey interfaces are recommended for storing NSString objects as the names are more interpretative.

If the data are not encrypted, strings stored with those two interfaces can be viewed in Sqlite DB viewer in a more intuitive way. Strings stored with setObject method will be first converted to NSData through Property List and then saved to the database.

setObject

The setObject method is recommended for storing Property List objects to achieve the highest efficiency.

Property List objects: Property List objects: NSNumber, NSString, NSData, NSDate, NSArray, and NSDictionary. The sub objects in NSArray and NSDictionary must also be PList objects.

When the Property List objects are saved by using setObject, the objects acquired with objectForKey method is mutable. The savedArray acquired in the following codes is NSMutableArray.

NSArray* array = [[NSArray alloc] initWithObjects:@"str", nil];
[APCommonPreferences setObject:array forKey:@"array" business:@"biz"];

NSArray* savedArray = [APCommonPreferences objectForKey:@"array" business:@"biz"];

archiveObject

For the Objective-C objects supporting the NSCoding protocol, Datacenter calls the system’s NSKeyedArchiver convert the objects into NSData objects and persist them.

Property List objects can use this interface, too, but with a low efficiency and thus not recommended.

saveJsonObject

When an Objective-C object is neither a Property List object nor an NSCoding-supporting one, you can use this method to persist it.

Through runtime dynamic reflection, this method maps Objective-C objects to JSON strings. But not all the Objective-C objects can be saved with this method, such as Objective-C objects that have an property serving as C struct pointer, reference each other, or contain dictionaries or arrays in properties.

objectForKey

When Datacenter saves the data of Objective-C objects, it will record the archiving method as well. The objectForKey method is used for acquiring objects.

Encrypt data

Use default encrypt method

Interfaces with extension argument support encryption, and pass in APDataCrypt struct.

APDefaultEncrypt is the default encryption method using AES symmetric encryption.

APDefaultDecrypt is the default decryption method and share the key with APDefaultEncrypt.

In usual cases, you need only the default encryption method provided by Datacenter, shown as follows:

[APUserPreferences setObject:aObject forKey:@"key" business:@"biz" extension:APDefaultEncrypt()];

id obj = [APUserPreferences objectForKey:@"key" business:@"biz" extension:APDefaultDecrypt()];
// or
id obj = [APUserPreferences objectForKey:@"key" business:@"biz"];

As the default encryption is applied, the data-acquiring interfaces can skip the extension argument.

Use self-defined encryption method

If you have higher security requirements on encryption, you can implement the APDataCrypt struct with specified function pointers for encryption and decryption. Ensure that the encryption and decryption methods are matched to save and recover data correctly.

Encrypt objects of basic types

To encrypt and store BOOL, NSInteger, double, and long long objects, you can convert them into strings or put them into the NSNumber, and then call the setString or setObject interface.

Specify options

typedef NS_OPTIONS (unsigned int, APDataOptions)
{
    //These two options are used to identify data encryption attribute. Do not use them in the interfaces. Please use extension to pass the encryption method.
    APDataOptionDefaultEncrypted    = 1 << 0,       //Do not pass this option. It doesn’t work even if it is passed. The Datacenter determines encryption method according to extension in interface rather than options.
    APDataOptionCustomEncrypted     = 1 << 1,       //Do not pass this option. It doesn’t work even if it is passed. The Datacenter determines encryption method according to extension in interface rather than options.

    //Indicate that the data can be cleared upon cache cleaning. Here, 1 is casted to unsinged int, because some compilation options may not compute 1 << 31 as unsigned int and cause assignment failure.
    APDataOptionPurgeable           = (unsigned int)1 << 31,
};

You can specify options in methods setObject, archiveObject and saveJsonObject.

APDataOptionPurgeable indicates that the data can be automatically cleared upon data cleaning, see Data cleaning.