001/*
002 * NodeMap.java July 2006
003 *
004 * Copyright (C) 2006, 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>NodeMap</code> object represents a map of nodes that
025 * can be set as name value pairs. This typically represents the
026 * attributes that belong to an element and is used as an neutral
027 * way to access an element for either an input or output event.
028 *
029 * @author Niall Gallagher
030 *
031 * @see org.simpleframework.xml.stream.Node
032 */ 
033public interface NodeMap<T extends Node> extends Iterable<String> {
034    
035    /**
036     * This is used to acquire the actual node this map represents.
037     * The source node provides further details on the context of
038     * the node, such as the parent name, the namespace, and even
039     * the value in the node. Care should be taken when using this. 
040     * 
041     * @return this returns the node that this map represents
042     */
043    T getNode();
044
045   /**
046    * This is used to get the name of the element that owns the
047    * nodes for the specified map. This can be used to determine
048    * which element the node map belongs to.
049    * 
050    * @return this returns the name of the owning element
051    */         
052   String getName();        
053
054   /**
055    * This is used to acquire the <code>Node</code> mapped to the
056    * given name. This returns a name value pair that represents
057    * either an attribute or element. If no node is mapped to the
058    * specified name then this method will return null.
059    *
060    * @param name this is the name of the node to retrieve
061    * 
062    * @return this will return the node mapped to the given name
063    */         
064   T get(String name);        
065
066   /**
067    * This is used to remove the <code>Node</code> mapped to the
068    * given name.  This returns a name value pair that represents
069    * either an attribute or element. If no node is mapped to the
070    * specified name then this method will return null.
071    *
072    * @param name this is the name of the node to remove
073    * 
074    * @return this will return the node mapped to the given name
075    */ 
076   T remove(String name);
077   
078   /**
079    * This returns an iterator for the names of all the nodes in
080    * this <code>NodeMap</code>. This allows the names to be 
081    * iterated within a for each loop in order to extract nodes.
082    *
083    * @return this returns the names of the nodes in the map
084    */ 
085   Iterator<String> iterator();
086
087   /**
088    * This is used to add a new <code>Node</code> to the map. The
089    * type of node that is created an added is left up to the map
090    * implementation. Once a node is created with the name value
091    * pair it can be retrieved and used.
092    *
093    * @param name this is the name of the node to be created
094    * @param value this is the value to be given to the node
095    * 
096    * @return this is the node that has been added to the map
097    */ 
098   T put(String name, String value);
099}