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/AIFileManagerAdditions.h>
  42 #import <AIUtilities/AIStringAdditions.h>
  43 #import <sys/stat.h>
  44 #import <fcntl.h>
  45
  46 #define XML_APPENDER_BLOCK_SIZE 4096
  47
  48 #define XML_MARKER @"<?xml version=\"1.0\" encoding=\"UTF-8\" ?>"
  49 enum {
  50         xmlMarkerLength = 21,
  51         failedUtf8BomLength = 6
  52 };
  53
  54 @interface AIXMLAppender(PRIVATE)
  55 - (NSString *)createElementWithName:(NSString *)name content:(NSString *)content attributeKeys:(NSArray *)keys attributeValues:(NSArray *)values;
  56 - (NSString *)rootElementNameForFileAtPath:(NSString *)path;
  57 - (void)prepareFileHandle;
  58 @end
  59
  60 /*!
  61  * @class AIXMLAppender
  62  * @brief Provides multiple-write access to an XML document while maintaining wellformedness.
  63  *
  64  * Just a couple of general comments here;
  65  * - Despite the hackish nature of seeking backwards and overwriting, sometimes you need to cheat a little or things
  66  *   get a bit insane. That's what was happening, so a Grand Compromise was reached, and this is what we're doing.
  67  */
  68
  69 @implementation AIXMLAppender
  70
  71 /*!
  72  * @brief Create a new, autoreleased document.
  73  *
  74  * @param path Path to the file where XML document will be stored
  75  */
  76 + (id)documentWithPath:(NSString *)path
  77 {
  78         return [[[self alloc] initWithPath:path] autorelease];
  79 }
  80
  81 /*!
  82  * @brief Create a new document at the path \a path
  83  *
  84  * @param path
  85  */
  86 - (id)initWithPath:(NSString *)path
  87 {
  88         if ((self = [super init])) {
  89                 //Set up our instance variables
  90                 rootElementName = nil;
  91                 filePath = [path copy];
  92
  93                 [self prepareFileHandle];
  94         }
  95
  96         return self;
  97 }
  98
  99 /*!
 100  * @brief Clean up.
 101  */
 102 - (void)dealloc
 103 {
 104         [filePath release];
 105         [file release]; //This will also close the fd, since we set the closeOnDealloc flag to YES
 106         [rootElementName release];
 107         [super dealloc];
 108 }
 109
 110
 111 /*!
 112  * @brief If the document is initialized.
 113  *
 114  * @return YES if the document is initialized. NO otherwise.
 115  *
 116  * This should be called before adding any elements to the document. If the document is uninitialized, any element
 117  * adding methods will fail. If the document is initialized, any initializing methods will fail.
 118  */
 119 - (BOOL)isInitialized
 120 {
 121         return initialized;
 122 }
 123
 124 /*!
 125  * @brief The path to the file.
 126  *
 127  * @return The path to the file the XML document is being written to.
 128  */
 129 - (NSString *)path
 130 {
 131         return filePath;
 132 }
 133
 134 /*!
 135  * @brief Name of the root element of this document
 136  *
 137  * @return The name of the root element of this document, nil if not initialized.
 138  */
 139 - (NSString *)rootElement
 140 {
 141         return rootElementName;
 142 }
 143
 144 - (void)prepareFileHandle
 145 {
 146         NSFileManager *manager = [NSFileManager defaultManager];
 147
 148         //Check if the file already exists
 149         if ([manager fileExistsAtPath:filePath]) {
 150                 //Get the root element name and set initialized
 151                 rootElementName = [[self rootElementNameForFileAtPath:filePath] retain];
 152                 initialized = (rootElementName != nil);
 153                 //We may need to create the directory structure, so call this just in case
 154         } else {
 155                 [manager createDirectoriesForPath:[filePath stringByDeletingLastPathComponent]];
 156                 initialized = NO;
 157         }
 158
 159         //Open our file handle and seek if necessary
 160         const char *pathCString = [filePath fileSystemRepresentation];
 161         int fd = open(pathCString, O_CREAT | O_WRONLY, 0644);
 162         if(fd == -1) {
 163                 AILog(@"Couldn't open log file %@ (%s - length %u) for writing!",
 164                           filePath, pathCString, (pathCString ? strlen(pathCString) : 0));
 165         } else {
 166                 file = [[NSFileHandle alloc] initWithFileDescriptor:fd closeOnDealloc:YES];
 167                 if (initialized) {
 168                         struct stat sb;
 169                         fstat(fd, &sb);
 170                         int closingTagLength = [rootElementName length] + 4; //</rootElementName>
 171                         [file seekToFileOffset:sb.st_size - closingTagLength];
 172                 }
 173         }
 174 }
 175
 176 - (BOOL)writeData:(NSData *)data seekBackLength:(int)seekBackLength
 177 {
 178         BOOL success = YES;
 179
 180         @try {
 181                 [file writeData:data];
 182
 183         } @catch (NSException *writingException) {
 184                 /* NSFileHandle raises an exception if:
 185                  *    * the file descriptor is closed or is not valid - we should reopen the file and try again
 186                  *    * if the receiver represents an unconnected pipe or socket endpoint - this should never happen
 187                  *    * if no free space is left on the file system - this should be handled gracefully if possible.. but the user is probably in trouble.
 188                  *    * if any other writing error occurs - as with lack of free space.
 189                  */
 190                 if (initialized &&
 191                         [[writingException name] isEqualToString:NSFileHandleOperationException] &&
 192                         [[writingException reason] rangeOfString:@"Bad file descriptor"].location != NSNotFound) {
 193                         @try {
 194                                 [file release]; file = nil;
 195                         } @catch (NSException *releaseException) {
 196                                 //Don't need to do anything... but if we failed to write, we may fail to deallocate, too.
 197                                  file = nil;
 198                         }
 199
 200                         [self prepareFileHandle];
 201                         @try {
 202                                 [file writeData:data];
 203                                 success = YES;
 204
 205                         } @catch (NSException *secondWritingException) {
 206                                 NSLog(@"Exception while writing %@ log file %@: %@ (%@)",
 207                                           (initialized ? @"initialized" : @"uninitialized"), filePath, [secondWritingException name], [secondWritingException reason]);
 208                                 success = NO;
 209                         }
 210
 211                 } else {
 212                         NSLog(@"Exception while writing %@ log file %@: %@ (%@)",
 213                                   (initialized ? @"initialized" : @"uninitialized"), filePath, [writingException name], [writingException reason]);
 214                         success = NO;
 215                 }
 216         }
 217
 218         if (success) {
 219                 fcntl([file fileDescriptor], F_FULLFSYNC, /*arg*/ 0);
 220                 @try {
 221                         [file seekToFileOffset:([file offsetInFile] - seekBackLength)];
 222
 223                 } @catch (NSException *seekException) {
 224                         /* -[NSFileHandler seekToFileOffset:] raises an exception if
 225                         *    * the message is sent to an NSFileHandle object representing a pipe or socket
 226                         *    * if the file descriptor is closed
 227                         *    * if any other error occurs in seeking.
 228                         */
 229                         NSLog(@"Exception while seeking in %@ log file %@: %@ (%@)",
 230                                   (initialized ? @"initialized" : @"uninitialized"), filePath, [seekException name], [seekException reason]);
 231                         success = NO;
 232                 }
 233         }
 234
 235         return success;
 236 }
 237
 238 /*!
 239  * @brief Sets up the document.
 240  *
 241  * @param name The name of the root element for this document.
 242  * @param keys An array of the attribute keys the element has.
 243  * @param values An array of the attribute values the element has.
 244  */
 245 - (BOOL)initializeDocumentWithRootElementName:(NSString *)name attributeKeys:(NSArray *)keys attributeValues:(NSArray *)values
 246 {
 247         //Don't initialize twice
 248         BOOL success = NO;
 249
 250         if (!initialized && file) {
 251                 //Keep track of this for later
 252                 rootElementName = [name retain];
 253
 254                 //Create our strings
 255                 int closingTagLength = [rootElementName length] + 4; //</rootElementName>
 256                 NSString *rootElement = [self createElementWithName:rootElementName content:@"" attributeKeys:keys attributeValues:values];
 257                 NSString *initialDocument = [NSString stringWithFormat:@"%@\n%@", XML_MARKER, rootElement];
 258
 259                 //Write the data, and then seek backwards
 260                 success = [self writeData:[initialDocument dataUsingEncoding:NSUTF8StringEncoding] seekBackLength:closingTagLength];
 261
 262                 initialized = YES;
 263         }
 264
 265         return success;
 266 }
 267
 268 /*!
 269  * @brief Adds a node to the document.
 270  *
 271  * @param name The name of the root element for this document.
 272  * @param content The stuff between the open and close tags. If nil, then the tag will be self closing.
 273  * @param keys An array of the attribute keys the element has.
 274  * @param values An array of the attribute values the element has.
 275  */
 276
 277 - (BOOL)addElementWithName:(NSString *)name content:(NSString *)content attributeKeys:(NSArray *)keys attributeValues:(NSArray *)values
 278 {
 279         return [self addElementWithName:name
 280                                          escapedContent:(content ? [content stringByEscapingForXMLWithEntities:nil] : nil)
 281                                           attributeKeys:keys
 282                                         attributeValues:values];
 283 }
 284
 285 /*!
 286  * @brief Adds a node to the document, performing no escaping on the content.
 287  *
 288  * @param name The name of the root element for this document.
 289  * @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.
 290  * @param keys An array of the attribute keys the element has.
 291  * @param values An array of the attribute values the element has.
 292  */
 293
 294 - (BOOL)addElementWithName:(NSString *)name escapedContent:(NSString *)content attributeKeys:(NSArray *)keys attributeValues:(NSArray *)values
 295 {
 296         BOOL success = NO;
 297
 298         //Don't add if not initialized, or if we couldn't open the file
 299         if (initialized && file) {
 300                 //Create our strings
 301                 NSString *element = [self createElementWithName:name content:content attributeKeys:keys attributeValues:values];
 302                 NSString *closingTag = [NSString stringWithFormat:@"</%@>\n", rootElementName];
 303
 304                 if (element != nil) {
 305                         //Write the data, and then seek backwards
 306                         success = [self writeData:[[element stringByAppendingString:closingTag] dataUsingEncoding:NSUTF8StringEncoding]
 307                                            seekBackLength:[closingTag length]];
 308                 }
 309         }
 310
 311         return success;
 312 }
 313
 314 #pragma mark Private Methods
 315
 316 /*!
 317  * @brief Creates an element node.
 318  *
 319  * @param name The name of the element.
 320  * @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.
 321  * @param keys An array of the attribute keys the element has.
 322  * @param values An array of the attribute values the element has.
 323  * @return An XML element, suitable for insertion into a document.
 324  *
 325  * The two attribute arrays must be of the same size, or the method will return nil.
 326  */
 327
 328 - (NSString *)createElementWithName:(NSString *)name content:(NSString *)content attributeKeys:(NSArray *)keys attributeValues:(NSArray *)values
 329 {
 330         //Check our precondition
 331         if ([keys count] != [values count]) {
 332                 NSLog(@"Attribute key (%@) and value (%@) arrays for element %@ are of differing lengths, %u and %u, respectively", keys, values, name, [keys count], [values count]);
 333                 return nil;
 334         }
 335
 336         //Collapse the attributes
 337         NSMutableString *attributeString = [NSMutableString string];
 338         NSEnumerator *attributeKeyEnumerator = [keys objectEnumerator];
 339         NSEnumerator *attributeValueEnumerator = [values objectEnumerator];
 340         NSString *key = nil, *value = nil;
 341         while ((key = [attributeKeyEnumerator nextObject]) && (value = [attributeValueEnumerator nextObject])) {
 342                 [attributeString appendFormat:@" %@=\"%@\"",
 343                         [key stringByEscapingForXMLWithEntities:nil],
 344                         [value stringByEscapingForXMLWithEntities:nil]];
 345         }
 346
 347         //Format and return
 348         NSString *escapedName = [name stringByEscapingForXMLWithEntities:nil];
 349         if (content)
 350                 return [NSString stringWithFormat:@"<%@%@>%@</%@>\n", escapedName, attributeString, content, escapedName];
 351         else
 352                 return [NSString stringWithFormat:@"<%@%@/>\n", escapedName, attributeString];
 353 }
 354
 355 /*!
 356  * @brief Get the root element name for file
 357  *
 358  * @return The root element name, or nil if there isn't one (possibly because the file is not valid XML)
 359  */
 360 - (NSString *)rootElementNameForFileAtPath:(NSString *)path
 361 {
 362         //Create a temporary file handle for validation, and read the marker
 363         NSFileHandle *handle = [NSFileHandle fileHandleForReadingAtPath:path];
 364
 365         if(!handle) return nil;
 366
 367         NSScanner *scanner = nil;
 368         do {
 369                 //Read a block of arbitrary size
 370                 NSString *block = [[[NSString alloc] initWithData:[handle readDataOfLength:XML_APPENDER_BLOCK_SIZE]
 371                                                                                                  encoding:NSUTF8StringEncoding] autorelease];
 372                 //If we read 0 characters, then we have reached the end of the file, so return
 373                 if ([block length] == 0) {
 374                         [handle closeFile];
 375                         return nil;
 376                 }
 377
 378                 scanner = [NSScanner scannerWithString:block];
 379                 [scanner scanUpToString:@"<" intoString:nil];
 380         } while([scanner isAtEnd]); //If the scanner is at the end, not found in this block
 381
 382         //Scn past the '<' we know is there
 383         [scanner scanString:@"<" intoString:nil];
 384
 385         NSString *accumulated = [NSString string];
 386         NSMutableString *accumulator = [NSMutableString string];
 387         BOOL found = NO;
 388         do {
 389                 [scanner scanUpToString:@" " intoString:&accumulated]; //very naive
 390                 [accumulator appendString:accumulated];
 391
 392                 //If the scanner is at the end, not found in this block
 393                 found = ![scanner isAtEnd];
 394
 395                 //If we've found the end of the element name, break
 396                 if (found)
 397                         break;
 398
 399                 NSString *block = [[[NSString alloc] initWithData:[handle readDataOfLength:XML_APPENDER_BLOCK_SIZE]
 400                                                                                                  encoding:NSUTF8StringEncoding] autorelease];
 401                 //Again, if we've reached the end of the file, we aren't initialized, so return nil
 402                 if ([block length] == 0) {
 403                         [handle closeFile];
 404                         return nil;
 405                 }
 406
 407                 scanner = [NSScanner scannerWithString:block];
 408         } while (!found);
 409
 410         [handle closeFile];
 411
 412         //We've obviously found the root element name, so return a nonmutable copy.
 413         return [NSString stringWithString:accumulator];
 414 }
 415
 416 @end