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

4 files changed, 281 insertions, 0 deletions

diff --git a/src/uk/org/ury/common/library/LibraryUtils.java b/src/uk/org/ury/common/library/LibraryUtils.java
new file mode 100644
index 0000000..335b8b5
--- /dev/null
+++ b/src/uk/org/ury/common/library/LibraryUtils.java
@@ -0,0 +1,144 @@
+/**
+ * 
+ */
+package uk.org.ury.common.library;
+
+import java.sql.ResultSet;
+import java.sql.SQLException;
+import java.util.ArrayList;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+
+import uk.org.ury.backend.database.DatabaseDriver;
+import uk.org.ury.backend.database.exceptions.QueryFailureException;
+import uk.org.ury.common.library.exceptions.EmptySearchException;
+import uk.org.ury.common.library.item.LibraryItem;
+import uk.org.ury.common.library.item.LibraryItemProperty;
+
+
+
+/**
+ * A set of common utility routines to facilitate the extraction of 
+ * library items from the library areas of the URY database. 
+ * 
+ * @author  Matt Windsor
+ */
+
+public class LibraryUtils
+{ 
+  /**
+   * Perform a library search.
+   * 
+   * @param db      The database to query.
+   * 
+   * @param search  The search fragment to include in the search.
+   *                Can be empty or null.
+   *                
+   * @throws        IllegalArgumentException if the search term is 
+   *                are null.
+   *                
+   * @throws        QueryFailureException if the database backend 
+   *                yielded an error while executing the search 
+   *                query.
+   *                
+   * @throws        EmptySearchException if the search term is 
+   *                empty (to be handled as a user error).
+   *                
+   * @return        a list of LibraryItems matching the search terms.
+   */
+  
+  public static List<LibraryItem>
+  search (DatabaseDriver db, String search)
+  throws QueryFailureException, EmptySearchException
+  {
+    if (db == null)
+      throw new IllegalArgumentException ("Database handle is null.");
+
+    if (search == null)
+      throw new IllegalArgumentException ("Search string is null.");
+
+    List<LibraryItem> results = new ArrayList<LibraryItem> ();
+    
+    
+    // Return empty set if the search term is null.
+    
+    if (search.equals(""))
+    	throw new EmptySearchException ();
+    
+    
+    ResultSet rs = null;
+
+    Object[] params = {"%" + search + "%", "%" + search + "%", "%" + search + "%"};
+    
+    try
+      {
+        rs = db.executeQuery (
+            "SELECT r.title AS album, t.title,"
+            + " t.artist, recordlabel AS label, status, media AS medium, format,"
+            + " datereleased, EXTRACT(EPOCH FROM dateadded) as dateadded,"
+            + " EXTRACT(EPOCH FROM datetime_lastedit) AS dateedited,"
+            + " shelfletter, shelfnumber, cdid, digitised, clean"
+            + " FROM rec_record AS r"
+            + " INNER JOIN rec_track AS t ON (r.recordid = t.recordid)"
+            + " WHERE t.title ILIKE ?"
+            + " OR t.artist ILIKE ?"
+            + " OR r.title ILIKE ?"
+            + " ORDER BY digitised DESC, medium ASC, r.title ASC,"
+            + " t.artist ASC, t.title ASC;", params, 50);
+      }
+    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 LibraryItem.
+   * 
+   * @param rs  The result-set, or database cursor, pointing to the 
+   *            row to translate.
+   *            
+   * @return    A new LibraryItem containing the properties extracted 
+   *            from the translated row.
+   */
+  
+  private static LibraryItem
+  translateRow (ResultSet rs)
+  {
+    // Translate SQL columns into a list of properties.
+            
+    Map<LibraryItemProperty, String> properties = new HashMap<LibraryItemProperty, String> ();
+            
+    for (LibraryItemProperty p : LibraryItemProperty.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 LibraryItem (properties);
+  }
+}
diff --git a/src/uk/org/ury/common/library/exceptions/EmptySearchException.java b/src/uk/org/ury/common/library/exceptions/EmptySearchException.java
new file mode 100644
index 0000000..fc4ed68
--- /dev/null
+++ b/src/uk/org/ury/common/library/exceptions/EmptySearchException.java
@@ -0,0 +1,49 @@
+/**
+ * 
+ */
+package uk.org.ury.common.library.exceptions;
+
+/**
+ * Exception thrown when a library search is initiated 
+ * in which the query string is null.
+ * 
+ * Frontends should handle this nicely.  Do NOT treat this 
+ * as a fatal error!
+ * 
+ * @author Matt Windsor
+ */
+
+public class EmptySearchException extends Exception
+{
+  
+  /**
+   * Change this!  ---v
+   */
+  
+  private static final long serialVersionUID = -397479334359858162L;
+
+
+  /**
+   * Construct a new EmptySearchException with a 
+   * default reason.
+   */
+  
+  public
+  EmptySearchException ()
+  {
+    super ("Query string was empty.");
+  }
+  
+  
+  /**
+   * Construct a new EmptySearchException.
+   * 
+   * @param reason  The explanation for the exception.
+   */
+  
+  public
+  EmptySearchException (String reason)
+  {
+    super (reason);
+  }
+}
diff --git a/src/uk/org/ury/common/library/item/LibraryItem.java b/src/uk/org/ury/common/library/item/LibraryItem.java
new file mode 100644
index 0000000..3e81041
--- /dev/null
+++ b/src/uk/org/ury/common/library/item/LibraryItem.java
@@ -0,0 +1,26 @@
+/**
+ * 
+ */
+package uk.org.ury.common.library.item;
+
+
+import java.util.Map;
+
+import uk.org.ury.backend.database.DatabaseItem;
+
+
+/**
+ * An item in the URY library.
+ * 
+ * @author Matt Windsor
+ */
+
+public class LibraryItem extends DatabaseItem<LibraryItemProperty,
+                                              String>
+{
+  public
+  LibraryItem (Map<LibraryItemProperty, String> properties)
+  {
+    super (properties);
+  }  
+}
\ No newline at end of file
diff --git a/src/uk/org/ury/common/library/item/LibraryItemProperty.java b/src/uk/org/ury/common/library/item/LibraryItemProperty.java
new file mode 100644
index 0000000..2e4d2ef
--- /dev/null
+++ b/src/uk/org/ury/common/library/item/LibraryItemProperty.java
@@ -0,0 +1,62 @@
+package uk.org.ury.common.library.item;
+
+/**
+ * The parameters that are stored in the LibraryItem.
+ * 
+ * @author  Matt Windsor
+ */
+
+public enum LibraryItemProperty
+  {
+    // Constant     SQL identifier       
+    TITLE           ("title"),
+    ALBUM           ("album"),
+    ARTIST          ("artist"),
+    LABEL           ("label"),
+    STATUS          ("status"),
+    MEDIUM          ("medium"),
+    FORMAT          ("format"),
+    DATE_RELEASED   ("datereleased"),
+    DATE_ADDED      ("dateadded"),
+    DATE_EDITED     ("dateedited"),
+    SHELF_LETTER    ("shelfletter"),
+    SHELF_NUMBER    ("shelfnumber"),
+    CD_ID           ("cdid"),
+    IS_DIGITISED    ("digitised"),
+    IS_CLEAN        ("clean");
+    
+    
+    public final String sql;
+    
+    
+    private
+    LibraryItemProperty (String sql)
+    {
+      this.sql = sql;
+    }
+
+
+    /**
+     * Retrieve a LibraryItemProperty given its SQL identifier.
+     * 
+     * @param string  The SQL identifier.
+     * @return        The first property to match.
+     * 
+     * @throws        IllegalArgumentException if no matches were
+     *                found.
+     */
+    
+    public static LibraryItemProperty
+    getFromSQL (String string)
+    {
+      // TODO: Better exception?
+      
+      for (LibraryItemProperty prop : values ())
+        {
+          if (prop.sql.equals (string))
+            return prop;
+        }
+      
+      throw new IllegalArgumentException ("Nonexistent property SQL.");
+    }
+  };
\ No newline at end of file