diff options
Diffstat (limited to 'src')
| -rw-r--r-- | src/uk/org/ury/database/DatabaseDriver.java | 298 | ||||
| -rw-r--r-- | src/uk/org/ury/database/DatabaseItem.java | 152 | ||||
| -rw-r--r-- | src/uk/org/ury/database/UserClass.java | 46 | ||||
| -rw-r--r-- | src/uk/org/ury/database/exceptions/package.html | 11 | ||||
| -rw-r--r-- | src/uk/org/ury/database/package.html | 15 | ||||
| -rw-r--r-- | src/uk/org/ury/library/viewer/LibraryViewer.java | 14 | ||||
| -rw-r--r-- | src/uk/org/ury/library/viewer/LibraryViewerPanel.java | 3 | ||||
| -rw-r--r-- | src/uk/org/ury/overview.html | 29 | ||||
| -rw-r--r-- | src/uk/org/ury/server/AbstractRequestHandler.java | 10 | ||||
| -rw-r--r-- | src/uk/org/ury/server/Server.java | 3 | ||||
| -rw-r--r-- | src/uk/org/ury/server/package.html | 23 | ||||
| -rw-r--r-- | src/uk/org/ury/show/ShowChannel.java | 221 | ||||
| -rw-r--r-- | src/uk/org/ury/show/ShowUtils.java | 361 | ||||
| -rw-r--r-- | src/uk/org/ury/show/ShowUtils.properties | 4 | ||||
| -rw-r--r-- | src/uk/org/ury/show/item/package.html | 14 |
15 files changed, 625 insertions, 579 deletions
diff --git a/src/uk/org/ury/database/DatabaseDriver.java b/src/uk/org/ury/database/DatabaseDriver.java index 7c71827..e48b0a1 100644 --- a/src/uk/org/ury/database/DatabaseDriver.java +++ b/src/uk/org/ury/database/DatabaseDriver.java @@ -11,162 +11,156 @@ import uk.org.ury.config.ConfigReader; import uk.org.ury.database.exceptions.ConnectionFailureException; import uk.org.ury.database.exceptions.MissingCredentialsException; - /** - * A database connection manager that connects to the URY databases - * using suitably privileged accounts, and handles the processing - * of SQL queries. - * + * A database connection manager that connects to the URY databases using + * suitably privileged accounts, and handles the processing of SQL queries. + * * @author Matt Windsor * @author Nathan Lasseter - * + * */ +public class DatabaseDriver { + /* The JDBC path used to connect to the URY database. */ + private String DATABASE_PATH = "jdbc:postgresql://"; + + /* The database connection. */ + private Connection conn; + + /** + * Construct a new DatabaseDriver with the given user class. + * + * @param config + * The config with login details. + * + * @param type + * The user class to log in to the database with. + * + * @throws IllegalArgumentException + * if the user class is not supported (this should not happen). + * + * @throws MissingCredentialsException + * if the user class login credentials could not be loaded. + * + * @throws ConnectionFailureException + * if the database backend failed to connect to the database + * server. + */ + public DatabaseDriver(ConfigReader config, UserClass type) + throws MissingCredentialsException, ConnectionFailureException { + try { + connect(config, type); + } catch (SQLException e) { + throw new ConnectionFailureException(e.getMessage()); + } + + } + + /** + * Connect to the URY database. + * + * @param config + * The config to use for the connection. + * @param type + * The access level of the connection + * + * @throws SQLException + * if the database connection failed. + */ + private void connect(ConfigReader config, UserClass type) + throws SQLException { + if (config == null) + throw new IllegalArgumentException("Supplied null config."); + + if (config.getDatabase().getHost() == null) + throw new IllegalArgumentException("config has no associated host."); + + if (config.getDatabase().getDb() == null) + throw new IllegalArgumentException( + "config has no associated database."); + + DATABASE_PATH = DATABASE_PATH + config.getDatabase().getHost() + "/" + + config.getDatabase().getDb(); + + if (type == UserClass.READ_ONLY) { + if (config.getRoAuth().getUser() == null) + throw new IllegalArgumentException( + "config has no associated username."); + if (config.getRoAuth().getPass() == null) + throw new IllegalArgumentException( + "config has no associated password."); + conn = DriverManager.getConnection(DATABASE_PATH, config + .getRoAuth().getUser(), config.getRoAuth().getPass()); + } else if (type == UserClass.READ_WRITE) { + if (config.getRwAuth().getUser() == null) + throw new IllegalArgumentException( + "config has no associated username."); + if (config.getRwAuth().getPass() == null) + throw new IllegalArgumentException( + "config has no associated password."); + conn = DriverManager.getConnection(DATABASE_PATH, config + .getRwAuth().getUser(), config.getRwAuth().getPass()); + } + } + + /** + * Execute an unprepared SQL statement with no arguments. + * + * @param sql + * The SQL statement to execute. + * @param fetchSize + * The maximum number of query rows to return. + * + * @return the JDBC results set. + * + * @throws SQLException + * if a SQL error occurs. + */ + public ResultSet executeQuery(String sql, int fetchSize) + throws SQLException { + Statement st = conn.createStatement(); + st.setFetchSize(fetchSize); + + return st.executeQuery(sql); + } + + /** + * Perform a SQL statement with arguments. + * + * This accepts an array of parameter objects, which must each either be + * String or Integer objects. The objects will be used sequentially to fill + * in '?' placeholders in the query text. + * + * @param sql + * The SQL statement to execute. + * @param params + * A list of parameter objects. + * @param fetchSize + * The maximum number of query rows to return. + * + * @return the set of results from the query. + * + * @throws IllegalArgumentException + * if any of the parameters is unsupported by the database as a + * statement parameter. + * + * @throws SQLException + * if a SQL error occurs. + */ + public ResultSet executeQuery(String sql, Object[] params, int fetchSize) + throws SQLException { + PreparedStatement st = conn.prepareStatement(sql); + + st.setFetchSize(fetchSize); + + for (int i = 0; i < params.length; i++) + if (params[i] instanceof String) + st.setString(i + 1, (String) params[i]); + else if (params[i] instanceof Integer) + st.setInt(i + 1, (Integer) params[i]); + else + throw new IllegalArgumentException("Unsupported parameter #" + + (i + 1)); -public class DatabaseDriver -{ - /* The JDBC path used to connect to the URY database. */ - private String DATABASE_PATH = "jdbc:postgresql://"; - - /* The database connection. */ - private Connection conn; - - - /** - * Construct a new DatabaseDriver with the given user class. - * - * @param config The config with login details. - * - * @param type The user class to log in to the database with. - * - * @throws IllegalArgumentException if the user class is - * not supported (this should not happen). - * - * @throws MissingCredentialsException if the user class - * login credentials could not be loaded. - * - * @throws ConnectionFailureException if the database - * backend failed to connect to the database - * server. - */ - - public - DatabaseDriver (ConfigReader config, UserClass type) - throws MissingCredentialsException, ConnectionFailureException - { - try - { - connect (config, type); - } - catch (SQLException e) - { - throw new ConnectionFailureException (e.getMessage ()); - } - - } - - - /** - * Connect to the URY database. - * - * @param config The config to use for the connection. - * @param type The access level of the connection - * - * @throws SQLException if the database connection failed. - */ - - private void - connect (ConfigReader config, UserClass type) - throws SQLException - { - if (config == null) - throw new IllegalArgumentException ("Supplied null config."); - - if (config.getDatabase().getHost() == null) - throw new IllegalArgumentException ("config has no associated host."); - - if (config.getDatabase().getDb() == null) - throw new IllegalArgumentException ("config has no associated database."); - - DATABASE_PATH = DATABASE_PATH + config.getDatabase().getHost() + "/" + config.getDatabase().getDb(); - - if(type == UserClass.READ_ONLY) { - if(config.getRoAuth().getUser() == null) - throw new IllegalArgumentException ("config has no associated username."); - if(config.getRoAuth().getPass() == null) - throw new IllegalArgumentException ("config has no associated password."); - conn = DriverManager.getConnection (DATABASE_PATH, - config.getRoAuth().getUser(), - config.getRoAuth().getPass()); - } else if(type == UserClass.READ_WRITE) { - if(config.getRwAuth().getUser() == null) - throw new IllegalArgumentException ("config has no associated username."); - if(config.getRwAuth().getPass() == null) - throw new IllegalArgumentException ("config has no associated password."); - conn = DriverManager.getConnection (DATABASE_PATH, - config.getRwAuth().getUser(), - config.getRwAuth().getPass()); + return st.executeQuery(); } - } - - - /** - * Execute an unprepared SQL statement with no arguments. - * - * @param sql The SQL statement to execute. - * @param fetchSize The maximum number of query rows to return. - * - * @return the JDBC results set. - * - * @throws SQLException if a SQL error occurs. - */ - - public ResultSet - executeQuery (String sql, int fetchSize) - throws SQLException - { - Statement st = conn.createStatement (); - st.setFetchSize (fetchSize); - - return st.executeQuery (sql); - } - - - /** - * Perform a SQL statement with arguments. - * - * This accepts an array of parameter objects, which must each - * either be String or Integer objects. The objects will be used - * sequentially to fill in '?' placeholders in the query text. - * - * @param sql The SQL statement to execute. - * @param params A list of parameter objects. - * @param fetchSize The maximum number of query rows to return. - * - * @return the set of results from the query. - * - * @throws IllegalArgumentException if any of the - * parameters is unsupported by the database as - * a statement parameter. - * - * @throws SQLException if a SQL error occurs. - */ - - public ResultSet - executeQuery (String sql, Object[] params, int fetchSize) - throws SQLException - { - PreparedStatement st = conn.prepareStatement (sql); - - st.setFetchSize (50); - - for (int i = 0; i < params.length; i++) - if (params[i] instanceof String) - st.setString (i + 1, (String) params[i]); - else if (params[i] instanceof Integer) - st.setInt (i + 1, (Integer) params[i]); - else - throw new IllegalArgumentException ("Unsupported parameter #" + (i + 1)); - - return st.executeQuery (); - } } diff --git a/src/uk/org/ury/database/DatabaseItem.java b/src/uk/org/ury/database/DatabaseItem.java index 54b2ef7..bac23a5 100644 --- a/src/uk/org/ury/database/DatabaseItem.java +++ b/src/uk/org/ury/database/DatabaseItem.java @@ -5,94 +5,76 @@ import java.util.Map; import uk.org.ury.database.exceptions.MissingPropertyException; - /** - * An abstract class presenting a template for objects serving as - * a data structure for collections of properties retrieved from - * a SQL database. - * - * @param E The enumeration type used as the property list. + * An abstract class presenting a template for objects serving as a data + * structure for collections of properties retrieved from a SQL database. + * + * @param E + * The enumeration type used as the property list. * - * @param T The type of datum stored for each property. + * @param T + * The type of datum stored for each property. * - * @author Matt Windsor + * @author Matt Windsor */ +public abstract class DatabaseItem<E, T> { + private Map<E, T> properties; + + /** + * Construct a new item from an existing list of properties. + * + * @param properties + * The map of properties that the new item will inherit. + */ + public DatabaseItem(Map<E, T> properties) { + this.properties = properties; + } + + /** + * Check whether a property has been set in the item. + * + * @return true if the property has been set; false otherwise. + */ + + public boolean has(E property) { + return properties.containsKey(property); + } + + /** + * Query this item for a property. + * + * @param property + * The property to query. + * + * @return The property, if it exists. + * + * @throws MissingPropertyException + * if the property does not exist. + */ + public T get(E property) throws MissingPropertyException { + if (properties.containsKey(property)) + return properties.get(property); + else + throw new MissingPropertyException(property.toString()); + } + + /** + * Retrieve a map of string representations of the properties. + * + * This relies on E and T having meaningful toString methods. + * + * @return a list of lines representing the response. + */ + public Map<String, String> asResponse() { + // TODO: Fan out implementation details into separate class + Map<String, String> response = new HashMap<String, String>(); + + for (E property : properties.keySet()) { + if (properties.get(property) != null) + response.put(property.toString(), properties.get(property) + .toString()); + } -public abstract class DatabaseItem<E, T> -{ - private Map<E, T> properties; - - - /** - * Construct a new item from an existing list of properties. - * - * @param properties The map of properties that the new item will - * inherit. - */ - - public - DatabaseItem (Map<E, T> properties) - { - this.properties = properties; - } - - - /** - * Check whether a property has been set in the item. - * - * @return true if the property has been set; false otherwise. - */ - - public boolean - has (E property) - { - return properties.containsKey (property); - } - - - /** - * Query this item for a property. - * - * @param property The property to query. - * - * @return The property, if it exists. - * - * @throws MissingPropertyException if the property does - * not exist. - */ - - public T - get (E property) throws MissingPropertyException - { - if (properties.containsKey (property)) - return properties.get (property); - else - throw new MissingPropertyException (property.toString ()); - } - - - /** - * Retrieve a map of string representations of the properties. - * - * This relies on E and T having meaningful toString methods. - * - * @return a list of lines representing the response. - */ - - public Map<String, String> - asResponse () - { - // TODO: Fan out implementation details into separate class - - Map<String, String> response = new HashMap<String, String> (); - - for (E property : properties.keySet ()) - { - if (properties.get (property) != null) - response.put (property.toString (), - properties.get (property).toString ()); - } - - return response; - } + return response; + } } diff --git a/src/uk/org/ury/database/UserClass.java b/src/uk/org/ury/database/UserClass.java index 79af61a..48cb2d3 100644 --- a/src/uk/org/ury/database/UserClass.java +++ b/src/uk/org/ury/database/UserClass.java @@ -3,38 +3,36 @@ */ package uk.org.ury.database; - /** * The various user classes of the database driver. * - * These refer to various users in the database proper, and thus - * grant various levels of permission to the program. + * These refer to various users in the database proper, and thus grant various + * levels of permission to the program. + * + * Please use the least privileged user class that works. For most cases, + * READ_ONLY should work perfectly. * - * Please use the least privileged user class that works. For most - * cases, READ_ONLY should work perfectly. + * @author Matt Windsor * - * @author Matt Windsor - * */ -public enum UserClass - { - // Constant configName - READ_ONLY ("read_only"), - READ_WRITE ("read_write"); - - +public enum UserClass { + // Constant configName + READ_ONLY ("read_only"), + READ_WRITE ("read_write"); + /** - * The name of the tag in the configuration file that contains - * the credentials for this user class. + * The name of the tag in the configuration file that contains the + * credentials for this user class. */ - public String configName; - - - private - UserClass (String configName) - { - this.configName = configName; + + /** + * Constructs a new UserClass. + * + * @param configName The name of the user class in the config. + */ + private UserClass(String configName) { + this.configName = configName; } - } +} diff --git a/src/uk/org/ury/database/exceptions/package.html b/src/uk/org/ury/database/exceptions/package.html new file mode 100644 index 0000000..b5e7cac --- /dev/null +++ b/src/uk/org/ury/database/exceptions/package.html @@ -0,0 +1,11 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" +"http://www.w3.org/TR/html4/strict.dtd"> + +<HTML> + <HEAD> + <TITLE>uk.org.ury.database.exceptions</TITLE> + </HEAD> + <BODY> + <P>Exceptions thrown by the database services classes.</P> + </BODY> +</HTML>
\ No newline at end of file diff --git a/src/uk/org/ury/database/package.html b/src/uk/org/ury/database/package.html new file mode 100644 index 0000000..2b138b8 --- /dev/null +++ b/src/uk/org/ury/database/package.html @@ -0,0 +1,15 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" +"http://www.w3.org/TR/html4/strict.dtd"> + +<HTML> + <HEAD> + <TITLE>uk.org.ury.database</TITLE> + </HEAD> + <BODY> + <P>Database services for the URY Presenter Suite.</P> + <P>The classes provided within this package are expected to be + used by the back-end through utility classes, and <EM>not</EM> + by the frontend, which should use the server API to indirectly + query the database.</P> + </BODY> +</HTML>
\ No newline at end of file diff --git a/src/uk/org/ury/library/viewer/LibraryViewer.java b/src/uk/org/ury/library/viewer/LibraryViewer.java index 810bf7e..9548338 100644 --- a/src/uk/org/ury/library/viewer/LibraryViewer.java +++ b/src/uk/org/ury/library/viewer/LibraryViewer.java @@ -33,6 +33,14 @@ import uk.org.ury.protocol.exceptions.InvalidMessageException; /** * Module for investigating the track library. * + * The <code>LibraryViewer</code> and its corresponding user + * interface, <code>LibraryViewerPanel</code>, provide a + * user interface for querying the server's library services + * for track information. + * + * Subclasses of this module provide editing features for + * the track library. + * * @author Matt Windsor */ public class LibraryViewer extends AbstractFrontendModule { @@ -44,7 +52,7 @@ public class LibraryViewer extends AbstractFrontendModule { private LibraryViewerPanel panel; /** - * Construct a new LibraryViewer as a frontend object. + * Constructs a new LibraryViewer as a frontend object. */ public LibraryViewer() { libraryList = new ArrayList<LibraryItem>(); @@ -52,7 +60,7 @@ public class LibraryViewer extends AbstractFrontendModule { } /** - * Run the library viewer frontend. + * Runs the library viewer frontend. */ @Override public FrontendModulePanel runFrontend(FrontendMaster master) { @@ -66,7 +74,7 @@ public class LibraryViewer extends AbstractFrontendModule { } /** - * Do a library search. + * Does a library search. * * This will update the library list to reflect the results of the search. * diff --git a/src/uk/org/ury/library/viewer/LibraryViewerPanel.java b/src/uk/org/ury/library/viewer/LibraryViewerPanel.java index c3ec351..94496fc 100644 --- a/src/uk/org/ury/library/viewer/LibraryViewerPanel.java +++ b/src/uk/org/ury/library/viewer/LibraryViewerPanel.java @@ -31,7 +31,8 @@ import uk.org.ury.protocol.exceptions.InvalidMessageException; /** * Frontend panel providing access to an underlying library viewer. * - * @author Matt Windsor, Nathan Lasseter + * @author Matt Windsor + * @author Nathan Lasseter */ public class LibraryViewerPanel extends FrontendModulePanel { /** diff --git a/src/uk/org/ury/overview.html b/src/uk/org/ury/overview.html new file mode 100644 index 0000000..003efd7 --- /dev/null +++ b/src/uk/org/ury/overview.html @@ -0,0 +1,29 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" +"http://www.w3.org/TR/html4/strict.dtd"> + +<HTML> + <HEAD> + <TITLE>uk.org.ury</TITLE> + </HEAD> + <BODY> + <H1>The URY broadcasting and presentation suite.</H1> + <P>This system, which goes under the working title SLUT + (Streaming Library of URY Tracks), is intended as a + replacement for the current (as of March 2011) system + in use at University Radio York, BAPS.</P> + <H2>Contents</H2> + <P>The system comprises:</P> + <UL> + <LI>A server system providing access to station assets + through a heavily documented JSON/HTTP API;</LI> + <LI>A client implementation providing a frontend similar + to the original BAPS system, using the Server API to access + data and sound systems;</LI> + <LI>An array of class modules corresponding to the resources + for use by both server and client implementation;</LI> + <LI>Documentation for the above.</LI> + </UL> + <H2>Organisation</H2> + <P>The system is organised as followed.</P> + </BODY> +</HTML>
\ No newline at end of file diff --git a/src/uk/org/ury/server/AbstractRequestHandler.java b/src/uk/org/ury/server/AbstractRequestHandler.java index 9682bec..9b964b0 100644 --- a/src/uk/org/ury/server/AbstractRequestHandler.java +++ b/src/uk/org/ury/server/AbstractRequestHandler.java @@ -41,7 +41,7 @@ public abstract class AbstractRequestHandler implements HttpRequestHandler { protected String mount; /** - * Construct a new AbstractRequestHandler. + * Constructs a new AbstractRequestHandler. * * Obviously, this class cannot be instantiated directly. * @@ -97,7 +97,7 @@ public abstract class AbstractRequestHandler implements HttpRequestHandler { } /** - * Serve a HTTP plain-text error as the HTTP response for a request. + * Serves a HTTP plain-text error as the HTTP response for a request. * * @param request * The request that is being responded to. @@ -151,7 +151,7 @@ public abstract class AbstractRequestHandler implements HttpRequestHandler { } /** - * Handle a HTTP GET request. + * Handles a HTTP GET request. * * @param request * The HTTP request. @@ -193,7 +193,7 @@ public abstract class AbstractRequestHandler implements HttpRequestHandler { UnknownFunctionException; /** - * Parse a query string, populating a key-value map of the URL-unescaped + * Parses a query string, populating a key-value map of the URL-unescaped * results. * * @param query @@ -234,7 +234,7 @@ public abstract class AbstractRequestHandler implements HttpRequestHandler { } /** - * Get the query string element of a + * Gets the query string element of a URI. * * @param uri * The Uniform Resource Indicator whose query string should be diff --git a/src/uk/org/ury/server/Server.java b/src/uk/org/ury/server/Server.java index 2419915..0ab8c8c 100644 --- a/src/uk/org/ury/server/Server.java +++ b/src/uk/org/ury/server/Server.java @@ -23,6 +23,7 @@ import uk.org.ury.database.exceptions.MissingCredentialsException; * The unified URY server, accepting requests over HTTP. * * @author Matt Windsor + * @version 2011.0320 */ public class Server { public static final String SERVER_VERSION = "SLUT 0.0"; @@ -66,7 +67,7 @@ public class Server { } /** - * Get a database connection using the given user class. + * Gets a database connection using the given user class. * * @param userClass * The user class to get a connection for. diff --git a/src/uk/org/ury/server/package.html b/src/uk/org/ury/server/package.html new file mode 100644 index 0000000..b19b3b7 --- /dev/null +++ b/src/uk/org/ury/server/package.html @@ -0,0 +1,23 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" +"http://www.w3.org/TR/html4/strict.dtd"> + +<HTML> + <HEAD> + <TITLE>uk.org.ury.server</TITLE> + </HEAD> + <BODY> + <P>The URY Server kernel.</P> + <P>The URY Server provides high-level access to the assets + (database, files and sound playback) available on the computer + systems of a radio station, exposing an intuitive application + programming interface using standard formats.</P> + <P>The server kernel consists of an Apache HttpCore-based HTTP + server implementation, which serves the high-level interface + to the server, code for managing the external modules that make + up the URY backend, and a common provider of objects useful to + server-level modules.</P> + <P>Though designed and built to replace the systems in place + at University Radio York, it is hoped that the URY Server will + be of use + </BODY> +</HTML>
\ No newline at end of file diff --git a/src/uk/org/ury/show/ShowChannel.java b/src/uk/org/ury/show/ShowChannel.java index 8448e0f..1b8c4fb 100644 --- a/src/uk/org/ury/show/ShowChannel.java +++ b/src/uk/org/ury/show/ShowChannel.java @@ -1,3 +1,14 @@ +/* + * ShowChannel.java + * ------------------ + * + * Part of the URY Presentation Suite + * + * V0.00 2011/03/21 + * + * (C) 2011 URY Computing + */ + package uk.org.ury.show; import java.util.ArrayList; @@ -7,125 +18,103 @@ import javax.swing.AbstractListModel; import uk.org.ury.show.item.ShowItem; - /** * A channel of ShowItems in a show. * - * @author Matt Windsor + * @author Matt Windsor */ +public class ShowChannel extends AbstractListModel { + /** + * + */ + private static final long serialVersionUID = -4651104185166068150L; + + /* Items enqueued in channel. */ + private List<ShowItem> items; + + /** + * Constructs a new, empty channel. + */ + public ShowChannel() { + items = new ArrayList<ShowItem>(); + } + + /** + * Adds a new item to the channel. + * + * @param index + * The position at which to add the item. + * + * @param item + * The new item to add. + * + * @throws IllegalArgumentException + * if the item is null, the index is negative or the index is + * out of bounds. + */ + public void add(int index, ShowItem item) { + if (item == null) + throw new IllegalArgumentException("Item is null."); + + if (index < 0 || index >= items.size()) + throw new IllegalArgumentException("Index " + index + + " out of bounds."); + + items.add(index, item); + fireIntervalAdded(this, index, index); + } + + /** + * Adds a new item to the end of the channel. + * + * @param item + * The new item to add. + */ + public void add(ShowItem item) { + if (item == null) + throw new IllegalArgumentException("Item is null."); + + items.add(item); + fireIntervalAdded(this, items.size() - 1, items.size() - 1); + } + + /** + * Retrieves an item from the channel. + * + * @param index + * The index of the item to retrieve from the channel. + * + * @return the item at the given index in the list. + * + * @throws IllegalArgumentException + * if the index is negative or overflowing. + */ + public ShowItem get(int index) { + if (index < 0 || index >= items.size()) + throw new IllegalArgumentException("Index " + index + + " out of bounds."); + + return items.get(index); + } + + /** + * List model retrieval wrapper for get. + * + * @param index + * The index of the item to retrieve from the channel. + * + * @return the item at the given index in the list. + */ + @Override + public Object getElementAt(int index) { + return get(index); + } -public class ShowChannel extends AbstractListModel -{ - /** - * - */ - private static final long serialVersionUID = -4651104185166068150L; - - /* Items enqueued in channel. */ - private List<ShowItem> items; - - - /** - * Construct a new, empty channel. - */ - - public - ShowChannel () - { - items = new ArrayList<ShowItem> (); - } - - - /** - * Add a new item to the channel. - * - * @param index The position at which to add the item. - * - * @param item The new item to add. - * - * @throws IllegalArgumentException if the item is - * null, the index is negative or the index - * is out of bounds. - */ - - public void - add (int index, ShowItem item) - { - if (item == null) - throw new IllegalArgumentException ("Item is null."); - - if (index < 0 || index >= items.size ()) - throw new IllegalArgumentException ("Index " + index + - " out of bounds."); - - items.add (index, item); - fireIntervalAdded (this, index, index); - } - - - /** - * Add a new item to the end of the channel. - * - * @param item The new item to add. - */ - - public void - add (ShowItem item) - { - if (item == null) - throw new IllegalArgumentException ("Item is null."); - - items.add (item); - fireIntervalAdded (this, items.size () - 1, items.size () - 1); - } - - - /** - * Retrieve an item from the channel. - * - * @param index The index of the item to retrieve from the channel. - * - * @return the item at the given index in the list. - * - * @throws IllegalArgumentException if the index is negative - * or overflowing. - */ - - public ShowItem - get (int index) - { - if (index < 0 || index >= items.size ()) - throw new IllegalArgumentException ("Index " + index + - " out of bounds."); - - return items.get (index); - } - - - /** - * List model retrieval wrapper for get. - * - * @param index The index of the item to retrieve from the channel. - * - * @return the item at the given index in the list. - */ - - @Override - public Object - getElementAt (int index) - { - return get (index); - } - - - /** - * @return the size of the list. - */ - - @Override - public int - getSize () - { - return items.size (); - } + /** + * @return the size of the list. + */ + @Override + public int getSize() { + return items.size(); + } } diff --git a/src/uk/org/ury/show/ShowUtils.java b/src/uk/org/ury/show/ShowUtils.java index aa041d9..32125ec 100644 --- a/src/uk/org/ury/show/ShowUtils.java +++ b/src/uk/org/ury/show/ShowUtils.java @@ -1,6 +1,14 @@ -/** +/* + * ShowUtils.java + * ------------------ + * + * Part of the URY Backend Platform + * + * V0.00 2011/03/21 * + * (C) 2011 URY Computing */ + package uk.org.ury.show; import java.sql.ResultSet; @@ -8,6 +16,7 @@ import java.sql.SQLException; import java.util.ArrayList; import java.util.HashMap; import java.util.List; +import java.util.ResourceBundle; import uk.org.ury.database.DatabaseDriver; import uk.org.ury.database.exceptions.QueryFailureException; @@ -15,199 +24,167 @@ import uk.org.ury.database.exceptions.QueryFailureException; import uk.org.ury.show.item.ShowItem; import uk.org.ury.show.item.ShowItemProperty; - /** - * A set of common utility routines to facilitate the extraction of - * show items from the show storage areas of the URY database. + * A set of common utility routines to facilitate the extraction of show items + * from the show storage areas of the URY database. * - * @author Matt Windsor - * + * @author Matt Windsor */ +public class ShowUtils { + /** + * The number of channels reserved for show items. + * + * TODO: move this somewhere more appropriate. + */ + public static final int NUM_CHANNELS = 3; + + // Maximum number of results to pull from database + private static final int MAX_RESULTS = 50; + + // Resource bundle (for exception reasons) + private static ResourceBundle rb = ResourceBundle.getBundle(ShowUtils.class + .getPackage().getName() + ".ShowUtils"); + + /** + * Return the names of the public track folders, or "bins". + * + * @param db + * The database to query. + * + * @return a list of the public folder names. The list may be empty. + * + * @throws IllegalArgumentException + * if the database is null, the show ID is negative or the + * channel index falls out of bounds. + * + * @throws QueryFailureException + * if the database backend yielded an error while executing the + * search query. + */ + public static List<String> getPublicFolders(DatabaseDriver db) + throws QueryFailureException { + if (db == null) + throw new IllegalArgumentException( + rb.getString("ERR_DB_HANDLE_IS_NULL")); + + List<String> results = new ArrayList<String>(); + + ResultSet rs = null; + + try { + rs = db.executeQuery("SELECT share AS name, description" + + " FROM baps_filefolder" + " WHERE baps_filefolder.public" + + " = TRUE" + " ORDER BY filefolderid ASC", MAX_RESULTS); + } catch (SQLException e1) { + throw new QueryFailureException(e1.getMessage()); + } + + try { + while (rs.next()) { + results.add(rs.getString(2)); + } + } catch (SQLException e) { + throw new QueryFailureException(e.getMessage()); + } + + return results; + } + + /** + * Given a show and a channel, retrieve a list of all show items bound to + * that channel for the show. + * + * @param db + * The database to query. + * + * @param showID + * The unique number that identifies the show. + * + * @param channel + * The index of the channel to query. + * + * @return a list of ShowItems extracted from the show and channel. The list + * may be empty. + * + * @throws IllegalArgumentException + * if the database is null, the show ID is negative or the + * channel index falls out of bounds. + * + * @throws QueryFailureException + * if the database backend yielded an error while executing the + * search query. + */ + public static List<ShowItem> getChannelList(DatabaseDriver db, int showID, + int channel) throws QueryFailureException { + if (db == null) + throw new IllegalArgumentException( + rb.getString("ERR_DB_HANDLE_IS_NULL")); + + if (showID < 0) + throw new IllegalArgumentException( + rb.getString("ERR_NEGATIVE_SHOW_ID")); + + if (channel < 0 || channel >= NUM_CHANNELS) + throw new IllegalArgumentException( + rb.getString("ERR_CH_OUT_OF_BOUNDS")); + + List<ShowItem> results = new ArrayList<ShowItem>(); + + ResultSet rs = null; + + Object[] params = { showID, channel }; + + try { + rs = db.executeQuery("SELECT name1, name2, position" + + " FROM baps_show" + " INNER JOIN baps_listing" + + " ON baps_show.showid" + + " = baps_listing.showid" + + " INNER JOIN baps_item" + + " ON baps_listing.listingid" + + " = baps_item.listingid" + + " WHERE baps_show.showid" + + " = ?" + + " AND baps_listing.channel" + + " = ?" + + " ORDER BY position ASC", params, MAX_RESULTS); + } catch (SQLException e) { + throw new QueryFailureException(e.getMessage()); + } + + try { + while (rs.next()) { + results.add(translateRow(rs)); + } + } catch (SQLException e) { + throw new QueryFailureException(e.getMessage()); + } + return results; + } + + /** + * Translate a row retrieved from the database into a ShowItem. + * + * @param rs + * The result-set, or database cursor, pointing to the row to + * translate. + * + * @return A new ShowItem containing the properties extracted from the + * translated row. + */ + private static ShowItem translateRow(ResultSet rs) { + // Translate SQL columns into a list of properties. + + HashMap<ShowItemProperty, String> properties = new HashMap<ShowItemProperty, String>(); + + for (ShowItemProperty p : ShowItemProperty.values()) { + try { + properties.put(p, rs.getString(p.sql)); + } catch (SQLException e) { + // Ignore this, as it is almost certainly just a non-existent + // property. + } + } -public class ShowUtils -{ - /** - * The number of channels reserved for show items. - * - * TODO: move this somewhere more appropriate. - */ - - public static final int NUM_CHANNELS = 3; - - - // Maximum number of results to pull from database - private static final int MAX_RESULTS = 50; - - - /** - * Return the names of the public track folders, or "bins". - * - * @param db The database to query. - * - * @return a list of the public folder names. - * The list may be empty. - * - * @throws IllegalArgumentException if the database is - * null, the show ID is negative or the - * channel index falls out of bounds. - * - * @throws QueryFailureException if the database backend - * yielded an error while executing the search - * query. - */ - - public static List<String> - getPublicFolders (DatabaseDriver db) - throws QueryFailureException - { - if (db == null) - throw new IllegalArgumentException ("Database handle is null."); - - - List<String> results = new ArrayList<String> (); - - - ResultSet rs = null; - - try - { - rs = db.executeQuery ("SELECT share AS name, description" - + " FROM baps_filefolder" - + " WHERE baps_filefolder.public" - + " = TRUE" - + " ORDER BY filefolderid ASC", MAX_RESULTS); - } - catch (SQLException e1) - { - throw new QueryFailureException (e1.getMessage ()); - } - - try - { - while (rs.next ()) - { - results.add (rs.getString (2)); - } - } - catch (SQLException e) - { - throw new QueryFailureException (e.getMessage ()); - } - - return results; - } - - - /** - * Given a show and a channel, retrieve a list of all show items - * bound to that channel for the show. - * - * @param db The database to query. - * - * @param showID The unique number that identifies the show. - * - * @param channel The index of the channel to query. - * - * @return a list of ShowItems extracted from the show and - * channel. The list may be empty. - * - * @throws IllegalArgumentException if the database is - * null, the show ID is negative or the - * channel index falls out of bounds. - * - * @throws QueryFailureException if the database backend - * yielded an error while executing the search - * query. - */ - - public static List<ShowItem> - getChannelList (DatabaseDriver db, int showID, int channel) - throws QueryFailureException - { - if (db == null) - throw new IllegalArgumentException ("Database handle is null."); - - if (showID < 0) - throw new IllegalArgumentException ("Show ID is negative."); - - if (channel < 0 || channel >= NUM_CHANNELS) - throw new IllegalArgumentException ("Channel index is out of bounds."); - - List<ShowItem> results = new ArrayList<ShowItem> (); - - - ResultSet rs = null; - - Object[] params = {showID, channel}; - - try - { - rs = db.executeQuery ("SELECT name1, name2, position" - + " FROM baps_show" - + " INNER JOIN baps_listing" - + " ON baps_show.showid" - + " = baps_listing.showid" - + " INNER JOIN baps_item" - + " ON baps_listing.listingid" - + " = baps_item.listingid" - + " WHERE baps_show.showid" - + " = ?" - + " AND baps_listing.channel" - + " = ?" - + " ORDER BY position ASC", params, MAX_RESULTS); - } - catch (SQLException e) - { - throw new QueryFailureException (e.getMessage ()); - } - - try - { - while (rs.next ()) - { - results.add (translateRow (rs)); - } - } - catch (SQLException e) - { - throw new QueryFailureException (e.getMessage ()); - } - - return results; - } - - - /** - * Translate a row retrieved from the database into a ShowItem. - * - * @param rs The result-set, or database cursor, pointing to the - * row to translate. - * - * @return A new ShowItem containing the properties extracted - * from the translated row. - */ - - private static ShowItem - translateRow (ResultSet rs) - { - // Translate SQL columns into a list of properties. - - HashMap<ShowItemProperty, String> properties = new HashMap<ShowItemProperty, String> (); - - for (ShowItemProperty p : ShowItemProperty.values ()) - { - try - { - properties.put (p, rs.getString (p.sql)); - } - catch (SQLException e) - { - // Ignore this, as it is almost certainly just a non-existent - // property. - } - } - - - return new ShowItem (properties); - } + return new ShowItem(properties); + } }
\ No newline at end of file diff --git a/src/uk/org/ury/show/ShowUtils.properties b/src/uk/org/ury/show/ShowUtils.properties new file mode 100644 index 0000000..7f8a2fa --- /dev/null +++ b/src/uk/org/ury/show/ShowUtils.properties @@ -0,0 +1,4 @@ +// Exceptions +ERR_DB_HANDLE_IS_NULL = "Database handle is null." +ERR_NEGATIVE_SHOW_ID = "Show ID is negative." +ERR_CH_OUT_OF_BOUNDS = Channel index is out of bounds."
\ No newline at end of file diff --git a/src/uk/org/ury/show/item/package.html b/src/uk/org/ury/show/item/package.html new file mode 100644 index 0000000..0b2af5a --- /dev/null +++ b/src/uk/org/ury/show/item/package.html @@ -0,0 +1,14 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" +"http://www.w3.org/TR/html4/strict.dtd"> + +<HTML> + <HEAD> + <TITLE>uk.org.ury.show.item</TITLE> + </HEAD> + <BODY> + <P>The show item class and related properties.</P> + <P>The two contained classes, ShowItem and ShowItemProperty, + implement the storage of items (songs, audio tracks, etc) that + can be placed in show channels.</P> + </BODY> +</HTML>
\ No newline at end of file |