org.wpi.gdc.cms.db
Class DBEngine

java.lang.Object
  |
  +--org.wpi.gdc.cms.db.DBEngine

Direct Known Subclasses:

MySQLDBEngine

public abstract class DBEngine

extends java.lang.Object

An abstract class that contains the basic interface that allows the CMS to load and save objects into the database.

The DBEngine interface is not dependent on any given implementation and should work on any given data storage method, given enough work.

Version:

1.11

Author:

imotic

Field Summary

static int	INCLUDE_AFTER_TODAY Constant for including items after the current date.
static int	INCLUDE_BEFORE_TODAY Constant for including items before the current date.
static int	ORDER_ASCENDING Constant for ordering in ascending order.
static int	ORDER_DESCENDING Constant for ordering in descending order.
protected Session	session The session object for this engine.

Constructor Summary

DBEngine()

Method Summary

abstract void	connect(java.lang.String dbURL, java.util.Properties properties) Connects to the database using the given db URL from the configuration options.
abstract boolean	isConnected() Determines if the database is connected (ie, a call to connect succeeded).
abstract Event	loadEvent(int id) Events are stored in a database via a numeric ID, this method should load the actual data based on the ID.
abstract Event	loadEvent(java.lang.String name) Each events to be accessed through the website must have a unique name identifier (which will correspond with that event's URL).
abstract int	loadEventCount() Counts the number of event groups available.
abstract DBIterator	loadEvents() Gets an DBIterator over the event groups in the database.
DBIterator	loadEvents(int field, int order) Gets a DBIterator over the event groups in the database, ordered by the given order.
abstract DBIterator	loadEvents(int field, int order, int limit) Gets a DBIterator over the event groups in the database, ordered by the given order, and limited to the given amount.
abstract DBIterator	loadEventsFromDate(int range, int order, int limit) Gets a DBIterator over the event groups in the database, either before or after the current day (determined by range), ordered by the given order, and limited to the given amount.
abstract Icon[]	loadIcons() Gets all the Icons in a database.
abstract DBIterator	loadNewsStories() Gets an DBIterator over the news stories in the database.
DBIterator	loadNewsStories(int field, int order) Gets a DBIterator over the news stories in the database, ordered by the given order.
abstract DBIterator	loadNewsStories(int field, int order, int limit) Gets a DBIterator over the news stories in the database, ordered by the given order, and limited to the given amount.
abstract NewsStory	loadNewsStory(int id) News stories are stored in a database via a numeric ID, this method should load the actual data based on the ID.
abstract int	loadNewsStoryCount() Counts the number of news stories available.
abstract Topic[]	loadTopics() Gets all the Topics in a database.
abstract User	loadUser(int id) Users are stored in a database via a numeric ID, this method should load the actual data based on the ID.
abstract User	loadUser(java.lang.String name) Load a User from the DB based on the username.
abstract void	saveNewsStory(NewsStory newsStory) Save a NewsStory into the database.
void	setSession(Session session) Sets the Session object for this DBEngine.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

ORDER_ASCENDING

public static final int ORDER_ASCENDING

Constant for ordering in ascending order.

For example, the set {4, 2, 3, 1} would be ordered as {1, 2, 3, 4}.

ORDER_DESCENDING

public static final int ORDER_DESCENDING

Constant for ordering in descending order.

For example, the set {4, 2, 3, 1} would be ordered as {4, 3, 2, 1}.

INCLUDE_BEFORE_TODAY

public static final int INCLUDE_BEFORE_TODAY

Constant for including items before the current date.

INCLUDE_AFTER_TODAY

public static final int INCLUDE_AFTER_TODAY

Constant for including items after the current date.

session

protected Session session

The session object for this engine.

Constructor Detail

DBEngine

public DBEngine()

Method Detail

setSession

public void setSession(Session session)

Sets the Session object for this DBEngine. This can ONLY be done once, after the Session is set, it cannot be changed.

Parameters:

session - the Session object

Throws:

IllegalStateException - if the session has already been set

connect

public abstract void connect(java.lang.String dbURL,
                             java.util.Properties properties)
                      throws DatabaseException

Connects to the database using the given db URL from the configuration options.

Throws:

DatabaseException - if there is an error accessing data from the database

isConnected

public abstract boolean isConnected()

Determines if the database is connected (ie, a call to connect succeeded).

Returns:

true if the database is connected and loadXXXX calls can succeed, false otherwise. A return of "true" does not guarentee success, calls may still throw a DatabaseException if something goes wrong. However, a return of false guarentees failure; all calls will throw a DatabaseException if this method returns false.

loadUser

public abstract User loadUser(int id)
                       throws DatabaseException

Users are stored in a database via a numeric ID, this method should load the actual data based on the ID.

Parameters:

id - the ID for the User being loaded

Returns:

the User object loaded from the database

loadUser

public abstract User loadUser(java.lang.String name)
                       throws DatabaseException

Load a User from the DB based on the username.

Parameters:

name - the username of the User being loaded

Returns:

the User object loaded from the database

Throws:

DatabaseException - if there is an error accessing data from the database

loadNewsStory

public abstract NewsStory loadNewsStory(int id)
                                 throws DatabaseException

News stories are stored in a database via a numeric ID, this method should load the actual data based on the ID.

Parameters:

id - the ID for the news story being loaded

Returns:

the NewsStory object loaded from the database

Throws:

DatabaseException - if there is an error accessing data from the database

loadNewsStories

public abstract DBIterator loadNewsStories()
                                    throws DatabaseException

Gets an DBIterator over the news stories in the database.

The remove() method in the DBIterator may or may not function depending on the implementation.

Returns:

a DBIterator that retrieves one story at a time.

Throws:

DatabaseException - if there is an error accessing data from the database

loadNewsStories

public DBIterator loadNewsStories(int field,
                                  int order)
                           throws DatabaseException

Gets a DBIterator over the news stories in the database, ordered by the given order.

Parameters:

field - The field to sort by, one of: NewsStory.FIELD_ID, NewsStory.FIELD_AUTHOR, NewsStory.FIELD_TOPIC, NewsStory.FIELD_POSTED, NewsStory.FIELD_HEADLINE, NewsStory.FIELD_ABSTRACT, or NewsStory.FIELD_BODY.

order - The order to sort the new stories, either ORDER_ASCENDING or ORDER_DESCENDING.

Returns:

a DBIterator that retrieves one story at a time

Throws:

java.lang.IllegalArgumentException - if field is not one of NewsStory.FIELD_ID, NewsStory.FIELD_AUTHOR, NewsStory.FIELD_TOPIC, NewsStory.FIELD_POSTED, NewsStory.FIELD_HEADLINE, NewsStory.FIELD_ABSTRACT, or NewsStory.FIELD_BODY; or if order is not either ORDER_ASCENDING or ORDER_DESCENDING.

DatabaseException - if there is an error accessing data from the database

loadNewsStories

public abstract DBIterator loadNewsStories(int field,
                                           int order,
                                           int limit)
                                    throws DatabaseException

Gets a DBIterator over the news stories in the database, ordered by the given order, and limited to the given amount.

If the given limit is more than the number of stories in the database, only the number available will be returned and no other error will occur.

Parameters:

field - The field to sort by, one of: NewsStory.FIELD_ID, NewsStory.FIELD_AUTHOR, NewsStory.FIELD_TOPIC, NewsStory.FIELD_POSTED, NewsStory.FIELD_HEADLINE, NewsStory.FIELD_ABSTRACT, or NewsStory.FIELD_BODY.

order - The order to sort the new stories, either ORDER_ASCENDING or ORDER_DESCENDING.

limit - The total number of stories to retrieve, or a negative number for all of them.

Returns:

a DBIterator that retrieves one story at a time.

Throws:

java.lang.IllegalArgumentException - if field is not one of NewsStory.FIELD_ID, NewsStory.FIELD_AUTHOR, NewsStory.FIELD_TOPIC, NewsStory.FIELD_POSTED, NewsStory.FIELD_HEADLINE, NewsStory.FIELD_ABSTRACT, or NewsStory.FIELD_BODY; or if order is not either ORDER_ASCENDING or ORDER_DESCENDING.

DatabaseException - if there is an error accessing data from the database

loadNewsStoryCount

public abstract int loadNewsStoryCount()
                                throws DatabaseException

Counts the number of news stories available. Returns a negative value if the number of stories could not be determined.

Returns:

the number of news stories in the database, or a negative value if the number of stories could not be determined

Throws:

DatabaseException - if there is an error accessing data from the database

saveNewsStory

public abstract void saveNewsStory(NewsStory newsStory)
                            throws DatabaseException

Save a NewsStory into the database. Should the numeric ID be less than 0, the DBEngine should pick one before saving the story into the database.

Parameters:

newsStory - the NewsStory object to save

Throws:

DatabaseException - if there is an error saving the data in the database

loadEvent

public abstract Event loadEvent(int id)
                         throws DatabaseException

Events are stored in a database via a numeric ID, this method should load the actual data based on the ID.

Parameters:

id - the ID for the event group being loaded

Returns:

the Event object loaded from the database

Throws:

DatabaseException - if there is an error accessing data from the database

loadEvent

public abstract Event loadEvent(java.lang.String name)
                         throws DatabaseException

Each events to be accessed through the website must have a unique name identifier (which will correspond with that event's URL). this method should load the actual data based on that name.

Parameters:

name - the name for the event group being loaded

Returns:

the Event object loaded from the database

Throws:

DatabaseException - if there is an error accessing data from the database (ie, if that event does not exist)

loadEvents

public abstract DBIterator loadEvents()
                               throws DatabaseException

Gets an DBIterator over the event groups in the database.

The remove() method in the DBIterator may or may not function depending on the implementation.

Returns:

a DBIterator that retrieves one event group at a time.

Throws:

DatabaseException - if there is an error accessing data from the database

loadEvents

public DBIterator loadEvents(int field,
                             int order)
                      throws DatabaseException

Gets a DBIterator over the event groups in the database, ordered by the given order.

Parameters:

field - The field to sort by, one of: Event.FIELD_ID, Event.FIELD_NAME, Event.FIELD_LOCATION, Event.FIELD_URL, or Event.FIELD_PAIRS.

order - The order to sort the new stories, either ORDER_ASCENDING or ORDER_DESCENDING.

Returns:

a DBIterator that retrieves one story at a time.

Throws:

java.lang.IllegalArgumentException - if field is not one of Event.FIELD_ID, Event.FIELD_NAME, Event.FIELD_LOCATION, Event.FIELD_URL, or Event.FIELD_PAIRS; or if order is not either ORDER_ASCENDING or ORDER_DESCENDING.

DatabaseException - if there is an error accessing data from the database

loadEvents

public abstract DBIterator loadEvents(int field,
                                      int order,
                                      int limit)
                               throws DatabaseException

Gets a DBIterator over the event groups in the database, ordered by the given order, and limited to the given amount.

If the given limit is more than the number of stories in the database, only the number available will be returned and no other error will occur.

Parameters:

field - The field to sort by, one of: Event.FIELD_ID, Event.FIELD_NAME, Event.FIELD_LOCATION, Event.FIELD_URL, or Event.FIELD_PAIRS.

order - The order to sort the new stories, either ORDER_ASCENDING or ORDER_DESCENDING.

limit - The total number of stories to retrieve, or a negative number for all of them.

Returns:

a DBIterator that retrieves one story at a time.

Throws:

java.lang.IllegalArgumentException - if field is not one of Event.FIELD_ID, Event.FIELD_NAME, Event.FIELD_LOCATION, Event.FIELD_URL, or Event.FIELD_PAIRS; or if order is not either ORDER_ASCENDING or ORDER_DESCENDING.

DatabaseException - if there is an error accessing data from the database

loadEventsFromDate

public abstract DBIterator loadEventsFromDate(int range,
                                              int order,
                                              int limit)
                                       throws DatabaseException

Gets a DBIterator over the event groups in the database, either before or after the current day (determined by range), ordered by the given order, and limited to the given amount.

If the given limit is more than the number of event groups in the database, only the number available will be returned and no other error will occur.

Parameters:

range - Determines if database will load events before (INCLUDE_BEFORE_TODAY) or after (INCLUDE_AFTER_TODAY) the current date.

order - The order to sort the new stories, either ORDER_ASCENDING or ORDER_DESCENDING.

limit - The total number of stories to retrieve, or a negative number for all of them.

Returns:

a DBIterator that retrieves one story at a time.

Throws:

java.lang.IllegalArgumentException - if range is not either INCLUDE_BEFORE_TODAY or INCLUDE_AFTER_TODAY; or if order is not either ORDER_ASCENDING or ORDER_DESCENDING.

DatabaseException - if there is an error accessing data from the database

loadEventCount

public abstract int loadEventCount()
                            throws DatabaseException

Counts the number of event groups available. Returns a negative value if the number of event groups could not be determined.

Returns:

the number of event groups in the database, or a negative value if the number of stories could not be determined.

Throws:

DatabaseException - if there is an error accessing data from the database

loadIcons

public abstract Icon[] loadIcons()
                          throws DatabaseException

Gets all the Icons in a database.

Returns:

the icons in the database

Throws:

DatabaseException - if there is an error accessing data from the database

loadTopics

public abstract Topic[] loadTopics()
                            throws DatabaseException

Gets all the Topics in a database.

Returns:

the topics in the database

Throws:

DatabaseException - if there is an error accessing data from the database