simple/simple-common/src/main/java/org/simpleframework/common/parse/MapParser.java - toolchain/jack - Git at Google

 /*
  * MapParser.java February 2005
  *
  * Copyright (C) 2005, Niall Gallagher <niallg@users.sf.net>
  *
  * 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.common.parse;

 import java.util.ArrayList;
 import java.util.Collection;
 import java.util.HashMap;
 import java.util.List;
 import java.util.Map;
 import java.util.Set;

 /**
  * The <code>MapParser</code> object represents a parser for name
  * value pairs. Any parser extending this will typically be parsing
  * name=value tokens or the like, and inserting these pairs into
  * the internal map. This type of parser is useful as it exposes all
  * pairs extracted using the <code>java.util.Map</code> interface
  * and as such can be used with the Java collections framework. The
  * internal map used by this is a <code>Hashtable</code>, however
  * subclasses are free to assign a different type to the map used.
  *
  * @author Niall Gallagher
  */
 public abstract class MapParser<T> extends Parser implements Map<T, T> {

    /**
     * Represents all values inserted to the map as a list of values.
     */
    protected Map<T, List<T>> all;

    /**
     * Represents the last value inserted into this map instance.
     */
    protected Map<T, T> map;

    /**
     * Constructor for the <code>MapParser</code> object. This is
     * used to create a new parser that makes use of a thread safe
     * map implementation. The <code>HashMap</code> is used so
     * that the resulting parser can be accessed in a concurrent
     * environment with the fear of data corruption.
     */
    protected MapParser(){
       this.all = new HashMap<T, List<T>>();
       this.map = new HashMap<T, T>();
    }

    /**
     * This is used to determine whether a token representing the
     * name of a pair has been inserted into the internal map. The
     * object passed into this method should be a string, as all
     * tokens stored within the map will be stored as strings.
     *
     * @param name this is the name of a pair within the map
     *
     * @return this returns true if the pair of that name exists
     */
    public boolean containsKey(Object name) {
       return map.containsKey(name);
    }

    /**
     * This method is used to determine whether any pair that has
     * been inserted into the internal map had the presented value.
     * If one or more pairs within the collected tokens contains
     * the value provided then this method will return true.
     *
     * @param value this is the value that is to be searched for
     *
     * @return this returns true if any value is equal to this
     */
    public boolean containsValue(Object value) {
       return map.containsValue(value);
    }

    /**
     * This method is used to acquire the name and value pairs that
     * have currently been collected by this parser. This is used
     * to determine which tokens have been extracted from the
     * source. It is useful when the tokens have to be gathered.
     *
     * @return this set of token pairs that have been extracted
     */
    public Set<Map.Entry<T, T>> entrySet() {
       return map.entrySet();
    }

    /**
     * The <code>get</code> method is used to acquire the value for
     * a named pair. So if a pair of name=value has been parsed and
     * inserted into the collection of tokens this will return the
     * value given the name. The value returned will be a string.
     *
     * @param name this is a string used to search for the value
     *
     * @return this is the value, as a string, that has been found
     */
    public T get(Object name) {
       return map.get(name);
    }

    /**
     * This method is used to acquire a <code>List</code> for all of
     * the values that have been put in to the map. The list allows
     * all values associated with the specified key. This enables a
     * parser to collect a number of associated tokens.
     *
     * @param key this is the key used to search for the value
     *
     * @return this is the list of values associated with the key
     */
    public List<T> getAll(Object key) {
       return all.get(key);
    }

    /**
     * This method is used to determine whether the parser has any
     * tokens available. If the <code>size</code> is zero then the
     * parser is empty and this returns true. The is acts as a
     * proxy the the <code>isEmpty</code> of the internal map.
     *
     * @return this is true if there are no available tokens
     */
    public boolean isEmpty() {
       return map.isEmpty();
    }

    /**
     * This is used to acquire the names for all the tokens that
     * have currently been collected by this parser. This is used
     * to determine which tokens have been extracted from the
     * source. It is useful when the tokens have to be gathered.
     *
     * @return the set of name tokens that have been extracted
     */
    public Set<T> keySet() {
       return map.keySet();
    }

    /**
     * The <code>put</code> method is used to insert the name and
     * value provided into the collection of tokens. Although it is
     * up to the parser to decide what values will be inserted it
     * is generally the case that the inserted tokens will be text.
     *
     * @param name this is the name token from a name=value pair
     * @param value this is the value token from a name=value pair
     *
     * @return this returns the previous value if there was any
     */
    public T put(T name, T value) {
       List<T> list = all.get(name);
       T first = map.get(name);

       if(list == null) {
          list = new ArrayList<T>();
          all.put(name, list);
       }
       list.add(value);

       if(first == null) {
          return map.put(name, value);
       }
       return null;
    }

    /**
     * This method is used to insert a collection of tokens into
     * the parsers map. This is used when another source of tokens
     * is required to populate the connection currently maintained
     * within this parsers internal map. Any tokens that currently
     * exist with similar names will be overwritten by this.
     *
     * @param data this is the collection of tokens to be added
     */
    public void putAll(Map<? extends T, ? extends T> data) {
       Set<? extends T> keySet = data.keySet();

       for(T key : keySet) {
          T value = data.get(key);

          if(value != null) {
             put(key, value);
          }
       }
    }

    /**
     * The <code>remove</code> method is used to remove the named
     * token pair from the collection of tokens. This acts like a
     * take, in that it will get the token value and remove if
     * from the collection of tokens the parser has stored.
     *
     * @param name this is a string used to search for the value
     *
     * @return this is the value, as a string, that is removed
     */
    public T remove(Object name) {
       return map.remove(name);
    }

    /**
     * This obviously enough provides the number of tokens that
     * have been inserted into the internal map. This acts as
     * a proxy method for the internal map <code>size</code>.
     *
     * @return this returns the number of tokens are available
     */
    public int size() {
       return map.size();
    }

    /**
     * This method is used to acquire the value for all tokens that
     * have currently been collected by this parser. This is used
     * to determine which tokens have been extracted from the
     * source. It is useful when the tokens have to be gathered.
     *
     * @return the list of value tokens that have been extracted
     */
    public Collection<T> values() {
       return map.values();
    }

    /**
     * The <code>clear</code> method is used to wipe out all the
     * currently existing tokens from the collection. This is used
     * to recycle the parser so that it can be used to parse some
     * other source of tokens without any lingering state.
     */
    public void clear() {
       all.clear();
       map.clear();
    }
 }
	/*
	* MapParser.java February 2005
	*
	* Copyright (C) 2005, Niall Gallagher <niallg@users.sf.net>
	*
	* 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.common.parse;

	import java.util.ArrayList;
	import java.util.Collection;
	import java.util.HashMap;
	import java.util.List;
	import java.util.Map;
	import java.util.Set;

	/**
	* The <code>MapParser</code> object represents a parser for name
	* value pairs. Any parser extending this will typically be parsing
	* name=value tokens or the like, and inserting these pairs into
	* the internal map. This type of parser is useful as it exposes all
	* pairs extracted using the <code>java.util.Map</code> interface
	* and as such can be used with the Java collections framework. The
	* internal map used by this is a <code>Hashtable</code>, however
	* subclasses are free to assign a different type to the map used.
	*
	* @author Niall Gallagher
	*/
	public abstract class MapParser<T> extends Parser implements Map<T, T> {

	/**
	* Represents all values inserted to the map as a list of values.
	*/
	protected Map<T, List<T>> all;

	/**
	* Represents the last value inserted into this map instance.
	*/
	protected Map<T, T> map;

	/**
	* Constructor for the <code>MapParser</code> object. This is
	* used to create a new parser that makes use of a thread safe
	* map implementation. The <code>HashMap</code> is used so
	* that the resulting parser can be accessed in a concurrent
	* environment with the fear of data corruption.
	*/
	protected MapParser(){
	this.all = new HashMap<T, List<T>>();
	this.map = new HashMap<T, T>();
	}

	/**
	* This is used to determine whether a token representing the
	* name of a pair has been inserted into the internal map. The
	* object passed into this method should be a string, as all
	* tokens stored within the map will be stored as strings.
	*
	* @param name this is the name of a pair within the map
	*
	* @return this returns true if the pair of that name exists
	*/
	public boolean containsKey(Object name) {
	return map.containsKey(name);
	}

	/**
	* This method is used to determine whether any pair that has
	* been inserted into the internal map had the presented value.
	* If one or more pairs within the collected tokens contains
	* the value provided then this method will return true.
	*
	* @param value this is the value that is to be searched for
	*
	* @return this returns true if any value is equal to this
	*/
	public boolean containsValue(Object value) {
	return map.containsValue(value);
	}

	/**
	* This method is used to acquire the name and value pairs that
	* have currently been collected by this parser. This is used
	* to determine which tokens have been extracted from the
	* source. It is useful when the tokens have to be gathered.
	*
	* @return this set of token pairs that have been extracted
	*/
	public Set<Map.Entry<T, T>> entrySet() {
	return map.entrySet();
	}

	/**
	* The <code>get</code> method is used to acquire the value for
	* a named pair. So if a pair of name=value has been parsed and
	* inserted into the collection of tokens this will return the
	* value given the name. The value returned will be a string.
	*
	* @param name this is a string used to search for the value
	*
	* @return this is the value, as a string, that has been found
	*/
	public T get(Object name) {
	return map.get(name);
	}

	/**
	* This method is used to acquire a <code>List</code> for all of
	* the values that have been put in to the map. The list allows
	* all values associated with the specified key. This enables a
	* parser to collect a number of associated tokens.
	*
	* @param key this is the key used to search for the value
	*
	* @return this is the list of values associated with the key
	*/
	public List<T> getAll(Object key) {
	return all.get(key);
	}

	/**
	* This method is used to determine whether the parser has any
	* tokens available. If the <code>size</code> is zero then the
	* parser is empty and this returns true. The is acts as a
	* proxy the the <code>isEmpty</code> of the internal map.
	*
	* @return this is true if there are no available tokens
	*/
	public boolean isEmpty() {
	return map.isEmpty();
	}

	/**
	* This is used to acquire the names for all the tokens that
	* have currently been collected by this parser. This is used
	* to determine which tokens have been extracted from the
	* source. It is useful when the tokens have to be gathered.
	*
	* @return the set of name tokens that have been extracted
	*/
	public Set<T> keySet() {
	return map.keySet();
	}

	/**
	* The <code>put</code> method is used to insert the name and
	* value provided into the collection of tokens. Although it is
	* up to the parser to decide what values will be inserted it
	* is generally the case that the inserted tokens will be text.
	*
	* @param name this is the name token from a name=value pair
	* @param value this is the value token from a name=value pair
	*
	* @return this returns the previous value if there was any
	*/
	public T put(T name, T value) {
	List<T> list = all.get(name);
	T first = map.get(name);

	if(list == null) {
	list = new ArrayList<T>();
	all.put(name, list);
	}
	list.add(value);

	if(first == null) {
	return map.put(name, value);
	}
	return null;
	}

	/**
	* This method is used to insert a collection of tokens into
	* the parsers map. This is used when another source of tokens
	* is required to populate the connection currently maintained
	* within this parsers internal map. Any tokens that currently
	* exist with similar names will be overwritten by this.
	*
	* @param data this is the collection of tokens to be added
	*/
	public void putAll(Map<? extends T, ? extends T> data) {
	Set<? extends T> keySet = data.keySet();

	for(T key : keySet) {
	T value = data.get(key);

	if(value != null) {
	put(key, value);
	}
	}
	}

	/**
	* The <code>remove</code> method is used to remove the named
	* token pair from the collection of tokens. This acts like a
	* take, in that it will get the token value and remove if
	* from the collection of tokens the parser has stored.
	*
	* @param name this is a string used to search for the value
	*
	* @return this is the value, as a string, that is removed
	*/
	public T remove(Object name) {
	return map.remove(name);
	}

	/**
	* This obviously enough provides the number of tokens that
	* have been inserted into the internal map. This acts as
	* a proxy method for the internal map <code>size</code>.
	*
	* @return this returns the number of tokens are available
	*/
	public int size() {
	return map.size();
	}

	/**
	* This method is used to acquire the value for all tokens that
	* have currently been collected by this parser. This is used
	* to determine which tokens have been extracted from the
	* source. It is useful when the tokens have to be gathered.
	*
	* @return the list of value tokens that have been extracted
	*/
	public Collection<T> values() {
	return map.values();
	}

	/**
	* The <code>clear</code> method is used to wipe out all the
	* currently existing tokens from the collection. This is used
	* to recycle the parser so that it can be used to parse some
	* other source of tokens without any lingering state.
	*/
	public void clear() {
	all.clear();
	map.clear();
	}
	}