001//
002// This file was generated by the JavaTM Architecture for XML Binding(JAXB) Reference Implementation, v1.0.6-01/24/2006 06:15 PM(kohsuke)-fcs 
003// See <a href="http://java.sun.com/xml/jaxb">http://java.sun.com/xml/jaxb</a> 
004// Any modifications to this file will be lost upon recompilation of the source schema. 
005// Generated on: 2012.10.03 at 04:27:47 AM CEST 
006//
007
008package org.jdtaus.mojo.resource.model.impl.runtime;
009
010import javax.xml.namespace.NamespaceContext;
011
012/**
013 * Maintains namespace&lt;->prefix bindings.
014 * 
015 * <p>
016 * This interface extends {@link NamespaceContext} and provides
017 * an additional functionality, which is necessary to declare
018 * namespaced attributes on elements. The added method is for
019 * self-consumption by the marshaller.
020 * 
021 * This object is composed into a Serializer.
022 */
023public interface NamespaceContext2 extends NamespaceContext
024{
025    /**
026     * Declares a new namespace binding within the current context.
027     * 
028     * <p>
029     * The prefix is automatically assigned by MarshallingContext. If
030     * a given namespace URI is already declared, nothing happens.
031     * 
032     * <p>
033     * It is <b>NOT</b> an error to declare the same namespace URI
034     * more than once.
035     * 
036     * <p>
037     * For marshalling to work correctly, all namespace bindings
038     * for an element must be declared between its startElement method and
039     * its endAttributes event. Calling the same method with the same
040     * parameter between the endAttributes and the endElement returns
041     * the same prefix.
042     * 
043     * @param   requirePrefix
044     *      If this parameter is true, this method must assign a prefix
045     *      to this namespace, even if it's already bound to the default
046     *      namespace. IOW, this method will never return null if this
047     *      flag is true. This functionality is necessary to declare
048     *      namespace URI used for attribute names.
049     * @param   preferedPrefix
050     *      If the caller has any particular preference to the
051     *      prefix, pass that as a parameter. The callee will try
052     *      to honor it. Set null if there's no particular preference.
053     * 
054     * @return
055     *      returns the assigned prefix. If the namespace is bound to
056     *      the default namespace, null is returned.
057     */
058    String declareNamespace( String namespaceUri, String preferedPrefix, boolean requirePrefix );
059}