1 /* 2 * Copyright (c) 1997, 2015, 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 26 package com.sun.xml.internal.bind.v2.runtime; 27 28 import javax.xml.namespace.NamespaceContext; 29 30 import com.sun.istack.internal.NotNull; 31 32 /** 33 * Maintains {@code 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 ); 79 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 }