From e3aed39330bcef586e51f72c719d8d273bf217d1 Mon Sep 17 00:00:00 2001 From: Michael Bayne Date: Tue, 16 Dec 2008 00:00:52 +0000 Subject: [PATCH] Document our thrown exceptions. --- .../com/samskivert/depot/DepotRepository.java | 90 +++++++++++++++++++ 1 file changed, 90 insertions(+) diff --git a/src/java/com/samskivert/depot/DepotRepository.java b/src/java/com/samskivert/depot/DepotRepository.java index 871e21e..8e6ff7c 100644 --- a/src/java/com/samskivert/depot/DepotRepository.java +++ b/src/java/com/samskivert/depot/DepotRepository.java @@ -96,6 +96,8 @@ public abstract class DepotRepository * Resolves all persistent records registered to this repository (via {@link * #getManagedRecords}. This will be done before the repository is initialized via {@link * #init}. + * + * @throws DatabaseException if any problem is encountered communicating with the database. */ protected void resolveRecords () throws DatabaseException @@ -110,6 +112,8 @@ public abstract class DepotRepository /** * Provides a place where a repository can perform any initialization that requires database * operations. + * + * @throws DatabaseException if any problem is encountered communicating with the database. */ protected void init () throws DatabaseException @@ -149,6 +153,8 @@ public abstract class DepotRepository /** * Loads the persistent object that matches the specified primary key. + * + * @throws DatabaseException if any problem is encountered communicating with the database. */ protected T load (Class type, Comparable primaryKey, QueryClause... clauses) @@ -160,6 +166,8 @@ public abstract class DepotRepository /** * Loads the persistent object that matches the specified primary key. + * + * @throws DatabaseException if any problem is encountered communicating with the database. */ protected T load (Class type, String ix, Comparable val, QueryClause... clauses) @@ -171,6 +179,8 @@ public abstract class DepotRepository /** * Loads the persistent object that matches the specified two-column primary key. + * + * @throws DatabaseException if any problem is encountered communicating with the database. */ protected T load (Class type, String ix1, Comparable val1, String ix2, Comparable val2, @@ -183,6 +193,8 @@ public abstract class DepotRepository /** * Loads the persistent object that matches the specified three-column primary key. + * + * @throws DatabaseException if any problem is encountered communicating with the database. */ protected T load (Class type, String ix1, Comparable val1, String ix2, Comparable val2, String ix3, @@ -195,6 +207,8 @@ public abstract class DepotRepository /** * Loads the first persistent object that matches the supplied query clauses. + * + * @throws DatabaseException if any problem is encountered communicating with the database. */ protected T load ( Class type, Collection clauses) @@ -205,6 +219,8 @@ public abstract class DepotRepository /** * Loads the first persistent object that matches the supplied query clauses. + * + * @throws DatabaseException if any problem is encountered communicating with the database. */ protected T load (Class type, QueryClause... clauses) throws DatabaseException @@ -214,6 +230,8 @@ public abstract class DepotRepository /** * Loads up all persistent records that match the supplied set of raw primary keys. + * + * @throws DatabaseException if any problem is encountered communicating with the database. */ protected List loadAll ( Class type, Collection> primaryKeys) @@ -230,6 +248,8 @@ public abstract class DepotRepository /** * Loads up all persistent records that match the supplied set of primary keys. + * + * @throws DatabaseException if any problem is encountered communicating with the database. */ protected List loadAll (Collection> keys) throws DatabaseException @@ -240,6 +260,8 @@ public abstract class DepotRepository /** * A varargs version of {@link #findAll(Class,Collection)}. + * + * @throws DatabaseException if any problem is encountered communicating with the database. */ protected List findAll (Class type, QueryClause... clauses) throws DatabaseException @@ -257,6 +279,8 @@ public abstract class DepotRepository * The more complex strategy could save a lot of data shuffling. On the other hand, its * complexity is an inherent drawback, and it does execute two separate database queries for * what the simple method does in one. + * + * @throws DatabaseException if any problem is encountered communicating with the database. */ protected List findAll ( Class type, Collection clauses) @@ -271,6 +295,8 @@ public abstract class DepotRepository * @param skipCache if true, our normal mixed select strategy that allows cached records to be * loaded from the cache will not be used even if it otherwise could. See {@link * #findAll(Class,Collection)} for details on the mixed strategy. + * + * @throws DatabaseException if any problem is encountered communicating with the database. */ protected List findAll ( Class type, boolean skipCache, Collection clauses) @@ -297,6 +323,8 @@ public abstract class DepotRepository * and may load keys from a slave. For performance reasons, you should always pass false unless * you know you will be modifying the database as a result of this query and absolutely need * the latest data. + * + * @throws DatabaseException if any problem is encountered communicating with the database. */ protected List> findAllKeys ( Class type, boolean forUpdate, QueryClause... clause) @@ -313,6 +341,8 @@ public abstract class DepotRepository * and may load keys from a slave. For performance reasons, you should always pass false unless * you know you will be modifying the database as a result of this query and absolutely need * the latest data. + * + * @throws DatabaseException if any problem is encountered communicating with the database. */ protected List> findAllKeys ( Class type, boolean forUpdate, Collection clauses) @@ -326,6 +356,10 @@ public abstract class DepotRepository * has one) in the process. * * @return the number of rows modified by this action, this should always be one. + * + * @throws DuplicateKeyException if the inserted record conflicts with the primary key (or any + * other unique key) of a record already in the database. + * @throws DatabaseException if any problem is encountered communicating with the database. */ protected int insert (T record) throws DatabaseException @@ -374,6 +408,8 @@ public abstract class DepotRepository * row to be updated. * * @return the number of rows modified by this action. + * + * @throws DatabaseException if any problem is encountered communicating with the database. */ protected int update (T record) throws DatabaseException @@ -412,6 +448,8 @@ public abstract class DepotRepository * cached value iff the record exists in the cache. * * @return the number of rows modified by this action. + * + * @throws DatabaseException if any problem is encountered communicating with the database. */ protected int update (T record, final String... modifiedFields) throws DatabaseException @@ -452,6 +490,10 @@ public abstract class DepotRepository * @param updates an mapping from the names of the fields/columns ti the values to be assigned. * * @return the number of rows modified by this action. + * + * @throws DuplicateKeyException if the update attempts to change the key columns of a row to + * values that duplicate another row already in the database. + * @throws DatabaseException if any problem is encountered communicating with the database. */ protected int updatePartial ( Class type, Comparable primaryKey, Map updates) @@ -475,6 +517,10 @@ public abstract class DepotRepository * assigned, in key, value, key, value, etc. order. * * @return the number of rows modified by this action. + * + * @throws DuplicateKeyException if the update attempts to change the key columns of a row to + * values that duplicate another row already in the database. + * @throws DatabaseException if any problem is encountered communicating with the database. */ protected int updatePartial ( Class type, Comparable primaryKey, Object... fieldsValues) @@ -492,6 +538,10 @@ public abstract class DepotRepository * assigned, in key, value, key, value, etc. order. * * @return the number of rows modified by this action. + * + * @throws DuplicateKeyException if the update attempts to change the key columns of a row to + * values that duplicate another row already in the database. + * @throws DatabaseException if any problem is encountered communicating with the database. */ protected int updatePartial ( Class type, String ix1, Comparable val1, String ix2, Comparable val2, @@ -510,6 +560,10 @@ public abstract class DepotRepository * assigned, in key, value, key, value, etc. order. * * @return the number of rows modified by this action. + * + * @throws DuplicateKeyException if the update attempts to change the key columns of a row to + * values that duplicate another row already in the database. + * @throws DatabaseException if any problem is encountered communicating with the database. */ protected int updatePartial ( Class type, String ix1, Comparable val1, String ix2, Comparable val2, @@ -527,6 +581,10 @@ public abstract class DepotRepository * assigned, in key, value, key, value, etc. order. * * @return the number of rows modified by this action. + * + * @throws DuplicateKeyException if the update attempts to change the key columns of a row to + * values that duplicate another row already in the database. + * @throws DatabaseException if any problem is encountered communicating with the database. */ protected int updatePartial (Key key, Object... fieldsValues) throws DatabaseException @@ -548,6 +606,10 @@ public abstract class DepotRepository * assigned, in key, value, key, value, etc. order. * * @return the number of rows modified by this action. + * + * @throws DuplicateKeyException if the update attempts to change the key columns of a row to + * values that duplicate another row already in the database. + * @throws DatabaseException if any problem is encountered communicating with the database. */ protected int updatePartial ( Class type, final WhereClause key, CacheInvalidator invalidator, Object... fieldsValues) @@ -598,6 +660,10 @@ public abstract class DepotRepository * assigned, in key, literal value, key, literal value, etc. order. * * @return the number of rows modified by this action. + * + * @throws DuplicateKeyException if the update attempts to change the key columns of a row to + * values that duplicate another row already in the database. + * @throws DatabaseException if any problem is encountered communicating with the database. */ protected int updateLiteral ( Class type, Comparable primaryKey, Map fieldsValues) @@ -622,6 +688,10 @@ public abstract class DepotRepository * assigned, in key, literal value, key, literal value, etc. order. * * @return the number of rows modified by this action. + * + * @throws DuplicateKeyException if the update attempts to change the key columns of a row to + * values that duplicate another row already in the database. + * @throws DatabaseException if any problem is encountered communicating with the database. */ protected int updateLiteral ( Class type, String ix1, Comparable val1, String ix2, Comparable val2, @@ -647,6 +717,10 @@ public abstract class DepotRepository * assigned, in key, literal value, key, literal value, etc. order. * * @return the number of rows modified by this action. + * + * @throws DuplicateKeyException if the update attempts to change the key columns of a row to + * values that duplicate another row already in the database. + * @throws DatabaseException if any problem is encountered communicating with the database. */ protected int updateLiteral ( Class type, String ix1, Comparable val1, String ix2, Comparable val2, @@ -673,6 +747,10 @@ public abstract class DepotRepository * assigned, in key, literal value, key, literal value, etc. order. * * @return the number of rows modified by this action. + * + * @throws DuplicateKeyException if the update attempts to change the key columns of a row to + * values that duplicate another row already in the database. + * @throws DatabaseException if any problem is encountered communicating with the database. */ protected int updateLiteral ( Class type, final WhereClause key, CacheInvalidator invalidator, @@ -719,6 +797,8 @@ public abstract class DepotRepository * and if that matches zero rows, the object will be inserted. * * @return true if the record was created, false if it was updated. + * + * @throws DatabaseException if any problem is encountered communicating with the database. */ protected boolean store (T record) throws DatabaseException @@ -789,6 +869,8 @@ public abstract class DepotRepository * of the supplied object. * * @return the number of rows deleted by this action. + * + * @throws DatabaseException if any problem is encountered communicating with the database. */ protected int delete (T record) throws DatabaseException @@ -806,6 +888,8 @@ public abstract class DepotRepository * primary key. * * @return the number of rows deleted by this action. + * + * @throws DatabaseException if any problem is encountered communicating with the database. */ protected int delete (Class type, Comparable primaryKeyValue) throws DatabaseException @@ -818,6 +902,8 @@ public abstract class DepotRepository * primary key. * * @return the number of rows deleted by this action. + * + * @throws DatabaseException if any problem is encountered communicating with the database. */ protected int delete (Class type, Key primaryKey) throws DatabaseException @@ -829,6 +915,8 @@ public abstract class DepotRepository * Deletes all persistent objects from the database that match the supplied where clause. * * @return the number of rows deleted by this action. + * + * @throws DatabaseException if any problem is encountered communicating with the database. */ protected int deleteAll (Class type, final WhereClause where) throws DatabaseException @@ -848,6 +936,8 @@ public abstract class DepotRepository * Deletes all persistent objects from the database that match the supplied key. * * @return the number of rows deleted by this action. + * + * @throws DatabaseException if any problem is encountered communicating with the database. */ protected int deleteAll ( Class type, final WhereClause where, CacheInvalidator invalidator)