1
2
3
4
5
6
7
8
9
10
11
12 package ca.spaz.cron.datasource;
13
14 import java.util.List;
15
16 import ca.spaz.cron.database.*;
17
18 /***
19 * This interface defines the interaction the application will have with a static,
20 * readonly data source. The methods on it are all the ways that the app might
21 * ask for information on elements of the food system.
22 *
23 * Note regaring <code>Food</code> instances and this interface -- this interface and
24 * all subclasses expect and should enforce (unless noted) that the <code>Food</code>
25 * object passes as a parameter to a given instance have that same instance as its
26 * <code>dataSource</code> property.
27 *
28 * @author Chris Rose
29 */
30 public interface IFoodDatasource {
31
32 /***
33 * Retrieve a <code>List</code> of all foods in this particular Datasource.
34 *
35 * @todo finalize the needed parameters here.
36 * @param keys the keys to search on. This searches with an AND relation.
37 * @return a List of <code>Food</code> objects matching the criteria.
38 * @throws <code>UnsupportedOperationException</code> if the datasource does not
39 * support searching. (if <code>isSearchable()</code> is false)
40 */
41 List findFoods(String[] keys);
42
43 /***
44 * Retrieve a <code>List</code> of all foods in this particular Datasource having
45 * the given food group and source.
46 *
47 * @param keys the keys to search on. This searches with an AND relation.
48 * @param foodGroup the food group to search for. <code>null</code> to ignore.
49 * @param source the source of this food item. <code>null</code> to ignore.
50 * @return a List of <code>Food</code> objects matching the criteria.
51 * @throws <code>UnsupportedOperationException</code> if the datasource does not
52 * support searching. (if <code>isSearchable()</code> is false)
53 */
54 List findFoods(String[] keys, String foodGroup, String source);
55
56 /***
57 * Retrieve a list of all foods in this datasource.
58 * @return a List of <code>Food</code> objects consisting of every food in the datasource.
59 * @throws <code>UnsupportedOperationException</code> if the datasource does not
60 * support listing. (if <code>isListable()</code> is false)
61 */
62 List findAllFoods();
63
64 /***
65 * Return a <code>List</code> of <code>Measure</code> objects for the provided food.
66 * @param food a <code>Food</code> object to find the measures for
67 * @return a <code>List</code> that is guaranteed to contain only <code>Measure</code>
68 * objects.
69 */
70 List getMeasuresFor(Food food);
71
72 /***
73 * Fill the provided <code>NutrientTable</code> with the nutrients associated with the
74 * <code>Food</code>.
75 * @param f The food item to load from
76 * @param nutrients the <code>NutrientTable</code> to fill.
77 */
78 void getNutrientsFor(Food f, NutrientTable nutrients);
79
80 /***
81 * Get a list of all sources in this datasource. What these are is subimplementation-
82 * dependent, and will most often be only one item.
83 *
84 * @return a <code>List</code> of <code>String</code> objects naming the sources
85 * for this Datasource.
86 */
87 List getSources();
88
89 /***
90 * Get a list of all food groups in this datasource.
91 *
92 * @return a <code>List</code> of <code>FoodGroup</code> objects naming the food
93 * groups for this Datasource.
94 */
95 List getFoodGroups();
96
97 /***
98 * Implementors that can provide search services should return true here, false
99 * otherwise.
100 * @return <code>true</code> if this Datasource supports search, <code>false</code>
101 * otherwise.
102 */
103 boolean isSearchable();
104
105 /***
106 * Implementors that can provide listing services should return true here, false
107 * otherwise.
108 * @return <code>true</code> if this Datasource supports listing, <code>false</code>
109 * otherwise.
110 */
111 boolean isListable();
112
113 /***
114 * Retrieve the name of this datasource for use in UI components.
115 * @return this Datasource's name.
116 */
117 String getName();
118
119 /***
120 * Close this connection. May or may not be required, but this method should
121 * ensure that there is nothing remaining of the connection.
122 */
123 void close();
124
125 /***
126 * Provides access to the last exception thrown by the underlying representation.
127 *
128 * @return the last <code>Throwable</code> that an implementation of this interface
129 * has thrown.
130 */
131 FoodDatasourceException getLastError();
132
133 /***
134 * Determines if the datasource is operable and available. This includes connections
135 * to physical datasources, proper setup of tables, or any other conditions that may
136 * prevent this from being a functional datasource.
137 * @return <code>true</code> if this datasource is functioning, <code>false</code>
138 * otherwise
139 */
140 boolean isAvailable();
141
142 /***
143 * Initialize the datasource to a working state. At the time that this method completes
144 * normally (without throwing an exception), <code>isAvailable</code> must return
145 * <code>true</code> for this data source. If this source is already available, this
146 * method will do nothing.
147 */
148 void initialize();
149
150 /***
151 * Determine if this datasource contains the specified food. This method will return true
152 * if for any <code>Food</code> in this datasource, the Food's <code>SourceUID</code> is equal
153 * to that of the food on the command line.
154 * @param food The food to test for
155 * @return <code>true</code> if there is a <code>Food</code> in this datasource matching the
156 * provided one.
157 */
158 boolean containsFood(Food food);
159 }