001 package hirondelle.web4j.database; 002 003 /** 004 Thrown when a uniqueness problem occurs in the datastore 005 during an <tt>ADD</tt> or <tt>CHANGE</tt> operation. 006 007 <P>This type of exception is singled out since it is so common. It allows 008 {@link hirondelle.web4j.action.Action}s to catch this specific kind of exception. 009 010 <P>For relational databases, this exception should be thrown for <tt>INSERT</tt> 011 and <tt>UPDATE</tt> operations which may violate a <tt>UNIQUE</tt> or 012 <tt>PRIMARY KEY</tt> constraint, or similar item. 013 {@link Db}, {@link DbTx}, and {@link TxTemplate} will throw a <tt>DuplicateException</tt> 014 exception for {@link java.sql.SQLException}s having an error code matching the 015 <tt>ErrorCodeForDuplicateKey</tt> configured in <tt>web.xml</tt>. 016 See <tt>web.xml</tt> for more information. 017 018 <h3>Typical Use Case</h3> 019 Here, an {@link hirondelle.web4j.action.Action} is calling a DAO method which may throw 020 a <tt>DuplicateException</tt>: 021 <PRE> 022 private void addSomething throws DAOException { 023 //this try..catch is needed only if the operation 024 //can have a duplicate problem 025 try { 026 dao.addSomething(); 027 } 028 catch (DuplicateException ex){ 029 addError("Cannot add. That item already exists."); 030 } 031 } 032 </PRE> 033 <P>Note that if the operation cannot have a duplicate problem, then the <tt>Action</tt> 034 should not attempt to catch <tt>DuplicateException</tt>. 035 <P> 036 Here is the DAO operation which may have a duplicate problem. 037 <PRE> 038 //It is highly recommended, but optional, to declare 039 //DuplicateException in this method header, to bring 040 //it to the attention of the caller 041 public addSomething() throws DAOException, DuplicateException { 042 //...elided 043 } 044 </PRE> 045 Again, if the operation cannot have a duplicate problem, then the DAO should not 046 declare a <tt>DuplicateException</tt> in its throws clause. 047 048 <P>The {@link Db#add(SqlId, Object[])} and {@link Db#edit(SqlId, Object[])} methods can throw a 049 <tt>DuplicateException</tt>. 050 */ 051 public final class DuplicateException extends DAOException { 052 053 /** 054 Constructor. 055 056 <P>Arguments are passed to {@link DAOException#DAOException(String, Throwable)}. 057 */ 058 public DuplicateException(String aMessage, Throwable aRootCause) { 059 super(aMessage, aRootCause); 060 } 061 062 }