kylefang/RestKit
1
0
Fork 0
mirror of https://github.com/zhigang1992/RestKit.git synced 2026-04-24 04:46:01 +08:00
Code Issues Packages Projects Releases Wiki Activity

Router docs formatting

Browse Source
This commit is contained in:
Blake Watters
2012-09-12 09:22:21 -04:00
parent 0f2013d67b
commit f7527dc1d2
1 changed files with 31 additions and 34 deletions
Download Patch File Download Diff File Expand all files Collapse all files

65
Code/Network/RKRouter.h
View File

@@ -23,38 +23,21 @@
@class RKRouteSet;
/**
An RKRouter instance is responsible for generating RKURL objects with a given
base URL and a route set. It is used to centralize the knowledge about the URL's
that are used by the application.
An `RKRouter` instance is responsible for generating `NSURL` objects with a given base URL and a route set. It is used to centralize the knowledge about the URL's that are used by the application.
URL's can be generated by the router in three ways:
1. By name. Named routes link a symbolic name with a path and an HTTP request method.
2. By object. Routes can be defined by class and HTTP request method. When a URL is requested from the
router for an object, the router will identify the most appropriate route for the object
and instantiate an RKURL with the route's path pattern and interpolate it against the object.
3. By object relationship. Routes can be defined for relationships to other objects. When a URL is requested
from the router for a relationship, the router will retrieve the appropriate route for the relationship
from the route set and interpolate the route's path pattern against the source object.
1. **By name**. Named routes link a symbolic name with a path and an HTTP request method.
2. **By object**. Routes can be defined by class and HTTP request method. When a URL is requested from the router for an object, the router will identify the most appropriate route for the object and instantiate an `NSURL` with the route's path pattern and interpolate it against the object.
3. **By object relationship**. Routes can be defined for relationships to other objects. When a URL is requested from the router for a relationship, the router will retrieve the appropriate route for the relationship from the route set and interpolate the route's path pattern against the source object.
@see RKURL
@see RKRoute
@see RKRouteSet
*/
@interface RKRouter : NSObject
/**
The base URL that all URLs constructed by the receiver are relative to.
*/
@property (nonatomic, strong) NSURL *baseURL;
/**
A route set defining all the routes addressable through the receiver.
*/
@property (nonatomic, strong) RKRouteSet *routeSet;
///-----------------------------------------------------------------------------
///----------------------------
/// @name Initializing a Router
///-----------------------------------------------------------------------------
///----------------------------
/**
Initializes a router with a given base URL.
@@ -64,36 +47,36 @@
*/
- (id)initWithBaseURL:(NSURL *)baseURL;
///-----------------------------------------------------------------------------
///----------------------
/// @name Generating URLs
///-----------------------------------------------------------------------------
///----------------------
/**
Generates a URL for the route with the given name.
The route set is searched for a route with the given name and a new RKURL object is instantiated
The route set is searched for a route with the given name and a new `NSURL` object is instantiated
with the baseURL of the receiver and the path pattern of the route, optionally interpolated
with a given object. If a pointer to an RKRequestMethod variable is provided, the HTTP method
with a given object. If a pointer to an `RKRequestMethod` variable is provided, the HTTP method
for the route will be assigned to the reference.
@param routeName The name of the route for which a URL is to be generated.
@param method A pointer to an RKRequestMethod variable in which to store the HTTP method associated
with the named route.
@param method A pointer to an `RKRequestMethod` variable in which to store the HTTP method associated
with the named route. May be nil.
@param object An optional object against which to interpolate the path pattern.
@return A new URL object constructed by appending the path pattern to the baseURL of the
@return A new `NSURL` object constructed by appending the path pattern to the baseURL of the
receiver and interpolating against a given object; or nil if no route was found with the given
name.
*/
- (NSURL *)URLForRouteNamed:(NSString *)routeName method:(out RKRequestMethod *)method object:(id)object;
/**
Generates a URL for a given object with a given HTTP method.
Generates a URL for a given object and HTTP method.
The route set is searched for a route that matches the HTTP method and class of
the object being routed. If there is not an exact match for the object's class, the inheritance
hierarchy is searched until a match is found or all possible routes are exhausted. Exact HTTP request
matches are favored over the wildcard method (RKRequestMethodAny). Once the appropriate route is identified,
a new RKURL object is instantiated with the baseURL of the receiver and the path pattern of the route,
matches are favored over the wildcard method (`RKRequestMethodAny`). Once the appropriate route is identified,
a new `NSURL` object is instantiated with the baseURL of the receiver and the path pattern of the route,
interpolated against the object being routed.
@param object The object for which a URL is to be generated.
@@ -108,7 +91,7 @@
Generates a URL for a relationship of a given object with a given HTTP method.
The route set is searched for a route that matches the relationship of the given object's class and the given
HTTP method. If a matching route is found, a new RKURL object is instantiated with the baseURL of the receiver
HTTP method. If a matching route is found, a new `NSURL` object is instantiated with the baseURL of the receiver
and the path pattern of the route, interpolated against the object being routed.
@param relationshipName The name of the relationship for which a URL is to be generated.
@@ -120,4 +103,18 @@
*/
- (NSURL *)URLForRelationship:(NSString *)relationshipName ofObject:(id)object method:(RKRequestMethod)method;
///---------------------------------------------
/// @name Configuring the Base URL and Route Set
///---------------------------------------------
/**
The base URL that all URLs constructed by the receiver are relative to.
*/
@property (nonatomic, strong) NSURL *baseURL;
/**
A route set defining all the routes addressable through the receiver.
*/
@property (nonatomic, strong) RKRouteSet *routeSet;
@end