No Description

AWSMTLJSONAdapter.h 7.0KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172
  1. //
  2. // MTLJSONAdapter.h
  3. // Mantle
  4. //
  5. // Created by Justin Spahr-Summers on 2013-02-12.
  6. // Copyright (c) 2013 GitHub. All rights reserved.
  7. //
  8. #import <Foundation/Foundation.h>
  9. @class AWSMTLModel;
  10. // A MTLModel object that supports being parsed from and serialized to JSON.
  11. @protocol AWSMTLJSONSerializing
  12. @required
  13. // Specifies how to map property keys to different key paths in JSON.
  14. //
  15. // Subclasses overriding this method should combine their values with those of
  16. // `super`.
  17. //
  18. // Any property keys not present in the dictionary are assumed to match the JSON
  19. // key that should be used. Any keys associated with NSNull will not participate
  20. // in JSON serialization.
  21. //
  22. // Returns a dictionary mapping property keys to JSON key paths (as strings) or
  23. // NSNull values.
  24. + (NSDictionary *)JSONKeyPathsByPropertyKey;
  25. @optional
  26. // Specifies how to convert a JSON value to the given property key. If
  27. // reversible, the transformer will also be used to convert the property value
  28. // back to JSON.
  29. //
  30. // If the receiver implements a `+<key>JSONTransformer` method, MTLJSONAdapter
  31. // will use the result of that method instead.
  32. //
  33. // Returns a value transformer, or nil if no transformation should be performed.
  34. + (NSValueTransformer *)JSONTransformerForKey:(NSString *)key;
  35. // Overridden to parse the receiver as a different class, based on information
  36. // in the provided dictionary.
  37. //
  38. // This is mostly useful for class clusters, where the abstract base class would
  39. // be passed into -[MTLJSONAdapter initWithJSONDictionary:modelClass:], but
  40. // a subclass should be instantiated instead.
  41. //
  42. // JSONDictionary - The JSON dictionary that will be parsed.
  43. //
  44. // Returns the class that should be parsed (which may be the receiver), or nil
  45. // to abort parsing (e.g., if the data is invalid).
  46. + (Class)classForParsingJSONDictionary:(NSDictionary *)JSONDictionary;
  47. @end
  48. // The domain for errors originating from MTLJSONAdapter.
  49. extern NSString * const AWSMTLJSONAdapterErrorDomain;
  50. // +classForParsingJSONDictionary: returned nil for the given dictionary.
  51. extern const NSInteger AWSMTLJSONAdapterErrorNoClassFound;
  52. // The provided JSONDictionary is not valid.
  53. extern const NSInteger AWSMTLJSONAdapterErrorInvalidJSONDictionary;
  54. // The model's implementation of +JSONKeyPathsByPropertyKey included a key which
  55. // does not actually exist in +propertyKeys.
  56. extern const NSInteger AWSMTLJSONAdapterErrorInvalidJSONMapping;
  57. // Converts a MTLModel object to and from a JSON dictionary.
  58. @interface AWSMTLJSONAdapter : NSObject
  59. // The model object that the receiver was initialized with, or that the receiver
  60. // parsed from a JSON dictionary.
  61. @property (nonatomic, strong, readonly) AWSMTLModel<AWSMTLJSONSerializing> *model;
  62. // Attempts to parse a JSON dictionary into a model object.
  63. //
  64. // modelClass - The MTLModel subclass to attempt to parse from the JSON.
  65. // This class must conform to <MTLJSONSerializing>. This
  66. // argument must not be nil.
  67. // JSONDictionary - A dictionary representing JSON data. This should match the
  68. // format returned by NSJSONSerialization. If this argument is
  69. // nil, the method returns nil.
  70. // error - If not NULL, this may be set to an error that occurs during
  71. // parsing or initializing an instance of `modelClass`.
  72. //
  73. // Returns an instance of `modelClass` upon success, or nil if a parsing error
  74. // occurred.
  75. + (id)modelOfClass:(Class)modelClass fromJSONDictionary:(NSDictionary *)JSONDictionary error:(NSError **)error;
  76. // Attempts to parse an array of JSON dictionary objects into a model objects
  77. // of a specific class.
  78. //
  79. // modelClass - The MTLModel subclass to attempt to parse from the JSON. This
  80. // class must conform to <MTLJSONSerializing>. This argument must
  81. // not be nil.
  82. // JSONArray - A array of dictionaries representing JSON data. This should
  83. // match the format returned by NSJSONSerialization. If this
  84. // argument is nil, the method returns nil.
  85. // error - If not NULL, this may be set to an error that occurs during
  86. // parsing or initializing an any of the instances of
  87. // `modelClass`.
  88. //
  89. // Returns an array of `modelClass` instances upon success, or nil if a parsing
  90. // error occurred.
  91. + (NSArray *)modelsOfClass:(Class)modelClass fromJSONArray:(NSArray *)JSONArray error:(NSError **)error;
  92. // Converts a model into a JSON representation.
  93. //
  94. // model - The model to use for JSON serialization. This argument must not be
  95. // nil.
  96. //
  97. // Returns a JSON dictionary, or nil if a serialization error occurred.
  98. + (NSDictionary *)JSONDictionaryFromModel:(AWSMTLModel<AWSMTLJSONSerializing> *)model;
  99. // Converts a array of models into a JSON representation.
  100. //
  101. // models - The array of models to use for JSON serialization. This argument
  102. // must not be nil.
  103. //
  104. // Returns a JSON array, or nil if a serialization error occurred for any
  105. // model.
  106. + (NSArray *)JSONArrayFromModels:(NSArray *)models;
  107. // Initializes the receiver by attempting to parse a JSON dictionary into
  108. // a model object.
  109. //
  110. // JSONDictionary - A dictionary representing JSON data. This should match the
  111. // format returned by NSJSONSerialization. If this argument is
  112. // nil, the method returns nil and an error with code
  113. // MTLJSONAdapterErrorInvalidJSONDictionary.
  114. // modelClass - The MTLModel subclass to attempt to parse from the JSON.
  115. // This class must conform to <MTLJSONSerializing>. This
  116. // argument must not be nil.
  117. // error - If not NULL, this may be set to an error that occurs during
  118. // parsing or initializing an instance of `modelClass`.
  119. //
  120. // Returns an initialized adapter upon success, or nil if a parsing error
  121. // occurred.
  122. - (id)initWithJSONDictionary:(NSDictionary *)JSONDictionary modelClass:(Class)modelClass error:(NSError **)error;
  123. // Initializes the receiver with an existing model.
  124. //
  125. // model - The model to use for JSON serialization. This argument must not be
  126. // nil.
  127. - (id)initWithModel:(AWSMTLModel<AWSMTLJSONSerializing> *)model;
  128. // Serializes the receiver's `model` into JSON.
  129. //
  130. // Returns a JSON dictionary, or nil if a serialization error occurred.
  131. - (NSDictionary *)JSONDictionary;
  132. // Looks up the JSON key path in the model's +propertyKeys.
  133. //
  134. // Subclasses may override this method to customize the adapter's seralizing
  135. // behavior. You should not call this method directly.
  136. //
  137. // key - The property key to retrieve the corresponding JSON key path for. This
  138. // argument must not be nil.
  139. //
  140. // Returns a key path to use, or nil to omit the property from JSON.
  141. - (NSString *)JSONKeyPathForPropertyKey:(NSString *)key;
  142. @end
  143. @interface AWSMTLJSONAdapter (Deprecated)
  144. + (id)modelOfClass:(Class)modelClass fromJSONDictionary:(NSDictionary *)JSONDictionary __attribute__((deprecated("Replaced by +modelOfClass:fromJSONDictionary:error:")));
  145. - (id)initWithJSONDictionary:(NSDictionary *)JSONDictionary modelClass:(Class)modelClass __attribute__((deprecated("Replaced by -initWithJSONDictionary:modelClass:error:")));
  146. @end