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