< Previous PageNext Page >

Hide TOC

Using XML Property Lists

This section describes how to work with XML property lists, the preferred way to store property lists in Mac OS X. “Using XML Property Lists in Objective-C” explains how to use XML plists in Objective-C, “Using XML Property Lists in Java” explains how to use them in Java, and “Using Property List Services with Cocoa” explains how to use the Core Foundation property list API with Cocoa property list objects.

Using XML Property Lists in Objective-C

The NSPropertyListSerialization class (available in Mac OS X v10.2 and later for Objective-C) provides methods for saving and restoring property lists from the three supported formats. To save a property list in XML format, use the dataFromPropertyList:format:errorDescription: method with NSPropertyListXMLFormat_v1_0 as the second parameter. This code fragment saves the property list plist to an XML plist at path:

id plist;       // Assume this exists.

NSString *path; // Assume this is a valid path.

NSData *xmlData;

NSString *error;

xmlData = [NSPropertyListSerialization dataFromPropertyList:plist

                                       format:NSPropertyListXMLFormat_v1_0

                                       errorDescription:&error];

if(xmlData)

    NSLog(@"No error creating XML data.");

    [xmlData writeToFile:path atomically:YES];

else

    NSLog(error);

    [error release];

To restore a property list from data, use NSPropertyListSerialization’s propertyListFromData:mutabilityOption:format:errorDescription: method. This code fragment creates an immutable property list from the file at path:

NSString *path; // Assume this is a path to a valid plist.

NSData *plistData;

NSString *error;

NSPropertyListFormat format;

id plist;

plistData = [NSData dataWithContentsOfFile:path];

plist = [NSPropertyListSerialization propertyListFromData:plistData

                                mutabilityOption:NSPropertyListImmutable

                                format:&format

                                errorDescription:&error];

if(!plist)

    NSLog(error);

    [error release];

Using XML Property Lists in Java

The NSPropertyListSerialization class provides methods for saving and restoring property lists in the three property list formats. To create XML data from a property list, use the XMLDataFromPropertyList static method. This code fragment stores the property list plist to url:

Object plist;     // Assume this is a valid property list.

java.net.URL url; // Assume this is a well-formed local file URL.

NSData xmlData;

xmlData = NSPropertyListSerialization.XMLDataFromPropertyList(plist);

xmlData.writeToURL(plistURL, true);

To restore XML data to a property list in memory, use the propertyListFromXMLData static method. This code fragment loads XML data from url, and converts it to a property list:

java.net.URL url; // Assume this is a URL to a well-formed XML plist.

Object plist;

NSData xmlData;

xmlData = new NSData(url);

plist = NSPropertyListSerialization.propertyListFromXMLData(xmlData);

Using Property List Services with Cocoa

Cocoa uses the Core Foundation property list API to read and write XML property lists. In some cases, you may wish to access the API directly in an Objective-C Cocoa application. For example, if you want to save an instance of a class other than NSArray or NSDictionary as the root object of an XML plist, currently the easiest way to do this is through Property List Services. This process is made simple because Cocoa objects can be automatically cast to and from corresponding Core Foundation types.

To create an XML property list from a property list object, use the CFPropertyListCreateXMLData function. This code fragment saves the property list plist into a file at path:

NSString *path; // Assume this is a valid path.

id plist;       // Assume this is a valid property list.

NSData *xmlData;

xmlData = (NSData *)CFPropertyListCreateXMLData(kCFAllocatorDefault,

                                               (CFPropertyListRef)plist);

[xmlData writeToFile:path atomically:YES];

[xmlData release];

To restore a property list object from XML data, use the CFPropertyListCreateFromXMLData function. This code fragment restores property list from the XML plist file at path with mutable containers but immutable leaves:

NSString *path; // Assume this is a path to a well-formed XML plist.

NSString *errorString;

NSData *xmlData;

id plist;

xmlData = [NSData dataWithContentsOfFile:path];

plist = (id)CFPropertyListCreateFromXMLData(kCFAllocatorDefault,

                 (CFDataRef)xmlData, kCFPropertyListMutableContainers,

                 (CFStringRef *)&errorString);

For more information about the Core Foundation Property Lists, see Property List Programming Topics for Core Foundation.

< Previous PageNext Page >

Hide TOC

Last updated: 2006-11-07

Did this document help you?
Yes: Tell us what works for you. It’s good, but: Report typos, inaccuracies, and so forth. It wasn’t helpful: Tell us what would have helped.




	Get information on Apple products. Visit the Apple Store online or at retail locations. 1-800-MY-APPLE Copyright © 2007 Apple Inc. All rights reserved. \| Terms of use \| Privacy Notice