001 /*-----------------------------------------------------------------------
002 * Copyright (C) 2006
003 * Associated Universities, Inc. Washington DC, USA.
004 * This program is free software; you can redistribute it and/or
005 * modify it under the terms of the GNU General Public License as
006 * published by the Free Software Foundation; either version 2 of
007 * the License, or (at your option) any later version.
008 *
009 * This program is distributed in the hope that it will be useful,
010 * but WITHOUT ANY WARRANTY; without even the implied warranty of
011 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
012 * GNU General Public License for more details.
013 *
014 * Correspondence concerning this software should be addressed as follows:
015 * Internet email: switz@nrao.edu
016 * Postal address: SSS Software
017 * National Radio Astronomy Observatory
018 * Post Office Box 0
019 * Socorro, NM 87801 USA
020 *-----------------------------------------------------------------------*/
021 package edu.nrao.sss.model.parameter;
022
023 import java.util.List;
024
025 import edu.nrao.sss.model.RepositoryException;
026
027 /**
028 * A provider of astronomical parameters.
029 * <p>
030 * <b>CVS Info:</b> <table style="margin-left:2em">
031 * <tr>
032 * <td>$Revision: 161 $</td>
033 * </tr>
034 * <tr>
035 * <td>$Date: 2006-12-15 11:48:34 -0700 (Fri, 15 Dec 2006) $</td>
036 * </tr>
037 * <tr>
038 * <td>$Author: btruitt $</td>
039 * </tr>
040 * </table>
041 * </p>
042 *
043 * @author David M. Harland
044 * @since 2006-08-03
045 */
046 public interface ParameterProvider {
047 // ============================================================================
048 // PARAMETERS
049 // ============================================================================
050
051 /**
052 * Returns the {@code Parameter} with the given {@code id}, if any.
053 * <p>
054 * If this provider holds no {@code Parameter} with an ID of {@code id},
055 * <i>null</i> is returned.
056 * </p>
057 *
058 * @param id
059 * the identifier (primary key) for a {@code Parameter} in this
060 * repository.
061 *
062 * @return The {@code Parameter} with the given {@code id}, or <i>null</i>,
063 * if this provider holds no such {@code Parameter}.
064 *
065 * @throws RepositoryException
066 * if anything goes wrong while trying to fetch parameters from
067 * this provider.
068 */
069 public Parameter findParameterById(long id) throws RepositoryException;
070
071 /**
072 * Returns the {@code Parameter}(s) with the given {@code name}, if any.
073 * <p>
074 * Ideally, the returned list will contain only one parameter. However,
075 * since the name is not usually used as a primary key to a parameter, it is
076 * possible that the returned list may contain more than one parameter. If
077 * this provider holds no {@code Parameter} with a name of {@code name},
078 * the returned list will be empty.
079 * </p>
080 *
081 * @param name
082 * the name of a {@code Parameter} requested from this provider.
083 *
084 * @return The {@code Parameter}s with the given {@code name}, or <i>null</i>,
085 * if this provider holds no such {@code Parameter}.
086 *
087 * @throws RepositoryException
088 * if anything goes wrong while trying to fetch parameters from
089 * this provider.
090 */
091 public List<Parameter> findParameterByName(String name)
092 throws RepositoryException;
093
094 /**
095 * Returns a list of parameters held this provider that can pass through
096 * {@code filter}. If {@code filter} is <i>null</i>, it will be treated as
097 * a wide-open filter, allowing all parameters to pass.
098 *
099 * @param filter
100 * the filter through which a parameter must pass in order to be
101 * included in the returned set.
102 *
103 * @return a list of parameters that can pass through {@code filter}.
104 *
105 * @throws RepositoryException
106 * if anything goes wrong while trying to fetch parameters from
107 * this provider.
108 */
109 public List<Parameter> getParameters(ParameterFilter filter)
110 throws RepositoryException;
111
112 /**
113 * Returns a list of all parameters held by this provider.
114 *
115 * @return a list of all parameters held by this provider. If the provider
116 * has no parameters the returned list will be empty.
117 *
118 * @throws RepositoryException
119 * if anything goes wrong while trying to fetch parameters from
120 * this provider.
121 */
122 public List<Parameter> getParameters() throws RepositoryException;
123
124 }