001    package hirondelle.web4j.database;
002    
003    /**
004     Thrown when a violation of a foreign key constraint occurs in the datastore
005     during an <tt>ADD</tt>, <tt>CHANGE</tt>, or <tt>DELETE</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     <tt>UPDATE</tt>, or <tt>DELETE</tt> operation which may violate a foreign key constraint.
012     {@link Db}, {@link DbTx}, and {@link TxTemplate} will throw a <tt>ForeignKeyException</tt> 
013     exception for {@link java.sql.SQLException}s having an error code matching the 
014     <tt>ErrorCodeForForeignKey</tt> setting configured in <tt>web.xml</tt>. 
015     See <tt>web.xml</tt> for more information.
016    
017     <h3>Typical Use Case</h3>
018     Here, an {@link hirondelle.web4j.action.Action} is calling a DAO method which may throw 
019     a <tt>ForeignKeyException</tt>: 
020    <PRE>
021    private void deleteSomething throws DAOException {
022      //this try..catch is needed only if the operation 
023      //can have a foreign key problem
024      try {
025        dao.deleteSomething();
026      }
027      catch (ForeignKeyException ex){
028        addError("Cannot delete. Referenced by some other item.");
029      }
030    }
031    </PRE>
032    <P>
033     Here is the DAO operation which may have a foreign key constraint problem. 
034    <PRE>
035    //It is highly recommended, but optional, to declare 
036    //ForeignKeyException in this method header, to bring 
037    //it to the attention of the caller
038    public deleteSomething() throws DAOException, ForeignKeyException {
039      //...elided
040    }
041    </PRE>
042    */
043    public final class ForeignKeyException extends DAOException {
044    
045      /**
046       Constructor.
047       
048       <P>Arguments are passed to {@link DAOException#DAOException(String, Throwable)}.
049      */
050      public ForeignKeyException(String aMessage, Throwable aRootCause) {
051        super(aMessage, aRootCause);
052      }
053      
054    }