001    package edu.nrao.sss.model.resource;
002    
003    import java.util.SortedSet;
004    
005    import edu.nrao.sss.measure.Frequency;
006    
007    /**
008     * An object that has frequency bandwidth.
009     * <p>
010     * <b>Version Info:</b>
011     * <table style="margin-left:2em">
012     *   <tr><td>$Revision: 1158 $</td></tr>
013     *   <tr><td>$Date: 2008-03-14 09:26:16 -0600 (Fri, 14 Mar 2008) $</td></tr>
014     *   <tr><td>$Author: dharland $ (last person to modify)</td></tr>
015     * </table></p>
016     * 
017     * @author David M. Harland
018     * @since 2008-03-13
019     */
020    public interface HasBandwidth
021    {
022      /**
023       * Returns the smallest bandwidth to which this object may be set.
024       * @return the smallest bandwidth to which this object may be set.
025       */
026      public Frequency getMinimumBandwidth();
027      
028      /**
029       * Returns the largest bandwidth to which this object may be set.
030       * @return the largest bandwidth to which this object may be set.
031       */
032      public Frequency getMaximumBandwidth();
033      
034      /**
035       * Returns <i>true</i> if this object may be set only to pretermined
036       * bandwidths.  A return value of <i>false</i> indicates that this object
037       * may be set to any bandwidth in the range allowed by
038       * {@link #getMinimumBandwidth()} and {@link #getMaximumBandwidth()}.
039       * <p>
040       * If the returned value is <i>true</i>, the method
041       * {@link #getAllowableBandwidths()} will give the set of predetermined
042       * bandwidths.</p>
043       * 
044       * @return
045       *   <i>true</i> if this object may be set only to pretermined bandwidths.
046       */
047      public boolean hasDiscreteBandwidths();
048    
049      /**
050       * Returns the set of bandwidths to which this object may be set.
051       * <p>
052       * If the return value of {@link #hasDiscreteBandwidths()} is <i>false</i>
053       * all frequencies in the range allowed by
054       * {@link #getMinimumBandwidth()} and {@link #getMaximumBandwidth()} are
055       * valid and this method will return an empty set.  Otherwise it will
056       * return the set of allowable bandwidths.</p>
057       * 
058       * @return the set of bandwidths to which this object may be set.
059       */
060      public SortedSet<Frequency> getAllowableBandwidths();
061      
062      /**
063       * Returns the smallest allowable bandwidth that is greater than
064       * {@code desiredWidth}.  If no allowable bandwidth is greater than
065       * {@code desiredWidth}, the maximum allowable bandwidth is returned.
066       * 
067       * @param desiredWidth
068       *   a desired bandwidth for which an allowable bandwidth is sought.
069       *   
070       * @return the smallest allowable bandwidth that is greater than
071       *         {@code desiredWidth}.
072       */
073      public Frequency getAllowableBandwidthFor(Frequency desiredWidth);
074    
075      /**
076       * Returns the allowable frequency that is closest to the parameter.
077       * 
078       * @param desiredWidth
079       *   a bandwidth for which the closest allowable bandwidth is desired.
080       *   If this value is below the minimum, the minimum allowable value
081       *   is returned.  If it is above the maximum, the maximum is returned.
082       *   If this value is <i>null</i>, the minimum value is returned.
083       *   
084       * @return
085       *   the allowable bandwidth of this baseband that is closest to
086       *   {@code desiredWidth}.
087       */
088      public Frequency getAllowableBandwidthClosestTo(Frequency desiredWidth);
089      
090      /**
091       * Returns this object's bandwidth.
092       * @return this object's bandwidth.
093       */
094      public Frequency getBandwidth();
095    }