001/*
002 * NamespaceMap.java July 2008
003 *
004 * Copyright (C) 2008, Niall Gallagher <niallg@users.sf.net>
005 *
006 * Licensed under the Apache License, Version 2.0 (the "License");
007 * you may not use this file except in compliance with the License.
008 * You may obtain a copy of the License at
009 *
010 *     http://www.apache.org/licenses/LICENSE-2.0
011 *
012 * Unless required by applicable law or agreed to in writing, software
013 * distributed under the License is distributed on an "AS IS" BASIS,
014 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or 
015 * implied. See the License for the specific language governing 
016 * permissions and limitations under the License.
017 */
018
019package org.simpleframework.xml.stream;
020
021import java.util.Iterator;
022
023/**
024 * The <code>NamespaceMap</code> object is used store the namespaces
025 * for an element. Each namespace added to this map can be added
026 * with a prefix. A prefix is added only if the associated reference
027 * has not been added to a parent element. If a parent element has
028 * the associated reference, then the parents prefix is the one that
029 * will be returned when requested from this map. 
030 * 
031 * @author Niall Gallagher
032 */
033public interface NamespaceMap extends Iterable<String> {
034   
035   /**
036    * This is the prefix that is associated with the source element.
037    * If the source element does not contain a namespace reference
038    * then this will return its parents namespace. This ensures 
039    * that if a namespace has been declared its child elements will
040    * inherit its prefix.
041    * 
042    * @return this returns the prefix that is currently in scope
043    */
044   String getPrefix();
045
046   /**
047    * This acquires the prefix for the specified namespace reference.
048    * If the namespace reference has been set on this node with a
049    * given prefix then that prefix is returned, however if it has
050    * not been set this will search the parent elements to find the
051    * prefix that is in scope for the specified reference.
052    * 
053    * @param reference the reference to find a matching prefix for
054    * 
055    * @return this will return the prefix that is is scope
056    */
057   String getPrefix(String reference);
058   
059   /**
060    * This acquires the namespace reference for the specified prefix.
061    * If the provided prefix has been set on this node with a given
062    * reference then that reference is returned, however if it has
063    * not been set this will search the parent elements to find the
064    * reference that is in scope for the specified reference.
065    * 
066    * @param prefix the prefix to find a matching reference for
067    * 
068    * @return this will return the reference that is is scope
069    */
070   String getReference(String prefix);
071
072   /**
073    * This returns an iterator for the namespace of all the nodes 
074    * in this <code>NamespaceMap</code>. This allows the namespaces 
075    * to be iterated within a for each loop in order to extract the
076    * prefix values associated with the map.
077    *
078    * @return this returns the namespaces contained in this map
079    */ 
080   Iterator<String> iterator();
081   
082   /**
083    * This is used to add the namespace reference to the namespace
084    * map. If the namespace has been added to a parent node then
085    * this will not add the reference. The prefix added to the map
086    * will be the default namespace, which is an empty prefix.
087    * 
088    * @param reference this is the reference to be added 
089    * 
090    * @return this returns the prefix that has been replaced
091    */
092   String setReference(String reference);
093   
094   /**
095    * This is used to add the namespace reference to the namespace
096    * map. If the namespace has been added to a parent node then
097    * this will not add the reference. 
098    * 
099    * @param reference this is the reference to be added 
100    * @param prefix this is the prefix to be added to the reference
101    * 
102    * @return this returns the prefix that has been replaced
103    */
104   String setReference(String reference, String prefix);
105}