Package Torello.JSON

Class JsonBindingException

    • Field Detail

      • serialVersionUID

        🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static final long serialVersionUID
        This fulfils the SerialVersion UID requirement for all classes that implement Java's interface java.io.Serializable. Using the Serializable Implementation offered by java is very easy, and can make saving program state when debugging a lot easier. It can also be used in place of more complicated systems like "hibernate" to store data as well.

        Note that Java's java.lang.Exception and java.lang.Error classes implement the Serializable interface, and a warning-free build expects this field be defined here.
        See Also:
        Constant Field Values
        Code:
        Exact Field Declaration Expression:
         public static final long serialVersionUID = 1;

      • errorSourceJsonStruct

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public final JsonStructure errorSourceJsonStruct
        This field is provided to the user as a matter of convenience. All instances of this Exception ought to guarantee that when an instance is thrown - any & all "Convenience Fields" have been properly set.

        If this package is extended, or if this exception is used elsewhere, try to remember to not to accidentally leave this field null when using this class' constructors.

        In Summary:
        All this is really trying to explain is that, when debugging your code, if in the analysis of a particular Exception, that analysis causes another exception throw (NullPointerException) - BECAUSE THIS CONVENIENCE FIELD WAS LEFT NULL - you would likely get pretty angry.

        This contains the actual JsonStructure (which should either be an instance of JsonObject or JsonArray) which contained the array-element or object-property that has caused this exception throw.
        Code:
        Exact Field Declaration Expression:
         public final JsonStructure errorSourceJsonStruct;

      • expectedJsonType

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public final JsonValue.ValueType expectedJsonType
        This field is provided to the user as a matter of convenience. All instances of this Exception ought to guarantee that when an instance is thrown - any & all "Convenience Fields" have been properly set.

        If this package is extended, or if this exception is used elsewhere, try to remember to not to accidentally leave this field null when using this class' constructors.

        In Summary:
        All this is really trying to explain is that, when debugging your code, if in the analysis of a particular Exception, that analysis causes another exception throw (NullPointerException) - BECAUSE THIS CONVENIENCE FIELD WAS LEFT NULL - you would likely get pretty angry.

        This contains the expected type which ought to have been found at the user-specified JsonArray or JsonObject location. Since both of these kinds of JsonStructure are only allowed to have Json-Type's; therefore this field's declared type is JsonValue.ValueType.

        ASIDE: The enum JsonValue.ValueType has two enum-constants which represent the Json-Type 'Boolean'. As a result, there are two possible values to which this field could be assigned to symbolize a Json Boolean Type (JsonValue.ValueType.FALSE and JsonValue.ValueType.TRUE). However, in Java HTML, a Json-Boolean Type will always be represented using the TRUE enum-constant.
        Code:
        Exact Field Declaration Expression:
         public final JsonValue.ValueType expectedJsonType;

      • valueRetrieved

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public final JsonValue valueRetrieved
        This field is provided to the user as a matter of convenience. All instances of this Exception ought to guarantee that when an instance is thrown - any & all "Convenience Fields" have been properly set.

        If this package is extended, or if this exception is used elsewhere, try to remember to not to accidentally leave this field null when using this class' constructors.

        In Summary:
        All this is really trying to explain is that, when debugging your code, if in the analysis of a particular Exception, that analysis causes another exception throw (NullPointerException) - BECAUSE THIS CONVENIENCE FIELD WAS LEFT NULL - you would likely get pretty angry.

        This is the value retrieved from the JsonArray or JsonObject. If the value was not present or unavailable, then this parameter will, indeed, evaulated to Java-Null. If Json-Null was retrieved, then this parameter will contain JsonValue.NULL.
        Code:
        Exact Field Declaration Expression:
         public final JsonValue valueRetrieved;

      • methodReturnJavaType

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public final java.lang.Class<?> methodReturnJavaType
        This field is provided to the user as a matter of convenience. All instances of this Exception ought to guarantee that when an instance is thrown - any & all "Convenience Fields" have been properly set.

        If this package is extended, or if this exception is used elsewhere, try to remember to not to accidentally leave this field null when using this class' constructors.

        In Summary:
        All this is really trying to explain is that, when debugging your code, if in the analysis of a particular Exception, that analysis causes another exception throw (NullPointerException) - BECAUSE THIS CONVENIENCE FIELD WAS LEFT NULL - you would likely get pretty angry.

        This specifies return type (as an instance of java.lang.Class<T> that is used by the method which has thrown this exception. This is the Java-Type to which the Json-Type was going to be assigned.
        Code:
        Exact Field Declaration Expression:
         public final Class<?> methodReturnJavaType;

    • Constructor Detail

      • JsonBindingException

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public JsonBindingException​(java.lang.String message,
                            JsonStructure errorSourceJsonStruct,
                            JsonValue.ValueType expectedJsonType,
                            JsonValue valueRetrieved,
                            java.lang.Class<?> methodReturnJavaType)
        Constructs a JsonBindingException with the specified detail message, and user-provided convenience-field values.
        Parameters:
        message - the detail message.
        errorSourceJsonStruct - The JsonStructure from which the element or property (dependent upon which subclass is inheriting this exception), is being retrieved / extracted.
        expectedJsonType - This is the Json-Type that was expected to be retrieved from JsonArray.
        valueRetrieved - This is the JsonValue that was extracted from the JsonArray which caused an exception. Note that if the entity did not exist, then this parameter will be Java-Null. If Json-Null was found, then this parameter should be JsonValue.NULL
        methodReturnJavaType - Class ReadJSON will always provide the ultimate Java-Type that is to be returned by the method where this exception is being thrown.

      • JsonBindingException

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public JsonBindingException​(java.lang.String message,
                            java.lang.Throwable cause,
                            JsonStructure errorSourceJsonStruct,
                            JsonValue.ValueType expectedJsonType,
                            JsonValue valueRetrieved,
                            java.lang.Class<?> methodReturnJavaType)
        Constructs a new JsonBindingException with the specified detail message and cause.

        NOTE:

        The detail message associated with cause is not automatically incorporated into this exception's detail message.
        Parameters:
        message - The detail message (which is saved for later retrieval by the Throwable.getMessage() method).
        cause - the cause (which is saved for later retrieval by the Throwable.getCause() method). (A null value is permitted, and indicates that the cause is nonexistent or unknown.)
        errorSourceJsonStruct - The JsonStructure from which the element or property (dependent upon which subclass is inheriting this exception), is being retrieved / extracted.
        expectedJsonType - This is the Json-Type that was expected to be retrieved from JsonArray.
        valueRetrieved - This is the JsonValue that was extracted from the JsonArray which caused an exception. Note that if the entity did not exist, then this parameter will be Java-Null. If Json-Null was found, then this parameter should be JsonValue.NULL
        methodReturnJavaType - Class ReadJSON will always provide the ultimate Java-Type that is to be returned by the method where this exception is being thrown.

      • JsonBindingException

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public JsonBindingException​(java.lang.Throwable cause,
                            JsonStructure errorSourceJsonStruct,
                            JsonValue.ValueType expectedJsonType,
                            JsonValue valueRetrieved,
                            java.lang.Class<?> methodReturnJavaType)
        Constructs a new JsonBindingException with the specified cause and a detail message of (cause==null ? null : cause.toString()) (which typically contains the class and detail message of cause).

        This constructor is useful for exceptions that are little more than wrappers for other throwables.
        Parameters:
        cause - The cause (which is saved for later retrieval by the Throwable.getCause() method). (A null value is permitted, and indicates that the cause is nonexistent or unknown.)
        errorSourceJsonStruct - The JsonStructure from which the element or property (dependent upon which subclass is inheriting this exception), is being retrieved / extracted.
        expectedJsonType - This is the Json-Type that was expected to be retrieved from JsonArray.
        valueRetrieved - This is the JsonValue that was extracted from the JsonArray which caused an exception. Note that if the entity did not exist, then this parameter will be Java-Null. If Json-Null was found, then this parameter should be JsonValue.NULL
        methodReturnJavaType - Class ReadJSON will always provide the ultimate Java-Type that is to be returned by the method where this exception is being thrown.

    • Method Detail

      • BASE_MESSAGE

        🡅  ⇈  ⮫ 🗕  🗗  🗖 
        protected static java.lang.String BASE_MESSAGE​
            (JsonStructure errorSourceJsonStruct,
             JsonValue.ValueType expectedJsonType,
             JsonValue valueRetrieved,
             java.lang.Class<?> methodReturnJavaType,
             java.lang.Throwable... causes)
        A simple helper method for printing consistent error messages using the input-data convenience fields.
        Parameters:
        errorSourceJsonStruct - The JsonStructure from which the element or property (dependent upon which subclass is inheriting this exception), is being retrieved / extracted.
        expectedJsonType - This is the Json-Type that was expected to be retrieved from JsonArray.
        valueRetrieved - This is the JsonValue that was extracted from the JsonArray which caused an exception. Note that if the entity did not exist, then this parameter will be Java-Null. If Json-Null was found, then this parameter should be JsonValue.NULL
        methodReturnJavaType - Class ReadJSON will always provide the ultimate Java-Type that is to be returned by the method where this exception is being thrown.
        causes - Optional Parameter. At most 1 cause is printed.
        Returns:
        The error message String.
        Code:
        Exact Method Body:
         // After much argument with Chat-GPT, I have decided to encode the following line
 // right here

 final String srcJsonAsStr = (errorSourceJsonStruct == null)

     // This means that the user's null JO or JA has trickled all the way here, before
     // and NPE has thrown.  The NPE should have thrown the minute that ReadJSON attempts
     // to extract an element from an array or object that is null.
     // 
     // I don't use "Assert Statements", and I don't know why, but that's how this works.
     // This is just a glorified "Assert Statement".  This should never happen.  The value
     // passed to "errorSourceJsonStruct" is just the JsonArray or JsonObject that the user
     // requested for data extraction.  If that were null, an actual NPE should throw by the
     // second or third line of the method.
    
     ? (
         '\n' +
         "\t*** ERROR: The Source Json-Structure you have passed is, itself, null\n" +
         "\t*** HOWEVER: My code should have already thrown an NPE, the moment you passed " +
             "null\n"+
         "\t*** SORRY!"
         )

     : errorSourceJsonStruct.getClass().getSimpleName();

 return
     "Problems Binding Json\n" +
     CAUSE_MESSAGE(causes) +
     "\tFound In JsonStructure:   " + ABBREV_STRUCT(errorSourceJsonStruct) + "\n" +
     "\tJsonStructure SubClass:   " + srcJsonAsStr + "\n" +
     "\tExpected Json-Type:       " + JT_STR(expectedJsonType) + "\n" +
     "\tContained JsonValue:      " + ABBREV_VAL(valueRetrieved) + "\n" +
     "\tHaving Actual Json-Type:  " + JT_STR((valueRetrieved != null)
             ? valueRetrieved.getValueType()
             : null
         ) + "\n" +
     RET_TYPE_STR(methodReturnJavaType) + '\n';