001 package edu.nrao.sss.model.source;
002
003 import java.util.List;
004
005 import edu.nrao.sss.model.RepositoryException;
006 import edu.nrao.sss.util.Filter;
007
008 /**
009 * A provider of astronomical sources.
010 * <p>
011 * <b>CVS Info:</b>
012 * <table style="margin-left:2em">
013 * <tr><td>$Revision: 2313 $</td></tr>
014 * <tr><td>$Date: 2009-05-20 15:00:52 -0600 (Wed, 20 May 2009) $</td></tr>
015 * <tr><td>$Author: btruitt $</td></tr>
016 * </table></p>
017 *
018 * @author David M. Harland
019 * @since 2006-08-03
020 */
021 public interface SourceProvider
022 {
023 //============================================================================
024 // SOURCES
025 //============================================================================
026
027 /**
028 * Returns the {@code Source} with the given {@code id}, if any.
029 * <p>
030 * If this provider holds no {@code Source} with an ID of {@code id},
031 * <i>null</i> is returned.</p>
032 *
033 * @param id the identifier (primary key) for a {@code Source} in this
034 * repository.
035 *
036 * @return The {@code Source} with the given {@code id}, or
037 * <i>null</i>, if this provider holds no such {@code Source}.
038 *
039 * @throws RepositoryException if anything goes wrong while trying to fetch
040 * sources from this provider.
041 */
042 public Source findSourceById(long id) throws RepositoryException;
043
044 /**
045 * Returns the {@code Source}(s) with the given {@code name}, if any.
046 * <p>
047 * Ideally, the returned list will contain only one source. However,
048 * since the name is not usually used as a primary key to a source, it
049 * is possible that the returned list may contain more than one source.
050 * If this provider holds no {@code Source} with a name of {@code name},
051 * the returned list will be empty.</p>
052 *
053 * @param name the name of a {@code Source} requested from this provider.
054 *
055 * @return The {@code Source}s with the given {@code name}, or
056 * <i>null</i>, if this provider holds no such {@code Source}.
057 *
058 * @throws RepositoryException if anything goes wrong while trying to fetch
059 * sources from this provider.
060 */
061 public List<Source> findSourceByName(String name)
062 throws RepositoryException;
063
064 /**
065 * Returns a list of sources held this provider that can pass through
066 * {@code filter}. If {@code filter} is <i>null</i>, it will be treated
067 * as a wide-open filter, allowing all sources to pass.
068 *
069 * @param filter the filter through which a source must pass in order
070 * to be included in the returned set.
071 *
072 * @return a list of sources that can pass through {@code filter}.
073 *
074 * @throws RepositoryException if anything goes wrong while trying to fetch
075 * sources from this provider.
076 */
077 public List<Source> getSources(Filter<Source> filter)
078 throws RepositoryException;
079
080 /**
081 * Returns a list of all sources held by this provider.
082 *
083 * @return a list of all sources held by this provider. If the provider has
084 * no sources the returned list will be empty.
085 *
086 * @throws RepositoryException if anything goes wrong while trying to fetch
087 * sources from this provider.
088 */
089 public List<Source> getSources()
090 throws RepositoryException;
091
092 //============================================================================
093 // SOURCE LOOKUP TABLES
094 //============================================================================
095
096 /**
097 * Returns the {@code SourceLookupTable} with the given {@code id}, if any.
098 * <p>
099 * If this provider holds no {@code SourceLookupTable} with an ID of
100 * {@code id}, <i>null</i> is returned.</p>
101 *
102 * @param id the identifier (primary key) for a {@code SourceLookupTable} in
103 * this repository.
104 *
105 * @return The {@code SourceLookupTable} with the given {@code id}, or
106 * <i>null</i>, if this provider holds no such
107 * {@code SourceLookupTable}.
108 *
109 * @throws RepositoryException if anything goes wrong while trying to fetch
110 * source tables from this provider.
111 */
112 public SourceLookupTable findSourceTableById(long id)
113 throws RepositoryException;
114
115 /**
116 * Returns the {@code SourceLookupTable}(s) with the given {@code name},
117 * if any.
118 * <p>
119 * Ideally, the returned list will contain only one table. However,
120 * since the name is not usually used as a primary key to a table, it
121 * is possible that the returned list may contain more than one table.
122 * If this provider holds no {@code SourceLookupTable} with a name of
123 * {@code name}, the returned list will be empty.</p>
124 *
125 * @param name the name of a {@code SourceLookupTable} requested from
126 * this provider.
127 *
128 * @return The {@code SourceLookupTable}s with the given {@code name},
129 * or <i>null</i>, if this provider holds no such table.
130 *
131 * @throws RepositoryException if anything goes wrong while trying to fetch
132 * tables from this provider.
133 */
134 public List<SourceLookupTable> findSourceTableByName(String name)
135 throws RepositoryException;
136
137 /**
138 * Returns a list of all source lookup tables held by this provider.
139 *
140 * @return a list of all tables held by this provider. If the provider has
141 * no tables the returned list will be empty.
142 *
143 * @throws RepositoryException if anything goes wrong while trying to fetch
144 * tables from this provider.
145 */
146 public List<SourceLookupTable> getSourceTables()
147 throws RepositoryException;
148 }