ca.spaz.cron.datasource
Interface IFoodDatasource

All Known Subinterfaces:

ILocalFoodDatasource

All Known Implementing Classes:

AbstractFoodDataSource, AbstractMutableFoodDatasource, AbstractWWWDatasource, NutritionDataDatasource, SQLDatasource

public interface IFoodDatasource

This interface defines the interaction the application will have with a static, readonly data source. The methods on it are all the ways that the app might ask for information on elements of the food system. Note regaring Food instances and this interface -- this interface and all subclasses expect and should enforce (unless noted) that the Food object passes as a parameter to a given instance have that same instance as its dataSource property.

Author:

Chris Rose

Method Summary

void	close() Close this connection.
boolean	containsFood(Food food) Determine if this datasource contains the specified food.
java.util.List	findAllFoods() Retrieve a list of all foods in this datasource.
java.util.List	findFoods(java.lang.String[] keys) Retrieve a List of all foods in this particular Datasource.
java.util.List	findFoods(java.lang.String[] keys, java.lang.String foodGroup, java.lang.String source) Retrieve a List of all foods in this particular Datasource having the given food group and source.
java.util.List	getFoodGroups() Get a list of all food groups in this datasource.
FoodDatasourceException	getLastError() Provides access to the last exception thrown by the underlying representation.
java.util.List	getMeasuresFor(Food food) Return a List of Measure objects for the provided food.
java.lang.String	getName() Retrieve the name of this datasource for use in UI components.
void	getNutrientsFor(Food f, NutrientTable nutrients) Fill the provided NutrientTable with the nutrients associated with the Food.
java.util.List	getSources() Get a list of all sources in this datasource.
void	initialize() Initialize the datasource to a working state.
boolean	isAvailable() Determines if the datasource is operable and available.
boolean	isListable() Implementors that can provide listing services should return true here, false otherwise.
boolean	isSearchable() Implementors that can provide search services should return true here, false otherwise.

Method Detail

findFoods

java.util.List findFoods(java.lang.String[] keys)

Retrieve a List of all foods in this particular Datasource.

Parameters:

keys - the keys to search on. This searches with an AND relation.

Returns:

a List of Food objects matching the criteria.

Throws:

UnsupportedOperationException - if the datasource does not support searching. (if isSearchable() is false)

To Do:

finalize the needed parameters here.

findFoods

java.util.List findFoods(java.lang.String[] keys,
                         java.lang.String foodGroup,
                         java.lang.String source)

Retrieve a List of all foods in this particular Datasource having the given food group and source.

Parameters:

keys - the keys to search on. This searches with an AND relation.

foodGroup - the food group to search for. null to ignore.

source - the source of this food item. null to ignore.

Returns:

a List of Food objects matching the criteria.

Throws:

UnsupportedOperationException - if the datasource does not support searching. (if isSearchable() is false)

findAllFoods

java.util.List findAllFoods()

Retrieve a list of all foods in this datasource.

Returns:

a List of Food objects consisting of every food in the datasource.

Throws:

UnsupportedOperationException - if the datasource does not support listing. (if isListable() is false)

getMeasuresFor

java.util.List getMeasuresFor(Food food)

Return a List of Measure objects for the provided food.

Parameters:

food - a Food object to find the measures for

Returns:

a List that is guaranteed to contain only Measure objects.

getNutrientsFor

void getNutrientsFor(Food f,
                     NutrientTable nutrients)

Fill the provided NutrientTable with the nutrients associated with the Food.

Parameters:

f - The food item to load from

nutrients - the NutrientTable to fill.

getSources

java.util.List getSources()

Get a list of all sources in this datasource. What these are is subimplementation- dependent, and will most often be only one item.

Returns:

a List of String objects naming the sources for this Datasource.

getFoodGroups

java.util.List getFoodGroups()

Get a list of all food groups in this datasource.

Returns:

a List of FoodGroup objects naming the food groups for this Datasource.

isSearchable

boolean isSearchable()

Implementors that can provide search services should return true here, false otherwise.

Returns:

true if this Datasource supports search, false otherwise.

isListable

boolean isListable()

Implementors that can provide listing services should return true here, false otherwise.

Returns:

true if this Datasource supports listing, false otherwise.

getName

java.lang.String getName()

Retrieve the name of this datasource for use in UI components.

Returns:

this Datasource's name.

close

void close()

Close this connection. May or may not be required, but this method should ensure that there is nothing remaining of the connection.

getLastError

FoodDatasourceException getLastError()

Provides access to the last exception thrown by the underlying representation.

Returns:

the last Throwable that an implementation of this interface has thrown.

isAvailable

boolean isAvailable()

Determines if the datasource is operable and available. This includes connections to physical datasources, proper setup of tables, or any other conditions that may prevent this from being a functional datasource.

Returns:

true if this datasource is functioning, false otherwise

initialize

void initialize()

Initialize the datasource to a working state. At the time that this method completes normally (without throwing an exception), isAvailable must return true for this data source. If this source is already available, this method will do nothing.

containsFood

boolean containsFood(Food food)

Determine if this datasource contains the specified food. This method will return true if for any Food in this datasource, the Food's SourceUID is equal to that of the food on the command line.

Parameters:

food - The food to test for

Returns:

true if there is a Food in this datasource matching the provided one.