001package Torello.Java.JSON;
002
003import javax.json.*;
004
005/**
006 * The parent class of all Json Binding Exceptions that are used for <B>{@link JsonObject}</B>
007 * property retrieval errors.  In order to hopefully continue to make easy-code actually look easy,
008 * the following keywords used in this exception's name are broken down below.
009 * 
010 * <BR /><BR /><B>NOTE:</B> This class is abstract, and cannot be instantiated.
011 * 
012 * <EMBED CLASS=globalDefs DATA-STRUCT=JsonObject DATA-TYPE=Object DATA-TYPE_ABBREV=Obj>
013 * <EMBED CLASS='external-html' DATA-FILE-ID=JE_FIELD_B_OBJ>
014 */
015@Torello.JavaDoc.JDHeaderBackgroundImg(EmbedTagFileID="JE_B_UL")
016@Torello.JavaDoc.CSSLinks(FileNames="JSONExceptions.css")
017public abstract class JsonBindingObjException extends JsonBindingException
018{
019    /** <EMBED CLASS='external-html' DATA-FILE-ID=SVUIDEX>  */
020    public static final long serialVersionUID = 1;
021
022    /**
023     * <EMBED CLASS='external-html' DATA-FILE-ID=EXPF>
024     * 
025     * <BR /><BR />The <B>{@link JsonObject}</B> property-name that has caused this exception to
026     * throw.
027     */
028    public final String propertyName;
029
030    /**
031     * Constructs a {@code JsonBindingObjException} with no specified detail messsage,
032     * and the user-provided convenience-field values.
033     * 
034     * @param errorSourceJsonObject <EMBED CLASS='external-html' DATA-FILE-ID=JBEX_ESJO>
035     * @param propertyName          <EMBED CLASS='external-html' DATA-FILE-ID=JBEX_PN>
036     * @param expectedJsonType      <EMBED CLASS='external-html' DATA-FILE-ID=JBEX_EJT>
037     * @param valueRetrieved        <EMBED CLASS='external-html' DATA-FILE-ID=JBEX_VR>
038     * @param methodReturnJavaType  <EMBED CLASS='external-html' DATA-FILE-ID=JBEX_MRJT>
039     * @param endingNote            <EMBED CLASS='external-html' DATA-FILE-ID=JBEX_EN>
040     */
041    public JsonBindingObjException(
042            JsonObject          errorSourceJsonObject,
043            String              propertyName,
044            JsonValue.ValueType expectedJsonType,
045            JsonValue           valueRetrieved,
046            Class<?>            methodReturnJavaType,
047            String              endingNote
048        )
049    {
050        super(
051            BASE_MESSAGE_OBJ(
052                errorSourceJsonObject, propertyName, expectedJsonType, valueRetrieved,
053                methodReturnJavaType, endingNote
054            ),
055            errorSourceJsonObject, expectedJsonType, valueRetrieved,
056            methodReturnJavaType
057        );
058
059        this.propertyName = propertyName;
060    }
061
062    /**
063     * Constructs a {@code JsonBindingObjException} with the specified detail message, and
064     * user-provided convenience-field values.
065     * 
066     * @param message the detail message.
067     * @param errorSourceJsonObject <EMBED CLASS='external-html' DATA-FILE-ID=JBEX_ESJO>
068     * @param propertyName          <EMBED CLASS='external-html' DATA-FILE-ID=JBEX_PN>
069     * @param expectedJsonType      <EMBED CLASS='external-html' DATA-FILE-ID=JBEX_EJT>
070     * @param valueRetrieved        <EMBED CLASS='external-html' DATA-FILE-ID=JBEX_VR>
071     * @param methodReturnJavaType  <EMBED CLASS='external-html' DATA-FILE-ID=JBEX_MRJT>
072     */
073    public JsonBindingObjException(
074            String              message,
075            JsonObject          errorSourceJsonObject,
076            String              propertyName,
077            JsonValue.ValueType expectedJsonType,
078            JsonValue           valueRetrieved,
079            Class<?>            methodReturnJavaType
080        )
081    {
082        super(
083            message, errorSourceJsonObject, expectedJsonType, valueRetrieved,
084            methodReturnJavaType
085        );
086
087        this.propertyName = propertyName;
088    }
089
090    /**
091     * Constructs a new {@code JsonBindingObjException} with the specified detail message and cause
092     * 
093     * <BR /><BR /><B>NOTE:</B> The detail message associated with cause is not automatically
094     * incorporated in this exception's detail message.
095     * 
096     * @param message The detail message (which is saved for later retrieval by the
097     * {@code Throwable.getMessage()} method).
098     * 
099     * @param cause the cause (which is saved for later retrieval by the
100     * {@code Throwable.getCause()} method).  (A null value is permitted, and indicates that the
101     * cause is nonexistent or unknown.)
102     * 
103     * @param errorSourceJsonObject <EMBED CLASS='external-html' DATA-FILE-ID=JBEX_ESJO>
104     * @param propertyName          <EMBED CLASS='external-html' DATA-FILE-ID=JBEX_PN>
105     * @param expectedJsonType      <EMBED CLASS='external-html' DATA-FILE-ID=JBEX_EJT>
106     * @param valueRetrieved        <EMBED CLASS='external-html' DATA-FILE-ID=JBEX_VR>
107     * @param methodReturnJavaType  <EMBED CLASS='external-html' DATA-FILE-ID=JBEX_MRJT>
108     */
109    public JsonBindingObjException(
110            String              message,
111            Throwable           cause,
112            JsonObject          errorSourceJsonObject,
113            String              propertyName,
114            JsonValue.ValueType expectedJsonType,
115            JsonValue           valueRetrieved,
116            Class<?>            methodReturnJavaType
117        )
118    {
119        super(
120            message, cause, errorSourceJsonObject, expectedJsonType, valueRetrieved,
121            methodReturnJavaType
122        );
123
124        this.propertyName = propertyName;
125    }
126
127    /**
128     * Constructs a new {@code JsonBindingObjException} with the specified cause and a detail
129     * message of {@code (cause==null ? null : cause.toString())} (which typically contains the
130     * class and detail message of cause).  This constructor is useful for exceptions that are
131     * little more than wrappers for other throwables.
132     * 
133     * @param cause The cause (which is saved for later retrieval by the
134     * {@code Throwable.getCause()} method).  (A null value is permitted, and indicates that the
135     * cause is nonexistent or unknown.)
136     * 
137     * @param errorSourceJsonObject <EMBED CLASS='external-html' DATA-FILE-ID=JBEX_ESJO>
138     * @param propertyName          <EMBED CLASS='external-html' DATA-FILE-ID=JBEX_PN>
139     * @param expectedJsonType      <EMBED CLASS='external-html' DATA-FILE-ID=JBEX_EJT>
140     * @param valueRetrieved        <EMBED CLASS='external-html' DATA-FILE-ID=JBEX_VR>
141     * @param methodReturnJavaType  <EMBED CLASS='external-html' DATA-FILE-ID=JBEX_MRJT>
142     * @param endingNote            <EMBED CLASS='external-html' DATA-FILE-ID=JBEX_EN>
143     */
144    public JsonBindingObjException(
145            Throwable           cause,
146            JsonObject          errorSourceJsonObject,
147            String              propertyName,
148            JsonValue.ValueType expectedJsonType,
149            JsonValue           valueRetrieved,
150            Class<?>            methodReturnJavaType,
151            String              endingNote
152        )
153    {
154        super(
155            BASE_MESSAGE_OBJ(
156                errorSourceJsonObject, propertyName, expectedJsonType, valueRetrieved,
157                methodReturnJavaType, endingNote, cause
158            ),
159            cause, errorSourceJsonObject, expectedJsonType, valueRetrieved,
160            methodReturnJavaType
161        );
162
163        this.propertyName = propertyName;
164    }
165
166    /**
167     * A simple helper method for printing a consistent error messge using the input-data
168     * convenience fields of <B>{@code JsonArray's}</B>.
169     * 
170     * @param errorSourceJsonObject <EMBED CLASS='external-html' DATA-FILE-ID=JBEX_ESJO>
171     * @param propertyName          <EMBED CLASS='external-html' DATA-FILE-ID=JBEX_PN>
172     * @param expectedJsonType      <EMBED CLASS='external-html' DATA-FILE-ID=JBEX_EJT>
173     * @param valueRetrieved        <EMBED CLASS='external-html' DATA-FILE-ID=JBEX_VR>
174     * @param methodReturnJavaType  <EMBED CLASS='external-html' DATA-FILE-ID=JBEX_MRJT>
175     * @param endingNote            <EMBED CLASS='external-html' DATA-FILE-ID=JBEX_EN>
176     * @param causes                Optional Parameter.  At most 1 cause is printed.
177     * 
178     * @return The error message {@code String}.
179     */
180    protected static String BASE_MESSAGE_OBJ(
181            JsonObject          errorSourceJsonObject,
182            String              propertyName,
183            JsonValue.ValueType expectedJsonType,
184            JsonValue           valueRetrieved,
185            Class<?>            methodReturnJavaType,
186            String              endingNote,
187            Throwable...        causes
188        )
189    {
190        return 
191            ((endingNote != null) ? endingNote : "") +"\n" +
192            CAUSE_MESSAGE(causes) +
193            "\tFound In JsonObject:      " + ABBREV_STRUCT(errorSourceJsonObject) + "\n" +
194            "\tProperty-Name:            " + propertyName + "\n" +
195            "\tExpected Json-Type:       " + JT_STR(expectedJsonType) + "\n" +
196            "\tContained JsonValue:      " + ABBREV_VAL(valueRetrieved) + "\n" +
197            "\tHaving Actual Json-Type:  " + JT_STR((valueRetrieved != null)
198                    ? valueRetrieved.getValueType()
199                    : null
200                ) + "\n" +
201            "\tConverting To Java-Type:  " + ((methodReturnJavaType != null)
202                    ? methodReturnJavaType.getCanonicalName()
203                    : "Java-Type Unknown"
204                );
205    }
206}