001    package hirondelle.web4j.model;
002    
003    import hirondelle.web4j.action.Action;
004    import hirondelle.web4j.request.RequestParameter;
005    import hirondelle.web4j.request.RequestParser;
006    
007    /**
008     Instructs WEB4J how to respond to any errors found during parsing of raw user input into 
009     'base' types such as <tt>Integer</tt>, <tt>Date</tt>, and so on.
010     
011     <P>See {@link hirondelle.web4j.BuildImpl} for important information on how this item is configured. 
012     {@link hirondelle.web4j.BuildImpl#forConvertParamError()} 
013     returns the configured implementation of this interface.
014     
015     <P>On behalf of the application, {@link RequestParser} and related classes will parse 
016     user input into various target types such as <tt>Integer</tt>, <tt>Date</tt> and so on, using 
017     the configured implementation of {@link hirondelle.web4j.model.ConvertParam}.
018     This centralizes such repetitive parsing into the framework, and allows the application programmer to 
019     mostly ignore the possibility of such errors - the <tt>try..catch</tt> block has 
020     already been written.
021     
022     <P>WEB4J performs such parsing as a <a href="../request/ApplicationFirewall.html#SoftValidation">soft validation</a>.
023     For example, if user input should be an {@link Integer} in the range <tt>0..150</tt>, then 
024     WEB4J will attempt to parse the raw user input (a <tt>String</tt>) first into an 
025     {@link Integer}. If that parse <em>succeeds</em>, 
026     then WEB4J will pass the <tt>Integer</tt> on to an {@link Action}, which will then perform further 
027     "business validation" using a business domain Model Object - that is, it will check that its value is in the range <tt>0..150</tt>. 
028     So, an {@link Action} and its Model Object can almost always assume that an object of the correct 'base' type already exists, 
029     without worrying about low level parsing problems. 
030      
031     <P>However, if user input <em>cannot be parsed</em> by WEB4J into the desired class, then an error message must 
032     be displayed to the user. Implementations of this interface allow an application 
033     programmer to specify the content of that response message.
034       
035     <P>Please see the example application for an example implementation.
036    */
037    public interface ConvertParamError {
038      
039      /**
040       Return a {@link ModelCtorException} for a given parsing error, suitable for presentation to the end user.
041       
042       @param aSupportedTargetClass identifies the class into which the user input cannot be successfully parsed
043       @param aUserInputValue value input by the user
044       @param aRequestParameter the request parameter 
045      */
046      public ModelCtorException get(Class<?> aSupportedTargetClass, String aUserInputValue, RequestParameter aRequestParameter);
047      
048    }