PageRenderTime 63ms CodeModel.GetById 24ms app.highlight 32ms RepoModel.GetById 1ms app.codeStats 0ms

/core/externals/update-engine/externals/gdata-objectivec-client/Source/BaseClasses/GDataObject.h

http://macfuse.googlecode.com/
C++ Header | 653 lines | 256 code | 137 blank | 260 comment | 0 complexity | 4e7e39befaca2c8435add4f1ff5d29c7 MD5 | raw file
  1/* Copyright (c) 2007 Google Inc.
  2 *
  3 * Licensed under the Apache License, Version 2.0 (the "License");
  4 * you may not use this file except in compliance with the License.
  5 * You may obtain a copy of the License at
  6 *
  7 *     http://www.apache.org/licenses/LICENSE-2.0
  8 *
  9 * Unless required by applicable law or agreed to in writing, software
 10 * distributed under the License is distributed on an "AS IS" BASIS,
 11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 12 * See the License for the specific language governing permissions and
 13 * limitations under the License.
 14 */
 15
 16//
 17//  GDataObject.h
 18//
 19
 20// This is the base class for most objects in the Objective-C GData implementation.
 21// Objects should derive from GDataObject in order to support XML parsing and
 22// generation, and to support the extension model.
 23
 24// Subclasses will typically implement:
 25//
 26// - (void)addExtensionDeclarations;  -- declaring extensions
 27// - (id)initWithXMLElement:(NSXMLElement *)element
 28//                   parent:(GDataObject *)parent;  -- parsing
 29// - (NSXMLElement *)XMLElement;  -- XML generation
 30//
 31// Subclasses should implement other typical NSObject methods, too:
 32//
 33// - (NSString *)description;
 34// - (id)copyWithZone:(NSZone *)zone; (be sure to call superclass)
 35// - (BOOL)isEqual:(GDataObject *)other; (be sure to call superclass)
 36// - (void)dealloc;
 37//
 38// Subclasses which may be used as extensions should implement the
 39// simple GDataExtension protocol.
 40//
 41
 42//
 43// Parsing and XML generation
 44//
 45// Parsing is done in the subclass's -initWithXMLElement:parent: method.
 46//
 47// For each parsed GData XML element, GDataObject maintains lists of
 48// un-parsed attributes and children (unknownChildren_ and unknownAttributes_)
 49// as raw NSXMLNodes.  Subclasses MUST use the methods in this class's
 50// "parsing helpers" (below) to extract properties and elements during parsing;
 51// this ensures that the lists of unknown properties and children are
 52// accurate.  DO NOT parse using NSXMLElement methods.
 53//
 54// XML generation is done in the subclass's -XMLElement method.
 55// That method will call XMLElementWithExtensionsAndDefaultName to get
 56// a "starter" NSXMLElement, already decorated with extensions, to which
 57// the subclass can add its unique children and attributes, if any.
 58//
 59//
 60//
 61// The extension model
 62//
 63// Extensions enable elements to contain children about which the element
 64// may know no details.
 65//
 66// Typically, entries add extensions to themselves. For example, a Calendar
 67// entry declares it may contain a color:
 68//
 69//  [self addExtensionDeclarationForParentClass:[GDataEntryCalendar class]
 70//                                   childClass:[GDataColorProperty class]];
 71//
 72// This lets the base class handle much of the work of managing the child
 73// element.  The Calendar entry can still provide accessor methods to get
 74// to the extension by calling into the base class, as in
 75//
 76//  - (GDataColorProperty *)color {
 77//    return (GDataColorProperty *)
 78//               [self objectForExtensionClass:[GDataColorProperty class]];
 79//  }
 80//
 81//  - (void)setColor:(GDataColorProperty *)val {
 82//    [self setObject:val forExtensionClass:[GDataColorProperty class]];
 83//  }
 84//
 85// The real purpose of extensions is to allow elements to contain children
 86// they may not know about.  For example, a CalendarEventEntry declares
 87// that GDataLinks contained within the calendar event entry may contain
 88// GDataWebContent elements:
 89//
 90//  [self addExtensionDeclarationForParentClass:[GDataLink class]
 91//                                   childClass:[GDataWebContent class]];
 92//
 93// The CalendarEvent has extended GDataLinks without GDataLinks knowing or
 94// caring.  Because GDataLink derives from GDataObject, the GDataLink
 95// object will automatically parse and maintain and copy and compare
 96// the GDataWebContents contained within.
 97//
 98
 99
100#import <Foundation/Foundation.h>
101
102#import "GDataDefines.h"
103#import "GDataUtilities.h"
104
105#undef _EXTERN
106#undef _INITIALIZE_AS
107#ifdef GDATAOBJECT_DEFINE_GLOBALS
108#define _EXTERN
109#define _INITIALIZE_AS(x) =x
110#else
111#define _EXTERN GDATA_EXTERN
112#define _INITIALIZE_AS(x)
113#endif
114
115_EXTERN NSString* const kGDataNamespaceAtom          _INITIALIZE_AS(@"http://www.w3.org/2005/Atom");
116_EXTERN NSString* const kGDataNamespaceAtomPrefix    _INITIALIZE_AS(@"atom");
117
118_EXTERN NSString* const kGDataNamespaceAtomPub       _INITIALIZE_AS(@"http://www.w3.org/2007/app");
119_EXTERN NSString* const kGDataNamespaceAtomPubPrefix _INITIALIZE_AS(@"app");
120
121_EXTERN NSString* const kGDataNamespaceOpenSearch       _INITIALIZE_AS(@"http://a9.com/-/spec/opensearch/1.1/");
122_EXTERN NSString* const kGDataNamespaceOpenSearchPrefix _INITIALIZE_AS(@"openSearch");
123
124_EXTERN NSString* const kGDataNamespaceXHTML       _INITIALIZE_AS(@"http://www.w3.org/1999/xhtml");
125_EXTERN NSString* const kGDataNamespaceXHTMLPrefix _INITIALIZE_AS(@"xh");
126
127_EXTERN NSString* const kGDataNamespaceGData       _INITIALIZE_AS(@"http://schemas.google.com/g/2005");
128_EXTERN NSString* const kGDataNamespaceGDataPrefix _INITIALIZE_AS(@"gd");
129
130_EXTERN NSString* const kGDataNamespaceBatch       _INITIALIZE_AS(@"http://schemas.google.com/gdata/batch");
131_EXTERN NSString* const kGDataNamespaceBatchPrefix _INITIALIZE_AS(@"batch");
132
133#define GDATA_DEBUG_ASSERT_MIN_SERVICE_VERSION(versionString) \
134  GDATA_DEBUG_ASSERT([self isServiceVersionAtLeast:versionString], \
135    @"%@ requires newer version", NSStringFromSelector(_cmd))
136
137#define GDATA_DEBUG_ASSERT_MAX_SERVICE_VERSION(versionString) \
138  GDATA_DEBUG_ASSERT([self isServiceVersionAtMost:versionString], \
139    @"%@ deprecated under v%@", NSStringFromSelector(_cmd), [self serviceVersion])
140
141#define GDATA_DEBUG_ASSERT_MIN_SERVICE_V2() \
142  GDATA_DEBUG_ASSERT_MIN_SERVICE_VERSION(@"2.0")
143
144@class GDataDateTime;
145@class GDataCategory;
146
147@protocol GDataExtension
148+ (NSString *)extensionElementURI;
149+ (NSString *)extensionElementPrefix;
150+ (NSString *)extensionElementLocalName;
151@end
152
153// GDataAttribute is the base class for attribute extensions.
154// It is *not* used for local attributes, which are simply stored in
155// GDataObject' attributes_ dictionary.
156//
157// This returns nil for the attribute's URI and prefix qualifier;
158// subclasses must declare at least a local name.
159//
160// Functionally, this just stores a string value for the attribute.
161
162@interface GDataAttribute : NSObject {
163 @private
164    NSString *value_;
165}
166+ (GDataAttribute *)attributeWithValue:(NSString *)str;
167- (id)initWithValue:(NSString *)value;
168
169- (void)setStringValue:(NSString *)str;
170- (NSString *)stringValue;
171@end
172
173// GDataDescriptionRecords are used for describing how the elements
174// and attributes of a GDataObject should be reported when -description
175// is called.
176
177typedef enum GDataDescRecTypes {
178  kGDataDescValueLabeled = 1,
179  kGDataDescLabelIfNonNil,
180  kGDataDescArrayCount,
181  kGDataDescArrayDescs,
182  kGDataDescBooleanLabeled,
183  kGDataDescBooleanPresent,
184  kGDataDescNonZeroLength,
185  kGDataDescValueIsKeyPath
186} GDataDescRecTypes;
187
188typedef struct GDataDescriptionRecord {
189  NSString GDATA_UNSAFE_UNRETAINED *label;
190  NSString GDATA_UNSAFE_UNRETAINED *keyPath;
191  GDataDescRecTypes reportType;
192} GDataDescriptionRecord;
193
194
195@interface GDataObject : NSObject <NSCopying> {
196
197  @private
198
199  // element name from original XML, used for later XML generation
200  NSString *elementName_;
201
202  GDataObject GDATA_UNSAFE_UNRETAINED *parent_;  // weak: parent in tree of GData objects
203
204  // GDataObjects keep namespaces as {key:prefix value:URI} dictionary entries
205  NSMutableDictionary *namespaces_;
206
207  // extension declaration cache, retained by the topmost parent
208  //
209  // keys are classes that have declared their extensions
210  //
211  // the values are dictionaries mapping declared parent classes to
212  // GDataExtensionDeclarations objects
213  NSMutableDictionary *extensionDeclarationsCache_;
214
215  // list of attributes to be parsed for each class
216  NSMutableDictionary *attributeDeclarationsCache_;
217
218  // list of attributes to be parsed for this class (points strongly into the
219  // attribute declarations cache)
220  NSMutableArray *attributeDeclarations_;
221
222  // arrays of actual extension elements found for this element, keyed by extension class
223  NSMutableDictionary *extensions_;
224
225  // dictionary of attributes set for this element, keyed by attribute name
226  NSMutableDictionary *attributes_;
227
228  // string for element body, if declared as parseable
229  NSString *contentValue_;
230
231  // XMLElements saved from element body but not parsed, if declared by the subclass
232  NSMutableArray *childXMLElements_;
233
234  // arrays of XMLNodes of attributes and child elements not yet parsed
235  NSMutableArray *unknownChildren_;
236  NSMutableArray *unknownAttributes_;
237  BOOL shouldIgnoreUnknowns_;
238
239  // mapping of standard classes to user's surrogate subclasses, used when
240  // creating objects from XML
241  NSDictionary *surrogates_;
242
243  // service version, set for feeds and entries
244  NSString *serviceVersion_;
245
246  // core protocol version, set from the service version when
247  // -coreProtocolVersion is invoked
248  NSString *coreProtocolVersion_;
249
250  // anything defined by the client; retained but not used internally; not
251  // copied by copyWithZone:
252  id userData_;
253  NSMutableDictionary *userProperties_;
254}
255
256///////////////////////////////////////////////////////////////////////////////
257//
258// Public methods
259//
260// These methods are intended for users of the library
261//
262
263+ (id)object;
264
265- (id)copyWithZone:(NSZone *)zone;
266
267- (id)initWithServiceVersion:(NSString *)serviceVersion;
268
269- (id)initWithXMLElement:(NSXMLElement *)element
270                  parent:(GDataObject *)parent; // subclasses must override
271- (NSXMLElement *)XMLElement; // subclasses must override
272
273- (NSXMLDocument *)XMLDocument; // returns this XMLElement wrapped in an NSXMLDocument
274
275// setters/getters
276
277// namespaces here are a dictionary mapping prefix to URI; they are not
278// NSXML namespace objects
279- (void)setNamespaces:(NSDictionary *)namespaces;
280- (void)addNamespaces:(NSDictionary *)namespaces;
281- (NSDictionary *)namespaces;
282
283// return a dictionary containing all namespaces
284// in this object and its parent objects
285- (NSDictionary *)completeNamespaces;
286
287// if a prefix is explicitly defined the same for a parent as it is locally,
288// remove it, since we can rely on the parent's definition
289- (void)pruneInheritedNamespaces;
290
291// name from original XML; this will be used during XML generation
292- (void)setElementName:(NSString *)elementName;
293- (NSString *)elementName;
294
295// parent in object tree (weak reference)
296- (void)setParent:(GDataObject *)obj;
297- (GDataObject *)parent;
298
299// surrogate lists for when alloc'ing classes from XML
300- (void)setSurrogates:(NSDictionary *)surrogates;
301- (NSDictionary *)surrogates;
302
303// service API version
304+ (NSString *)defaultServiceVersion;
305
306// a side-effect of setServiceVersion: is that the coreProtocolVersion is
307// reset
308- (void)setServiceVersion:(NSString *)str;
309- (NSString *)serviceVersion;
310
311- (BOOL)isServiceVersionAtLeast:(NSString *)otherVersion;
312- (BOOL)isServiceVersionAtMost:(NSString *)otherVersion;
313
314// calling -coreProtocolVersion sets the initial core protocol version based
315// on the service version
316- (NSString *)coreProtocolVersion;
317- (void)setCoreProtocolVersion:(NSString *)str;
318- (BOOL)isCoreProtocolVersion1;
319
320// userData is available for client use; retained by GDataObject, but not
321// copied by the copyWithZone
322- (void)setUserData:(id)obj;
323- (id)userData;
324
325// properties are supported for client convenience, but are not copied by
326// copyWithZone.  Properties keys beginning with _ are reserved by the library.
327- (void)setProperties:(NSDictionary *)dict;
328- (NSDictionary *)properties;
329
330- (void)setProperty:(id)obj forKey:(NSString *)key; // pass nil obj to remove property
331- (id)propertyForKey:(NSString *)key;
332
333// XMLNode children not parsed; primarily for internal use by the framework
334- (void)setUnknownChildren:(NSArray *)arr;
335- (NSArray *)unknownChildren;
336
337// XMLNode attributes not parsed; primarily for internal use by the framework
338- (void)setUnknownAttributes:(NSArray *)arr;
339- (NSArray *)unknownAttributes;
340
341// feeds and their elements may exclude tracking of unknown child elements
342// and unknown attributes; see GDataServiceBase for more information
343- (void)setShouldIgnoreUnknowns:(BOOL)flag;
344- (BOOL)shouldIgnoreUnknowns;
345
346///////////////////////////////////////////////////////////////////////////////
347//
348//  Protected methods
349//
350//  All remaining methods are intended for use only by subclasses
351//  of GDataObject.
352//
353
354// this init method should  be used only when creating the base of a tree
355// containing surrogates (the surrogate map is a dictionary of
356// standard GDataObject classes to replacement subclasses); this method
357// calls through to [self initWithXMLElement:parent:]
358- (id)initWithXMLElement:(NSXMLElement *)element
359                  parent:(GDataObject *)parent
360          serviceVersion:(NSString *)serviceVersion
361              surrogates:(NSDictionary *)surrogates
362    shouldIgnoreUnknowns:(BOOL)shouldIgnoreUnknowns;
363
364- (void)addExtensionDeclarations; // subclasses may override this to declare extensions
365
366- (void)addParseDeclarations; // subclasses may override this to declare local attributes and content value
367
368- (void)clearExtensionDeclarationsCache; // used by GDataServiceBase and by subclasses
369
370// content stream and upload data: these always return NO/nil for objects
371// other than entries
372
373- (BOOL)generateContentInputStream:(NSInputStream **)outInputStream
374                            length:(unsigned long long *)outLength
375                           headers:(NSDictionary **)outHeaders;
376
377- (NSString *)uploadMIMEType;
378- (NSData *)uploadData;
379- (NSFileHandle *)uploadFileHandle;
380- (NSURL *)uploadLocationURL;
381- (BOOL)shouldUploadDataOnly;
382
383//
384// Extensions
385//
386
387// declaring a potential extension; applies to this object and its children
388- (void)addExtensionDeclarationForParentClass:(Class)parentClass
389                                   childClass:(Class)childClass;
390- (void)addExtensionDeclarationForParentClass:(Class)parentClass
391                                 childClasses:(Class)firstChildClass, ...;
392
393- (void)removeExtensionDeclarationForParentClass:(Class)parentClass
394                                      childClass:(Class)childClass;
395
396- (void)addAttributeExtensionDeclarationForParentClass:(Class)parentClass
397                                            childClass:(Class)childClass;
398- (void)removeAttributeExtensionDeclarationForParentClass:(Class)parentClass
399                                               childClass:(Class)childClass;
400
401// accessing actual extensions in this object
402- (NSArray *)objectsForExtensionClass:(Class)theClass;
403- (id)objectForExtensionClass:(Class)theClass;
404
405- (NSString *)attributeValueForExtensionClass:(Class)theClass;
406
407// replacing or adding actual extensions in this object
408- (void)setObjects:(NSArray *)objects forExtensionClass:(Class)theClass;
409- (void)setObject:(id)object forExtensionClass:(Class)theClass; // removes all previous objects for this class
410- (void)addObject:(id)object forExtensionClass:(Class)theClass;
411- (void)removeObject:(id)object forExtensionClass:(Class)theClass;
412
413- (void)setAttributeValue:(NSString *)str forExtensionClass:(Class)theClass;
414
415//
416// Local attributes
417//
418
419// derived classes may override parseAttributesForElement if they need to
420// inspect attributes prior to parsing of element content
421- (void)parseAttributesForElement:(NSXMLElement *)element;
422
423// derived classes should call -addLocalAttributeDeclarations in their
424// -addParseDeclarations method if they want element attributes to
425// automatically be parsed
426- (void)addLocalAttributeDeclarations:(NSArray *)attributeLocalNames;
427
428- (NSString *)stringValueForAttribute:(NSString *)name;
429- (NSNumber *)intNumberForAttribute:(NSString *)name;
430- (NSNumber *)doubleNumberForAttribute:(NSString *)name;
431- (NSNumber *)longLongNumberForAttribute:(NSString *)name;
432- (NSDecimalNumber *)decimalNumberForAttribute:(NSString *)name;
433- (GDataDateTime *)dateTimeForAttribute:(NSString *)name;
434- (BOOL)boolValueForAttribute:(NSString *)name defaultValue:(BOOL)defaultVal;
435
436// setting nil value for attribute removes it
437- (void)setStringValue:(NSString *)str forAttribute:(NSString *)name;
438- (void)setBoolValue:(BOOL)flag defaultValue:(BOOL)defaultVal forAttribute:(NSString *)name;
439- (void)setExplicitBoolValue:(BOOL)flag forAttribute:(NSString *)name;
440- (void)setDecimalNumberValue:(NSDecimalNumber *)num forAttribute:(NSString *)name;
441- (void)setDateTimeValue:(GDataDateTime *)cdate forAttribute:(NSString *)name;
442
443// dictionary of all local attributes actually found in the XML element
444- (void)setAttributes:(NSDictionary *)dict;
445- (NSDictionary *)attributes;
446
447
448//
449// Element Content Value
450//
451
452// derived classes should call -addContentValueDeclaration in their
453// -addParseDeclarations method if they want element content to
454// automatically be parsed as a string
455- (void)addContentValueDeclaration;
456- (BOOL)hasDeclaredContentValue;
457- (void)setContentStringValue:(NSString *)str;
458- (NSString *)contentStringValue;
459
460//
461// Unparsed XML child elements
462//
463
464// derived classes should call -addXMLValuesDeclaration in their
465// -addParseDeclarations method if they want all child elements to
466// be held as an array of NSXMLElements
467- (void)addChildXMLElementsDeclaration;
468- (BOOL)hasDeclaredChildXMLElements;
469- (NSArray *)childXMLElements;
470- (void)setChildXMLElements:(NSArray *)array;
471- (void)addChildXMLElement:(NSXMLNode *)node;
472
473
474//
475// Dynamic GDataObject generation
476//
477// Feeds and entries can register themselves in their + (void)load
478// methods.  When XML is being parsed, if a matching category
479// is found, the proper class is instantiated.
480//
481// The scheme or term in a category may be nil (during
482// registration and lookup) to match any values.
483
484// class registration method
485+ (void)registerClass:(Class)theClass
486                inMap:(NSMutableDictionary **)map
487forCategoryWithScheme:(NSString *)scheme
488                 term:(NSString *)term;
489
490+ (Class)classForCategoryWithScheme:(NSString *)scheme
491                               term:(NSString *)term
492                            fromMap:(NSDictionary *)map;
493
494// objectClassForXMLElement: returns a found registered feed
495// or entry class for the XML according to its contained category
496//
497// If no registered class is found with a matching category,
498// this returns GDataFeedBase for feed elements, GDataEntryBase
499// for entry elements.
500//
501// If the element is not a <feed> or <entry> then nil is returned
502+ (Class)objectClassForXMLElement:(NSXMLElement *)element;
503
504//
505// XML parsing helpers (used in initWithXMLElement:parent:)
506//
507// Use these parsing helpers, since they remove the parsed items from the
508// "unknown children" list for this object.
509//
510
511// this creates a single object of the specified class for the first XML child
512// element with the specified name. Returns nil if no child element is present.
513- (id)objectForChildOfElement:(NSXMLElement *)parentElement
514                qualifiedName:(NSString *)qualifiedName
515                 namespaceURI:(NSString *)namespaceURI
516                  objectClass:(Class)objectClass;
517
518// this creates an array of objects of the specified class for each XML child
519// element with the specified name
520- (id)objectOrArrayForChildrenOfElement:(NSXMLElement *)parentElement
521                          qualifiedName:(NSString *)qualifiedName
522                           namespaceURI:(NSString *)namespaceURI
523                            objectClass:(Class)objectClass;
524
525// childOfElement:withName returns the element with the name, or nil of there
526// are not exactly one of the element
527- (NSXMLElement *)childWithQualifiedName:(NSString *)localName
528                            namespaceURI:(NSString *)namespaceURI
529                             fromElement:(NSXMLElement *)parentElement;
530
531// searches up the parent tree to find a surrogate for the standard class;
532// if there is  no surrogate, returns the standard class itself
533- (Class)classOrSurrogateForClass:(Class)standardClass;
534
535// element parsing
536
537+ (NSDictionary *)dictionaryForElementNamespaces:(NSXMLElement *)element;
538
539// this method avoids the "recursive descent" behavior of NSXMLElement's
540// stringValue; the element parameter may be nil
541- (NSString *)stringValueFromElement:(NSXMLElement *)element;
542
543- (GDataDateTime *)dateTimeFromElement:(NSXMLElement *)element;
544
545- (NSNumber *)intNumberValueFromElement:(NSXMLElement *)element;
546
547- (NSNumber *)doubleNumberValueFromElement:(NSXMLElement *)element;
548
549// attribute parsing
550- (NSString *)stringForAttributeName:(NSString *)attributeName
551                         fromElement:(NSXMLElement *)element;
552
553- (NSString *)stringForAttributeLocalName:(NSString *)localName
554                                      URI:(NSString *)attributeURI
555                              fromElement:(NSXMLElement *)element;
556
557- (GDataDateTime *)dateTimeForAttributeName:(NSString *)attributeName
558                                fromElement:(NSXMLElement *)element;
559
560- (NSXMLNode *)attributeForName:(NSString *)attributeName
561                    fromElement:(NSXMLElement *)element;
562
563- (BOOL)boolForAttributeName:(NSString *)attributeName
564                 fromElement:(NSXMLElement *)element;
565
566- (NSNumber *)doubleNumberForAttributeName:(NSString *)attributeName
567                               fromElement:(NSXMLElement *)element;
568
569- (NSNumber *)intNumberForAttributeName:(NSString *)attributeName
570                            fromElement:(NSXMLElement *)element;
571
572
573//
574// XML generation helpers
575//
576
577// subclasses start their -XMLElement method by calling this
578- (NSXMLElement *)XMLElementWithExtensionsAndDefaultName:(NSString *)defaultName;
579
580// adding attributes
581- (NSXMLNode *)addToElement:(NSXMLElement *)element
582     attributeValueIfNonNil:(NSString *)val
583                   withName:(NSString *)name;
584
585- (NSXMLNode *)addToElement:(NSXMLElement *)element
586     attributeValueIfNonNil:(NSString *)val
587          withQualifiedName:(NSString *)qName
588                        URI:(NSString *)attributeURI;
589
590- (NSXMLNode *)addToElement:(NSXMLElement *)element
591  attributeValueWithInteger:(NSInteger)val
592                   withName:(NSString *)name;
593
594// adding child elements
595- (NSXMLNode *)addToElement:(NSXMLElement *)element
596childWithStringValueIfNonEmpty:(NSString *)str
597                   withName:(NSString *)name;
598
599- (void)addToElement:(NSXMLElement *)element
600 XMLElementForObject:(id)object;
601
602- (void)addToElement:(NSXMLElement *)element
603 XMLElementsForArray:(NSArray *)arrayOfGDataObjects;
604
605//
606// decription method helpers
607//
608
609// the final descRecord in the list should be { nil, nil, 0 }
610- (void)addDescriptionRecords:(GDataDescriptionRecord *)descRecordList
611                      toItems:(NSMutableArray *)items;
612
613- (void)addToArray:(NSMutableArray *)stringItems
614objectDescriptionIfNonNil:(id)obj
615          withName:(NSString *)name;
616
617- (void)addAttributeDescriptionsToArray:(NSMutableArray *)stringItems;
618
619- (void)addContentDescriptionToArray:(NSMutableArray *)stringItems
620                            withName:(NSString *)name;
621
622// optional methods for overriding
623//
624// subclasses may implement -itemsForDescription and add to or
625// replace the superclass's array of items
626//
627// The base class itemsForDescription provides items for local attributes and
628// content, but not for any element extensions or attribute extensions
629- (NSMutableArray *)itemsForDescription;
630- (NSString *)descriptionWithItems:(NSArray *)items;
631- (NSString *)description;
632
633// coreProtocolVersionForServiceVersion maps the service version to the
634// underlying core protocol version.  The default implementation returns
635// the service version as the core protocol version.
636//
637// Entry and feed subclasses will need to implement this if their service
638// version numbers deviate from the core protocol version numbers.
639+ (NSString *)coreProtocolVersionForServiceVersion:(NSString *)str;
640
641@end
642
643@interface NSXMLElement (GDataObjectExtensions)
644
645// XML generation helpers
646
647// NSXMLNode's setStringValue: wipes out other children, so we'll use this
648// instead
649- (void)addStringValue:(NSString *)str;
650
651// creating objects from child elements
652+ (id)elementWithName:(NSString *)name attributeName:(NSString *)attrName attributeValue:(NSString *)attrValue;
653@end