001    package edu.nrao.sss.electronics;
002    
003    import java.util.SortedSet;
004    
005    /**
006     * A device that can be configured to produce digital samplings
007     * of different bit depths.
008     * <p>
009     * <b>Developer's Note:</b>
010     * <i>This class was created after this package
011     * was completed and was shoehorned in without much thought.
012     * One could argue that a <tt>SignalSampler</tt> is a <tt>Digitizer</tt>
013     * and ought to implement this class.  Fair enough.  Let this note
014     * stand as a TODO marker for someone to come back and make this
015     * interface fit more naturally into this package.</i></p>  
016     * <p>
017     * <b>Version Info:</b>
018     * <table style="margin-left:2em">
019     *   <tr><td>$Revision: 1048 $</td></tr>
020     *   <tr><td>$Date: 2008-01-18 09:07:05 -0700 (Fri, 18 Jan 2008) $</td></tr>
021     *   <tr><td>$Author: dharland $ (last person to modify)</td></tr>
022     * </table></p>
023     * 
024     * @author David M. Harland
025     * @since 2008-01-17
026     */
027    public interface Digitizer
028    {
029      /**
030       * Returns the name of this digitizer.
031       * @return the name of this digitizer.
032       */
033      public String getName();
034      
035      /**
036       * Returns the number of bits per sample this device is configured to produce.
037       * @return the number of bits per sample this device is configured to produce.
038       */
039      public int getBitsPerSample();
040      
041      /**
042       * Configures this digitizer so that it produces output with
043       * the given number of bits per sample.
044       * <p>
045       * Most digitizers can handle only a few bit per sample values.
046       * The set of allowable values is given by
047       * {@link #getAllowableBitsPerSample()}.  Implementing classes
048       * are free to do one of two things with values that are not in
049       * that set:</p>
050       * <ol>
051       *   <li>Ignore the value and leave the state of
052       *       this digitizer unchanged.</li>
053       *   <li>Use the closest legal value.  (If two values are equally
054       *       close, the implementing class may be biased toward one
055       *       or the other at its discretion.)</li>
056       * </ol>
057       * 
058       * @param numberOfBits
059       *   the type of output, expressed as bits per sample, that this
060       *   digitizer should produce.
061       */
062      public void setBitsPerSample(int numberOfBits);
063      
064      /**
065       * Returns the set of bit per sample values that this digitizer
066       * can produce.
067       * 
068       * @return the set of bit per sample values that this digitizer
069       *         can produce. 
070       */
071      public SortedSet<Integer> getAllowableBitsPerSample();
072    }