1 // ================================================================================================= 2 // ADOBE SYSTEMS INCORPORATED 3 // Copyright 2006-2007 Adobe Systems Incorporated 4 // All Rights Reserved 5 // 6 // NOTICE: Adobe permits you to use, modify, and distribute this file in accordance with the terms 7 // of the Adobe license agreement accompanying it. 8 // ================================================================================================= 9 10 package com.adobe.xmp; 11 12 import java.util.Calendar; 13 14 import com.adobe.xmp.options.IteratorOptions; 15 import com.adobe.xmp.options.PropertyOptions; 16 import com.adobe.xmp.properties.XMPProperty; 17 18 19 /** 20 * This class represents the set of XMP metadata as a DOM representation. It has methods to read and 21 * modify all kinds of properties, create an iterator over all properties and serialize the metadata 22 * to a String, byte-array or <code>OutputStream</code>. 23 * 24 * @since 20.01.2006 25 */ 26 public interface XMPMeta extends Cloneable 27 { 28 // --------------------------------------------------------------------------------------------- 29 // Basic property manipulation functions 30 31 /** 32 * The property value getter-methods all take a property specification: the first two parameters 33 * are always the top level namespace URI (the "schema" namespace) and the basic name 34 * of the property being referenced. See the introductory discussion of path expression usage 35 * for more information. 36 * <p> 37 * All of the functions return an object inherited from <code>PropertyBase</code> or 38 * <code>null</code> if the property does not exists. The result object contains the value of 39 * the property and option flags describing the property. Arrays and the non-leaf levels of 40 * nodes do not have values. 41 * <p> 42 * See {@link PropertyOptions} for detailed information about the options. 43 * <p> 44 * This is the simplest property getter, mainly for top level simple properties or after using 45 * the path composition functions in XMPPathFactory. 46 * 47 * @param schemaNS The namespace URI for the property. May be <code>null</code> or the empty 48 * string if the first component of the propName path contains a namespace prefix. The 49 * URI must be for a registered namespace. 50 * @param propName The name of the property. May be a general path expression, must not be 51 * <code>null</code> or the empty string. Using a namespace prefix on the first 52 * component is optional. If present without a schemaNS value then the prefix specifies 53 * the namespace. The prefix must be for a registered namespace. If both a schemaNS URI 54 * and propName prefix are present, they must be corresponding parts of a registered 55 * namespace. 56 * @return Returns a <code>XMPProperty</code> containing the value and the options or 57 * <code>null</code> if the property does not exist. 58 * @throws XMPException Wraps all errors and exceptions that may occur. 59 */ getProperty(String schemaNS, String propName)60 XMPProperty getProperty(String schemaNS, String propName) throws XMPException; 61 62 63 /** 64 * Provides access to items within an array. The index is passed as an integer, you need not 65 * worry about the path string syntax for array items, convert a loop index to a string, etc. 66 * 67 * @param schemaNS The namespace URI for the array. Has the same usage as in getProperty. 68 * @param arrayName The name of the array. May be a general path expression, must not be 69 * <code>null</code> or the empty string. Has the same namespace prefix usage as 70 * propName in <code>getProperty()</code>. 71 * @param itemIndex The index of the desired item. Arrays in XMP are indexed from 1. The 72 * constant {@link XMPConst#ARRAY_LAST_ITEM} always refers to the last existing array 73 * item. 74 * @return Returns a <code>XMPProperty</code> containing the value and the options or 75 * <code>null</code> if the property does not exist. 76 * @throws XMPException Wraps all errors and exceptions that may occur. 77 */ getArrayItem(String schemaNS, String arrayName, int itemIndex)78 XMPProperty getArrayItem(String schemaNS, String arrayName, int itemIndex) throws XMPException; 79 80 81 /** 82 * Returns the number of items in the array. 83 * 84 * @param schemaNS The namespace URI for the array. Has the same usage as in getProperty. 85 * @param arrayName The name of the array. May be a general path expression, must not be 86 * <code>null</code> or the empty string. Has the same namespace prefix usage as 87 * propName in <code>getProperty()</code>. 88 * @return Returns the number of items in the array. 89 * @throws XMPException Wraps all errors and exceptions that may occur. 90 */ countArrayItems(String schemaNS, String arrayName)91 int countArrayItems(String schemaNS, String arrayName) throws XMPException; 92 93 94 /** 95 * Provides access to fields within a nested structure. The namespace for the field is passed as 96 * a URI, you need not worry about the path string syntax. 97 * <p> 98 * The names of fields should be XML qualified names, that is within an XML namespace. The path 99 * syntax for a qualified name uses the namespace prefix. This is unreliable since the prefix is 100 * never guaranteed. The URI is the formal name, the prefix is just a local shorthand in a given 101 * sequence of XML text. 102 * 103 * @param schemaNS The namespace URI for the struct. Has the same usage as in getProperty. 104 * @param structName The name of the struct. May be a general path expression, must not be 105 * <code>null</code> or the empty string. Has the same namespace prefix usage as 106 * propName in <code>getProperty()</code>. 107 * @param fieldNS The namespace URI for the field. Has the same URI and prefix usage as the 108 * schemaNS parameter. 109 * @param fieldName The name of the field. Must be a single XML name, must not be 110 * <code>null</code> or the empty string. Has the same namespace prefix usage as the 111 * structName parameter. 112 * @return Returns a <code>XMPProperty</code> containing the value and the options or 113 * <code>null</code> if the property does not exist. Arrays and non-leaf levels of 114 * structs do not have values. 115 * @throws XMPException Wraps all errors and exceptions that may occur. 116 */ getStructField( String schemaNS, String structName, String fieldNS, String fieldName)117 XMPProperty getStructField( 118 String schemaNS, 119 String structName, 120 String fieldNS, 121 String fieldName) throws XMPException; 122 123 124 /** 125 * Provides access to a qualifier attached to a property. The namespace for the qualifier is 126 * passed as a URI, you need not worry about the path string syntax. In many regards qualifiers 127 * are like struct fields. See the introductory discussion of qualified properties for more 128 * information. 129 * <p> 130 * The names of qualifiers should be XML qualified names, that is within an XML namespace. The 131 * path syntax for a qualified name uses the namespace prefix. This is unreliable since the 132 * prefix is never guaranteed. The URI is the formal name, the prefix is just a local shorthand 133 * in a given sequence of XML text. 134 * <p> 135 * <em>Note:</em> Qualifiers are only supported for simple leaf properties at this time. 136 * 137 * @param schemaNS The namespace URI for the struct. Has the same usage as in getProperty. 138 * @param propName The name of the property to which the qualifier is attached. May be a general 139 * path expression, must not be <code>null</code> or the empty string. Has the same 140 * namespace prefix usage as in <code>getProperty()</code>. 141 * @param qualNS The namespace URI for the qualifier. Has the same URI and prefix usage as the 142 * schemaNS parameter. 143 * @param qualName The name of the qualifier. Must be a single XML name, must not be 144 * <code>null</code> or the empty string. Has the same namespace prefix usage as the 145 * propName parameter. 146 * @return Returns a <code>XMPProperty</code> containing the value and the options of the 147 * qualifier or <code>null</code> if the property does not exist. The name of the 148 * qualifier must be a single XML name, must not be <code>null</code> or the empty 149 * string. Has the same namespace prefix usage as the propName parameter. 150 * <p> 151 * The value of the qualifier is only set if it has one (Arrays and non-leaf levels of 152 * structs do not have values). 153 * @throws XMPException Wraps all errors and exceptions that may occur. 154 */ getQualifier( String schemaNS, String propName, String qualNS, String qualName)155 XMPProperty getQualifier( 156 String schemaNS, 157 String propName, 158 String qualNS, 159 String qualName) throws XMPException; 160 161 162 163 // --------------------------------------------------------------------------------------------- 164 // Functions for setting property values 165 166 /** 167 * The property value <code>setters</code> all take a property specification, their 168 * differences are in the form of this. The first two parameters are always the top level 169 * namespace URI (the <code>schema</code> namespace) and the basic name of the property being 170 * referenced. See the introductory discussion of path expression usage for more information. 171 * <p> 172 * All of the functions take a string value for the property and option flags describing the 173 * property. The value must be Unicode in UTF-8 encoding. Arrays and non-leaf levels of structs 174 * do not have values. Empty arrays and structs may be created using appropriate option flags. 175 * All levels of structs that is assigned implicitly are created if necessary. appendArayItem 176 * implicitly creates the named array if necessary. 177 * <p> 178 * See {@link PropertyOptions} for detailed information about the options. 179 * <p> 180 * This is the simplest property setter, mainly for top level simple properties or after using 181 * the path composition functions in {@link XMPPathFactory}. 182 * 183 * @param schemaNS The namespace URI for the property. Has the same usage as in getProperty. 184 * @param propName The name of the property. 185 * Has the same usage as in <code>getProperty()</code>. 186 * @param propValue the value for the property (only leaf properties have a value). 187 * Arrays and non-leaf levels of structs do not have values. 188 * Must be <code>null</code> if the value is not relevant.<br/> 189 * The value is automatically detected: Boolean, Integer, Long, Double, XMPDateTime and 190 * byte[] are handled, on all other <code>toString()</code> is called. 191 * 192 * @param options Option flags describing the property. See the earlier description. 193 * @throws XMPException Wraps all errors and exceptions that may occur. 194 */ setProperty( String schemaNS, String propName, Object propValue, PropertyOptions options)195 void setProperty( 196 String schemaNS, 197 String propName, 198 Object propValue, 199 PropertyOptions options) throws XMPException; 200 201 202 /** 203 * @see XMPMeta#setProperty(String, String, Object, PropertyOptions) 204 * 205 * @param schemaNS The namespace URI 206 * @param propName The name of the property 207 * @param propValue the value for the property 208 * @throws XMPException Wraps all errors and exceptions 209 */ setProperty( String schemaNS, String propName, Object propValue)210 void setProperty( 211 String schemaNS, 212 String propName, 213 Object propValue) throws XMPException; 214 215 216 /** 217 * Replaces an item within an array. The index is passed as an integer, you need not worry about 218 * the path string syntax for array items, convert a loop index to a string, etc. The array 219 * passed must already exist. In normal usage the selected array item is modified. A new item is 220 * automatically appended if the index is the array size plus 1. 221 * 222 * @param schemaNS The namespace URI for the array. Has the same usage as in getProperty. 223 * @param arrayName The name of the array. May be a general path expression, must not be 224 * <code>null</code> or the empty string. Has the same namespace prefix usage as 225 * propName in getProperty. 226 * @param itemIndex The index of the desired item. Arrays in XMP are indexed from 1. To address 227 * the last existing item, use {@link XMPMeta#countArrayItems(String, String)} to find 228 * out the length of the array. 229 * @param itemValue the new value of the array item. Has the same usage as propValue in 230 * <code>setProperty()</code>. 231 * @param options the set options for the item. 232 * @throws XMPException Wraps all errors and exceptions that may occur. 233 */ setArrayItem( String schemaNS, String arrayName, int itemIndex, String itemValue, PropertyOptions options)234 void setArrayItem( 235 String schemaNS, 236 String arrayName, 237 int itemIndex, 238 String itemValue, 239 PropertyOptions options) throws XMPException; 240 241 242 /** 243 * @see XMPMeta#setArrayItem(String, String, int, String, PropertyOptions) 244 * 245 * @param schemaNS The namespace URI 246 * @param arrayName The name of the array 247 * @param itemIndex The index to insert the new item 248 * @param itemValue the new value of the array item 249 * @throws XMPException Wraps all errors and exceptions 250 */ setArrayItem( String schemaNS, String arrayName, int itemIndex, String itemValue)251 void setArrayItem( 252 String schemaNS, 253 String arrayName, 254 int itemIndex, 255 String itemValue) throws XMPException; 256 257 258 /** 259 * Inserts an item into an array previous to the given index. The index is passed as an integer, 260 * you need not worry about the path string syntax for array items, convert a loop index to a 261 * string, etc. The array passed must already exist. In normal usage the selected array item is 262 * modified. A new item is automatically appended if the index is the array size plus 1. 263 * 264 * @param schemaNS The namespace URI for the array. Has the same usage as in getProperty. 265 * @param arrayName The name of the array. May be a general path expression, must not be 266 * <code>null</code> or the empty string. Has the same namespace prefix usage as 267 * propName in getProperty. 268 * @param itemIndex The index to insert the new item. Arrays in XMP are indexed from 1. Use 269 * <code>XMPConst.ARRAY_LAST_ITEM</code> to append items. 270 * @param itemValue the new value of the array item. Has the same usage as 271 * propValue in <code>setProperty()</code>. 272 * @param options the set options that decide about the kind of the node. 273 * @throws XMPException Wraps all errors and exceptions that may occur. 274 */ insertArrayItem( String schemaNS, String arrayName, int itemIndex, String itemValue, PropertyOptions options)275 void insertArrayItem( 276 String schemaNS, 277 String arrayName, 278 int itemIndex, 279 String itemValue, 280 PropertyOptions options) throws XMPException; 281 282 283 /** 284 * @see XMPMeta#insertArrayItem(String, String, int, String, PropertyOptions) 285 * 286 * @param schemaNS The namespace URI for the array 287 * @param arrayName The name of the array 288 * @param itemIndex The index to insert the new item 289 * @param itemValue the value of the array item 290 * @throws XMPException Wraps all errors and exceptions 291 */ insertArrayItem( String schemaNS, String arrayName, int itemIndex, String itemValue)292 void insertArrayItem( 293 String schemaNS, 294 String arrayName, 295 int itemIndex, 296 String itemValue) throws XMPException; 297 298 299 /** 300 * Simplifies the construction of an array by not requiring that you pre-create an empty array. 301 * The array that is assigned is created automatically if it does not yet exist. Each call to 302 * appendArrayItem() appends an item to the array. The corresponding parameters have the same 303 * use as setArrayItem(). The arrayOptions parameter is used to specify what kind of array. If 304 * the array exists, it must have the specified form. 305 * 306 * @param schemaNS The namespace URI for the array. Has the same usage as in getProperty. 307 * @param arrayName The name of the array. May be a general path expression, must not be null or 308 * the empty string. Has the same namespace prefix usage as propPath in getProperty. 309 * @param arrayOptions Option flags describing the array form. The only valid options are 310 * <ul> 311 * <li> {@link PropertyOptions#ARRAY}, 312 * <li> {@link PropertyOptions#ARRAY_ORDERED}, 313 * <li> {@link PropertyOptions#ARRAY_ALTERNATE} or 314 * <li> {@link PropertyOptions#ARRAY_ALT_TEXT}. 315 * </ul> 316 * <em>Note:</em> the array options only need to be provided if the array is not 317 * already existing, otherwise you can set them to <code>null</code> or use 318 * {@link XMPMeta#appendArrayItem(String, String, String)}. 319 * @param itemValue the value of the array item. Has the same usage as propValue in getProperty. 320 * @param itemOptions Option flags describing the item to append ({@link PropertyOptions}) 321 * @throws XMPException Wraps all errors and exceptions that may occur. 322 */ appendArrayItem( String schemaNS, String arrayName, PropertyOptions arrayOptions, String itemValue, PropertyOptions itemOptions)323 void appendArrayItem( 324 String schemaNS, 325 String arrayName, 326 PropertyOptions arrayOptions, 327 String itemValue, 328 PropertyOptions itemOptions) throws XMPException; 329 330 331 /** 332 * @see XMPMeta#appendArrayItem(String, String, PropertyOptions, String, PropertyOptions) 333 * 334 * @param schemaNS The namespace URI for the array 335 * @param arrayName The name of the array 336 * @param itemValue the value of the array item 337 * @throws XMPException Wraps all errors and exceptions 338 */ appendArrayItem( String schemaNS, String arrayName, String itemValue)339 void appendArrayItem( 340 String schemaNS, 341 String arrayName, 342 String itemValue) throws XMPException; 343 344 345 /** 346 * Provides access to fields within a nested structure. The namespace for the field is passed as 347 * a URI, you need not worry about the path string syntax. The names of fields should be XML 348 * qualified names, that is within an XML namespace. The path syntax for a qualified name uses 349 * the namespace prefix, which is unreliable because the prefix is never guaranteed. The URI is 350 * the formal name, the prefix is just a local shorthand in a given sequence of XML text. 351 * 352 * @param schemaNS The namespace URI for the struct. Has the same usage as in getProperty. 353 * @param structName The name of the struct. May be a general path expression, must not be null 354 * or the empty string. Has the same namespace prefix usage as propName in getProperty. 355 * @param fieldNS The namespace URI for the field. Has the same URI and prefix usage as the 356 * schemaNS parameter. 357 * @param fieldName The name of the field. Must be a single XML name, must not be null or the 358 * empty string. Has the same namespace prefix usage as the structName parameter. 359 * @param fieldValue the value of thefield, if the field has a value. 360 * Has the same usage as propValue in getProperty. 361 * @param options Option flags describing the field. See the earlier description. 362 * @throws XMPException Wraps all errors and exceptions that may occur. 363 */ setStructField( String schemaNS, String structName, String fieldNS, String fieldName, String fieldValue, PropertyOptions options)364 void setStructField( 365 String schemaNS, 366 String structName, 367 String fieldNS, 368 String fieldName, 369 String fieldValue, 370 PropertyOptions options) throws XMPException; 371 372 373 /** 374 * @see XMPMeta#setStructField(String, String, String, String, String, PropertyOptions) 375 * 376 * @param schemaNS The namespace URI for the struct 377 * @param structName The name of the struct 378 * @param fieldNS The namespace URI for the field 379 * @param fieldName The name of the field 380 * @param fieldValue the value of the field 381 * @throws XMPException Wraps all errors and exceptions 382 */ setStructField( String schemaNS, String structName, String fieldNS, String fieldName, String fieldValue)383 void setStructField( 384 String schemaNS, 385 String structName, 386 String fieldNS, 387 String fieldName, 388 String fieldValue) throws XMPException; 389 390 391 /** 392 * Provides access to a qualifier attached to a property. The namespace for the qualifier is 393 * passed as a URI, you need not worry about the path string syntax. In many regards qualifiers 394 * are like struct fields. See the introductory discussion of qualified properties for more 395 * information. The names of qualifiers should be XML qualified names, that is within an XML 396 * namespace. The path syntax for a qualified name uses the namespace prefix, which is 397 * unreliable because the prefix is never guaranteed. The URI is the formal name, the prefix is 398 * just a local shorthand in a given sequence of XML text. The property the qualifier 399 * will be attached has to exist. 400 * 401 * @param schemaNS The namespace URI for the struct. Has the same usage as in getProperty. 402 * @param propName The name of the property to which the qualifier is attached. Has the same 403 * usage as in getProperty. 404 * @param qualNS The namespace URI for the qualifier. Has the same URI and prefix usage as the 405 * schemaNS parameter. 406 * @param qualName The name of the qualifier. Must be a single XML name, must not be 407 * <code>null</code> or the empty string. Has the same namespace prefix usage as the 408 * propName parameter. 409 * @param qualValue A pointer to the <code>null</code> terminated UTF-8 string that is the 410 * value of the qualifier, if the qualifier has a value. Has the same usage as propValue 411 * in getProperty. 412 * @param options Option flags describing the qualifier. See the earlier description. 413 * @throws XMPException Wraps all errors and exceptions that may occur. 414 */ setQualifier( String schemaNS, String propName, String qualNS, String qualName, String qualValue, PropertyOptions options)415 void setQualifier( 416 String schemaNS, 417 String propName, 418 String qualNS, 419 String qualName, 420 String qualValue, 421 PropertyOptions options) throws XMPException; 422 423 424 /** 425 * @see XMPMeta#setQualifier(String, String, String, String, String, PropertyOptions) 426 * 427 * @param schemaNS The namespace URI for the struct 428 * @param propName The name of the property to which the qualifier is attached 429 * @param qualNS The namespace URI for the qualifier 430 * @param qualName The name of the qualifier 431 * @param qualValue the value of the qualifier 432 * @throws XMPException Wraps all errors and exceptions 433 */ setQualifier( String schemaNS, String propName, String qualNS, String qualName, String qualValue)434 void setQualifier( 435 String schemaNS, 436 String propName, 437 String qualNS, 438 String qualName, 439 String qualValue) throws XMPException; 440 441 442 443 // --------------------------------------------------------------------------------------------- 444 // Functions for deleting and detecting properties. These should be obvious from the 445 // descriptions of the getters and setters. 446 447 /** 448 * Deletes the given XMP subtree rooted at the given property. It is not an error if the 449 * property does not exist. 450 * 451 * @param schemaNS The namespace URI for the property. Has the same usage as in 452 * <code>getProperty()</code>. 453 * @param propName The name of the property. Has the same usage as in getProperty. 454 */ deleteProperty(String schemaNS, String propName)455 void deleteProperty(String schemaNS, String propName); 456 457 458 /** 459 * Deletes the given XMP subtree rooted at the given array item. It is not an error if the array 460 * item does not exist. 461 * 462 * @param schemaNS The namespace URI for the array. Has the same usage as in getProperty. 463 * @param arrayName The name of the array. May be a general path expression, must not be 464 * <code>null</code> or the empty string. Has the same namespace prefix usage as 465 * propName in <code>getProperty()</code>. 466 * @param itemIndex The index of the desired item. Arrays in XMP are indexed from 1. The 467 * constant <code>XMPConst.ARRAY_LAST_ITEM</code> always refers to the last 468 * existing array item. 469 */ deleteArrayItem(String schemaNS, String arrayName, int itemIndex)470 void deleteArrayItem(String schemaNS, String arrayName, int itemIndex); 471 472 473 /** 474 * Deletes the given XMP subtree rooted at the given struct field. It is not an error if the 475 * field does not exist. 476 * 477 * @param schemaNS The namespace URI for the struct. Has the same usage as in 478 * <code>getProperty()</code>. 479 * @param structName The name of the struct. May be a general path expression, must not be 480 * <code>null</code> or the empty string. Has the same namespace prefix usage as 481 * propName in getProperty. 482 * @param fieldNS The namespace URI for the field. Has the same URI and prefix usage as the 483 * schemaNS parameter. 484 * @param fieldName The name of the field. Must be a single XML name, must not be 485 * <code>null</code> or the empty string. Has the same namespace prefix usage as the 486 * structName parameter. 487 */ deleteStructField(String schemaNS, String structName, String fieldNS, String fieldName)488 void deleteStructField(String schemaNS, String structName, String fieldNS, String fieldName); 489 490 491 /** 492 * Deletes the given XMP subtree rooted at the given qualifier. It is not an error if the 493 * qualifier does not exist. 494 * 495 * @param schemaNS The namespace URI for the struct. Has the same usage as in 496 * <code>getProperty()</code>. 497 * @param propName The name of the property to which the qualifier is attached. Has the same 498 * usage as in getProperty. 499 * @param qualNS The namespace URI for the qualifier. Has the same URI and prefix usage as the 500 * schemaNS parameter. 501 * @param qualName The name of the qualifier. Must be a single XML name, must not be 502 * <code>null</code> or the empty string. Has the same namespace prefix usage as the 503 * propName parameter. 504 */ deleteQualifier(String schemaNS, String propName, String qualNS, String qualName)505 void deleteQualifier(String schemaNS, String propName, String qualNS, String qualName); 506 507 508 /** 509 * Returns whether the property exists. 510 * 511 * @param schemaNS The namespace URI for the property. Has the same usage as in 512 * <code>getProperty()</code>. 513 * @param propName The name of the property. 514 * Has the same usage as in <code>getProperty()</code>. 515 * @return Returns true if the property exists. 516 */ doesPropertyExist(String schemaNS, String propName)517 boolean doesPropertyExist(String schemaNS, String propName); 518 519 520 /** 521 * Tells if the array item exists. 522 * 523 * @param schemaNS The namespace URI for the array. Has the same usage as in 524 * <code>getProperty()</code>. 525 * @param arrayName The name of the array. May be a general path expression, must not be 526 * <code>null</code> or the empty string. Has the same namespace prefix usage as 527 * propName in <code>getProperty()</code>. 528 * @param itemIndex The index of the desired item. Arrays in XMP are indexed from 1. The 529 * constant <code>XMPConst.ARRAY_LAST_ITEM</code> always refers to the last 530 * existing array item. 531 * @return Returns <code>true</code> if the array exists, <code>false</code> otherwise. 532 */ doesArrayItemExist(String schemaNS, String arrayName, int itemIndex)533 boolean doesArrayItemExist(String schemaNS, String arrayName, int itemIndex); 534 535 536 /** 537 * DoesStructFieldExist tells if the struct field exists. 538 * 539 * @param schemaNS The namespace URI for the struct. Has the same usage as in 540 * <code>getProperty()</code>. 541 * @param structName The name of the struct. May be a general path expression, must not be 542 * <code>null</code> or the empty string. Has the same namespace prefix usage as 543 * propName in <code>getProperty()</code>. 544 * @param fieldNS The namespace URI for the field. Has the same URI and prefix usage as the 545 * schemaNS parameter. 546 * @param fieldName The name of the field. Must be a single XML name, must not be 547 * <code>null</code> or the empty string. Has the same namespace prefix usage as the 548 * structName parameter. 549 * @return Returns true if the field exists. 550 */ doesStructFieldExist( String schemaNS, String structName, String fieldNS, String fieldName)551 boolean doesStructFieldExist( 552 String schemaNS, 553 String structName, 554 String fieldNS, 555 String fieldName); 556 557 558 /** 559 * DoesQualifierExist tells if the qualifier exists. 560 * 561 * @param schemaNS The namespace URI for the struct. Has the same usage as in 562 * <code>getProperty()</code>. 563 * @param propName The name of the property to which the qualifier is attached. Has the same 564 * usage as in <code>getProperty()</code>. 565 * @param qualNS The namespace URI for the qualifier. Has the same URI and prefix usage as the 566 * schemaNS parameter. 567 * @param qualName The name of the qualifier. Must be a single XML name, must not be 568 * <code>null</code> or the empty string. Has the same namespace prefix usage as the 569 * propName parameter. 570 * @return Returns true if the qualifier exists. 571 */ doesQualifierExist(String schemaNS, String propName, String qualNS, String qualName)572 boolean doesQualifierExist(String schemaNS, String propName, String qualNS, String qualName); 573 574 575 // --------------------------------------------------------------------------------------------- 576 // Specialized Get and Set functions 577 578 /** 579 * These functions provide convenient support for localized text properties, including a number 580 * of special and obscure aspects. Localized text properties are stored in alt-text arrays. They 581 * allow multiple concurrent localizations of a property value, for example a document title or 582 * copyright in several languages. The most important aspect of these functions is that they 583 * select an appropriate array item based on one or two RFC 3066 language tags. One of these 584 * languages, the "specific" language, is preferred and selected if there is an exact match. For 585 * many languages it is also possible to define a "generic" language that may be used if there 586 * is no specific language match. The generic language must be a valid RFC 3066 primary subtag, 587 * or the empty string. For example, a specific language of "en-US" should be used in the US, 588 * and a specific language of "en-UK" should be used in England. It is also appropriate to use 589 * "en" as the generic language in each case. If a US document goes to England, the "en-US" 590 * title is selected by using the "en" generic language and the "en-UK" specific language. It is 591 * considered poor practice, but allowed, to pass a specific language that is just an RFC 3066 592 * primary tag. For example "en" is not a good specific language, it should only be used as a 593 * generic language. Passing "i" or "x" as the generic language is also considered poor practice 594 * but allowed. Advice from the W3C about the use of RFC 3066 language tags can be found at: 595 * http://www.w3.org/International/articles/language-tags/ 596 * <p> 597 * <em>Note:</em> RFC 3066 language tags must be treated in a case insensitive manner. The XMP 598 * Toolkit does this by normalizing their capitalization: 599 * <ul> 600 * <li> The primary subtag is lower case, the suggested practice of ISO 639. 601 * <li> All 2 letter secondary subtags are upper case, the suggested practice of ISO 3166. 602 * <li> All other subtags are lower case. The XMP specification defines an artificial language, 603 * <li>"x-default", that is used to explicitly denote a default item in an alt-text array. 604 * </ul> 605 * The XMP toolkit normalizes alt-text arrays such that the x-default item is the first item. 606 * The SetLocalizedText function has several special features related to the x-default item, see 607 * its description for details. The selection of the array item is the same for GetLocalizedText 608 * and SetLocalizedText: 609 * <ul> 610 * <li> Look for an exact match with the specific language. 611 * <li> If a generic language is given, look for a partial match. 612 * <li> Look for an x-default item. 613 * <li> Choose the first item. 614 * </ul> 615 * A partial match with the generic language is where the start of the item's language matches 616 * the generic string and the next character is '-'. An exact match is also recognized as a 617 * degenerate case. It is fine to pass x-default as the specific language. In this case, 618 * selection of an x-default item is an exact match by the first rule, not a selection by the 619 * 3rd rule. The last 2 rules are fallbacks used when the specific and generic languages fail to 620 * produce a match. <code>getLocalizedText</code> returns information about a selected item in 621 * an alt-text array. The array item is selected according to the rules given above. 622 * 623 * <em>Note:</em> In a future version of this API a method 624 * using Java <code>java.lang.Locale</code> will be added. 625 * 626 * @param schemaNS The namespace URI for the alt-text array. Has the same usage as in 627 * <code>getProperty()</code>. 628 * @param altTextName The name of the alt-text array. May be a general path expression, must not 629 * be <code>null</code> or the empty string. Has the same namespace prefix usage as 630 * propName in <code>getProperty()</code>. 631 * @param genericLang The name of the generic language as an RFC 3066 primary subtag. May be 632 * <code>null</code> or the empty string if no generic language is wanted. 633 * @param specificLang The name of the specific language as an RFC 3066 tag. Must not be 634 * <code>null</code> or the empty string. 635 * @return Returns an <code>XMPProperty</code> containing the value, the actual language and 636 * the options if an appropriate alternate collection item exists, <code>null</code> 637 * if the property. 638 * does not exist. 639 * @throws XMPException Wraps all errors and exceptions that may occur. 640 */ getLocalizedText( String schemaNS, String altTextName, String genericLang, String specificLang)641 XMPProperty getLocalizedText( 642 String schemaNS, 643 String altTextName, 644 String genericLang, 645 String specificLang) throws XMPException; 646 647 648 /** 649 * Modifies the value of a selected item in an alt-text array. Creates an appropriate array item 650 * if necessary, and handles special cases for the x-default item. If the selected item is from 651 * a match with the specific language, the value of that item is modified. If the existing value 652 * of that item matches the existing value of the x-default item, the x-default item is also 653 * modified. If the array only has 1 existing item (which is not x-default), an x-default item 654 * is added with the given value. If the selected item is from a match with the generic language 655 * and there are no other generic matches, the value of that item is modified. If the existing 656 * value of that item matches the existing value of the x-default item, the x-default item is 657 * also modified. If the array only has 1 existing item (which is not x-default), an x-default 658 * item is added with the given value. If the selected item is from a partial match with the 659 * generic language and there are other partial matches, a new item is created for the specific 660 * language. The x-default item is not modified. If the selected item is from the last 2 rules 661 * then a new item is created for the specific language. If the array only had an x-default 662 * item, the x-default item is also modified. If the array was empty, items are created for the 663 * specific language and x-default. 664 * 665 * <em>Note:</em> In a future version of this API a method 666 * using Java <code>java.lang.Locale</code> will be added. 667 * 668 * 669 * @param schemaNS The namespace URI for the alt-text array. Has the same usage as in 670 * <code>getProperty()</code>. 671 * @param altTextName The name of the alt-text array. May be a general path expression, must not 672 * be <code>null</code> or the empty string. Has the same namespace prefix usage as 673 * propName in <code>getProperty()</code>. 674 * @param genericLang The name of the generic language as an RFC 3066 primary subtag. May be 675 * <code>null</code> or the empty string if no generic language is wanted. 676 * @param specificLang The name of the specific language as an RFC 3066 tag. Must not be 677 * <code>null</code> or the empty string. 678 * @param itemValue A pointer to the <code>null</code> terminated UTF-8 string that is the new 679 * value for the appropriate array item. 680 * @param options Option flags, none are defined at present. 681 * @throws XMPException Wraps all errors and exceptions that may occur. 682 */ setLocalizedText( String schemaNS, String altTextName, String genericLang, String specificLang, String itemValue, PropertyOptions options)683 void setLocalizedText( 684 String schemaNS, 685 String altTextName, 686 String genericLang, 687 String specificLang, 688 String itemValue, 689 PropertyOptions options) throws XMPException; 690 691 692 /** 693 * @see XMPMeta#setLocalizedText(String, String, String, String, String, PropertyOptions) 694 * 695 * @param schemaNS The namespace URI for the alt-text array 696 * @param altTextName The name of the alt-text array 697 * @param genericLang The name of the generic language 698 * @param specificLang The name of the specific language 699 * @param itemValue the new value for the appropriate array item 700 * @throws XMPException Wraps all errors and exceptions 701 */ setLocalizedText( String schemaNS, String altTextName, String genericLang, String specificLang, String itemValue)702 void setLocalizedText( 703 String schemaNS, 704 String altTextName, 705 String genericLang, 706 String specificLang, 707 String itemValue) throws XMPException; 708 709 710 711 // --------------------------------------------------------------------------------------------- 712 // Functions accessing properties as binary values. 713 714 715 /** 716 * These are very similar to <code>getProperty()</code> and <code>SetProperty()</code> above, 717 * but the value is returned or provided in a literal form instead of as a UTF-8 string. 718 * The path composition functions in <code>XMPPathFactory</code> may be used to compose an path 719 * expression for fields in nested structures, items in arrays, or qualifiers. 720 * 721 * @param schemaNS The namespace URI for the property. Has the same usage as in 722 * <code>getProperty()</code>. 723 * @param propName The name of the property. 724 * Has the same usage as in <code>getProperty()</code>. 725 * @return Returns a <code>Boolean</code> value or <code>null</code> 726 * if the property does not exist. 727 * @throws XMPException Wraps all exceptions that may occur, 728 * especially conversion errors. 729 */ getPropertyBoolean(String schemaNS, String propName)730 Boolean getPropertyBoolean(String schemaNS, String propName) throws XMPException; 731 732 733 /** 734 * Convenience method to retrieve the literal value of a property. 735 * 736 * @param schemaNS The namespace URI for the property. Has the same usage as in 737 * <code>getProperty()</code>. 738 * @param propName The name of the property. 739 * Has the same usage as in <code>getProperty()</code>. 740 * @return Returns an <code>Integer</code> value or <code>null</code> 741 * if the property does not exist. 742 * @throws XMPException Wraps all exceptions that may occur, 743 * especially conversion errors. 744 */ getPropertyInteger(String schemaNS, String propName)745 Integer getPropertyInteger(String schemaNS, String propName) throws XMPException; 746 747 748 /** 749 * Convenience method to retrieve the literal value of a property. 750 * 751 * @param schemaNS The namespace URI for the property. Has the same usage as in 752 * <code>getProperty()</code>. 753 * @param propName The name of the property. 754 * Has the same usage as in <code>getProperty()</code>. 755 * @return Returns a <code>Long</code> value or <code>null</code> 756 * if the property does not exist. 757 * @throws XMPException Wraps all exceptions that may occur, 758 * especially conversion errors. 759 */ getPropertyLong(String schemaNS, String propName)760 Long getPropertyLong(String schemaNS, String propName) throws XMPException; 761 762 763 /** 764 * Convenience method to retrieve the literal value of a property. 765 * 766 * @param schemaNS The namespace URI for the property. Has the same usage as in 767 * <code>getProperty()</code>. 768 * @param propName The name of the property. 769 * Has the same usage as in <code>getProperty()</code>. 770 * @return Returns a <code>Double</code> value or <code>null</code> 771 * if the property does not exist. 772 * @throws XMPException Wraps all exceptions that may occur, 773 * especially conversion errors. 774 */ getPropertyDouble(String schemaNS, String propName)775 Double getPropertyDouble(String schemaNS, String propName) throws XMPException; 776 777 778 /** 779 * Convenience method to retrieve the literal value of a property. 780 * 781 * @param schemaNS The namespace URI for the property. Has the same usage as in 782 * <code>getProperty()</code>. 783 * @param propName The name of the property. 784 * Has the same usage as in <code>getProperty()</code>. 785 * @return Returns a <code>XMPDateTime</code>-object or <code>null</code> 786 * if the property does not exist. 787 * @throws XMPException Wraps all exceptions that may occur, 788 * especially conversion errors. 789 */ getPropertyDate(String schemaNS, String propName)790 XMPDateTime getPropertyDate(String schemaNS, String propName) throws XMPException; 791 792 793 /** 794 * Convenience method to retrieve the literal value of a property. 795 * 796 * @param schemaNS The namespace URI for the property. Has the same usage as in 797 * <code>getProperty()</code>. 798 * @param propName The name of the property. 799 * Has the same usage as in <code>getProperty()</code>. 800 * @return Returns a Java <code>Calendar</code>-object or <code>null</code> 801 * if the property does not exist. 802 * @throws XMPException Wraps all exceptions that may occur, 803 * especially conversion errors. 804 */ getPropertyCalendar(String schemaNS, String propName)805 Calendar getPropertyCalendar(String schemaNS, String propName) throws XMPException; 806 807 808 /** 809 * Convenience method to retrieve the literal value of a property. 810 * 811 * @param schemaNS The namespace URI for the property. Has the same usage as in 812 * <code>getProperty()</code>. 813 * @param propName The name of the property. 814 * Has the same usage as in <code>getProperty()</code>. 815 * @return Returns a <code>byte[]</code>-array contained the decoded base64 value 816 * or <code>null</code> if the property does not exist. 817 * @throws XMPException Wraps all exceptions that may occur, 818 * especially conversion errors. 819 */ getPropertyBase64(String schemaNS, String propName)820 byte[] getPropertyBase64(String schemaNS, String propName) throws XMPException; 821 822 823 /** 824 * Convenience method to retrieve the literal value of a property. 825 * <em>Note:</em> There is no <code>setPropertyString()</code>, 826 * because <code>setProperty()</code> sets a string value. 827 * 828 * @param schemaNS The namespace URI for the property. Has the same usage as in 829 * <code>getProperty()</code>. 830 * @param propName The name of the property. 831 * Has the same usage as in <code>getProperty()</code>. 832 * @return Returns a <code>String</code> value or <code>null</code> 833 * if the property does not exist. 834 * @throws XMPException Wraps all exceptions that may occur, 835 * especially conversion errors. 836 */ getPropertyString(String schemaNS, String propName)837 String getPropertyString(String schemaNS, String propName) throws XMPException; 838 839 840 /** 841 * Convenience method to set a property to a literal <code>boolean</code> value. 842 * 843 * @param schemaNS The namespace URI for the property. Has the same usage as in 844 * <code>setProperty()</code>. 845 * @param propName The name of the property. 846 * Has the same usage as in <code>getProperty()</code>. 847 * @param propValue the literal property value as <code>boolean</code>. 848 * @param options options of the property to set (optional). 849 * @throws XMPException Wraps all exceptions that may occur. 850 */ setPropertyBoolean( String schemaNS, String propName, boolean propValue, PropertyOptions options)851 void setPropertyBoolean( 852 String schemaNS, 853 String propName, 854 boolean propValue, 855 PropertyOptions options) throws XMPException; 856 857 858 /** 859 * @see XMPMeta#setPropertyBoolean(String, String, boolean, PropertyOptions) 860 * 861 * @param schemaNS The namespace URI for the property 862 * @param propName The name of the property 863 * @param propValue the literal property value as <code>boolean</code> 864 * @throws XMPException Wraps all exceptions 865 */ setPropertyBoolean( String schemaNS, String propName, boolean propValue)866 void setPropertyBoolean( 867 String schemaNS, 868 String propName, 869 boolean propValue) throws XMPException; 870 871 872 /** 873 * Convenience method to set a property to a literal <code>int</code> value. 874 * 875 * @param schemaNS The namespace URI for the property. Has the same usage as in 876 * <code>setProperty()</code>. 877 * @param propName The name of the property. 878 * Has the same usage as in <code>getProperty()</code>. 879 * @param propValue the literal property value as <code>int</code>. 880 * @param options options of the property to set (optional). 881 * @throws XMPException Wraps all exceptions that may occur. 882 */ setPropertyInteger( String schemaNS, String propName, int propValue, PropertyOptions options)883 void setPropertyInteger( 884 String schemaNS, 885 String propName, 886 int propValue, 887 PropertyOptions options) throws XMPException; 888 889 890 /** 891 * @see XMPMeta#setPropertyInteger(String, String, int, PropertyOptions) 892 * 893 * @param schemaNS The namespace URI for the property 894 * @param propName The name of the property 895 * @param propValue the literal property value as <code>int</code> 896 * @throws XMPException Wraps all exceptions 897 */ setPropertyInteger( String schemaNS, String propName, int propValue)898 void setPropertyInteger( 899 String schemaNS, 900 String propName, 901 int propValue) throws XMPException; 902 903 904 /** 905 * Convenience method to set a property to a literal <code>long</code> value. 906 * 907 * @param schemaNS The namespace URI for the property. Has the same usage as in 908 * <code>setProperty()</code>. 909 * @param propName The name of the property. 910 * Has the same usage as in <code>getProperty()</code>. 911 * @param propValue the literal property value as <code>long</code>. 912 * @param options options of the property to set (optional). 913 * @throws XMPException Wraps all exceptions that may occur. 914 */ setPropertyLong( String schemaNS, String propName, long propValue, PropertyOptions options)915 void setPropertyLong( 916 String schemaNS, 917 String propName, 918 long propValue, 919 PropertyOptions options) throws XMPException; 920 921 922 /** 923 * @see XMPMeta#setPropertyLong(String, String, long, PropertyOptions) 924 * 925 * @param schemaNS The namespace URI for the property 926 * @param propName The name of the property 927 * @param propValue the literal property value as <code>long</code> 928 * @throws XMPException Wraps all exceptions 929 */ setPropertyLong( String schemaNS, String propName, long propValue)930 void setPropertyLong( 931 String schemaNS, 932 String propName, 933 long propValue) throws XMPException; 934 935 936 /** 937 * Convenience method to set a property to a literal <code>double</code> value. 938 * 939 * @param schemaNS The namespace URI for the property. Has the same usage as in 940 * <code>setProperty()</code>. 941 * @param propName The name of the property. 942 * Has the same usage as in <code>getProperty()</code>. 943 * @param propValue the literal property value as <code>double</code>. 944 * @param options options of the property to set (optional). 945 * @throws XMPException Wraps all exceptions that may occur. 946 */ setPropertyDouble( String schemaNS, String propName, double propValue, PropertyOptions options)947 void setPropertyDouble( 948 String schemaNS, 949 String propName, 950 double propValue, 951 PropertyOptions options) throws XMPException; 952 953 954 /** 955 * @see XMPMeta#setPropertyDouble(String, String, double, PropertyOptions) 956 * 957 * @param schemaNS The namespace URI for the property 958 * @param propName The name of the property 959 * @param propValue the literal property value as <code>double</code> 960 * @throws XMPException Wraps all exceptions 961 */ setPropertyDouble( String schemaNS, String propName, double propValue)962 void setPropertyDouble( 963 String schemaNS, 964 String propName, 965 double propValue) throws XMPException; 966 967 968 /** 969 * Convenience method to set a property with an XMPDateTime-object, 970 * which is serialized to an ISO8601 date. 971 * 972 * @param schemaNS The namespace URI for the property. Has the same usage as in 973 * <code>setProperty()</code>. 974 * @param propName The name of the property. 975 * Has the same usage as in <code>getProperty()</code>. 976 * @param propValue the property value as <code>XMPDateTime</code>. 977 * @param options options of the property to set (optional). 978 * @throws XMPException Wraps all exceptions that may occur. 979 */ setPropertyDate( String schemaNS, String propName, XMPDateTime propValue, PropertyOptions options)980 void setPropertyDate( 981 String schemaNS, 982 String propName, 983 XMPDateTime propValue, 984 PropertyOptions options) throws XMPException; 985 986 987 /** 988 * @see XMPMeta#setPropertyDate(String, String, XMPDateTime, PropertyOptions) 989 * 990 * @param schemaNS The namespace URI for the property 991 * @param propName The name of the property 992 * @param propValue the property value as <code>XMPDateTime</code> 993 * @throws XMPException Wraps all exceptions 994 */ setPropertyDate( String schemaNS, String propName, XMPDateTime propValue)995 void setPropertyDate( 996 String schemaNS, 997 String propName, 998 XMPDateTime propValue) throws XMPException; 999 1000 1001 /** 1002 * Convenience method to set a property with a Java Calendar-object, 1003 * which is serialized to an ISO8601 date. 1004 * 1005 * @param schemaNS The namespace URI for the property. Has the same usage as in 1006 * <code>setProperty()</code>. 1007 * @param propName The name of the property. 1008 * Has the same usage as in <code>getProperty()</code>. 1009 * @param propValue the property value as Java <code>Calendar</code>. 1010 * @param options options of the property to set (optional). 1011 * @throws XMPException Wraps all exceptions that may occur. 1012 */ setPropertyCalendar( String schemaNS, String propName, Calendar propValue, PropertyOptions options)1013 void setPropertyCalendar( 1014 String schemaNS, 1015 String propName, 1016 Calendar propValue, 1017 PropertyOptions options) throws XMPException; 1018 1019 1020 /** 1021 * @see XMPMeta#setPropertyCalendar(String, String, Calendar, PropertyOptions) 1022 * 1023 * @param schemaNS The namespace URI for the property 1024 * @param propName The name of the property 1025 * @param propValue the property value as <code>Calendar</code> 1026 * @throws XMPException Wraps all exceptions 1027 */ setPropertyCalendar( String schemaNS, String propName, Calendar propValue)1028 void setPropertyCalendar( 1029 String schemaNS, 1030 String propName, 1031 Calendar propValue) throws XMPException; 1032 1033 1034 /** 1035 * Convenience method to set a property from a binary <code>byte[]</code>-array, 1036 * which is serialized as base64-string. 1037 * 1038 * @param schemaNS The namespace URI for the property. Has the same usage as in 1039 * <code>setProperty()</code>. 1040 * @param propName The name of the property. 1041 * Has the same usage as in <code>getProperty()</code>. 1042 * @param propValue the literal property value as byte array. 1043 * @param options options of the property to set (optional). 1044 * @throws XMPException Wraps all exceptions that may occur. 1045 */ setPropertyBase64( String schemaNS, String propName, byte[] propValue, PropertyOptions options)1046 void setPropertyBase64( 1047 String schemaNS, 1048 String propName, 1049 byte[] propValue, 1050 PropertyOptions options) throws XMPException; 1051 1052 1053 /** 1054 * @see XMPMeta#setPropertyBase64(String, String, byte[], PropertyOptions) 1055 * 1056 * @param schemaNS The namespace URI for the property 1057 * @param propName The name of the property 1058 * @param propValue the literal property value as byte array 1059 * @throws XMPException Wraps all exceptions 1060 */ setPropertyBase64( String schemaNS, String propName, byte[] propValue)1061 void setPropertyBase64( 1062 String schemaNS, 1063 String propName, 1064 byte[] propValue) throws XMPException; 1065 1066 1067 /** 1068 * Constructs an iterator for the properties within this XMP object. 1069 * 1070 * @return Returns an <code>XMPIterator</code>. 1071 * @see XMPMeta#iterator(String, String, IteratorOptions) 1072 * @throws XMPException Wraps all errors and exceptions that may occur. 1073 */ iterator()1074 XMPIterator iterator() throws XMPException; 1075 1076 1077 /** 1078 * Constructs an iterator for the properties within this XMP object using some options. 1079 * 1080 * @param options Option flags to control the iteration. 1081 * @return Returns an <code>XMPIterator</code>. 1082 * @see XMPMeta#iterator(String, String, IteratorOptions) 1083 * @throws XMPException Wraps all errors and exceptions that may occur. 1084 */ iterator(IteratorOptions options)1085 XMPIterator iterator(IteratorOptions options) throws XMPException; 1086 1087 1088 /** 1089 * Construct an iterator for the properties within an XMP object. The general operation of an 1090 * XMP object iterator was. According to the parameters it iterates the entire data tree, 1091 * properties within a specific schema, or a subtree rooted at a specific node. 1092 * 1093 * @param schemaNS Optional schema namespace URI to restrict the iteration. Omitted (visit all 1094 * schema) by passing <code>null</code> or empty String. 1095 * @param propName Optional property name to restrict the iteration. May be an arbitrary path 1096 * expression. Omitted (visit all properties) by passing <code>null</code> or empty 1097 * String. If no schema URI is given, it is ignored. 1098 * @param options Option flags to control the iteration. See {@link IteratorOptions} for 1099 * details. 1100 * @return Returns an <code>XMPIterator</code> for this <code>XMPMeta</code>-object 1101 * considering the given options. 1102 * @throws XMPException Wraps all errors and exceptions that may occur. 1103 */ iterator( String schemaNS, String propName, IteratorOptions options)1104 XMPIterator iterator( 1105 String schemaNS, 1106 String propName, 1107 IteratorOptions options) throws XMPException; 1108 1109 1110 /** 1111 * This correlates to the about-attribute, 1112 * returns the empty String if no name is set. 1113 * 1114 * @return Returns the name of the XMP object. 1115 */ getObjectName()1116 String getObjectName(); 1117 1118 1119 /** 1120 * @param name Sets the name of the XMP object. 1121 */ setObjectName(String name)1122 void setObjectName(String name); 1123 1124 1125 /** 1126 * @return Returns the unparsed content of the <?xpacket> processing instruction. 1127 * This contains normally the attribute-like elements 'begin="<BOM>" 1128 * id="W5M0MpCehiHzreSzNTczkc9d"' and possibly the deprecated elements 'bytes="1234"' or 1129 * 'encoding="XXX"'. If the parsed packet has not been wrapped into an xpacket, 1130 * <code>null</code> is returned. 1131 */ getPacketHeader()1132 String getPacketHeader(); 1133 1134 1135 /** 1136 * Clones the complete metadata tree. 1137 * 1138 * @return Returns a deep copy of this instance. 1139 */ clone()1140 Object clone(); 1141 1142 1143 /** 1144 * Sorts the complete datamodel according to the following rules: 1145 * <ul> 1146 * <li>Schema nodes are sorted by prefix. 1147 * <li>Properties at top level and within structs are sorted by full name, that is 1148 * prefix + local name. 1149 * <li>Array items are not sorted, even if they have no certain order such as bags. 1150 * <li>Qualifier are sorted, with the exception of "xml:lang" and/or "rdf:type" 1151 * that stay at the top of the list in that order. 1152 * </ul> 1153 */ sort()1154 void sort(); 1155 1156 1157 /** 1158 * Renders this node and the tree unter this node in a human readable form. 1159 * @return Returns a multiline string containing the dump. 1160 */ dumpObject()1161 String dumpObject(); 1162 }