1
2
3
4
5
6
7
8
9
10
11
12 package ca.spaz.cron.datasource;
13
14 import java.util.*;
15
16 import ca.spaz.cron.database.*;
17
18 /***
19 * This interface defines a datasource whose contents may be changed by
20 * interested classes. All of the standard issues apply (especially the
21 * <code>Food</code> needing to be associated with this datasource)
22 *
23 * @author Chris Rose
24 */
25 public interface ILocalFoodDatasource extends IFoodDatasource {
26
27 /***
28 * This method consumes the food in a serving. This an
29 * exception to the requirement that a <code>Food</code> object have
30 * this as its datasource, since in this case if the <code>Food</code>
31 * object has a different datasource, it will either A) be added to this
32 * one, and then consumed, or B) if it is already present in this datasource
33 * it will simply be added from this datasource.
34 *
35 * @param serving a <code>Serving</code> to add to the user's consumed list.
36 * @return A new <code>Food</code> object that represents the <code>Food</code>
37 * that is associated with this datasource. If the food was already associated
38 * with this datasource, the same object will be returned. <code>null</code>
39 * will be returned if some error occurred.
40 */
41 Food addServing(Serving serving);
42
43 /***
44 * Add a new FoodGroup to the data source. The food group may already exist, in
45 * which case an implementing method should silently succeed.
46 *
47 * @param foodGroup the new food group to add to the data source.
48 */
49 void addFoodGroup(FoodGroup foodGroup);
50
51 /***
52 * Changes the amount of a food consumed to the amount in the serving provided.
53 * This will alter the amount of the <code>Food</code> retrieved by calling
54 * <code>getFood()</code> on <code>newServing</code>. If the food is not already
55 * in the database as being consumed, it will be added. The food must already
56 * be in the user datasource, however.
57 *
58 * @param newServing a <code>Serving</code> object whose <code>Food</code>'s serving
59 * quantity on the proper date will be altered.
60 * @return <code>true</code> if the serving was altered, <code>false</code> if some
61 * error occurred.
62 */
63 boolean changeServingAmount(Serving newServing);
64
65 /***
66 * Remove the <code>Food</code> in a particular serving from the user's consumed
67 * list. Operates regardless of quantity.
68 *
69 * @param serving the serving to un-consume.
70 * @return <code>true</code> if the action succeeded, <code>false</code> if there
71 * was some error.
72 */
73 boolean removeServing(Serving serving);
74
75 /***
76 * Each food in the Datasource has available a list of <code>Measure</code>s that
77 * describe portions or servings. This method will add a valid <code>Measure</code>
78 * to a <code>Food</code> object stored in this datasource.
79 *
80 * @param food The <code>Food</code> object to which the new measure applies.
81 * @param measure The new <code>Measure</code>.
82 * @return <code>true</code> if successful, <code>false</code> if some error occurred.
83 */
84 boolean addMeasure(Food food, Measure measure);
85
86 /***
87 * @param food
88 * @param measures
89 * @return <code>true</code> if successful, <code>false</code> if some error occurred.
90 */
91 boolean changeMeasure(Food food, List measures);
92
93 /***
94 * Remove a particular form of <code>Measure</code> from the list of those available for
95 * a particular <code>Food</code>.
96 * @param food
97 * @param measure
98 * @return <code>true</code> if successful, <code>false</code> if some error occurred.
99 */
100 boolean removeMeasure(Food food, Measure measure);
101
102 /***
103 * Retrieve the total number of times that this food has been consumed.
104 *
105 * @param food the <code>Food</code> to check.
106 * @return the number of times consumed, or <code>-1</code> on error.
107 */
108 int getTimesConsumed(Food food);
109
110 /***
111 * Retrieve the number of times the specified <code>Food</code> was consumed
112 * between the provided dates.
113 *
114 * @param food the <code>Food</code> to check.
115 * @param startDate the starting date.
116 * @param endDate the ending date.
117 * @return the number of times consumed between the two dates, or <code>-1</code>
118 * on error.
119 */
120 int getTimesConsumed(Food food, Date startDate, Date endDate);
121
122 /***
123 * Retrieve a list of all <code>Servings</code> consumed on a particular date.
124 *
125 * @param date the <code>Date</code> to retrieve the foods for.
126 * @return a <code>List</code> consisting only of <code>Serving</code> objects,
127 * or <code>null</code> if some error occurred. If no servings were consumed
128 * on the specified date, an empty list will be returned.
129 */
130 List getConsumedOn(Date date);
131
132 /***
133 * Add a <code>Food</code> to this datasource.
134 *
135 * This method is an exception to the local datasource rule -- the <code>Food</code>
136 * provided to this method <em>must not</em> be attached to this datasource.
137 *
138 * @param food A <code>Food</code> object that comes from another datasource.
139 * @return a <code>Food</code> object whose information is the same as the parameter,
140 * but that exists only in this datasource, with all nutrient information still
141 * represtented. <code>null</code> will be returned if some error occurred.
142 */
143 Food addFood(Food food);
144
145 /***
146 * Create a new <code>Food</code> object associated with this datasource.
147 * @return a new <code>Food</code> instance.
148 */
149 Food createNewFood();
150
151 /***
152 * Alter the information of some Food object in the backing representation of the
153 * datasource. This method has potential complications. If the
154 * <code>Food</code> implementation specific to the datasource has a concept of
155 * unique identifiers, a true alteration will occur. However, if the <code>Food</code>
156 * object does not have this feature, for example in a flat-file database or something
157 * like it, the implementor should check for name similarity, and if that does not
158 * match, simply add the new food to the database.
159 *
160 * @param food a <code>Food</code> object to be changed.
161 * @return <code>true</code> if successful, <code>false</code> if some error occurred.
162 */
163 boolean saveFood(Food food);
164
165 /***
166 * Remove a <code>Food</code> from the datasource.
167 *
168 * @param food the <code>Food</code> to remove.
169 * @return <code>true</code> if successful, <code>false</code> if some error occurred.
170 */
171 boolean removeFood(Food food);
172
173 /***
174 * Add a new <code>IFoodDatasourceListener</code> to this implementation. The listener
175 * will be notified on any successful change to the underlying datasource.
176 *
177 * @param listener the new <code>IFoodDatasourceListener</code>.
178 */
179 void addFoodDatasourceListener(IFoodDatasourceListener listener);
180
181 /***
182 * Remove an <code>IFoodDatasourceListener</code> from the list of observers of this class.
183 *
184 * @param listener the <code>IFoodDatasourceListener</code>.
185 */
186 void removeFoodDatasourceListener(IFoodDatasourceListener listener);
187
188 }