1/*
2 * Copyright (c) 1997, 2013, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation.  Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26package com.sun.xml.internal.org.jvnet.staxex;
27
28import javax.xml.namespace.NamespaceContext;
29import java.util.Iterator;
30
31/**
32 * Extended {@link NamespaceContext}.
33 *
34 * @author Kohsuke Kawaguchi
35 * @author Paul Sandoz
36 */
37public interface NamespaceContextEx extends NamespaceContext, Iterable<NamespaceContextEx.Binding> {
38
39    /**
40     * Iterates all the in-scope namespace bindings.
41     *
42     * <p>
43     * This method enumerates all the active in-scope namespace bindings.
44     * This does not include implicit bindings, such as
45     * {@code "xml"->"http://www.w3.org/XML/1998/namespace"}
46     * or {@code ""->""} (the implicit default namespace URI.)
47     *
48     * <p>
49     * The returned iterator may not include the same prefix more than once.
50     * For example, the returned iterator may only contain {@code f=ns2}
51     * if the document is as follows and this method is used at the bar element.
52     *
53     * <pre>{@code
54     * <foo xmlns:f='ns1'>
55     *   <bar xmlns:f='ns2'>
56     *     ...
57     * }</pre>
58     *
59     * <p>
60     * The iteration may be done in no particular order.
61     *
62     * @return
63     *      may return an empty iterator, but never null.
64     */
65    Iterator<Binding> iterator();
66
67    /**
68     * Prefix to namespace URI binding.
69     */
70    interface Binding {
71        /**
72         * Gets the prefix.
73         *
74         * <p>
75         * The default namespace URI is represented by using an
76         * empty string "", not null.
77         *
78         * @return
79         *      never null. String like "foo", "ns12", or "".
80         */
81        String getPrefix();
82
83        /**
84         * Gets the namespace URI.
85         *
86         * <p>
87         * The empty namespace URI is represented by using
88         * an empty string "", not null.
89         *
90         * @return
91         *      never null. String like "http://www.w3.org/XML/1998/namespace",
92         *      "urn:oasis:names:specification:docbook:dtd:xml:4.1.2", or "".
93         */
94        String getNamespaceURI();
95    }
96}
97