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
10package com.adobe.xmp;
11
12import 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 */
68public 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}