001 package edu.nrao.sss.model.resource;
002
003 import java.util.List;
004
005 import edu.nrao.sss.measure.FrequencyRange;
006
007 /**
008 * A selector of the best receiver(s) for a given
009 * {@link ResourceSpecification}.
010 * <p>
011 * <b>Version Info:</b>
012 * <table style="margin-left:2em">
013 * <tr><td>$Revision: 1710 $</td></tr>
014 * <tr><td>$Date: 2008-11-14 11:54:07 -0700 (Fri, 14 Nov 2008) $</td></tr>
015 * <tr><td>$Author: dharland $</td></tr>
016 * </table></p>
017 *
018 * @author David M. Harland
019 * @since 2006-09-08
020 */
021 public interface ReceiverSelector
022 {
023 /**
024 * Sets the universe of receivers from which selections will be made.
025 * @param provider a provider of receivers.
026 */
027 public void setProvider(ReceiverProvider provider);
028
029 /**
030 * Returns a list of one or more selections that satisfy the given specs.
031 * The first selection in the list will be the best match, the second
032 * selection the next best match, and so on. If a perfect match was
033 * found, the returned list will contain only that selection.
034 * If no receiver was even a partial match, the returned list will
035 * contain a single receiver that was nearest the frequencies needed
036 * by the {@code specs}.
037 *
038 * @param specs a resource specification, expressed in terms of science,
039 * as opposed to instrumentation.
040 *
041 * @return a list of one or more selections based on the specifications.
042 */
043 public List<ReceiverSelection> selectReceivers(ResourceSpecification specs);
044
045 /**
046 * Returns a list of one or more selections that satisfy the given specs.
047 * The first selection in the list will be the best match, the second
048 * selection the next best match, and so on. If a perfect match was
049 * found, the returned list will contain only that selection.
050 * If no receiver was even a partial match, the returned list will
051 * contain a single receiver that was nearest the frequencies needed
052 * by the {@code specs}.
053 *
054 * @param specs a resource specification, expressed in terms of science,
055 * as opposed to instrumentation.
056 *
057 * @return a list of one or more selections based on the specifications.
058 */
059 public List<ReceiverSelection> selectReceivers(SkyFrequencySpecification specs);
060
061 /**
062 * Returns a list of one or more selections that satisfy the given specs.
063 * The first selection in the list will be the best match, the second
064 * selection the next best match, and so on. If a perfect match was
065 * found, the returned list will contain only that selection.
066 * If no receiver was even a partial match, the returned list will
067 * contain a single receiver that was nearest the frequencies needed
068 * by the {@code specs}.
069 *
070 * @param specs a resource specification, expressed in terms of science,
071 * as opposed to instrumentation.
072 *
073 * @return a list of one or more selections based on the specifications.
074 */
075 public List<ReceiverSelection> selectReceivers(SpectralLineSpecification specs);
076
077 /**
078 * Returns a list of one or more selections that satisfy the given specs.
079 * The first selection in the list will be the best match, the second
080 * selection the next best match, and so on. If a perfect match was
081 * found, the returned list will contain only that selection.
082 * If no receiver was even a partial match, the returned list will
083 * contain a single receiver that was nearest the frequencies needed
084 * by the {@code specs}.
085 *
086 * @param specs a resource specification, expressed in terms of science,
087 * as opposed to instrumentation.
088 *
089 * @return a list of one or more selections based on the specifications.
090 */
091 public List<ReceiverSelection> selectReceivers(PulsarSpecification specs);
092
093 /**
094 * Returns a list of one or more selections that satisfy the given
095 * portion of the given specs.
096 * The first selection in the list will be the best match, the second
097 * selection the next best match, and so on. If a perfect match was
098 * found, the returned list will contain only that selection.
099 * If no receiver was even a partial match, the returned list will
100 * contain a single receiver that was nearest the frequencies needed
101 * by the {@code specs}.
102 * <p>
103 * The {@code mode} parameter is used to ignore the portions of
104 * {@code specs} that are of different modes. For example, calling
105 * {@code mySelector.selectReceivers(ObservingMode.SPECTRAL_LINE, mySpecs)}
106 * will cause this selector to consider only the spectral line specifications.
107 * Note that this is a little different than calling
108 * {@code mySelector.selectReceivers(mySpecs.getSpectralLineSpecs().get(i))}
109 * because <i>all</i> the spectral line specifications in {@code specs} will
110 * be considered by this method.</p>
111 *
112 * @param mode the portion of {@code specs} to which this method will
113 * limit its attention.
114 *
115 * @param specs a resource specification, expressed in terms of science,
116 * as opposed to instrumentation.
117 *
118 * @return a list of one or more selections based on the specifications.
119 */
120 public List<ReceiverSelection> selectReceivers(ObservingMode mode,
121 ResourceSpecification specs);
122
123 /**
124 * Returns the best receiver to use for the given range of sky frequencies.
125 * <p>
126 * This method returns a single receiver, even if multiple receivers cover
127 * the target range. If one receiver covers more of the target range than
128 * the others, it is the receiver returned. If multiple receivers cover
129 * the range equally well, the receiver returned is up to the implementing
130 * class. If no receiver overlaps the target range, the receiver that
131 * has the smallest distance between itself and the target range is returned.
132 * <b>Note</b> that this means the returned receiver may not be useful for
133 * the target it range at all, but is merely the best of the not-so-useful
134 * receivers.</p>
135 * <p>
136 * This method may return <i>null</i> if any one or more of the following
137 * is true:</p>
138 * <ol>
139 * <li>This selector's <i>receiver provider</i> is <i>null</i>.</li>
140 * <li>This receiver provider of this selector has a <i>null</i> list
141 * of receivers.</li>
142 * <li>This receiver provider of this selector has an empty list
143 * of receivers.</li>
144 * </ol>
145 * @param targetRange
146 * a sky frequency range for which the best receiver is sought.
147 *
148 * @return
149 * the best receiver to use for the given range of sky frequencies.
150 */
151 public ReceiverBand selectBestReceiverFor(FrequencyRange targetRange);
152 }