mirror of
https://github.com/zhigang1992/RestKit.git
synced 2026-04-02 17:57:22 +08:00
233 lines
8.9 KiB
Objective-C
233 lines
8.9 KiB
Objective-C
//
|
|
// RKURL.h
|
|
// RestKit
|
|
//
|
|
// Created by Jeff Arena on 10/18/10.
|
|
// Copyright (c) 2009-2012 RestKit. All rights reserved.
|
|
//
|
|
// Licensed under the Apache License, Version 2.0 (the "License");
|
|
// you may not use this file except in compliance with the License.
|
|
// You may obtain a copy of the License at
|
|
//
|
|
// http://www.apache.org/licenses/LICENSE-2.0
|
|
//
|
|
// Unless required by applicable law or agreed to in writing, software
|
|
// distributed under the License is distributed on an "AS IS" BASIS,
|
|
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
// See the License for the specific language governing permissions and
|
|
// limitations under the License.
|
|
//
|
|
|
|
/**
|
|
RKURL extends the Cocoa NSURL base class to provide support for the concepts of
|
|
base URL and resource path that are used extensively throughout the RestKit
|
|
framework. RKURL is immutable, but provides numerous methods for constructing
|
|
new RKURL instances where the received becomes the baseURL of the RKURL
|
|
instance.
|
|
|
|
Instances of RKURL are aware of:
|
|
|
|
- the baseURL they were constructed against, if any
|
|
- the resource path that was appended to that baseURL
|
|
- any query parameters present in the URL
|
|
|
|
### Example
|
|
|
|
NSDictionary *queryParams;
|
|
queryParams = [NSDictionary dictionaryWithObjectsAndKeys:@"pitbull", @"username",
|
|
@"pickles", @"password", nil];
|
|
|
|
RKURL *URL = [RKURL URLWithBaseURLString:@"http://restkit.org"
|
|
resourcePath:@"/test"
|
|
queryParameters:queryParams];
|
|
*/
|
|
@interface RKURL : NSURL
|
|
|
|
///-----------------------------------------------------------------------------
|
|
/// @name Creating an RKURL
|
|
///-----------------------------------------------------------------------------
|
|
|
|
/**
|
|
Creates and returns an RKURL object intialized with a provided base URL.
|
|
|
|
@param baseURL The URL object with which to initialize the RKURL object.
|
|
@return An RKURL object initialized with baseURL.
|
|
*/
|
|
+ (id)URLWithBaseURL:(NSURL *)baseURL;
|
|
|
|
/**
|
|
Creates and returns an RKURL object intialized with a provided base URL and
|
|
resource path.
|
|
|
|
@param baseURL The URL object with which to initialize the RKURL object.
|
|
@param resourcePath The resource path for the RKURL object.
|
|
@return An RKURL object initialized with baseURL and resourcePath.
|
|
*/
|
|
+ (id)URLWithBaseURL:(NSURL *)baseURL resourcePath:(NSString *)resourcePath;
|
|
|
|
/**
|
|
Creates and returns an RKURL object intialized with a provided base URL,
|
|
resource path, and a dictionary of query parameters.
|
|
|
|
@param baseURL The URL object with which to initialize the RKURL object.
|
|
@param resourcePath The resource path for the RKURL object.
|
|
@param queryParameters The query parameters for the RKURL object.
|
|
@return An RKURL object initialized with baseURL, resourcePath, and
|
|
queryParameters.
|
|
*/
|
|
+ (id)URLWithBaseURL:(NSURL *)baseURL resourcePath:(NSString *)resourcePath queryParameters:(NSDictionary *)queryParameters;
|
|
|
|
/**
|
|
Creates and returns an RKURL object intialized with a base URL constructed from
|
|
the specified base URL string.
|
|
|
|
@param baseURLString The string with which to initialize the RKURL object.
|
|
@return An RKURL object initialized with baseURLString.
|
|
*/
|
|
+ (id)URLWithBaseURLString:(NSString *)baseURLString;
|
|
|
|
/**
|
|
Creates and returns an RKURL object intialized with a base URL constructed from
|
|
the specified base URL string and resource path.
|
|
|
|
@param baseURLString The string with which to initialize the RKURL object.
|
|
@param resourcePath The resource path for the RKURL object.
|
|
@return An RKURL object initialized with baseURLString and resourcePath.
|
|
*/
|
|
+ (id)URLWithBaseURLString:(NSString *)baseURLString resourcePath:(NSString *)resourcePath;
|
|
|
|
/**
|
|
Creates and returns an RKURL object intialized with a base URL constructed from
|
|
the specified base URL string, resource path and a dictionary of query
|
|
parameters.
|
|
|
|
@param baseURLString The string with which to initialize the RKURL object.
|
|
@param resourcePath The resource path for the RKURL object.
|
|
@param queryParameters The query parameters for the RKURL object.
|
|
@return An RKURL object initialized with baseURLString, resourcePath and
|
|
queryParameters.
|
|
*/
|
|
+ (id)URLWithBaseURLString:(NSString *)baseURLString resourcePath:(NSString *)resourcePath queryParameters:(NSDictionary *)queryParameters;
|
|
|
|
/**
|
|
Initializes an RKURL object with a base URL, a resource path string, and a
|
|
dictionary of query parameters.
|
|
|
|
`initWithBaseURL:resourcePath:queryParameters:` is the designated initializer.
|
|
|
|
@param theBaseURL The NSURL with which to initialize the RKURL object.
|
|
@param theResourcePath The resource path for the RKURL object.
|
|
@param theQueryParameters The query parameters for the RKURL object.
|
|
@return An RKURL object initialized with baseURL, resourcePath and queryParameters.
|
|
*/
|
|
- (id)initWithBaseURL:(NSURL *)theBaseURL resourcePath:(NSString *)theResourcePath queryParameters:(NSDictionary *)theQueryParameters;
|
|
|
|
|
|
///-----------------------------------------------------------------------------
|
|
/// @name Accessing the URL parts
|
|
///-----------------------------------------------------------------------------
|
|
|
|
/**
|
|
Returns the base URL of the receiver.
|
|
|
|
The base URL includes everything up to the resource path, typically the portion
|
|
that is repeated in every API call.
|
|
*/
|
|
@property (nonatomic, copy, readonly) NSURL *baseURL;
|
|
|
|
/**
|
|
Returns the resource path of the receiver.
|
|
|
|
The resource path is the path portion of the complete URL beyond that contained
|
|
in the baseURL.
|
|
*/
|
|
@property (nonatomic, copy, readonly) NSString *resourcePath;
|
|
|
|
/**
|
|
Returns the query component of a URL conforming to RFC 1808 as a dictionary.
|
|
|
|
If the receiver does not conform to RFC 1808, returns nil just as
|
|
`NSURL query` does.
|
|
*/
|
|
@property (nonatomic, readonly) NSDictionary *queryParameters;
|
|
|
|
|
|
///-----------------------------------------------------------------------------
|
|
/// @name Modifying the URL
|
|
///-----------------------------------------------------------------------------
|
|
|
|
/**
|
|
Returns a new RKURL object with a new resource path appended to its path.
|
|
|
|
@param theResourcePath The resource path to append to the receiver's path.
|
|
@return A new RKURL that refers to a new resource at theResourcePath.
|
|
*/
|
|
- (RKURL *)URLByAppendingResourcePath:(NSString *)theResourcePath;
|
|
|
|
/**
|
|
Returns a new RKURL object with a new resource path appended to its path and a
|
|
dictionary of query parameters merged with the existing query component.
|
|
|
|
@param theResourcePath The resource path to append to the receiver's path.
|
|
@param theQueryParameters A dictionary of query parameters to merge with any
|
|
existing query parameters.
|
|
@return A new RKURL that refers to a new resource at theResourcePath with a new
|
|
query component including the values from theQueryParameters.
|
|
*/
|
|
- (RKURL *)URLByAppendingResourcePath:(NSString *)theResourcePath queryParameters:(NSDictionary *)theQueryParameters;
|
|
|
|
/**
|
|
Returns a new RKURL object with a dictionary of query parameters merged with
|
|
the existing query component.
|
|
|
|
@param theQueryParameters A dictionary of query parameters to merge with any
|
|
existing query parameters.
|
|
@return A new RKURL that refers to the same resource as the receiver with a new
|
|
query component including the values from theQueryParameters.
|
|
*/
|
|
- (RKURL *)URLByAppendingQueryParameters:(NSDictionary *)theQueryParameters;
|
|
|
|
/**
|
|
Returns a new RKURL object with the baseURL of the receiver and a new
|
|
resourcePath.
|
|
|
|
@param newResourcePath The resource path to replace the value of resourcePath
|
|
in the new RKURL object.
|
|
@return An RKURL object with newResourcePath appended to the receiver's baseURL.
|
|
*/
|
|
- (RKURL *)URLByReplacingResourcePath:(NSString *)newResourcePath;
|
|
|
|
/**
|
|
Returns a new RKURL object with its resource path processed as a pattern and
|
|
evaluated against the specified object.
|
|
|
|
Resource paths may contain pattern strings prefixed by colons (":") that refer
|
|
to key-value coding accessible properties on the provided object.
|
|
|
|
For example:
|
|
|
|
// Given an RKURL initialized as:
|
|
RKURL *myURL = [RKURL URLWithBaseURLString:@"http://restkit.org"
|
|
resourcePath:@"/paginate?per_page=:perPage&page=:page"];
|
|
|
|
// And a dictionary containing values:
|
|
NSDictionary *dictionary = [NSDictionary dictionaryWithObjectsAndKeys:@"25", @"perPage",
|
|
@"5", @"page", nil];
|
|
|
|
// A new RKURL can be constructed by interpolating the dictionary with the original URL
|
|
RKURL *interpolatedURL = [myURL URLByInterpolatingResourcePathWithObject:dictionary];
|
|
|
|
The absoluteString of this new URL would be:
|
|
`http://restkit.org/paginate?per_page=25&page=5`
|
|
|
|
@see RKPathMatcher
|
|
|
|
@param object The object to call methods on for the pattern strings in the
|
|
resource path.
|
|
@return A new RKURL object with its resource path evaluated as a pattern and
|
|
interpolated with properties of object.
|
|
*/
|
|
- (RKURL *)URLByInterpolatingResourcePathWithObject:(id)object;
|
|
|
|
@end
|