iPhone SDK / Objective C Syntax Question

Question

To all,

I was looking at the sample project from http://iphoneonrails.com/ and I saw they took the NSObject class and added methods to it for the SOAP calls.

Their sample project can be downloaded from here http://iphoneonrails.com/downloads/objective_resource-1.01.zip.

My question is related to my lack of knowledge on the following syntax as I haven't seen it yet in a iPhone project.

There is a header file called NSObject+ObjectiveResource.h where they declare and change NSObject to have extra methods for this project. Is the "+ObjectiveResource.h" in the name there a special syntax or is that just the naming convention of the developers.

Finally inside the class NSObject we have the following

#import <Foundation/Foundation.h>

@interface NSObject (ObjectiveResource)


// Response Formats
typedef enum {
 XmlResponse = 0,
 JSONResponse,
} ORSResponseFormat;

// Resource configuration
+ (NSString *)getRemoteSite;
+ (void)setRemoteSite:(NSString*)siteURL;
+ (NSString *)getRemoteUser;
+ (void)setRemoteUser:(NSString *)user;
+ (NSString *)getRemotePassword;
+ (void)setRemotePassword:(NSString *)password;
+ (SEL)getRemoteParseDataMethod;
+ (void)setRemoteParseDataMethod:(SEL)parseMethod;
+ (SEL) getRemoteSerializeMethod;
+ (void) setRemoteSerializeMethod:(SEL)serializeMethod;
+ (NSString *)getRemoteProtocolExtension;
+ (void)setRemoteProtocolExtension:(NSString *)protocolExtension;
+ (void)setRemoteResponseType:(ORSResponseFormat) format;
+ (ORSResponseFormat)getRemoteResponseType;


// Finders
+ (NSArray *)findAllRemote;
+ (NSArray *)findAllRemoteWithResponse:(NSError **)aError;
+ (id)findRemote:(NSString *)elementId;
+ (id)findRemote:(NSString *)elementId withResponse:(NSError **)aError; 

// URL construction accessors
+ (NSString *)getRemoteElementName;
+ (NSString *)getRemoteCollectionName;
+ (NSString *)getRemoteElementPath:(NSString *)elementId;
+ (NSString *)getRemoteCollectionPath;
+ (NSString *)getRemoteCollectionPathWithParameters:(NSDictionary *)parameters;
+ (NSString *)populateRemotePath:(NSString *)path withParameters:(NSDictionary *)parameters;

// Instance-specific methods
- (id)getRemoteId;
- (void)setRemoteId:(id)orsId;
- (NSString *)getRemoteClassIdName;
- (BOOL)createRemote;
- (BOOL)createRemoteWithResponse:(NSError **)aError;
- (BOOL)createRemoteWithParameters:(NSDictionary *)parameters;
- (BOOL)createRemoteWithParameters:(NSDictionary *)parameters andResponse:(NSError **)aError;
- (BOOL)destroyRemote;
- (BOOL)destroyRemoteWithResponse:(NSError **)aError;
- (BOOL)updateRemote;
- (BOOL)updateRemoteWithResponse:(NSError **)aError;
- (BOOL)saveRemote;
- (BOOL)saveRemoteWithResponse:(NSError **)aError;


- (BOOL)createRemoteAtPath:(NSString *)path withResponse:(NSError **)aError;
- (BOOL)updateRemoteAtPath:(NSString *)path withResponse:(NSError **)aError;
- (BOOL)destroyRemoteAtPath:(NSString *)path withResponse:(NSError **)aError;

// Instance helpers for getting at commonly used class-level values
- (NSString *)getRemoteCollectionPath;
- (NSString *)convertToRemoteExpectedType;

//Equality test for remote enabled objects based on class name and remote id
- (BOOL)isEqualToRemote:(id)anObject;
- (NSUInteger)hashForRemote;

@end

What is the "ObjectiveResource" in the () mean for NSObject? What is that telling Xcode and the compiler about what is happening..?

After that things look normal to me as they have various static and instance methods. I know that by doing this all user classes that inherit from NSObject now have all the extra methods for this project.

My question is what is the parenthesis are doing after the NSObject. Is that referencing a header file, or is that letting the compiler know that this class is being over ridden.

Thanks again and my apologies ahead of time if this is a dumb question but just trying to learn what I lack.

Answer 1

This is a Category. It allows you to extend an existing class. Instead of

MyClass : MySuperclass

it's declared via:

MyClass (MyCategoryName)

The name of the file is simply a convention MyClass+MyCategory.h. The filename makes no real difference, but this makes it easy to tell the file contains a category of methods that extends a specific class.

Note that you can implement new methods in a category, but you cannot add instance variables. And to use a category elsewhere in your codebase, all you must do is import the category header and all methods it contains will be made available on the objects the category extends.

Answer 2

This is called a "category" in Objective-C. See the "Categories and Extensions" chapter of The Objective-C Programming Language for more information.

The +ObjectiveResource.h thing is just a common convention for naming files that contain categories. It doesn't have any significance to the compiler.

Answer 3

The first two answers are correct - it's a Category, which is a way to extend the functionality of an existing class.

It's a really powerful feature in Objective-C, but it can be abused too. It can be dangerous to put Categories on low-level classes like NSObject, unless you know exactly what the implications are. For example, if you add methods to NSObject, you are essentially adding the methods to any class that inherits from NSObject, which is pretty much everything. Note that you can only utilize the category methods if you include the header, but it can still produce unexpected results in some cases.