org.simpleframework.xml.util.Dictionary Maven / Gradle / Ivy

Show more of this group Show more artifacts with this name
Show all versions of simple-xml Show documentation
Simple is a high performance XML serialization and configuration framework for Java
The newest version!
/*
 * Dictionary.java July 2006
 *
 * Copyright (C) 2006, Niall Gallagher 
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or 
 * implied. See the License for the specific language governing 
 * permissions and limitations under the License.
 */

package org.simpleframework.xml.util;

import java.util.AbstractSet;
import java.util.HashMap;
import java.util.Iterator;

/**
 * The Dictionary object represents a mapped set of entry
 * objects that can be serialized and deserialized. This is used when
 * there is a need to load a list of objects that can be mapped using 
 * a name attribute. Using this object avoids the need to implement a
 * commonly required pattern of building a map of XML element objects.
 *  *
 *    <dictionary>
 *       <entry name="example">
 *          <element>example text</element>
 *       </entry>
 *       <entry name="example">
 *          <element>example text</element>
 *       </entry>       
 *    </dictionary>
 * 
 * 
 * This can contain implementations of the Entry object 
 * which contains a required "name" attribute. Implementations of the
 * entry object can add further XML attributes an elements. This must
 * be annotated with the ElementList annotation in order
 * to be serialized and deserialized as an object field.
 * 
 * @author Niall Gallagher
 *
 * @see org.simpleframework.xml.util.Entry
 */ 
public class Dictionary extends AbstractSet {

   /**
    * Used to map the entries to their configured names.
    */         
   protected final Table map;
        
   /**
    * Constructor for the Dictionary object. This 
    * is used to create a set that contains entry objects mapped 
    * to an XML attribute name value. Entry objects added to this
    * dictionary can be retrieved using its name value.
    */ 
   public Dictionary() {
      this.map = new Table();           
   }

   /**
    * This method is used to add the provided entry to this set. If
    * an entry of the same name already existed within the set then
    * it is replaced with the specified Entry object.
    * 
    * @param item this is the entry object that is to be inserted
    */ 
   public boolean add(T item) {
      return map.put(item.getName(), item) != null;           
   }

   /**
    * This returns the number of Entry objects within
    * the dictionary. This will use the internal map to acquire the
    * number of entry objects that have been inserted to the map.
    *
    * @return this returns the number of entry objects in the set
    */ 
   public int size() {
      return map.size();            
   }

   /**
    * Returns an iterator of Entry objects which can be
    * used to remove items from this set. This will use the internal
    * map object and return the iterator for the map values.
    * 
    * @return this returns an iterator for the entry objects
    */ 
   public Iterator iterator() {
      return map.values().iterator();            
   }

   /**
    * This is used to acquire an Entry from the set by
    * its name. This uses the internal map to look for the entry, if
    * the entry exists it is returned, if not this returns null.
    * 
    * @param name this is the name of the entry object to retrieve
    *
    * @return this returns the entry mapped to the specified name
    */ 
   public T get(String name) {
      return map.get(name);           
   }

   /**
    * This is used to remove an Entry from the set by
    * its name. This uses the internal map to look for the entry, if
    * the entry exists it is returned and removed from the map.
    * 
    * @param name this is the name of the entry object to remove
    *
    * @return this returns the entry mapped to the specified name
    */ 
   public T remove(String name) {
      return map.remove(name);           
   }
 
   /**
    * The Table object is used to represent a map of
    * entries mapped to a string name. Each implementation of the
    * entry must contain a name attribute, which is used to insert
    * the entry into the map. This acts as a typedef.
    *
    * @see org.simpleframework.xml.util.Entry
    */
   private static class Table extends HashMap {
      
      /**
       * Constructor for the Table object. This will
       * create a map that is used to store the entry objects that
       * are serialized and deserialized to and from an XML source.
       */
      public Table() {
         super();
      }         
   }     
}