01: /*
02: * Copyright 2006 Sun Microsystems, Inc. All Rights Reserved.
03: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
04: *
05: * This code is free software; you can redistribute it and/or modify it
06: * under the terms of the GNU General Public License version 2 only, as
07: * published by the Free Software Foundation. Sun designates this
08: * particular file as subject to the "Classpath" exception as provided
09: * by Sun 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 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
22: * CA 95054 USA or visit www.sun.com if you need additional information or
23: * have any questions.
24: */
25:
26: package com.sun.xml.internal.bind.v2.runtime;
27:
28: import javax.xml.namespace.NamespaceContext;
29:
30: /**
31: * Maintains namespace<->prefix bindings.
32: *
33: * <p>
34: * This interface extends {@link NamespaceContext} and provides
35: * an additional functionality, which is necessary to declare
36: * namespaced attributes on elements. The added method is for
37: * self-consumption by the marshaller.
38: *
39: * This object is composed into a Serializer.
40: */
41: public interface NamespaceContext2 extends NamespaceContext {
42: /**
43: * Declares a new namespace binding within the current context.
44: *
45: * <p>
46: * The prefix is automatically assigned by MarshallingContext. If
47: * a given namespace URI is already declared, nothing happens.
48: *
49: * <p>
50: * It is <b>NOT</b> an error to declare the same namespace URI
51: * more than once.
52: *
53: * <p>
54: * For marshalling to work correctly, all namespace bindings
55: * for an element must be declared between its startElement method and
56: * its endAttributes event. Calling the same method with the same
57: * parameter between the endAttributes and the endElement returns
58: * the same prefix.
59: *
60: * @param requirePrefix
61: * If this parameter is true, this method must assign a prefix
62: * to this namespace, even if it's already bound to the default
63: * namespace. IOW, this method will never return null if this
64: * flag is true. This functionality is necessary to declare
65: * namespace URI used for attribute names.
66: * @param preferedPrefix
67: * If the caller has any particular preference to the
68: * prefix, pass that as a parameter. The callee will try
69: * to honor it. Set null if there's no particular preference.
70: *
71: * @return
72: * returns the assigned prefix. If the namespace is bound to
73: * the default namespace, null is returned.
74: */
75: String declareNamespace(String namespaceUri, String preferedPrefix,
76: boolean requirePrefix);
77: }
|