Fri, 24 Oct 2014 15:02:28 +0200
8054367: More references for endpoints
Summary: fix also reviewed by Iaroslav.Savytskyi@oracle.com, Alexander.Fomin@oracle.com
Reviewed-by: mullan, skoivu
1 /*
2 * Copyright (c) 1997, 2011, 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 */
26 package com.sun.xml.internal.bind.v2.runtime;
28 import javax.xml.namespace.NamespaceContext;
30 import com.sun.istack.internal.NotNull;
32 /**
33 * Maintains namespace<->prefix bindings.
34 *
35 * <p>
36 * This interface extends {@link NamespaceContext} and provides
37 * an additional functionality, which is necessary to declare
38 * namespaced attributes on elements. The added method is for
39 * self-consumption by the marshaller.
40 *
41 * This object is composed into a Serializer.
42 */
43 public interface NamespaceContext2 extends NamespaceContext
44 {
45 /**
46 * Declares a new namespace binding within the current context.
47 *
48 * <p>
49 * The prefix is automatically assigned by MarshallingContext. If
50 * a given namespace URI is already declared, nothing happens.
51 *
52 * <p>
53 * It is <b>NOT</b> an error to declare the same namespace URI
54 * more than once.
55 *
56 * <p>
57 * For marshalling to work correctly, all namespace bindings
58 * for an element must be declared between its startElement method and
59 * its endAttributes event. Calling the same method with the same
60 * parameter between the endAttributes and the endElement returns
61 * the same prefix.
62 *
63 * @param requirePrefix
64 * If this parameter is true, this method must assign a prefix
65 * to this namespace, even if it's already bound to the default
66 * namespace. IOW, this method will never return null if this
67 * flag is true. This functionality is necessary to declare
68 * namespace URI used for attribute names.
69 * @param preferedPrefix
70 * If the caller has any particular preference to the
71 * prefix, pass that as a parameter. The callee will try
72 * to honor it. Set null if there's no particular preference.
73 *
74 * @return
75 * returns the assigned prefix. If the namespace is bound to
76 * the default namespace, null is returned.
77 */
78 String declareNamespace( String namespaceUri, String preferedPrefix, boolean requirePrefix );
80 /**
81 * Forcibly make a namespace declaration in effect.
82 *
83 * If the (prefix,uri) binding is already in-scope, this method
84 * simply returns the assigned prefix index. Otherwise a new
85 * declaration will be put.
86 */
87 int force(@NotNull String uri, @NotNull String prefix);
88 }