Source/AIXMLAppender.m

   1 /*
   2  * AIXMLAppender.m
   3  *
   4  * Created by Colin Barrett on 12/23/05.
   5  *
   6  * This class is explicitly released under the BSD license with the following modification:
   7  * It may be used without reproduction of its copyright notice within The Adium Project.
   8  *
   9  * This class was created for use in the Adium project, which is released under the GPL.
  10  * The release of this specific class (AIXMLAppender) under BSD in no way changes the licensing of any other portion
  11  * of the Adium project.
  12  *
  13  ****
  14  Copyright (c) 2005, 2006 Colin Barrett
  15  All rights reserved.
  16
  17  Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
  18
  19  Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
  20  Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer
  21  in the documentation and/or other materials provided with the distribution.
  22  Neither the name of Adium nor the names of its contributors may be used to endorse or promote products
  23  derived from this software without specific prior written permission.
  24
  25  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES,
  26  INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  27  IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  28  CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  29  HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  30  ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  31  */
  32
  33 /* TODO:
  34 - Possible support for "healing" a damaged XML file?
  35 - Possibly refactor the initializeDocument... and addElement... methods to return a BOOL and/or RBR an error code of some kind to indicate success or failure.
  36 - Instead of just testing for ' ' in -rootElementNameForFileAtPath:, use NSCharacterSet and be more general.
  37 */
  38
  39
  40 #import "AIXMLAppender.h"
  41 #import <AIUtilities/AIStringAdditions.h>
  42 #import <sys/stat.h>
  43
  44 #define XML_APPENDER_BLOCK_SIZE 4096
  45
  46 #define XML_MARKER @"<?xml version=\"1.0\"?>"
  47 enum { xmlMarkerLength = 21 };
  48
  49 @interface AIXMLAppender(PRIVATE)
  50 - (NSString *)createElementWithName:(NSString *)name content:(NSString *)content attributeKeys:(NSArray *)keys attributeValues:(NSArray *)values;
  51 - (NSString *)rootElementNameForFileAtPath:(NSString *)path;
  52 @end
  53
  54 /*!
  55  * @class AIXMLAppender
  56  * @brief Provides multiple-write access to an XML document while maintaining wellformedness.
  57  *
  58  * Just a couple of general comments here;
  59  * - Despite the hackish nature of seeking backwards and overwriting, sometimes you need to cheat a little or things
  60  *   get a bit insane. That's what was happening, so a Grand Compromise was reached, and this is what we're doing.
  61  */
  62
  63 @implementation AIXMLAppender
  64
  65 /*!
  66  * @brief Create a new, autoreleased document.
  67  *
  68  * @param path Path to the file where XML document will be stored
  69  */
  70 + (id)documentWithPath:(NSString *)path
  71 {
  72         return [[[self alloc] initWithPath:path] autorelease];
  73 }
  74
  75 /*!
  76  * @brief Create a new document at the path \a path
  77  *
  78  * @param path
  79  */
  80 - (id)initWithPath:(NSString *)path
  81 {
  82         if ((self = [super init])) {
  83                 //Set up our instance variables
  84                 initialized = NO;
  85                 rootElementName = nil;
  86                 filePath = [path copy];
  87
  88                 //Check if the file already exists
  89                 if ([[NSFileManager defaultManager] fileExistsAtPath:filePath]) {
  90                         //Get the root element name and set initialized
  91                         rootElementName = [[self rootElementNameForFileAtPath:filePath] retain];
  92                         initialized = (rootElementName != nil);
  93                 //We may need to create the directory structure, so call this just in case
  94                 } else {
  95                         NSFileManager *mgr = [NSFileManager defaultManager];
  96
  97                         //Save the current working directory, so we can change back to it.
  98                         NSString *savedWorkingDirectory = [mgr currentDirectoryPath];
  99                         //Change to the root.
 100                         [mgr changeCurrentDirectoryPath:@"/"];
 101
 102                         /*Create each component of the path, then change into it.
 103                          *E.g. /foo/bar/baz:
 104                          *      cd /
 105                          *      mkdir foo
 106                          *      cd foo
 107                          *      mkdir bar
 108                          *      cd bar
 109                          *      mkdir baz
 110                          *      cd baz
 111                          *      cd $savedWorkingDirectory
 112                          */
 113                         NSArray *pathComponents = [[filePath stringByDeletingLastPathComponent] pathComponents];
 114                         NSEnumerator *pathComponentsEnum = [pathComponents objectEnumerator];
 115                         NSString *component;
 116                         while ((component = [pathComponentsEnum nextObject])) {
 117                                 [mgr createDirectoryAtPath:component attributes:nil];
 118                                 [mgr changeCurrentDirectoryPath:component];
 119                         }
 120
 121                         [mgr changeCurrentDirectoryPath:savedWorkingDirectory];
 122                 }
 123
 124                 //Open our file handle and seek if necessary
 125                 const char *pathCString = [filePath fileSystemRepresentation];
 126                 int fd = open(pathCString, O_CREAT | O_WRONLY, 0644);
 127                 file = [[NSFileHandle alloc] initWithFileDescriptor:fd closeOnDealloc:YES];
 128                 if (initialized) {
 129                         struct stat sb;
 130                         fstat(fd, &sb);
 131                         int closingTagLength = [rootElementName length] + 4; //</rootElementName>
 132                         [file seekToFileOffset:sb.st_size - closingTagLength];
 133                 }
 134         }
 135
 136         return self;
 137 }
 138
 139 /*!
 140  * @brief Clean up.
 141  */
 142 - (void)dealloc
 143 {
 144         [filePath release];
 145         [file release]; //This will also close the fd, since we set the closeOnDealloc flag to YES
 146         [rootElementName release];
 147         [super dealloc];
 148 }
 149
 150
 151 /*!
 152  * @brief If the document is initialized.
 153  *
 154  * @return YES if the document is initialized. NO otherwise.
 155  *
 156  * This should be called before adding any elements to the document. If the document is uninitialized, any element
 157  * adding methods will fail. If the document is initialized, any initializing methods will fail.
 158  */
 159 - (BOOL)isInitialized
 160 {
 161         return initialized;
 162 }
 163
 164 /*!
 165  * @brief The path to the file.
 166  *
 167  * @return The path to the file the XML document is being written to.
 168  */
 169 - (NSString *)path
 170 {
 171         return filePath;
 172 }
 173
 174 /*!
 175  * @brief Name of the root element of this document
 176  *
 177  * @return The name of the root element of this document, nil if not initialized.
 178  */
 179 - (NSString *)rootElement
 180 {
 181         return rootElementName;
 182 }
 183
 184 /*!
 185  * @brief Sets up the document.
 186  *
 187  * @param name The name of the root element for this document.
 188  * @param attributeKeys An array of the attribute keys the element has.
 189  * @param attributeValues An array of the attribute values the element has.
 190  */
 191 - (void)initializeDocumentWithRootElementName:(NSString *)name attributeKeys:(NSArray *)keys attributeValues:(NSArray *)values
 192 {
 193         //Don't initialize twice
 194         if (!initialized) {
 195                 //Keep track of this for later
 196                 rootElementName = [name retain];
 197
 198                 //Create our strings
 199                 int closingTagLength = [rootElementName length] + 4; //</rootElementName>
 200                 NSString *rootElement = [self createElementWithName:rootElementName content:@"" attributeKeys:keys attributeValues:values];
 201                 NSString *initialDocument = [NSString stringWithFormat:@"%@\n%@", XML_MARKER, rootElement];
 202
 203                 //Write the data, and then seek backwards
 204                 [file writeData:[initialDocument dataUsingEncoding:NSUTF8StringEncoding]];
 205                 [file synchronizeFile];
 206                 [file seekToFileOffset:([file offsetInFile] - closingTagLength)];
 207
 208                 initialized = YES;
 209         }
 210 }
 211
 212 /*!
 213  * @brief Adds a node to the document.
 214  *
 215  * @param name The name of the root element for this document.
 216  * @param content The stuff between the open and close tags. If nil, then the tag will be self closing.
 217  * @param attributeKeys An array of the attribute keys the element has.
 218  * @param attributeValues An array of the attribute values the element has.
 219  */
 220
 221 - (void)addElementWithName:(NSString *)name content:(NSString *)content attributeKeys:(NSArray *)keys attributeValues:(NSArray *)values
 222 {
 223         [self addElementWithName:name
 224                           escapedContent:(content ? [content stringByEscapingForXMLWithEntities:nil] : nil)
 225                            attributeKeys:keys
 226                          attributeValues:values];
 227 }
 228
 229 /*!
 230  * @brief Adds a node to the document, performing no escaping on the content.
 231  *
 232  * @param name The name of the root element for this document.
 233  * @param content The stuff between the open and close tags. If nil, then the tag will be self closing. No escaping will be performed on the content.
 234  * @param attributeKeys An array of the attribute keys the element has.
 235  * @param attributeValues An array of the attribute values the element has.
 236  */
 237
 238 - (void)addElementWithName:(NSString *)name escapedContent:(NSString *)content attributeKeys:(NSArray *)keys attributeValues:(NSArray *)values
 239 {
 240         //Don't add if not initialized
 241         if (initialized) {
 242                 //Create our strings
 243                 NSString *element = [self createElementWithName:name content:content attributeKeys:keys attributeValues:values];
 244                 NSString *closingTag = [NSString stringWithFormat:@"</%@>\n", rootElementName];
 245
 246                 if(element != nil)
 247                 {
 248                         //Write the data, and then seek backwards
 249                         [file writeData:[[element stringByAppendingString:closingTag] dataUsingEncoding:NSUTF8StringEncoding]];
 250                         [file synchronizeFile];
 251                         [file seekToFileOffset:([file offsetInFile] - [closingTag length])];
 252                 }
 253         }
 254 }
 255
 256 #pragma mark Private Methods
 257
 258 /*!
 259  * @brief Creates an element node.
 260  *
 261  * @param name The name of the element.
 262  * @param content The stuff between the open and close tags. If nil, then the tag will be self closing. No escaping will be performed on the content.
 263  * @param attributeKeys An array of the attribute keys the element has.
 264  * @param attributeValues An array of the attribute values the element has.
 265  * @return An XML element, suitable for insertion into a document.
 266  *
 267  * The two attribute arrays must be of the same size, or the method will return nil.
 268  */
 269
 270 - (NSString *)createElementWithName:(NSString *)name content:(NSString *)content attributeKeys:(NSArray *)keys attributeValues:(NSArray *)values
 271 {
 272         //Check our precondition
 273         if ([keys count] != [values count]) {
 274                 NSLog(@"Attribute key (%@) and value (%@) arrays for element %@ are of differing lengths, %u and %u, respectively", keys, values, name, [keys count], [values count]);
 275                 return nil;
 276         }
 277
 278         //Collapse the attributes
 279         NSMutableString *attributeString = [NSMutableString string];
 280         NSEnumerator *attributeKeyEnumerator = [keys objectEnumerator];
 281         NSEnumerator *attributeValueEnumerator = [values objectEnumerator];
 282         NSString *key = nil, *value = nil;
 283         while ((key = [attributeKeyEnumerator nextObject]) && (value = [attributeValueEnumerator nextObject])) {
 284                 [attributeString appendFormat:@" %@=\"%@\"",
 285                         [key stringByEscapingForXMLWithEntities:nil],
 286                         [value stringByEscapingForXMLWithEntities:nil]];
 287         }
 288
 289         //Format and return
 290         NSString *escapedName = [name stringByEscapingForXMLWithEntities:nil];
 291         if (content)
 292                 return [NSString stringWithFormat:@"<%@%@>%@</%@>\n", escapedName, attributeString, content, escapedName];
 293         else
 294                 return [NSString stringWithFormat:@"<%@%@/>\n", escapedName, attributeString];
 295 }
 296
 297 /*!
 298  * @brief Get the root element name for file
 299  *
 300  * @return The root element name, or nil if there isn't one (possibly because the file is not valid XML)
 301  */
 302 - (NSString *)rootElementNameForFileAtPath:(NSString *)path
 303 {
 304         //Create a temporary file handle for validation, and read the marker
 305         NSFileHandle *handle = [NSFileHandle fileHandleForReadingAtPath:path];
 306         NSString *markerString = [[[NSString alloc] initWithData:[handle readDataOfLength:xmlMarkerLength]
 307                                                                                                         encoding:NSUTF8StringEncoding] autorelease];
 308
 309         if (![markerString isEqualToString:XML_MARKER]) {
 310                 [handle closeFile];
 311                 return nil;
 312         }
 313
 314         NSScanner *scanner = nil;
 315         do {
 316                 //Read a block of arbitrary size
 317                 NSString *block = [[[NSString alloc] initWithData:[handle readDataOfLength:XML_APPENDER_BLOCK_SIZE]
 318                                                                                                  encoding:NSUTF8StringEncoding] autorelease];
 319                 //If we read 0 characters, then we have reached the end of the file, so return
 320                 if ([block length] == 0) {
 321                         [handle closeFile];
 322                         return nil;
 323                 }
 324
 325                 scanner = [NSScanner scannerWithString:block];
 326                 [scanner scanUpToString:@"<" intoString:nil];
 327         } while([scanner isAtEnd]); //If the scanner is at the end, not found in this block
 328
 329         //Scn past the '<' we know is there
 330         [scanner scanString:@"<" intoString:nil];
 331
 332         NSString *accumulated = [NSString string];
 333         NSMutableString *accumulator = [NSMutableString string];
 334         BOOL found = NO;
 335         do {
 336                 [scanner scanUpToString:@" " intoString:&accumulated]; //very naive
 337                 [accumulator appendString:accumulated];
 338
 339                 //If the scanner is at the end, not found in this block
 340                 found = ![scanner isAtEnd];
 341
 342                 //If we've found the end of the element name, break
 343                 if (found)
 344                         break;
 345
 346                 NSString *block = [[[NSString alloc] initWithData:[handle readDataOfLength:XML_APPENDER_BLOCK_SIZE]
 347                                                                                                  encoding:NSUTF8StringEncoding] autorelease];
 348                 //Again, if we've reached the end of the file, we aren't initialized, so return nil
 349                 if ([block length] == 0) {
 350                         [handle closeFile];
 351                         return nil;
 352                 }
 353
 354                 scanner = [NSScanner scannerWithString:block];
 355         } while (!found);
 356
 357         [handle closeFile];
 358
 359         //We've obviously found the root element name, so return a nonmutble copy.
 360         return [NSString stringWithString:accumulator];
 361 }
 362
 363 @end