gov/nasa/worldwind/AVList.java

   1 /*
   2 Copyright (C) 2001, 2006 United States Government
   3 as represented by the Administrator of the
   4 National Aeronautics and Space Administration.
   5 All Rights Reserved.
   6 */
   7 package gov.nasa.worldwind;
   8
   9 import java.util.*;
  10
  11 /**
  12  * An interface for managing an attribute-value pair collection.
  13  *
  14  * @author Tom Gaskins
  15  * @version $Id: AVList.java 2215 2007-07-04 15:38:23Z tgaskins $
  16  */
  17 public interface AVList
  18 {
  19     /**
  20      * Adds a key/value pair to the list. Replaces an existing key/value pair if the list already contains the key.
  21      *
  22      * @param key   the attribute name. May not be <code>null</code>.
  23      * @param value the attribute value. May be <code>null</code>, in which case any existing value for the key is
  24      *              removed from the collection.
  25      * @throws NullPointerException if <code>key</code> is <code>null</code>.
  26      */
  27     void setValue(String key, Object value);
  28
  29     void setValues(AVList avList);
  30
  31     /**
  32      * Returns the value for a specified key.
  33      *
  34      * @param key the attribute name. May not be <code>null</code>.
  35      * @return the attribute value if one exists in the collection, otherwise <code>null</code>.
  36      * @throws NullPointerException if <code>key</code> is <code>null</code>.
  37      */
  38     Object getValue(String key);
  39
  40     /**
  41      * Returns the value for a specified key. The value must be a {@link String}.
  42      *
  43      * @param key the attribute name. May not be <code>null</code>.
  44      * @return the attribute value if one exists in the collection, otherwise <code>null</code>.
  45      * @throws NullPointerException if <code>key</code> is <code>null</code>.
  46      * @throws WWRuntimeException   if the value in the collection is not a <code>String</code> type.
  47      */
  48     String getStringValue(String key);
  49
  50     Set<Map.Entry<String, Object>>getValues();
  51
  52     /**
  53      * Indicates whether a key is in the collection.
  54      *
  55      * @param key the attribute name. May not be <code>null</code>.
  56      * @return <code>true</code> if the key exists in the collection, otherwise <code>false</code>.
  57      * @throws NullPointerException if <code>key</code> is <code>null</code>.
  58      */
  59     boolean hasKey(String key);
  60
  61     /**
  62      * Removes a specified key from the collection if the key exists, otherwise returns without affecting the
  63      * collection.
  64      *
  65      * @param key the attribute name. May not be <code>null</code>.
  66      * @throws NullPointerException if <code>key</code> is <code>null</code>.
  67      */
  68     void removeKey(String key);
  69
  70     /**
  71      * Adds a property change listener for the specified key.
  72      * @param propertyName the key to associate the listener with.
  73      * @param listener the listener to associate with the key.
  74      * @throws IllegalArgumentException if either <code>propertyName</code> or <code>listener</code> is null
  75      * @see java.beans.PropertyChangeSupport
  76      */
  77     void addPropertyChangeListener(String propertyName, java.beans.PropertyChangeListener listener);
  78
  79     /**
  80      * Removes a property change listener associated with the specified key.
  81      * @param propertyName the key associated with the change listener.
  82      * @param listener the listener to remove.
  83      * @throws IllegalArgumentException if either <code>propertyName</code> or <code>listener</code> is null
  84      * @see java.beans.PropertyChangeSupport
  85      */
  86     void removePropertyChangeListener(String propertyName, java.beans.PropertyChangeListener listener);
  87
  88     /**
  89      * Adds the specified all-property property change listener that will be called for all list changes.
  90      * @param listener the listener to call.
  91      * @throws IllegalArgumentException if <code>listener</code> is null
  92      * @see java.beans.PropertyChangeSupport
  93      */
  94     void addPropertyChangeListener(java.beans.PropertyChangeListener listener);
  95
  96     /**
  97      * Removes the specified all-property property change listener.
  98      * @param listener the listener to remove.
  99      * @throws IllegalArgumentException if <code>listener</code> is null
 100      * @see java.beans.PropertyChangeSupport
 101      */
 102     void removePropertyChangeListener(java.beans.PropertyChangeListener listener);
 103
 104     /**
 105      * Calls all property change listeners associated with the specified key.
 106      * No listeners are called if <code>odValue</code> and <code>newValue</code> are equal and non-null.
 107      * @param propertyName the key
 108      * @param oldValue the value associated with the key before the even causing the firing.
 109      * @param newValue the new value associated with the key.
 110      * @throws IllegalArgumentException if <code>propertyName</code> is null
 111      * @see java.beans.PropertyChangeSupport
 112      */
 113     void firePropertyChange(String propertyName, Object oldValue, Object newValue);
 114
 115     /**
 116      * Calls all registered property change listeners with the specified property change event.
 117      * @param propertyChangeEvent the event
 118      * @throws IllegalArgumentException if <code>propertyChangeEvent</code> is null
 119      * @see java.beans.PropertyChangeSupport
 120      */
 121     void firePropertyChange(java.beans.PropertyChangeEvent propertyChangeEvent);
 122
 123     /**
 124      * Returns a shallow copy of this <code>AVList</code> instance: the keys and values themselves are not cloned.
 125      * @return a shallow copy of this <code>AVList</code>.
 126      */
 127     AVList copy();
 128 }