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 }