//
|
// OBSMTLModel+NSCoding.h
|
// Mantle
|
//
|
// Created by Justin Spahr-Summers on 2013-02-12.
|
// Copyright (c) 2013 GitHub. All rights reserved.
|
//
|
#import "OBSMTLModel.h"
|
|
/// Defines how a OBSMTLModel property key should be encoded into an archive.
|
///
|
/// OBSMTLModelEncodingBehaviorExcluded - The property should never be encoded.
|
/// OBSMTLModelEncodingBehaviorUnconditional - The property should always be
|
/// encoded.
|
/// OBSMTLModelEncodingBehaviorConditional - The object should be encoded only
|
/// if unconditionally encoded elsewhere.
|
/// This should only be used for object
|
/// properties.
|
typedef enum : NSUInteger {
|
OBSMTLModelEncodingBehaviorExcluded = 0,
|
OBSMTLModelEncodingBehaviorUnconditional,
|
OBSMTLModelEncodingBehaviorConditional,
|
} OBSMTLModelEncodingBehavior;
|
|
/// Implements default archiving and unarchiving behaviors for OBSMTLModel.
|
@interface OBSMTLModel (NSCoding) <NSCoding>
|
|
/// Initializes the receiver from an archive.
|
///
|
/// This will decode the original +modelVersion of the archived object, then
|
/// invoke -decodeValueForKey:withCoder:modelVersion: for each of the receiver's
|
/// +propertyKeys.
|
///
|
/// Returns an initialized model object, or nil if a decoding error occurred.
|
- (id)initWithCoder:(NSCoder *)coder;
|
|
/// Archives the receiver using the given coder.
|
///
|
/// This will encode the receiver's +modelVersion, then the receiver's properties
|
/// according to the behaviors specified in +encodingBehaviorsByPropertyKey.
|
- (void)encodeWithCoder:(NSCoder *)coder;
|
|
/// Determines how the +propertyKeys of the class are encoded into an archive.
|
/// The values of this dictionary should be boxed OBSMTLModelEncodingBehavior
|
/// values.
|
///
|
/// Any keys not present in the dictionary will be excluded from the archive.
|
///
|
/// Subclasses overriding this method should combine their values with those of
|
/// `super`.
|
///
|
/// Returns a dictionary mapping the receiver's +propertyKeys to default encoding
|
/// behaviors. If a property is an object with `weak` semantics, the default
|
/// behavior is OBSMTLModelEncodingBehaviorConditional; otherwise, the default is
|
/// OBSMTLModelEncodingBehaviorUnconditional.
|
+ (NSDictionary *)encodingBehaviorsByPropertyKey;
|
|
/// Determines the classes that are allowed to be decoded for each of the
|
/// receiver's properties when using <NSSecureCoding>. The values of this
|
/// dictionary should be NSArrays of Class objects.
|
///
|
/// If any encodable keys (as determined by +encodingBehaviorsByPropertyKey) are
|
/// not present in the dictionary, an exception will be thrown during secure
|
/// encoding or decoding.
|
///
|
/// Subclasses overriding this method should combine their values with those of
|
/// `super`.
|
///
|
/// Returns a dictionary mapping the receiver's encodable keys (as determined by
|
/// +encodingBehaviorsByPropertyKey) to default allowed classes, based on the
|
/// type that each property is declared as. If type of an encodable property
|
/// cannot be determined (e.g., it is declared as `id`), it will be omitted from
|
/// the dictionary, and subclasses must provide a valid value to prevent an
|
/// exception being thrown during encoding/decoding.
|
+ (NSDictionary *)allowedSecureCodingClassesByPropertyKey;
|
|
/// Decodes the value of the given property key from an archive.
|
///
|
/// By default, this method looks for a `-decode<Key>WithCoder:modelVersion:`
|
/// method on the receiver, and invokes it if found.
|
///
|
/// If the custom method is not implemented and `coder` does not require secure
|
/// coding, `-[NSCoder decodeObjectForKey:]` will be invoked with the given
|
/// `key`.
|
///
|
/// If the custom method is not implemented and `coder` requires secure coding,
|
/// `-[NSCoder decodeObjectOfClasses:forKey:]` will be invoked with the
|
/// information from +allowedSecureCodingClassesByPropertyKey and the given `key`. The
|
/// receiver must conform to <NSSecureCoding> for this to work correctly.
|
///
|
/// key - The property key to decode the value for. This argument cannot
|
/// be nil.
|
/// coder - The NSCoder representing the archive being decoded. This
|
/// argument cannot be nil.
|
/// modelVersion - The version of the original model object that was encoded.
|
///
|
/// Returns the decoded and boxed value, or nil if the key was not present.
|
- (id)decodeValueForKey:(NSString *)key withCoder:(NSCoder *)coder modelVersion:(NSUInteger)modelVersion;
|
|
/// The version of this OBSMTLModel subclass.
|
///
|
/// This version number is saved in archives so that later model changes can be
|
/// made backwards-compatible with old versions.
|
///
|
/// Subclasses should override this method to return a higher version number
|
/// whenever a breaking change is made to the model.
|
///
|
/// Returns 0.
|
+ (NSUInteger)modelVersion;
|
|
@end
|
|
/// This method must be overridden to support archives created by older versions
|
/// of Mantle (before the `OBSMTLModel+NSCoding` interface existed).
|
@interface OBSMTLModel (OldArchiveSupport)
|
|
/// Converts an archived external representation to a dictionary suitable for
|
/// passing to -initWithDictionary:.
|
///
|
/// externalRepresentation - The decoded external representation of the receiver.
|
/// fromVersion - The model version at the time the external
|
/// representation was encoded.
|
///
|
/// Returns nil by default, indicating that conversion failed.
|
+ (NSDictionary *)dictionaryValueFromArchivedExternalRepresentation:(NSDictionary *)externalRepresentation version:(NSUInteger)fromVersion;
|
|
@end
|
