InvalidJsonType class: Difference between revisions

From m204wiki
Jump to navigation Jump to search
(Created page with "<!-- InvalidJsonType class --> Json objects simulate JavaScript untyped variables. However, many Json functions only make sense for specific underlying Json dat...")
 
No edit summary
 
(6 intermediate revisions by one other user not shown)
Line 2: Line 2:
[[Json class|Json]] objects simulate JavaScript untyped variables. However, many Json functions only make sense for specific underlying Json data. For example, the [[Add (Json function)|Add function]] only makes sense if the underlying json object is an Array. If a function applied to a Json object is invalid for the underlying object, an <var>InvalidJsonType</var> exception is thrown.
[[Json class|Json]] objects simulate JavaScript untyped variables. However, many Json functions only make sense for specific underlying Json data. For example, the [[Add (Json function)|Add function]] only makes sense if the underlying json object is an Array. If a function applied to a Json object is invalid for the underlying object, an <var>InvalidJsonType</var> exception is thrown.
   
   
To create an <var>InvalidjsonType</var> exception yourself, you typically use a SOUL <var>[[Exceptions#Using the Throw statement|Throw]]</var> statement with an <var>InvalidJsonTyoe</var> <var>[[New_(InvalidJsonType_constructor)|New]]</var> constructor.  This statement must be issued from within a method, and it can only be caught by the code that calls the method.  For example, the following statement throws an <var>InvalidJsonType</var> exception:
To create an <var>InvalidjsonType</var> exception yourself, you typically use a SOUL <var>[[Exceptions#Using the Throw statement|Throw]]</var> statement with an <var>InvalidJsonType</var> <var>[[New_(InvalidJsonType_constructor)|New]]</var> constructor.  This statement must be issued from within a method, and it can only be caught by the code that calls the method.  For example, the following statement throws an <var>InvalidJsonType</var> exception:
<p class="code">throw %(invalidJsonType):new(type=array, method="MyJsonMethod")
<p class="code">throw %(invalidJsonType):new(type=array, method="MyJsonMethod")
</p>
</p>
Line 8: Line 8:
Remember that you catch an exception with the <var>[[Exceptions#Try and Catch|Catch]]</var> statement; if an exception condition occurs outside a <var>Catch</var> for it, the request is cancelled.
Remember that you catch an exception with the <var>[[Exceptions#Try and Catch|Catch]]</var> statement; if an exception condition occurs outside a <var>Catch</var> for it, the request is cancelled.
   
   
The <var>InvalidJsonType</var> class, like the Json class is available as of <var class="product">Model 204</var> 7.6.
The <var>InvalidJsonType</var> class, like the Json class, is available as of <var class="product">Model 204</var> 7.6.
   
   
==The InvalidJsonTypes methods==
==The InvalidJsonTypes methods==
Line 19: Line 19:
<li>[[InvalidJsonType methods syntax|"InvalidJsonType methods syntax"]] is a single page that contains the syntax diagrams of all the methods in the class.
<li>[[InvalidJsonType methods syntax|"InvalidJsonType methods syntax"]] is a single page that contains the syntax diagrams of all the methods in the class.
</ul>
</ul>
==MethodName property==
{{Template:InvalidJsonType:MethodName subtitle}}
   
   
This <var>[[Classes and Objects#readWrite|ReadOnly]]</var> property returns a string that indicates the name of the failing method.
   
   
===Syntax===
{{Template:InvalidJsonType:MethodName syntax}}
====Syntax terms====
<table class="syntaxTable">
<tr><th>%string</th>
<td>The name of the failing method.</td></tr>
<tr><th>invalidJsonType</th>
<td>A reference to an instance of an <var>[[InvalidJsonType_class|InvalidJsonType]]</var> object.</td></tr>
</table>
==Type property==
{{Template:InvalidJsonType:Type subtitle}}
This <var>[[Classes and Objects#readWrite|ReadOnly]]</var> property returns a [[JsonType enumeration]] value that indicates the underlying Json object type for the object against which the failing method was applied.
===Syntax===
{{Template:InvalidJsonType:Type syntax}}
====Syntax terms====
<table class="syntaxTable">
<tr><th>%jsonType</th>
<td>The underlying Json object type for the object against which the failing method was applied.</td></tr>
<tr><th>invalidJsonType</th>
<td>A reference to an instance of an <var>[[InvalidJsonType_class|InvalidJsonType]]</var> object.</td></tr>
</table>
==New constructor==
==New constructor==
{{Template:InvalidJsonType:New subtitle}}
{{Template:InvalidJsonType:New subtitle}}
   
   
This <var>Constructor</var> generates an instance of an <var>[[InvalidGZipData_class|InvalidGZipData]]</var> exception. The <var>New</var> method format follows:
This <var>Constructor</var> generates an instance of an <var>[[InvalidJsonType_class|InvalidJsonType]]</var> exception. The <var>New</var> method format follows:
===Syntax===
===Syntax===
{{Template:InvalidJsonType:New syntax}}
{{Template:InvalidJsonType:New syntax}}
Line 30: Line 62:
====Syntax terms====
====Syntax terms====
<table class="syntaxTable">
<table class="syntaxTable">
<tr><th>%invalidJsonType</th>
<tr><th>%invalidJsonType</th><td>A reference to an instance of an <var>InvalidJsonType</var> object.</td></tr>
<td>A reference to an instance of an <var>InvalidJsonType</var> object. </td></tr>
<tr><th><var>[%(InvalidJsonType):]</var></th><td>The class name in parentheses denotes a <var>[[Notation conventions for methods#Constructors|Constructor]]</var>.</td></tr>
<tr><th><var>[%(InvalidGZipData):]</var></th>
<tr><th>jsonType</th><td>A [[JsonType enumeration]] value that indicates the underlying JSON type of the object to which the invalid method was applied.</td></tr>
<td>The class name in parentheses denotes a <var>[[Notation conventions for methods#Constructors|Constructor]]</var>. See [[#Usage notes|"Usage notes"]], below, for more information about invoking an <var>InvalidGZipData</var> <var>Constructor</var>.</td></tr>
<tr><th>string</th><td>The name of the method that encountered the error.</td></tr>
</table>
</table>
 
===Usage notes===
===Usage notes===
<ul>
<ul>
<li>As described in [[Object variables#Using New or other Constructors|"Using New or other Constructors"]], <var>New</var> can be invoked with no object, with an explicit class name, or with an object variable in the class, even if that object is <var>Null</var>:<p class="code">%invalid = new
<li>Json object tree can be created from data received from an outside data source that was generated via the [[Parse (Json function)|Json Parse]] function. If the external data source is considered 100% in terms of sending JSON data with a known format, the data could be extracted without worries about InvalidJsonType exceptions. However, if there is a concern that the data will not be exactly what is expected, one should either test each object for the expected datatype via the [[Type (Json function)|Type function]] or wrap the data extraction inside a Try/Catch InvalidJsonType. Obviously, the latter requires less effort and is more efficient. For example, if an application expects an order to come in as an array of objects with a product name, code, quantity, and price but the source is not 100% trustworthy, one can do something like:
<p class="code">try
%invalid = %(InvalidGZipData):new
  for %i from 1 to %order:count
      %name    = %order(%i)("name"):stringValue
%invalid = %invalid:new
      %code    = %order(%i)("code"):stringValue
      %quantity = %order(%i)("quantity"):numberValue
      %price  = %order(%i)("price"):numberValue
      ... process the order item
  end for
catch invalidJsonType
  ... deal with the error
end try
</p>
</p>
The Try/Catch adds no overhead to the processing but makes it easy to trap a malformed request.
</ul>
</ul>
[[Category:System exception classes]]
[[Category:System exception classes]]

Latest revision as of 16:12, 23 August 2016

Json objects simulate JavaScript untyped variables. However, many Json functions only make sense for specific underlying Json data. For example, the Add function only makes sense if the underlying json object is an Array. If a function applied to a Json object is invalid for the underlying object, an InvalidJsonType exception is thrown.

To create an InvalidjsonType exception yourself, you typically use a SOUL Throw statement with an InvalidJsonType New constructor. This statement must be issued from within a method, and it can only be caught by the code that calls the method. For example, the following statement throws an InvalidJsonType exception:

throw %(invalidJsonType):new(type=array, method="MyJsonMethod")

Remember that you catch an exception with the Catch statement; if an exception condition occurs outside a Catch for it, the request is cancelled.

The InvalidJsonType class, like the Json class, is available as of Model 204 7.6.

The InvalidJsonTypes methods

The following are the available InvalidJsonType class methods.

MethodDescription
MethodNameType of object for invalid method
NewCreate a new InvalidJsonType object
TypeType of object for invalid method

The methods in the class are described in the subsections that follow. In addition:

MethodName property

Type of object for invalid method (InvalidJsonType class)

This ReadOnly property returns a string that indicates the name of the failing method.

Syntax

%string = invalidJsonType:MethodName

Syntax terms

%string The name of the failing method.
invalidJsonType A reference to an instance of an InvalidJsonType object.

Type property

Type of object for invalid method (InvalidJsonType class)

This ReadOnly property returns a JsonType enumeration value that indicates the underlying Json object type for the object against which the failing method was applied.

Syntax

%jsonType = invalidJsonType:Type

Syntax terms

%jsonType The underlying Json object type for the object against which the failing method was applied.
invalidJsonType A reference to an instance of an InvalidJsonType object.

New constructor

Create a new InvalidJsonType object (InvalidJsonType class)

This Constructor generates an instance of an InvalidJsonType exception. The New method format follows:

Syntax

%invalidJsonType = [%(InvalidJsonType):]New( Type= jsonType, MethodName= string)

Syntax terms

%invalidJsonTypeA reference to an instance of an InvalidJsonType object.
[%(InvalidJsonType):]The class name in parentheses denotes a Constructor.
jsonTypeA JsonType enumeration value that indicates the underlying JSON type of the object to which the invalid method was applied.
stringThe name of the method that encountered the error.

Usage notes

  • Json object tree can be created from data received from an outside data source that was generated via the Json Parse function. If the external data source is considered 100% in terms of sending JSON data with a known format, the data could be extracted without worries about InvalidJsonType exceptions. However, if there is a concern that the data will not be exactly what is expected, one should either test each object for the expected datatype via the Type function or wrap the data extraction inside a Try/Catch InvalidJsonType. Obviously, the latter requires less effort and is more efficient. For example, if an application expects an order to come in as an array of objects with a product name, code, quantity, and price but the source is not 100% trustworthy, one can do something like:

    try for %i from 1 to %order:count %name = %order(%i)("name"):stringValue %code = %order(%i)("code"):stringValue %quantity = %order(%i)("quantity"):numberValue %price = %order(%i)("price"):numberValue ... process the order item end for catch invalidJsonType ... deal with the error end try

    The Try/Catch adds no overhead to the processing but makes it easy to trap a malformed request.