GREAT PACKAGE RESHUFFLE: Everything is now organised into frontend, backend and common (to frontend and backend) packages. Things may have been broken. Doc refresh.

6 files changed, 422 insertions, 0 deletions

diff --git a/src/uk/org/ury/common/show/ShowChannel.java b/src/uk/org/ury/common/show/ShowChannel.java
new file mode 100644
index 0000000..1c1b8ce
--- /dev/null
+++ b/src/uk/org/ury/common/show/ShowChannel.java
@@ -0,0 +1,120 @@
+/*
+ * ShowChannel.java
+ * ------------------
+ * 
+ * Part of the URY Presentation Suite
+ * 
+ * V0.00  2011/03/21
+ * 
+ * (C) 2011 URY Computing
+ */
+
+package uk.org.ury.common.show;
+
+import java.util.ArrayList;
+import java.util.List;
+
+import javax.swing.AbstractListModel;
+
+import uk.org.ury.common.show.item.ShowItem;
+
+/**
+ * A channel of ShowItems in a show.
+ * 
+ * @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);
+    }
+
+    /**
+     * @return the size of the list.
+     */
+    @Override
+    public int getSize() {
+	return items.size();
+    }
+}
diff --git a/src/uk/org/ury/common/show/ShowUtils.java b/src/uk/org/ury/common/show/ShowUtils.java
new file mode 100644
index 0000000..a806d8f
--- /dev/null
+++ b/src/uk/org/ury/common/show/ShowUtils.java
@@ -0,0 +1,190 @@
+/*
+ * ShowUtils.java
+ * ------------------
+ * 
+ * Part of the URY Backend Platform
+ * 
+ * V0.00  2011/03/21
+ * 
+ * (C) 2011 URY Computing
+ */
+
+package uk.org.ury.common.show;
+
+import java.sql.ResultSet;
+import java.sql.SQLException;
+import java.util.ArrayList;
+import java.util.HashMap;
+import java.util.List;
+import java.util.ResourceBundle;
+
+import uk.org.ury.backend.database.DatabaseDriver;
+import uk.org.ury.backend.database.exceptions.QueryFailureException;
+import uk.org.ury.common.show.item.ShowItem;
+import uk.org.ury.common.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.
+ * 
+ * @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.
+	    }
+	}
+
+	return new ShowItem(properties);
+    }
+}
\ No newline at end of file
diff --git a/src/uk/org/ury/common/show/ShowUtils.properties b/src/uk/org/ury/common/show/ShowUtils.properties
new file mode 100644
index 0000000..7f8a2fa
--- /dev/null
+++ b/src/uk/org/ury/common/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/common/show/item/ShowItem.java b/src/uk/org/ury/common/show/item/ShowItem.java
new file mode 100644
index 0000000..d1d1be1
--- /dev/null
+++ b/src/uk/org/ury/common/show/item/ShowItem.java
@@ -0,0 +1,68 @@
+/**
+ * 
+ */
+package uk.org.ury.common.show.item;
+
+
+import java.util.Map;
+
+import uk.org.ury.backend.database.DatabaseItem;
+import uk.org.ury.backend.database.exceptions.MissingPropertyException;
+
+
+/**
+ * An item in the show database.
+ * 
+ * @author Matt Windsor
+ */
+
+public class ShowItem extends DatabaseItem<ShowItemProperty, String>
+{
+  /**
+   * Construct a new ShowItem.
+   * 
+   * @param properties  The map of properties to store in the show item.
+   */
+  
+  public
+  ShowItem (Map<ShowItemProperty, String> properties)
+  {
+    super (properties);
+  }
+  
+  
+  /**
+   * @return  a string representation of the ShowItem.
+   */
+  
+  @Override
+  public String
+  toString ()
+  {
+    String name1;
+    String name2;
+    
+    try
+      {
+        name1 = get (ShowItemProperty.NAME1);
+      }
+    catch (MissingPropertyException e1)
+      {
+        name1 = "Unknown";
+      }
+
+    try
+      {
+        name2 = get (ShowItemProperty.NAME2);
+      }
+    catch (MissingPropertyException e2)
+      {
+        name2 = null;
+      }
+    
+    if (name2 != null)
+      return name1 + " - " + name2;
+    else
+      return name1;
+  }
+}
diff --git a/src/uk/org/ury/common/show/item/ShowItemProperty.java b/src/uk/org/ury/common/show/item/ShowItemProperty.java
new file mode 100644
index 0000000..43d4e99
--- /dev/null
+++ b/src/uk/org/ury/common/show/item/ShowItemProperty.java
@@ -0,0 +1,26 @@
+package uk.org.ury.common.show.item;
+
+
+/**
+ * Enumeration of the parameters that are stored in a ShowItem.
+ * 
+ * @author  Matt Windsor
+ */
+
+public enum ShowItemProperty
+  {
+    // Constant     SQL identifier       
+    NAME1           ("name1"),
+    NAME2           ("name2"),
+    POSITION        ("positionid");
+  
+  
+    public final String sql;
+  
+  
+    private
+    ShowItemProperty (String sql)
+    {
+      this.sql = sql;
+    }
+  };
\ No newline at end of file
diff --git a/src/uk/org/ury/common/show/item/package.html b/src/uk/org/ury/common/show/item/package.html
new file mode 100644
index 0000000..0b2af5a
--- /dev/null
+++ b/src/uk/org/ury/common/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