001package Torello.Browser;
002
003import Torello.Browser.CDPTypes;
004import Torello.Browser.NestedDescriptor;
005import Torello.Browser.TypeBuilder;
006import Torello.Java.WrongMethodException;
007
008/**
009 * Thrown by {@link AbstractBuilder} when a programmer attempts to assign a value
010 * using a Java type that is incompatible with the builder property's expected
011 * type.
012 * 
013 * <BR /><BR /><DIV CLASS=JDHint>
014 * 👉 This exception provides several "convenience fields" intended to assist
015 * with detailed error reporting and debugging diagnostics.
016 * </DIV>
017 * 
018 * @see AbstractBuilder
019 */
020public class TypeAssignmentException extends WrongMethodException
021{
022    /** <EMBED CLASS='external-html' DATA-FILE-ID=SVUIDEX>  */
023    public static final long serialVersionUID = 1;
024
025    /**
026     * The name of the builder property being assigned when this exception was thrown.
027     * 
028     * <BR /><BR /><DIV CLASS=JDHint>
029     * 💡 For a {@link TypeBuilder}, this name identifies a field in the CDP type being built.  For
030     * a {@link CommandBuilder}, it identifies one of the command's input parameters.
031     * </DIV>
032     */
033    public final String name;
034
035    /**
036     * The {@link CDPTypes} byte constant describing the type implied by the accept method that was
037     * invoked.
038     * 
039     * <BR /><BR /><DIV CLASS=JDHint>
040     * 📎 This value identifies the Java/CDP type that the programmer attempted to assign.
041     * </DIV>
042     * 
043     * @see CDPTypes
044     */
045    public final byte providedType;
046
047    /**
048     * The {@link CDPTypes} byte constant describing the type expected by the builder.
049     * 
050     * <BR /><BR /><DIV CLASS=JDHint>
051     * 📎 This value will be equal to one of the constants listed in {@link CDPTypes}.
052     * </DIV>
053     * 
054     * @see CDPTypes
055     */
056    public final byte expectedType;
057
058    /**
059     * The descriptor whose builder property was being assigned when this exception was thrown.
060     * 
061     * <BR /><BR /><DIV CLASS=JDHint>
062     * 👉 This field is provided as a programmer convenience, to make debugging and error investigation
063     * easier.
064     * </DIV>
065     */
066    public final AbstractDescriptor descriptor;
067
068    /**
069     * Constructs a {@code TypeAssignmentException} with the default error message.
070     * 
071     * @param providedType the byte constant describing the type supplied by the programmer.
072     * @param expectedType the byte constant describing the type expected by the descriptor.
073     * @param name the name of the builder property being assigned.
074     * @param descriptor the descriptor used by the builder.
075     * 
076     * @see CDPTypes
077     */
078    public TypeAssignmentException(
079            final byte                  providedType,
080            final byte                  expectedType,
081            final String                name,
082            final AbstractDescriptor    descriptor
083        )
084    {
085        super(
086            "An attempt has been made to assign an inappropriate value to the builder " +
087            "property named '" + name + "'." + '\n' +
088            "The programmer provided a value of type: " + CDPTypes.names.get(providedType) + '\n' +
089            "The descriptor indicates that the expected type is: " +
090            CDPTypes.names.get(expectedType) + '\n' +
091            "The descriptor was: " + descriptor
092        );
093
094        this.providedType   = providedType;
095        this.expectedType   = expectedType;
096        this.name           = name;
097        this.descriptor     = descriptor;
098    }
099 
100    /**
101     * Constructs a {@code TypeAssignmentException} with the specified detail message.
102     * 
103     * @param message the detail message.
104     * @param providedType the byte constant describing the type supplied by the programmer.
105     * @param expectedType the byte constant describing the type expected by the descriptor.
106     * @param name the name of the builder property being assigned.
107     * @param descriptor the descriptor used by the builder.
108     */
109    public TypeAssignmentException(
110            final String                message, 
111            final byte                  providedType,
112            final byte                  expectedType,
113            final String                name,
114            final AbstractDescriptor    descriptor
115        )
116    {
117        super(message);
118
119        this.expectedType   = expectedType;
120        this.providedType   = providedType;
121        this.name           = name;
122        this.descriptor     = descriptor;
123    }
124
125}