eTextReader.clientInterface
Class DBClient

java.lang.Object
  eTextReader.clientInterface.DBClient

All Implemented Interfaces:

NotationClient

public class DBClient
extends java.lang.Object
implements NotationClient

An class implementing the methods of interface NotationClient. Also contains several static utility methods.

Version:

5.1, 7/24/2003

Author:

Marty Kane Hope College REU 2002, Daniel Morrison Hope College Independent Study Research 2003

Nested Class Summary

static class

DBClient.NEW_USER_STATUS An enum to describe the possible outcomes when creating a new user

Field Summary

private static java.util.Vector	allClients
private java.sql.Connection	con
private static int	dbVersion
private static int	defaultTransactionIsolationLevel
private static java.lang.String	driverName
static int	FETCH_SIZE
private static java.lang.String	host
private static java.lang.String	jdbcString
private java.util.Vector	listeners
private java.lang.String	name
private java.sql.Connection	nextCon
private java.sql.Connection	offlineCon
private boolean	online
private DBClientOnlineTest	onlineTester
private int	reconnectTime
private boolean	tryNextCon
private boolean	verbose

Constructor Summary

DBClient()
Constructs a DBClient object.

DBClient(boolean verbose)
Constructs a DB client object with specified value for verbose and name of "Unnamed";

DBClient(boolean verbose, java.lang.String name)
Constructs a DBClient object.

Method Summary

boolean	addBookToCourse(java.lang.String courseID, java.lang.String bookURL) Adds the book identified by the given URL to the specified course
void	addDatabaseEventListener(java.lang.Object listener) Register an object as an DatabaseEventListener of this class.
void	addMember(java.lang.String memberName, java.lang.String groupName)
boolean	addUserToCourse(java.lang.String userName, java.lang.String courseName) Adds the specified user to the specified course
void	beginTransaction() Executes a begin transaction statement.
boolean	bookmarkExists(Notation n) determines if an annotation bookmark exists for the annotation n
static Criteria	buildCriteria(java.lang.Object[] args) Builds a Criteria object out of an array of pairs of objects
static Notation	buildNotation(java.lang.Object[] args) Builds a Notation object out of an array of pairs of objects
void	clearApplicationPreferences(java.lang.String userName) Deletes any stored application preferences for the given user.
void	clearCourseBooks(java.lang.String courseID) Remove records of any books associated with the specified course from the database.
void	clearLogRecords(java.lang.String userName) This method clears all log activity associated with the given user.
void	clearUserAnnotations(java.lang.String author, Notation.AnnotationType type) Removes all annotations of the specified type authored by the given author from the database.
void	clearUserCourses(java.lang.String userName) Remove records of any courses associated with the given user from the database.
boolean	closeConnection() Permanently close the connection to the database for this client.
void	commitTransaction() Executes a commit transaction statement.
int	computeIdentity(java.lang.String type) get an identity value that will be unique, even across replicated servers.
java.lang.String	computeUniqueNotationSubject(java.lang.String candidate, java.lang.String userName) looks in the database for notations with a subject matching candidate.
int	createNewGroup(java.lang.String newGroupName, java.lang.String userName)
DBClient.NEW_USER_STATUS	createNewUser(java.lang.String userName, java.lang.String password, PasswordPolicy policy) Creates a new user with the given user name and password, if it doesn't already exist
void	deleteNotation(java.lang.String userName, java.lang.String theTable, Criteria selectCriteria) Delete an existing notation.
boolean	deleteUser(java.lang.String userName) Deletes the given user from the set of valid users
java.sql.ResultSet	executeString(java.lang.String sqlstmt) Deprecated. Use query(String) method as of 6/16/03. This simply calls that method.
void	fireDatabaseEvent(DatabaseEvent de) Send an DatabaseEvent to all registered listeners.
java.util.Map	getAllowableNotations() retrieve a Map of NotationType, AllowableMode pairs The keys of the Map are the Notation Types, while the values are a Collection of all the allowable display modes for that type
Notation	getAnnotationBookmark(Notation n) Retrieves the annotation bookmark associated with the given annotation
java.util.List	getAnnotationURLS() retrieve a list of all the URL's containing annotations
static int	getDefaultTransactionIsolationLevel()
static int	getFETCH_SIZE()
int	getLastId() Gets the last id assigned to an inserted notation by the database.
java.lang.String	getName() retrieve the name given to this client when it was created
int	getNumberOfPosts(Notation disc) returns the number of posts that exist in the discussion that disc is a part of
java.util.Map	getQuickLaunchPrefs(java.lang.String user) retrieve the user's preference for QuickAnnotation viewing modes
boolean	goOffline() requests that the client work offline note that most likely, you want to call the static version of this method in order to make all open DBClient objects work offline
boolean	goOnline() requests that the client work online note that most likely, you want to call the static version of this method in order to make all open DBClient objects work online
boolean	goOnline(boolean on) attempts to change the online/offline status
boolean	isOnline() returns whether or not client is currently online
void	leaveGroup(java.lang.String leaveName, java.lang.String userName)
int	lookupISFID(int pngID) Looks up the notation id of the ISF version of a notation, given the id of the PNG value
void	lookupReference(Notation not)
static void	main(java.lang.String[] args) Test bed for DBClient implementation
void	markAlerted(java.lang.String userName, Notation viewed) Mark the specified notation as read in the bigbrother logging table
void	modifyGroupAdmin(java.lang.String groupName)
int	postNewBookmark(Notation.AnnotationType bookmarkType, java.lang.String name, java.lang.String author, java.lang.String url, java.lang.String addressStart, java.lang.String addressEnd) Creates a new bookmark with the specified parameters.
int	postNotation(java.lang.String userName, java.lang.String theTable, Notation theNotation) Post a notation to a document.
java.sql.ResultSet	preparedPostNotation(java.lang.String userName, java.lang.String theTable, Notation theNotation) Creates a prepared statement and calls preparedQuery to post the Notation.
java.sql.ResultSet	preparedQuery(java.lang.String statement, java.util.ArrayList info) Takes a string and an arraylist of statement info objects to build and execute a stored procedure using a callable statement
boolean	preparedQuery(java.lang.String sqlString, Notation theNotation) Takes a String and a Notation, creates a prepared statement out of them, and executes, returning a boolean.
private void	printSQLError(java.sql.SQLException e) Prints error information about an SQLException.
java.sql.ResultSet	query(java.lang.String statement) Takes a String and executes it as an SQL query that returns a ResultSet All queries should use query( String ) or updateQuery( String ) to enable offline (local) database access.
void	removeMember(java.lang.String memberName, java.lang.String groupName)
static java.lang.String	replaceSingleQuotes(java.lang.String s) Return a string which is a copy of the parameter, with all single quotes escaped as "''"
java.util.List<java.lang.String>	requestBookList(java.lang.String courseID) Retrieves a list of book URLs for the given course
java.util.List<java.lang.String>	requestEnrolledIn(java.lang.String userName) Returns a list of courses that the current user is enrolled in
java.util.List<java.lang.String>	requestFieldList(java.lang.String userName, java.lang.String theTable) Query the server for a list of valid Criteria fields.
int	requestFontSize(java.lang.String userName)
java.util.Vector	requestGroupList()
java.util.Vector	requestGroupMembers(java.lang.String groupName)
java.util.Vector	requestGroupMembership(java.lang.String userName) Send a request to the server to retrieve the name and ID of all the groups to which a particular user belongs.
java.util.Vector	requestGroupNames(java.lang.String userName)
java.util.Vector	requestGroupNotationPreferences(java.lang.String userName) Get the group view preferences for the specified user's notations
java.lang.String	requestHighlighterColor(java.lang.String userName, java.lang.String highlighterName)
int	requestIsReference(java.lang.String type, java.lang.String viewMode, boolean deft)
java.util.Vector	requestLeaveNames(java.lang.String userName)
java.util.Vector	requestMyManagedGroups(java.lang.String userName)
int	requestNotationCount(java.lang.String userName, java.lang.String theTable, Criteria selectCriteria) Query the server for a count of the number of notations on a document.
java.util.Vector<Notation>	requestNotationDownload(java.lang.String userName, java.lang.String theTable, Criteria selectCriteria, Criteria retrieveCriteria) Send a request to the server to download all notations that match the given criteria, retrieving only the fields indicated by retrieveCriteria.
Notation	requestNotationFromId(int notationId)
int	requestNotationsEnabled(java.lang.String userName) Send a request to the server to retrieve the value of the enable notations column for the specified user
java.util.Set<java.lang.Integer>	requestNotationsVisited(java.lang.String userName)
java.util.Vector	requestNotationTypes(boolean displayed)
java.util.Vector	requestPagesInRange(java.lang.String userName, java.lang.String startDate, java.lang.String endDate)
java.util.Vector	requestShare(int id, int isUser)
java.util.ArrayList<TabInfo>	requestTabPositions(java.lang.String userName) Retrieves and removes the stored tab positions from the user's last use of the book.
java.util.Vector	requestTarget(int id, int isUser)
java.util.Vector	requestTargetNotations(java.lang.String userName, int all) Send a request to the server to download all notations targeted to the specified user using the GetTargetNotations stored procedure to adjust the list according to share and view preferences
java.util.Vector	requestUserList(java.lang.String courseID) Send a request to the server to retrieve a particular user's users and their associated userIDs
java.util.Vector	requestUserNotationPreferences(java.lang.String userName, java.lang.String course) Get the user view preferences for the specified user's notations
java.util.Vector<Notation>	requestViewableNotations(java.lang.String url, java.lang.String userName) returns viewable notations for the specified URL regardless of date range
java.util.Vector	requestViewableNotations(java.lang.String url, java.lang.String userName, java.lang.String startDate, java.lang.String endDate)
Notation	requestViewingPreferences(java.lang.String userName) Send a request to the server to retrieve the name of all the viewing prefernces based on the current available types
java.util.Vector	requestViewModes(java.lang.String type)
java.util.Hashtable<ApplicationPreferences,java.lang.Object>	retrieveApplicationPrefs(java.lang.String user) retrieves user's ApplicationPrefs preferences from the database
boolean	retrieveDiagram(int notationId) Downloads the Diagram corresponding to notationID as a file named notationID.png into the temporary directory
void	rollbackTransaction() Executes a rollback transaction statement.
void	runDBSyncAgent() Synchronize the online and offline databases.
private void	selectConnection() Selects the best connection to use
void	setAutoCommitMode(boolean isAutoCommit) Sets the auto-commit mode of the JDBC connection associated with this client.
static void	setDefaultTransactionIsolationLevel(int level)
static void	setFETCH_SIZE(int fetch_size)
void	setNextConnection(java.sql.Connection c) Method to setup a Connection to be used next.
static java.util.List	setOnline(boolean on) requests that all active DBClient objects set their online status to on
void	setQuickLaunchPrefs(java.lang.String user, java.util.Map prefs) stores user's QuickLaunch preferences into the database
private java.sql.Connection	setupDBConnection(java.lang.String host) Connect to a provided host
void	setupInkAnnotation(int isfID, int pngID)
void	setVerbose(boolean v) Turn on or off extra command-line information.
void	synchronize()
void	updateAnnotation(Notation note) updates the annotation contained in note.
void	updateApplicationPrefs(java.lang.String user, Notation note) stores user's ApplicationPrefs preferences into the database
void	updateDiagram(Notation n)
int	updateNotation(java.lang.String userName, java.lang.String theTable, Criteria selectCriteria, Notation theNotation) Update an existing notation.
int	updatePassword(java.lang.String userName, java.lang.String pwd) Update a user's password
void	updateQuery(java.lang.String statement) Takes a String and executes it as an SQL update query Identical to query( String ) but does not return a ResultSet All queries should use query( String ) or updateQuery( String ) to enable offline (local) database access.
boolean	userNameExists(java.lang.String userName) Determines whether a given user name exists in the database
static java.util.List	workOffline()
static java.util.List	workOnline()

Methods inherited from class java.lang.Object

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

Field Detail

FETCH_SIZE

public static int FETCH_SIZE

name

private java.lang.String name

con

private java.sql.Connection con

nextCon

private java.sql.Connection nextCon

offlineCon

private java.sql.Connection offlineCon

verbose

private boolean verbose

online

private boolean online

tryNextCon

private boolean tryNextCon

onlineTester

private DBClientOnlineTest onlineTester

listeners

private java.util.Vector listeners

reconnectTime

private int reconnectTime

host

private static java.lang.String host

dbVersion

private static int dbVersion

driverName

private static java.lang.String driverName

jdbcString

private static java.lang.String jdbcString

defaultTransactionIsolationLevel

private static int defaultTransactionIsolationLevel

allClients

private static java.util.Vector allClients

Constructor Detail

DBClient

public DBClient()

Constructs a DBClient object. Default constructor. Verbose is false by default, name is "Unnamed"

DBClient

public DBClient(boolean verbose)

Constructs a DB client object with specified value for verbose and name of "Unnamed";

DBClient

public DBClient(boolean verbose,
                java.lang.String name)

Constructs a DBClient object.

Parameters:

verbose - indicates whether the client should output status information and errors to the command line.

Method Detail

setDefaultTransactionIsolationLevel

public static void setDefaultTransactionIsolationLevel(int level)

getDefaultTransactionIsolationLevel

public static int getDefaultTransactionIsolationLevel()

isOnline

public boolean isOnline()

returns whether or not client is currently online

Returns:

true if client thinks it is currently online; false otherwise

goOnline

public boolean goOnline(boolean on)

attempts to change the online/offline status

Parameters:

on - whether we should work online or not

Returns:

true if the online status was successfully changed to on, false otherwise

goOnline

public boolean goOnline()

requests that the client work online note that most likely, you want to call the static version of this method in order to make all open DBClient objects work online

Returns:

true if the client was able to successfully switch to online mode

goOffline

public boolean goOffline()

requests that the client work offline note that most likely, you want to call the static version of this method in order to make all open DBClient objects work offline

Returns:

true if the client was able to successfully switch to offline mode

setOnline

public static java.util.List setOnline(boolean on)

requests that all active DBClient objects set their online status to on

Parameters:

on - true if requesting the client to work online; false if requesting offline operation

Returns:

an ArrayList of client objects for which setting the status failed; if empty, then all client objects have been set successfully

workOnline

public static java.util.List workOnline()

workOffline

public static java.util.List workOffline()

setVerbose

public void setVerbose(boolean v)

Turn on or off extra command-line information. (Mostly used for debugging) Turning verbose mode off also supresses error messages.

Parameters:

v - indicates whether the client should output extra information

computeIdentity

public int computeIdentity(java.lang.String type)

get an identity value that will be unique, even across replicated servers. Calls the stored procedure ComputeIdentity

Parameters:

type - The type of identity value being generated. This is not really used, but could be used to track what has happened

Returns:

an integer value that can server as a unique identifier, or -1 if an error has occurred

requestTabPositions

public java.util.ArrayList<TabInfo> requestTabPositions(java.lang.String userName)

Retrieves and removes the stored tab positions from the user's last use of the book. The tab positions are then deleted

Parameters:

userName - the name of the user to load tab positions for

requestFieldList

public java.util.List<java.lang.String> requestFieldList(java.lang.String userName,
                                                         java.lang.String theTable)

Description copied from interface: NotationClient

Query the server for a list of valid Criteria fields.

Specified by:

requestFieldList in interface NotationClient

theTable - the URL location of the server.

requestNotationCount

public int requestNotationCount(java.lang.String userName,
                                java.lang.String theTable,
                                Criteria selectCriteria)

Description copied from interface: NotationClient

Query the server for a count of the number of notations on a document.

Specified by:

requestNotationCount in interface NotationClient

theTable - the table to retrieve Notations from

selectCriteria - the criteria used to select notations to count.

Returns:

The number of notations on the document which match the specified criteria.

requestViewableNotations

public java.util.Vector<Notation> requestViewableNotations(java.lang.String url,
                                                           java.lang.String userName)

returns viewable notations for the specified URL regardless of date range

Specified by:

requestViewableNotations in interface NotationClient

Parameters:

url - the url of the page for which the notations are desired

userName - the name of the user for which notations are retrieved

requestViewableNotations

public java.util.Vector requestViewableNotations(java.lang.String url,
                                                 java.lang.String userName,
                                                 java.lang.String startDate,
                                                 java.lang.String endDate)

requestTargetNotations

public java.util.Vector requestTargetNotations(java.lang.String userName,
                                               int all)

Description copied from interface: NotationClient

Send a request to the server to download all notations targeted to the specified user using the GetTargetNotations stored procedure to adjust the list according to share and view preferences

Specified by:

requestTargetNotations in interface NotationClient

Parameters:

userName - the name of the user for which notations are retrieved

all - determines whether to retrieve all targeted notations (1) or just those that have not yet been viewed (0)

requestNotationFromId

public Notation requestNotationFromId(int notationId)

lookupReference

public void lookupReference(Notation not)

requestNotationDownload

public java.util.Vector<Notation> requestNotationDownload(java.lang.String userName,
                                                          java.lang.String theTable,
                                                          Criteria selectCriteria,
                                                          Criteria retrieveCriteria)

Description copied from interface: NotationClient

Send a request to the server to download all notations that match the given criteria, retrieving only the fields indicated by retrieveCriteria.

Specified by:

requestNotationDownload in interface NotationClient

theTable - the table to retrieve Notations from.

selectCriteria - the criteria used to select notations to count.

retrieveCriteria - the criteria used to specify which parts of the selected notations are downloaded.

Returns:

A Vector containing all the matching Notations.

requestNotationsEnabled

public int requestNotationsEnabled(java.lang.String userName)

Description copied from interface: NotationClient

Send a request to the server to retrieve the value of the enable notations column for the specified user

Specified by:

requestNotationsEnabled in interface NotationClient

Parameters:

userName - the name of the user

Returns:

An int containing the value of enableNotations

requestGroupList

public java.util.Vector requestGroupList()

requestUserList

public java.util.Vector requestUserList(java.lang.String courseID)

Description copied from interface: NotationClient

Send a request to the server to retrieve a particular user's users and their associated userIDs

Specified by:

requestUserList in interface NotationClient

Returns:

A Vector containing the usernames and IDs in notation objects

requestNotationsVisited

public java.util.Set<java.lang.Integer> requestNotationsVisited(java.lang.String userName)

requestViewingPreferences

public Notation requestViewingPreferences(java.lang.String userName)

Description copied from interface: NotationClient

Send a request to the server to retrieve the name of all the viewing prefernces based on the current available types

Specified by:

requestViewingPreferences in interface NotationClient

Parameters:

userName - the username for which the preferences are downloaded

Returns:

A notation object containing the types and settings

requestFontSize

public int requestFontSize(java.lang.String userName)

requestNotationTypes

public java.util.Vector requestNotationTypes(boolean displayed)

requestViewModes

public java.util.Vector requestViewModes(java.lang.String type)

requestIsReference

public int requestIsReference(java.lang.String type,
                              java.lang.String viewMode,
                              boolean deft)

requestShare

public java.util.Vector requestShare(int id,
                                     int isUser)

requestTarget

public java.util.Vector requestTarget(int id,
                                      int isUser)

requestGroupNames

public java.util.Vector requestGroupNames(java.lang.String userName)

requestLeaveNames

public java.util.Vector requestLeaveNames(java.lang.String userName)

requestGroupMembership

public java.util.Vector requestGroupMembership(java.lang.String userName)

Description copied from interface: NotationClient

Send a request to the server to retrieve the name and ID of all the groups to which a particular user belongs.

Specified by:

requestGroupMembership in interface NotationClient

Parameters:

userName - the user name of the person using the client

Returns:

A Vector containing the group names and IDs in notation objects

requestMyManagedGroups

public java.util.Vector requestMyManagedGroups(java.lang.String userName)

requestGroupMembers

public java.util.Vector requestGroupMembers(java.lang.String groupName)

addMember

public void addMember(java.lang.String memberName,
                      java.lang.String groupName)

removeMember

public void removeMember(java.lang.String memberName,
                         java.lang.String groupName)

modifyGroupAdmin

public void modifyGroupAdmin(java.lang.String groupName)

createNewGroup

public int createNewGroup(java.lang.String newGroupName,
                          java.lang.String userName)

leaveGroup

public void leaveGroup(java.lang.String leaveName,
                       java.lang.String userName)

requestGroupNotationPreferences

public java.util.Vector requestGroupNotationPreferences(java.lang.String userName)

Description copied from interface: NotationClient

Get the group view preferences for the specified user's notations

Specified by:

requestGroupNotationPreferences in interface NotationClient

Parameters:

userName - the user name for which the preferences will be retrieved

Returns:

A Vector containing the matching database entries

requestUserNotationPreferences

public java.util.Vector requestUserNotationPreferences(java.lang.String userName,
                                                       java.lang.String course)

Description copied from interface: NotationClient

Get the user view preferences for the specified user's notations

Specified by:

requestUserNotationPreferences in interface NotationClient

Parameters:

userName - the user name for which the preferences will be retrieved

course - the course ID for the current class

Returns:

A Vector containing the matching database entries

requestHighlighterColor

public java.lang.String requestHighlighterColor(java.lang.String userName,
                                                java.lang.String highlighterName)

requestPagesInRange

public java.util.Vector requestPagesInRange(java.lang.String userName,
                                            java.lang.String startDate,
                                            java.lang.String endDate)

postNotation

public int postNotation(java.lang.String userName,
                        java.lang.String theTable,
                        Notation theNotation)

Description copied from interface: NotationClient

Post a notation to a document.

Specified by:

postNotation in interface NotationClient

theTable - the table to retrieve Notations from.

theNotation - the Notation to post, which will be assigned an ID by the server.

Returns:

the ID of the posted Notation. Note: if the object being posted is not a Notation (does not have an identity) the returned value is not valid.

updateAnnotation

public void updateAnnotation(Notation note)

updates the annotation contained in note. At the least, note must contain an id field to identify the annotation

Parameters:

note - a Notation object describing the fields of the notation to be updated

markAlerted

public void markAlerted(java.lang.String userName,
                        Notation viewed)

Description copied from interface: NotationClient

Mark the specified notation as read in the bigbrother logging table

Specified by:

markAlerted in interface NotationClient

Parameters:

userName - the name of the user

viewed - the notation object that we wish to mark as viewed

updatePassword

public int updatePassword(java.lang.String userName,
                          java.lang.String pwd)

Description copied from interface: NotationClient

Update a user's password

Specified by:

updatePassword in interface NotationClient

Parameters:

userName - the name of the user

pwd - the value to which the password is changed

Returns:

an int indcating whether or not it was successful. A 0 indicates that an error was encountered, otherwise returns 1.

updateNotation

public int updateNotation(java.lang.String userName,
                          java.lang.String theTable,
                          Criteria selectCriteria,
                          Notation theNotation)

Description copied from interface: NotationClient

Update an existing notation.

Specified by:

updateNotation in interface NotationClient

theTable - the table to retrieve Notations from.

selectCriteria - determines which notation is updated

theNotation - the new Notation object.

Returns:

the ID of the posted Notation.

deleteNotation

public void deleteNotation(java.lang.String userName,
                           java.lang.String theTable,
                           Criteria selectCriteria)

Description copied from interface: NotationClient

Delete an existing notation.

Specified by:

deleteNotation in interface NotationClient

theTable - the table to retrieve Notations from.

selectCriteria - determines which notation is updated

closeConnection

public boolean closeConnection()

Description copied from interface: NotationClient

Permanently close the connection to the database for this client. To open a new connection, a new client object must be instantiated.

Specified by:

closeConnection in interface NotationClient

getLastId

public int getLastId()

Gets the last id assigned to an inserted notation by the database.

Returns:

the last identity assigned by the database, or -1 on error.

setupDBConnection

private java.sql.Connection setupDBConnection(java.lang.String host)

Connect to a provided host

Parameters:

host - The host to connect to

Returns:

Connection The created connection object connected to host

replaceSingleQuotes

public static java.lang.String replaceSingleQuotes(java.lang.String s)

Return a string which is a copy of the parameter, with all single quotes escaped as "''"

Parameters:

s - The string to escape

Returns:

a the escaped String

buildCriteria

public static Criteria buildCriteria(java.lang.Object[] args)

Builds a Criteria object out of an array of pairs of objects

Parameters:

an - array containing key,value pairs for the Criteria

Returns:

a Critieria object

buildNotation

public static Notation buildNotation(java.lang.Object[] args)

Builds a Notation object out of an array of pairs of objects

Parameters:

an - array containing key,value pairs for the Notation

Returns:

a Notation object

preparedPostNotation

public java.sql.ResultSet preparedPostNotation(java.lang.String userName,
                                               java.lang.String theTable,
                                               Notation theNotation)

Creates a prepared statement and calls preparedQuery to post the Notation. This function is used for instances of Diagram to allow posting of their binaray data.

Parameters:

userName - the name of the author of theNotation.

theTable - the name of the database table that theNotation is to be posted into.

theNotation - the Notation to be posted into the database.

Returns:

a ResultSet corresponding to the new column in theTable.

updateDiagram

public void updateDiagram(Notation n)

retrieveDiagram

public boolean retrieveDiagram(int notationId)

Downloads the Diagram corresponding to notationID as a file named notationID.png into the temporary directory

Parameters:

notationId - The ID of the Diagram to be downloaded.

Returns:

Returns true if Diagram was sucessfully downloaded.

executeString

public java.sql.ResultSet executeString(java.lang.String sqlstmt)

Deprecated. Use query(String) method as of 6/16/03. This simply calls that method.

Takes a String and executes it as an SQL statement

Parameters:

a - String that is executed

preparedQuery

public boolean preparedQuery(java.lang.String sqlString,
                             Notation theNotation)

Takes a String and a Notation, creates a prepared statement out of them, and executes, returning a boolean. This method enables offline (local) database access.

Parameters:

sqlString - The String used as a basis for the PreparedStatement.

theNotation - The Notation to be stored into the database.

Returns:

True if the statement executed correctly.

query

public java.sql.ResultSet query(java.lang.String statement)

Takes a String and executes it as an SQL query that returns a ResultSet All queries should use query( String ) or updateQuery( String ) to enable offline (local) database access.

Parameters:

a - String that is executed

Returns:

A ResultSet object

Since:

5.0

updateQuery

public void updateQuery(java.lang.String statement)

Takes a String and executes it as an SQL update query Identical to query( String ) but does not return a ResultSet All queries should use query( String ) or updateQuery( String ) to enable offline (local) database access.

Parameters:

a - String that is executed

Since:

5.0

preparedQuery

public java.sql.ResultSet preparedQuery(java.lang.String statement,
                                        java.util.ArrayList info)

Takes a string and an arraylist of statement info objects to build and execute a stored procedure using a callable statement

Parameters:

statement - the callable statement which may contain one or more '?' characters

info - the arraylist containing StatementInfo objects to replace the '?'s in the string

Returns:

the ResultSet object retrieved by the query

printSQLError

private void printSQLError(java.sql.SQLException e)

Prints error information about an SQLException.

Parameters:

The - SQLException to print.

Since:

5.0

setNextConnection

public void setNextConnection(java.sql.Connection c)

Method to setup a Connection to be used next. Doesn't sync the DB; we'll leave that up to listeners to do so there is more control

Parameters:

A - set up Connection object.

Since:

5.1

selectConnection

private void selectConnection()

Selects the best connection to use

Since:

5.1

runDBSyncAgent

public void runDBSyncAgent()

Synchronize the online and offline databases.

Since:

5.1

fireDatabaseEvent

public void fireDatabaseEvent(DatabaseEvent de)

Send an DatabaseEvent to all registered listeners.

Parameters:

de - the DatabaseEvent to send.

addDatabaseEventListener

public void addDatabaseEventListener(java.lang.Object listener)

Register an object as an DatabaseEventListener of this class.

Parameters:

listener - the listener object.

getName

public java.lang.String getName()

retrieve the name given to this client when it was created

getAnnotationURLS

public java.util.List getAnnotationURLS()

retrieve a list of all the URL's containing annotations

Returns:

a java.util.List of distinct URL's that have been annotated

getAllowableNotations

public java.util.Map getAllowableNotations()

retrieve a Map of NotationType, AllowableMode pairs The keys of the Map are the Notation Types, while the values are a Collection of all the allowable display modes for that type

getQuickLaunchPrefs

public java.util.Map getQuickLaunchPrefs(java.lang.String user)

retrieve the user's preference for QuickAnnotation viewing modes

Parameters:

user: - The user whose preferences are to be retrieved

Returns:

a java.util.Map containing ViewMode entries as keys, and the user's preferred mode as values

setQuickLaunchPrefs

public void setQuickLaunchPrefs(java.lang.String user,
                                java.util.Map prefs)

stores user's QuickLaunch preferences into the database

Parameters:

user - the user whose preferences are being stored

prefs - a Map containing the user preferences; the key of the entries are NotationTypes, and values are ViewModes

updateApplicationPrefs

public void updateApplicationPrefs(java.lang.String user,
                                   Notation note)

stores user's ApplicationPrefs preferences into the database

Parameters:

user - the user whose preferences are being stored

note - the Notation object containing the preferences Hashtable in a storeable byte format

retrieveApplicationPrefs

public java.util.Hashtable<ApplicationPreferences,java.lang.Object> retrieveApplicationPrefs(java.lang.String user)

retrieves user's ApplicationPrefs preferences from the database

Parameters:

user - the user whose preferences are being stored

Returns:

a Hashtable mapping ApplicationPreferences to Objects, containing the specified user's application preferences

See Also:

eTextReader.AplicationPreferences

computeUniqueNotationSubject

public java.lang.String computeUniqueNotationSubject(java.lang.String candidate,
                                                     java.lang.String userName)

looks in the database for notations with a subject matching candidate. If none exist, candidate is returned; otherwise, an increasing integer value is appended to candiate until a unique title is found

Parameters:

candidate - the string to look for in the databaes

userName - the user name of the notation to be created

Returns:

a unique subject string containing candidate; the string is unique only in terms of userName (e.g., identical subjects with different username are allowed)

setupInkAnnotation

public void setupInkAnnotation(int isfID,
                               int pngID)

lookupISFID

public int lookupISFID(int pngID)

Looks up the notation id of the ISF version of a notation, given the id of the PNG value

bookmarkExists

public boolean bookmarkExists(Notation n)

determines if an annotation bookmark exists for the annotation n

Parameters:

n - the notation to look for a bookmark for

Returns:

true if an annotation bookmark exists for notation n, false otherwise

postNewBookmark

public int postNewBookmark(Notation.AnnotationType bookmarkType,
                           java.lang.String name,
                           java.lang.String author,
                           java.lang.String url,
                           java.lang.String addressStart,
                           java.lang.String addressEnd)

Creates a new bookmark with the specified parameters. This is a convenience method which is a wrapper around the postNotation method.

Parameters:

bookmarkType -

name -

author -

addressStart -

addressEnd -

Returns:

the ID of the newly created notation, or -1 if a bookmark with the specified subject by the given author already exists

See Also:

postNotation(String, String, Notation)

getAnnotationBookmark

public Notation getAnnotationBookmark(Notation n)

Retrieves the annotation bookmark associated with the given annotation

Parameters:

n - the annotation to look for a bookmark

Returns:

a Notation object representing the annotation bookmark, or null if no such bookmark exists

getNumberOfPosts

public int getNumberOfPosts(Notation disc)

returns the number of posts that exist in the discussion that disc is a part of

requestBookList

public java.util.List<java.lang.String> requestBookList(java.lang.String courseID)

Retrieves a list of book URLs for the given course

Parameters:

courseID - the courseID to retrieve books for

Returns:

a (possibly empty) List of strings representing URLs for books for the given course, or null if an SQL exception occurs trying to retrieve the list

requestEnrolledIn

public java.util.List<java.lang.String> requestEnrolledIn(java.lang.String userName)

Returns a list of courses that the current user is enrolled in

Parameters:

userName - the user to look up enrollment for

Returns:

a List of strings containing the course ID, or null if an SQLException occurs while attempting to retrieve the list of courses

setAutoCommitMode

public void setAutoCommitMode(boolean isAutoCommit)
                       throws java.sql.SQLException

Sets the auto-commit mode of the JDBC connection associated with this client.

Parameters:

isAutoCommit - if true, then each statement executed by the connection is immediately committed; if false, then the user is responsible for managing connections

Throws:

java.sql.SQLException

beginTransaction

public void beginTransaction()

Executes a begin transaction statement. Note that the DBClient must not be in autoCommit mode for this to have any impact on how the client executes

See Also:

setAutoCommitMode(boolean)

commitTransaction

public void commitTransaction()

Executes a commit transaction statement. Note that the DBClient must not be in autoCommit mode for this to have any impact on how the client executes

See Also:

setAutoCommitMode(boolean)

rollbackTransaction

public void rollbackTransaction()

Executes a rollback transaction statement. Note that the DBClient must not be in autoCommit mode for this to have any impact on how the client executes

See Also:

setAutoCommitMode(boolean)

synchronize

public void synchronize()

main

public static void main(java.lang.String[] args)

Test bed for DBClient implementation

getFETCH_SIZE

public static int getFETCH_SIZE()

setFETCH_SIZE

public static void setFETCH_SIZE(int fetch_size)

clearLogRecords

public void clearLogRecords(java.lang.String userName)

This method clears all log activity associated with the given user. This is primarily used for testing purposes, and shouldn't be called from outside of that environment

Parameters:

userName - the user whose log records should be cleared

clearApplicationPreferences

public void clearApplicationPreferences(java.lang.String userName)

Deletes any stored application preferences for the given user. This is primarily used for testing purposes, and won't generally be used outside of that environment

Parameters:

userName - the user whose application preferences should be cleared

clearUserCourses

public void clearUserCourses(java.lang.String userName)

Remove records of any courses associated with the given user from the database. This is primarily used for testing purposes, and won't generally be used outside of that environment.

Parameters:

userName - the user whose course records should be cleared

clearCourseBooks

public void clearCourseBooks(java.lang.String courseID)

Remove records of any books associated with the specified course from the database. This is primarily used for testing purposes, and probably won't be used outside fo that environment.

Parameters:

courseID - the course to remove books for

clearUserAnnotations

public void clearUserAnnotations(java.lang.String author,
                                 Notation.AnnotationType type)

Removes all annotations of the specified type authored by the given author from the database. This is primarily used for testing purposes, and won't generally be used outside of that environment

Parameters:

author - the name of the author of the annotation

type - the

addUserToCourse

public boolean addUserToCourse(java.lang.String userName,
                               java.lang.String courseName)

Adds the specified user to the specified course

Parameters:

userName - the user to add

courseName - the course to add the user to

Returns:

true if the user was added to the course, false if the user already existed

addBookToCourse

public boolean addBookToCourse(java.lang.String courseID,
                               java.lang.String bookURL)

Adds the book identified by the given URL to the specified course

Parameters:

courseID - the course to which the book should be added

bookURL - the URL where the OEBPackageFile describing the book can be found

Returns:

true if the book was added, false if it already existed

userNameExists

public boolean userNameExists(java.lang.String userName)

Determines whether a given user name exists in the database

Parameters:

userName - the user name to check

Returns:

true if the user name already exists, false otherwise

createNewUser

public DBClient.NEW_USER_STATUS createNewUser(java.lang.String userName,
                                              java.lang.String password,
                                              PasswordPolicy policy)

Creates a new user with the given user name and password, if it doesn't already exist

Parameters:

userName - the user name for the new user

password - a plaintext password for the user

PasswordPolicy -

Returns:

a NEW_USER_STATUS object describing the outcome of the call

deleteUser

public boolean deleteUser(java.lang.String userName)

Deletes the given user from the set of valid users

Parameters:

userName - the user to delete

Returns:

true if the user was successfully deleted, false if the user did not exist