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    }