1 // ================================================================================================= 2 // ADOBE SYSTEMS INCORPORATED 3 // Copyright 2006 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.Iterator; 13 14 15 /** 16 * Interface for the <code>XMPMeta</code> iteration services. 17 * <code>XMPIterator</code> provides a uniform means to iterate over the 18 * schema and properties within an XMP object. 19 * <p> 20 * The iteration over the schema and properties within an XMP object is very 21 * complex. It is helpful to have a thorough understanding of the XMP data tree. 22 * One way to learn this is to create some complex XMP and examine the output of 23 * <code>XMPMeta#toString</code>. This is also described in the XMP 24 * Specification, in the XMP Data Model chapter. 25 * <p> 26 * The top of the XMP data tree is a single root node. This does not explicitly 27 * appear in the dump and is never visited by an iterator (that is, it is never 28 * returned from <code>XMPIterator#next()</code>). Beneath the root are 29 * schema nodes. These are just collectors for top level properties in the same 30 * namespace. They are created and destroyed implicitly. Beneath the schema 31 * nodes are the property nodes. The nodes below a property node depend on its 32 * type (simple, struct, or array) and whether it has qualifiers. 33 * <p> 34 * An <code>XMPIterator</code> is created by XMPMeta#interator() constructor 35 * defines a starting point for the iteration and options that control how it 36 * proceeds. By default the iteration starts at the root and visits all nodes 37 * beneath it in a depth first manner. The root node is not visited, the first 38 * visited node is a schema node. You can provide a schema name or property path 39 * to select a different starting node. By default this visits the named root 40 * node first then all nodes beneath it in a depth first manner. 41 * <p> 42 * The <code>XMPIterator#next()</code> method delivers the schema URI, path, 43 * and option flags for the node being visited. If the node is simple it also 44 * delivers the value. Qualifiers for this node are visited next. The fields of 45 * a struct or items of an array are visited after the qualifiers of the parent. 46 * <p> 47 * The options to control the iteration are: 48 * <ul> 49 * <li>JUST_CHILDREN - Visit just the immediate children of the root. Skip 50 * the root itself and all nodes below the immediate children. This omits the 51 * qualifiers of the immediate children, the qualifier nodes being below what 52 * they qualify, default is to visit the complete subtree. 53 * <li>UST_LEAFNODES - Visit just the leaf property nodes and their 54 * qualifiers. 55 * <li>JUST_LEAFNAME - Return just the leaf component of the node names. 56 * The default is to return the full xmp path. 57 * <li>OMIT_QUALIFIERS - Do not visit the qualifiers. 58 * <li>INCLUDE_ALIASES - Adds known alias properties to the properties in the iteration. 59 * <em>Note:</em> Not supported in Java XMPCore! 60 * </ul> 61 * <p> 62 * <code>next()</code> returns <code>XMPPropertyInfo</code>-objects and throws 63 * a <code>NoSuchElementException</code> if there are no more properties to 64 * return. 65 * 66 * @since 25.01.2006 67 */ 68 public interface XMPIterator extends Iterator 69 { 70 /** 71 * Skip the subtree below the current node when <code>next()</code> is 72 * called. 73 */ 74 void skipSubtree(); 75 76 77 /** 78 * Skip the subtree below and remaining siblings of the current node when 79 * <code>next()</code> is called. 80 */ 81 void skipSiblings(); 82 }
