Merge pull request #54 from inaka/v2

V2

.swiftlint.yml

@@ -0,0 +1,9 @@
+disabled_rules:
+  - force_cast
+  - force_try
+  - line_length
+  - todo
+  - trailing_whitespace
+  - statement_position
+  - valid_docs
+  - variable_name_min_length

CHANGELOG.md

@@ -0,0 +1,67 @@
+# Change Log
+
+All notable changes to this project will be documented in this file. `Jayme` adheres to [Semantic Versioning](http://semver.org/).
+
+---
+
+### 2.x Releases
+
+- `2.0.x` Releases - [2.0.0](#200)
+
+### 1.x Releases
+
+- `1.0.x` Releases - [1.0.1](#101) | [1.0.2](#102) | [1.0.3](#103) | [1.0.4](#104) 
+
+---
+
+## 2.0.0
+
+#### Repository related changes
+
+- `path` variable has been renamed to `name` in `Repository` protocol declaration. (Issue [#17](https://github.com/inaka/Jayme/issues/17))
+- `ServerRepository` has been renamed to `CRUDRepository`. (Issue [#19](https://github.com/inaka/Jayme/issues/19))
+- `PagedRepository` no longer conforms to `CRUDRepository` (ex `ServerRepository`); now it conforms directly to `Repository`. (Issue [#20](https://github.com/inaka/Jayme/issues/20))
+- `create(…)` and `update(…)` methods in `CRUDRepository` now return `Future<EntityType, JaymeError>` instead of `Future<Void, JaymeError>`, containing the created or updated entity. (Issue [#37](https://github.com/inaka/Jayme/issues/37))
+- Convenient parsing functions have been plucked out from `CRUDRepository` (ex `ServerRepository`) and put into new classes named `DataParser` and `EntityParser`.  (Issue [#20](https://github.com/inaka/Jayme/issues/20))
+
+#### Backend related changes
+
+- `ServerBackend` protocol has been renamed to `NSURLSessionBackend`. (Issue [#18](https://github.com/inaka/Jayme/issues/18))
+- `ServerBackendConfiguration` has been renamed to `NSURLSessionBackendConfiguration`. (Issue [#18](https://github.com/inaka/Jayme/issues/18))
+
+#### Entity related changes
+
+- `init?(dictionary)` has been replaced by `init(dictionary) throws` in `DictionaryInitializable` protocol. (Issue [#25](https://github.com/inaka/Jayme/issues/25))
+- `StringDictionary` typealias has been removed. (Issue [#28](https://github.com/inaka/Jayme/issues/28))
+- `Identifier` typealias has been removed. (Issue [#22](https://github.com/inaka/Jayme/issues/22))
+- `id` variable in `Identifiable` protocol no longer works with `Identifier`. Now it uses an associated type (`IdentifierType`) for that. (Issue [#22](https://github.com/inaka/Jayme/issues/22))
+
+#### Error handling related changes
+
+- `ServerBackendError` has been renamed to `JaymeError`. (Issue [#21](https://github.com/inaka/Jayme/issues/21))
+- `case BadURL` in `JaymeError` (ex `ServerBackendError`) has been renamed to `case BadRequest` and now it also covers a scenario where request parameters can't be parsed into a valid JSON object. (Issue [#49](https://github.com/inaka/Jayme/issues/49))
+
+#### Bug Fixes
+
+- `parameters` are now actually used in `NSURLSessionBackend` (ex `ServerBackend`). (Issue [#49](https://github.com/inaka/Jayme/issues/49))
+- `"Content-Type": "application/json"` header is no longer duplicated in requests. (Issue [#50](https://github.com/inaka/Jayme/issues/50))
+
+---
+
+## 1.0.4
+
+- Added support for custom logging function injection.
+- Fixed access level related issues.
+
+## 1.0.3
+
+- Lowered deployment target to `8.0` since `9.3` was unnecessary.
+
+## 1.0.2
+
+- Moved documentation assets into a separated folder.
+- Changed images references in README file; using absolute paths now in order to make them work in cocoapods documentation.
+
+## 1.0.1
+
+- Released on March 3rd, 2016.

Documentation/Jayme 2.0 Migration Guide.md

@@ -0,0 +1,50 @@
+# Jayme 2.0 Migration Guide
+
+**Jayme 2.0** is the latest major release of Jayme. As a major release, following Semantic Versioning conventions, 2.0 introduces several API-breaking changes that one should be aware of.
+
+This guide is provided in order to ease the transition of existing applications using Jayme 1.x to the latest APIs, as well as explain the design and structure of new and changed functionality.
+
+---
+
+### Automatically Suggested Changes
+
+There are some compiler migration mechanisms that have been implemented in Jayme 2.0 by leveraging the `@unavailable` attribute in a `Compatibility.swift` file.
+
+***For these changes you only have to follow the compiler suggestions and they should be applied automatically.***
+
+For instance:
+
+* `ServerRepository` has been renamed to `CRUDRepository`. 
+  * The compiler will automatically suggest the replacement of `ServerRepository` to `CRUDRepository`.
+
+---
+
+### Manual Changes
+
+However, there are some other changes that would have required overwhelming (if ever possible) mechanisms to be implemented in order to keep automatic suggestions from the compiler. In consequence, we decided not to implement them but to write them down here in a separated list.
+
+⚠️ ***Therefore, it's up to you to perform these changes manually.***
+
+They are listed below:
+
+- `path` variable has been renamed to `name` in `Repository` protocol declaration. (related issue: [#17](https://github.com/inaka/Jayme/issues/17))
+  - You have to change every `path` appearance in your Repositories by using `name` instead.
+- `init?(dictionary: StringDictionary)` has been replaced by `init(dictionary: [String: AnyObject]) throws`. (related issues: [#25](https://github.com/inaka/Jayme/issues/25), [#28](https://github.com/inaka/Jayme/issues/28))
+  - `StringDictionary` → `[String: AnyObject]` replacements should be suggested by the compiler.
+  - You have to manually replace your `init?` initializers for every class or struct that conforms to `DictionaryInitializable` by its throwable equivalent.
+  - You have to perform `{ throw JaymeError.ParsingError }` whenever you can't initialize a `DictionaryInitializable` object instead of performing `{ return nil }`.
+- `Identifier` typealias no longer exists. Now your entities define their own identifier type.  (related issue: [#22](https://github.com/inaka/Jayme/issues/22))
+
+  - You have to change every `Identifier` appearance and replace it by a concrete type you need to use (e.g. `String`, `Int`, or your own, as long as it conforms to `CustomStringConvertible`). This change should be suggested by the compiler.
+  - However, since by default `String` does not conform to `CustomStringConvertible`, you'd probably want to add this extension to your code: 
+    - `extension String: CustomStringConvertible { public var description: String { return self } }`
+- Convenient parsing functions under one of the extensions in `ServerRepository` (now `CRUDRepository`) have been moved into separated new classes called `DataParser` and `EntityParser`. If you were calling those functions somewhere in your code, you have to change their calls to use those parsers classes instead of your repository itself. (related issue: [#20](https://github.com/inaka/Jayme/issues/20))
+  - Possible replacements are:
+    - `self.parseDataAsArray(…)` → `DataParser().dictionariesFromData(…)`
+    - `self.parseDataAsDictionary(…)` → `DataParser().dictionaryFromData(…)`
+    - `self.parseEntitiesFromArray(…)` → `EntityParser().entitiesFromDictionaries(…)`
+    - `self.parseEntityFromDictionary(…)` → `EntityParser().entityFromDictionary(…)`
+
+---
+
+For further documentation regarding changes, check out the **[Change Log](../Changelog.md)**.

Example/Extensions.swift

@@ -0,0 +1,30 @@
+// JaymeExample
+// Extensions.swift
+//
+// Copyright (c) 2016 Inaka - http://inaka.net/
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal
+// in the Software without restriction, including without limitation the rights
+// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+// copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in
+// all copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+// THE SOFTWARE.
+
+import Foundation
+
+extension String: CustomStringConvertible {
+    public var description: String {
+        return self
+    }
+}

Example/Post.swift

@@ -24,34 +24,34 @@
 import Foundation
 
 struct Post: Identifiable {
-    let id: Identifier
-    let authorID: Identifier
+    let id: PostIdentifier
+    let authorID: String
     let title: String
     let abstract: String
     let date: NSDate
 }
 
 extension Post: DictionaryInitializable, DictionaryRepresentable {
 
-    init?(dictionary: StringDictionary) {
+    init(dictionary: [String: AnyObject]) throws {
         guard let
             id = dictionary["id"] as? String,
             authorID = dictionary["author_id"] as? String,
             title = dictionary["title"] as? String,
             abstract = dictionary["abstract"] as? String,
             dateString = dictionary["date"] as? String,
             date = dateString.toDate()
-            else { return nil }
-        self.id = id
+            else { throw JaymeError.ParsingError }
+        self.id = .Server(id)
         self.authorID = authorID
         self.title = title
         self.abstract = abstract
         self.date = date
     }
 
-    var dictionaryValue: StringDictionary {
+    var dictionaryValue: [String: AnyObject] {
         return [
-            "id": self.id,
+            "id": "\(self.id)",
             "author_id": self.authorID,
             "title": self.title,
             "abstract": self.abstract,

Example/PostIdentifier.swift

@@ -0,0 +1,41 @@
+// JaymeExample
+// PostIdentifier.swift
+//
+// Copyright (c) 2016 Inaka - http://inaka.net/
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal
+// in the Software without restriction, including without limitation the rights
+// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+// copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in
+// all copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+// THE SOFTWARE.
+
+import Foundation
+
+/// Enumeration for identifying a Post via either a local ID or a server-defined ID, and being able to distinguish which scenario it corresponds to.
+enum PostIdentifier {
+    case Local(String)
+    case Server(String)
+}
+
+extension PostIdentifier: CustomStringConvertible {
+    var description: String {
+        switch self {
+        case .Local(let id):
+            return "local_\(id)"
+        case .Server(let id):
+            return id
+        }
+    }
+}

Example/PostRepository.swift

@@ -23,13 +23,13 @@
 
 import Foundation
 
-class PostRepository: ServerRepository {
+class PostRepository: CRUDRepository {
 
     typealias EntityType = Post
-    let backend = ServerBackend()
-    let path = "posts"
+    let backend = NSURLSessionBackend()
+    let name = "posts"
 
-    func findPostsForUser(user: User) -> Future<[Post], ServerBackendError> {
+    func findPostsForUser(user: User) -> Future<[Post], JaymeError> {
         return self.findAll().map {
             $0.filter { $0.authorID == user.id }
         }

Example/User.swift

@@ -24,25 +24,25 @@
 import Foundation
 
 struct User: Identifiable {
-    let id: Identifier
+    let id: String
     let name: String
     let email: String
 }
 
 extension User: DictionaryInitializable, DictionaryRepresentable {
 
-    init?(dictionary: StringDictionary) {
+    init(dictionary: [String: AnyObject]) throws {
         guard let
             id = dictionary["id"] as? String,
             name = dictionary["name"] as? String,
             email = dictionary["email"] as? String
-            else { return nil }
+            else { throw JaymeError.ParsingError }
         self.id = id
         self.name = name
         self.email = email
     }
 
-    var dictionaryValue: StringDictionary {
+    var dictionaryValue: [String: AnyObject] {
         return [
             "id": self.id,
             "name": self.name,

Example/UserDetailViewController.swift

@@ -53,14 +53,14 @@ class UserDetailViewController: UIViewController {
         }
     }
 
-    private func showAlertControllerForError(error: ServerBackendError) {
+    private func showAlertControllerForError(error: JaymeError) {
         let message = self.descriptionForError(error)
         let alert = UIAlertController(title: "Error", message: message, preferredStyle: .Alert)
         alert.addAction(UIAlertAction(title: "OK", style: .Default, handler: nil))
         self.presentViewController(alert, animated: true, completion: nil)
     }
 
-    private func descriptionForError(error: ServerBackendError) -> String {
+    private func descriptionForError(error: JaymeError) -> String {
         switch error {
         case .ServerError(let code):
             return "Server Error (code: \(code))"

Example/UserRepository.swift

@@ -23,10 +23,10 @@
 
 import Foundation
 
-class UserRepository: ServerRepository {
+class UserRepository: CRUDRepository {
 
     typealias EntityType = User
-    let backend = ServerBackend()
-    let path = "users"
+    let backend = NSURLSessionBackend()
+    let name = "users"
 
 }

Example/UsersViewController.swift

@@ -55,14 +55,14 @@ class UsersViewController: UIViewController {
         }
     }
 
-    private func showAlertControllerForError(error: ServerBackendError) {
+    private func showAlertControllerForError(error: JaymeError) {
         let message = self.descriptionForError(error)
         let alert = UIAlertController(title: "Error", message: message, preferredStyle: .Alert)
         alert.addAction(UIAlertAction(title: "OK", style: .Default, handler: nil))
         self.presentViewController(alert, animated: true, completion: nil)
     }
 
-    private func descriptionForError(error: ServerBackendError) -> String {
+    private func descriptionForError(error: JaymeError) -> String {
         switch error {
         case .ServerError(let code):
             return "Server Error (code: \(code))"

Jayme.podspec

@@ -1,10 +1,10 @@
 
 Pod::Spec.new do |s|
   s.name         = "Jayme"
-  s.version      = "1.0.4"
+  s.version      = "2.0.0"
   s.summary      = "Abstraction layer that eases RESTful interconnections in Swift"
   s.description  = <<-DESC
-                   What's the best place to put your entities business logic code? What's the best place to put your networking code? Jayme answers those two existencial questions by defining a straightforward and extendable architecture based on Repositories and Backends. It provides a neat API for dealing with REST communication, leaving your ViewControllers out of that business by abstracting all that logic, thereby allowing them to focus on what they should do rather on how they should connect to services.
+                   What's the best place to put your entities business logic code? What's the best place to put your networking code? Jayme answers those two existencial questions by defining a straightforward and extendable architecture based on Repositories and Backends. It provides a neat API to deal with REST communication, leaving your ViewControllers out of that business by abstracting all that logic, thereby allowing them to focus on what they should do rather than on how they should connect to services.
                    DESC
 
   s.homepage     = "https://github.com/inaka/Jayme/tree/master"