001    package hirondelle.web4j.database;
002    
003    import java.sql.ResultSet;
004    import java.sql.SQLException;
005    
006    /**
007     Convert <tt>ResultSet</tt> column values into common 'building block' objects.
008     <P>
009     Here, a <em>building block</em> class is one of the 'base' objects from which Model
010     Objects can in turn be built - <tt>Integer</tt>, <tt>BigDecimal</tt>, <tt>Date</tt>,
011     and so on. 
012    
013     <P>See {@link hirondelle.web4j.BuildImpl} for important information on how this item is configured. 
014     {@link hirondelle.web4j.BuildImpl#forConvertColumn()} 
015     returns the configured implementation of this interface.
016     
017     <P>{@link ConvertColumnImpl} is provided as a default implementation. It is likely that 
018     most applications will find this implementation adequate. 
019    */
020    public interface ConvertColumn {
021    
022      /**
023       Translate a single column value of a <tt>ResultSet</tt> into a possibly-null 'building block' object.
024       
025       <P>A building block object is like <tt>Integer</tt>, <tt>BigDecimal</tt>, <tt>Date</tt>, and so on.
026       
027       <P>It is required that implementations use 
028       {@link hirondelle.web4j.model.ConvertParam#isSupported(Class)} to 
029       verify that <tt>aSupportedTargetType</tt> is indeed supported. 
030       This ensures the front end and back end are synchronized, and support the same set of classes.
031       
032       @param aRow from iteration over a <tt>ResultSet</tt>.  
033       @param aColumnIdx specific column in <tt>aRow</tt>.
034       @param aSupportedTargetType class of the desired return value. Implementations are not required to 
035       support all possible target classes.
036      */
037      public <T> T convert(ResultSet aRow, int aColumnIdx, Class<T> aSupportedTargetType) throws SQLException;
038      
039    }