From 42adebc9c39fbaf03e3502ba00386a53bf389745 Mon Sep 17 00:00:00 2001 From: nayanda Date: Wed, 28 Oct 2020 13:15:05 +0700 Subject: [PATCH] Added Comment for Thenable Object --- .../Classes/Thenable/DataRequestPromise.swift | 14 +++++++++ .../Thenable/DownloadRequestPromise.swift | 11 +++++++ iONess/Classes/Thenable/Thenable.swift | 19 ++++++++++++ .../Classes/Thenable/URLRequestPromise.swift | 24 ++++++++++++++- .../Classes/Thenable/URLThenableRequest.swift | 29 +++++++++++++++++++ .../Thenable/UploadRequestPromise.swift | 17 +++++++++-- 6 files changed, 110 insertions(+), 4 deletions(-) diff --git a/iONess/Classes/Thenable/DataRequestPromise.swift b/iONess/Classes/Thenable/DataRequestPromise.swift index 6249fc7..2198f87 100644 --- a/iONess/Classes/Thenable/DataRequestPromise.swift +++ b/iONess/Classes/Thenable/DataRequestPromise.swift @@ -7,8 +7,22 @@ import Foundation +/// Thenable HTTPRequest for get response data open class DataRequestPromise: HTTPRequestPromise { + /// Default Init + /// - Parameters: + /// - request: HTTPRequestMessage object which describe the request + /// - networkSessionManager: NetworkSessionManager + /// - retryControl: RetryControl object + /// - Throws: Error when generating URLRequest from HTTPRequestMessage + public override init(request: HTTPRequestMessage, with networkSessionManager: NetworkSessionManager, retryControl: RetryControl?) throws { + try super.init(request: request, with: networkSessionManager, retryControl: retryControl) + } + + /// Method to run closure after the request is finished. + /// - Parameter closure: closure which will be run when the request is finished + /// - Returns: DropableURLRequest object @discardableResult open override func then(run closure: @escaping (URLResult) -> Void) -> DropableURLRequest { let dispatcher = self.dispatcher diff --git a/iONess/Classes/Thenable/DownloadRequestPromise.swift b/iONess/Classes/Thenable/DownloadRequestPromise.swift index d3f15a9..507d6fb 100644 --- a/iONess/Classes/Thenable/DownloadRequestPromise.swift +++ b/iONess/Classes/Thenable/DownloadRequestPromise.swift @@ -7,14 +7,25 @@ import Foundation +/// Thenable HTTPRequest for downloading data open class DownloadRequestPromise: HTTPRequestPromise { var targetUrl: URL + /// Default Init + /// - Parameters: + /// - request: HTTPRequestMessage object which describe the request + /// - networkSessionManager: NetworkSessionManager object + /// - retryControl: RetryControl object + /// - targetUrl: local URL file which data will be downloaded + /// - Throws: Error when generating URLRequest from HTTPRequestMessage public init(request: HTTPRequestMessage, with networkSessionManager: NetworkSessionManager, retryControl: RetryControl?, targetUrl: URL) throws { self.targetUrl = targetUrl try super.init(request: request, with: networkSessionManager, retryControl: retryControl) } + /// Method to run closure after the request is finished. + /// - Parameter closure: closure which will be run when the request is finished + /// - Returns: DropableURLRequest object @discardableResult open override func then(run closure: @escaping (DownloadResult) -> Void) -> DropableURLRequest { let dispatcher = self.dispatcher diff --git a/iONess/Classes/Thenable/Thenable.swift b/iONess/Classes/Thenable/Thenable.swift index 1ad3848..fd67804 100644 --- a/iONess/Classes/Thenable/Thenable.swift +++ b/iONess/Classes/Thenable/Thenable.swift @@ -7,21 +7,40 @@ import Foundation +/// Thenable protocol +/// This protocol are designed to run the thenable closure after doing some task which produced Result and Dropable object public protocol Thenable { associatedtype Result associatedtype DropablePromise: Dropable + /// Method to run task and then running closures passed + /// - Parameters: + /// - closure: closure which will be run when task succeed + /// - failClosure: closure which will be run when task fail @discardableResult func then(run closure: @escaping (Result) -> Void, whenFailed failClosure: @escaping (Result) -> Void) -> DropablePromise + /// Method to run task and then running closure passed + /// - Parameter closure: closure which will be run when task finished @discardableResult func then(run closure: @escaping (Result) -> Void) -> DropablePromise + /// Method to run task and then running closures passed + /// - Parameters: + /// - closure: closure which will be run when task succeed + /// - failClosure: closure which will be run when task fail + /// - deferClosure: closure which will be run after closure or failClosure @discardableResult func then(run closure: @escaping (Result) -> Void, whenFailed failClosure: @escaping (Result) -> Void, finally deferClosure: @escaping (Result) -> Void) -> DropablePromise } public extension Thenable { + /// Method to run task and then running closures passed + /// - Parameters: + /// - closure: closure which will be run when task succeed + /// - failClosure: closure which will be run when task fail + /// - deferClosure: closure which will be run after closure or failClosure + /// - Returns: DropablePromise object @discardableResult func then(run closure: @escaping (Result) -> Void, whenFailed failClosure: @escaping (Result) -> Void, finally deferClosure: @escaping (Result) -> Void) -> DropablePromise { then( diff --git a/iONess/Classes/Thenable/URLRequestPromise.swift b/iONess/Classes/Thenable/URLRequestPromise.swift index 706fe9e..b1e22c4 100644 --- a/iONess/Classes/Thenable/URLRequestPromise.swift +++ b/iONess/Classes/Thenable/URLRequestPromise.swift @@ -7,23 +7,38 @@ import Foundation +/// Base class for Thenable URLRequest open class URLRequestPromise: URLThenableRequest { + /// URLValidator which will validate result from URL Request public var urlValidator: URLValidator? + /// DispatchQueue which will run the completion closure public var dispatcher: DispatchQueue = .main + /// Default init + public init() { } + + /// Method to run closure after the request is finished. It should be overriden, otherwise it will throw fatalError + /// - Parameter closure: closure which will be run when the request is finished + /// - Returns: DropableURLRequest object @discardableResult open func then(run closure: @escaping (Result) -> Void) -> DropableURLRequest { fatalError("iONess Error: method did not overridden 'then(run closure: @escaping (URLResult) -> Void) -> DropableURLRequest'") } } +/// Thenable URLRequest which should be used as Thenable for URLRequest which already failed when prepared open class ErrorRequestPromise: URLRequestPromise { var error: Error - init(error: Error) { + /// Default Init + /// - Parameter error: Error on prepared + public init(error: Error) { self.error = error } + /// Method to run closure after the request is finished. It should automatically fail + /// - Parameter closure: Closure which will fail + /// - Returns: FailedURLRequest object @discardableResult open override func then(run closure: @escaping (Result) -> Void) -> DropableURLRequest { let error = self.error @@ -35,11 +50,18 @@ open class ErrorRequestPromise: UR } +/// Thenable HTTPRequest open class HTTPRequestPromise: URLRequestPromise { var urlRequest: URLRequest var networkSessionManager: NetworkSessionManager var retryControl: RetryControl? + /// Default Init + /// - Parameters: + /// - request: HTTPRequestMessage object which describe the request + /// - networkSessionManager: NetworkSessionManager + /// - retryControl: RetryControl object + /// - Throws: Error when generating URLRequest from HTTPRequestMessage public init(request: HTTPRequestMessage, with networkSessionManager: NetworkSessionManager, retryControl: RetryControl?) throws { let mutableRequest = try request.getFullUrl().asMutableRequest() for header in request.headers { diff --git a/iONess/Classes/Thenable/URLThenableRequest.swift b/iONess/Classes/Thenable/URLThenableRequest.swift index ddd307d..bef97b5 100644 --- a/iONess/Classes/Thenable/URLThenableRequest.swift +++ b/iONess/Classes/Thenable/URLThenableRequest.swift @@ -7,16 +7,25 @@ import Foundation +/// Thenable URL Request protocol public protocol URLThenableRequest: Thenable where DropablePromise: DropableURLRequest, Result: NetworkResult { associatedtype Response: URLResponse + /// URLValidator which will validate result from URL Request var urlValidator: URLValidator? { get set } + /// DispatchQueue which will run the completion closure var dispatcher: DispatchQueue { get set } + /// Method to execute and ignore any result @discardableResult func executeAndForget() -> DropableURLRequest } public extension URLThenableRequest { + /// Method to execute request and then run any closure passed + /// - Parameters: + /// - closure: Closure which will run when request succeed + /// - failClosure: Closure which will run when request fail + /// - Returns: DroppableURLRequest object @discardableResult func then(run closure: @escaping (Result) -> Void, whenFailed failClosure: @escaping (Result) -> Void) -> DropableURLRequest { return then { result in @@ -28,6 +37,8 @@ public extension URLThenableRequest { } } + /// Method to execute and ignore any result + /// - Returns: DroppableURLRequest object @discardableResult func executeAndForget() -> DropableURLRequest { then { _ in } @@ -36,6 +47,9 @@ public extension URLThenableRequest { public extension URLThenableRequest { + /// Method to set DispatchQueue where the completion will run + /// - Parameter dispatcher: DispatchQueue object + /// - Returns: URLThenableRequest which have custom DispatchQueue @discardableResult func completionDispatch(on dispatcher: DispatchQueue) -> Self { var requestWithDispatch = self @@ -43,21 +57,33 @@ public extension URLThenableRequest { return requestWithDispatch } + /// Method to add URLValidator which validate using status code + /// - Parameter statusCode: valid status code + /// - Returns: URLThenableRequest which have status code URLValidator combined with previous validator if have any @discardableResult func validate(statusCode: Int) -> Self { return validate(statusCodes: statusCode..) -> Self { validate(using: StatusCodeValidator(statusCodes)) } + /// Method to add URLValidator which validate result headers + /// - Parameter headers: valid result headers + /// - Returns: URLThenableRequest which have headers URLValidator combined with previous validator if have any @discardableResult func validate(shouldHaveHeaders headers: [String:String]) -> Self { validate(using: HeaderValidator(headers)) } + /// Method to add custom URLValidator + /// - Parameter validator: custom URLValidator + /// - Returns: URLThenableRequest which have custom URLValidator combined with previous validator if have any @discardableResult func validate(using validator: URLValidator) -> Self { var requestWithValidation = self @@ -71,6 +97,9 @@ public extension URLThenableRequest { } public extension URLThenableRequest { + /// Method to aggregate request with another request + /// - Parameter request: other request to aggregate + /// - Returns: RequestAggregator object func aggregate(with request: Self) -> RequestAggregator { RequestAggregator(requests: [self, request]) } diff --git a/iONess/Classes/Thenable/UploadRequestPromise.swift b/iONess/Classes/Thenable/UploadRequestPromise.swift index 8d9218c..16a4f26 100644 --- a/iONess/Classes/Thenable/UploadRequestPromise.swift +++ b/iONess/Classes/Thenable/UploadRequestPromise.swift @@ -7,14 +7,25 @@ import Foundation +/// Thenable HTTPRequest for uploading data open class UploadRequestPromise: HTTPRequestPromise { var fileURL: URL + /// Default init + /// - Parameters: + /// - request: HTTPRequestMessage object which describe the request + /// - networkSessionManager: NetworkSessionManager object + /// - retryControl: RetryControl object + /// - fileURL: local URL file which will be uploaded + /// - Throws: Error when generating URLRequest from HTTPRequestMessage public init(request: HTTPRequestMessage, with networkSessionManager: NetworkSessionManager, retryControl: RetryControl?, fileURL: URL) throws { self.fileURL = fileURL try super.init(request: request, with: networkSessionManager, retryControl: retryControl) } + /// Method to run closure after the request is finished. + /// - Parameter closure: closure which will be run when the request is finished + /// - Returns: DropableURLRequest object @discardableResult open override func then(run closure: @escaping (URLResult) -> Void) -> DropableURLRequest { let dispatcher = self.dispatcher @@ -24,9 +35,9 @@ open class UploadRequestPromise: HTTPRequestPromise { fileUrl: fileURL, retryControl: retryControl, urlValidator: urlValidator) { result in - dispatcher.async { - closure(result) - } + dispatcher.async { + closure(result) + } } } }