Design¶

Philosophies¶

Hydrant has some opinions that are reflected in its code base and design – some more strongly than others. Individually, they are useful, but as more of these are combined, they become greater than the sum of their parts.

Mapper¶

Let’s look at the mapper protocol which is the foundation to Hydrant’s design:

@protocol HYDMapper <NSObject>

- (id)objectFromSourceObject:(id)sourceObject error:(__autoreleasing HYDError **)error;
- (id<HYDMapper>)reverseMapper;

@end

Using this protocol plus object composition, provides a shared method for mappers to compose with each other.

Let’s break it down by method – along with their purposes and expectations:

- (id)objectFromSourceObject:(id)sourceObject error:(__autoreleasing HYDError **)error;

This method is where all the grunt work occurs. Here a new object is created from the source object. This also provides a method for returning errors that should conform to Hydrant’s error handling policies. This includes:

• Emitting fatal errors when mapping fails.
• Emitting non-fatal errors when an alternative mapping occurred.
• Including as much userInfo about the error (see constants).
• Returning nil if a fatal error occurs.

It is the responsibility of each mapper to avoid throwing exceptions. This matches Apple’s convention of exceptions in Objective-C, where they should be used to indicate programmer error.

For easy of discovery, many mappers will validate its construction instead of possibly raising exceptions on -[objectFromSourceObject:error:].

For Hydrant Mappers, any operation on the sourceObject should be treated defensively. Doing work on a sourceObject should never raise an exception. Even under ARC, memory leaks can occur when exceptions are caught since the underlying libraries may not support the -fobjc-arc-exceptions flag.

That being said, exceptions can be raised if the definition of the resulting object is improperly configured. For example, HYDObjectMapper will throw an exception if the destination object is missing a key that is specified by the Hydrant user. But whenever possible, produce these exceptions as early as possible (eg - on object construction time instead of when -[objectFromSourceObject:error:] is called).

The next method on HYDMapper are for compositions of mappers:

- (id<HYDAccessor>)destinationAccessor;

This method returns an accessor instance for parent mappers (mappers that hold this mapper). Accessors, which are described more in the later section, are an abstraction to how to read and write values from an object. In this case, the destinationAccessor is how the parent mapper should map the value. This method exists for syntactic reasons of the DSL.

Accessor¶

Some mappers use a smaller abstraction called accessors. Accessors describe how to set and get values. Surprisingly, they are larger than the Mapper protocol:

@protocol HYDAccessor <NSObject>

- (NSArray *)valuesFromSourceObject:(id)sourceObject error:(__autoreleasing HYDError **)error;
- (HYDError *)setValues:(NSArray *)values onObject:(id)destinationObject;
- (NSArray *)fieldNames;

@end

There are currently two implementations of accessors: HYDAccessKey and HYDAccessKeyPath which use KVC to set and get values off of objects.

The accessor protocol supports getting and setting multiple values at once. In fact, both built-in Hydrant accessors support parsing multiple values. Allowing mappers to process multiple values at once gives an opportunity to do value joining (eg - joining a “date” and “time” field into a “datetime” field).

The method -[fieldNames] exists only for debuggability – providing the developer enough contextual information to location the exact mapper that failed in a large composition of mappers. The values in this method is used by mappers to populate Hydrant errors.

Mapping Data Structure¶

Various mappers built on top of HYDMapKVCObject utilize an informal data structure based format for describing field-to-field mapping which follows the form of:

@{<HYDAccessor>: <HYDMapping>}

Where’s HYDMapping? It’s just a tuple, which is fancy for saying an array:

@[<HYDMapper>, <HYDAccessor>]

So in summary, mapping dictionaries are just:

@{<HYDAccessor1>: @[<HYDMapper>, <HYDAccessor2>]}

Which reads, map <HYDAccessor1> to <HYDAccessor2> using <HYDMapper>.

To get this mapping into this form, it is first normalized by:

• Converting all keys that are strings into HYDAccessKeyPaths.
• Converting all keys that are arrays into HYDAccessKeyPaths with an array.
• Converting all values that are strings into a mapping of HYDMapIdentity and HYDKeyPathAccessors.
• Converting all values that are arrays into a mapping of HYDMapIdentity and HYDKeyPathAccessors.

And that’s it! Anything else specific must be done explicitly using the array-styled syntax. If you so choose, you can use your own tuple-like object for the HYDMapping protocol.

How do you have function overloading without being Objective-C++?¶

Hydrant makes use of a little known Clang-specific feature:

__attribute__((overloadable))

This overloadable attribute allows basic C++ overloaded functions with some notable exceptions:

- It cannot overload with a zero-arity function.
- Protocols are not part of the type dispatch -- so you cannot have two
  overloaded functions with different protocols

For convience, Hydrant uses the macro HYD_EXTERN_OVERLOADED to define these functions:

HYD_EXTERN_OVERLOADED
id<HYDMapper> MyMapper(NSString *foo);

Since the custom attribute changes the compiled function name, adding the overloadable attribute to an existing will break existing consumers. For iOS, this is not usually a problem since recompilation is required for static libraries. But for dynamic OSX libraries, this can be problematic.

Trade-offs¶

Every design and implementation has trade-offs. Anyone who tells you otherwise is not giving the entire picture. Hydrant is no exception:

• It is slower than naive parsing, because it’s doing more validation checks
• It is design for parsing data that you do not control, if you control the JSON API, it might not be necessary to use Hydrant
• It provides no other features other serialization/deserialization, such as value objects, persistence, networking, etc.