ImaJson (Eclipse Amlen Javadoc Reference)

Package com.ibm.ima.plugin.util

## Class ImaJson

- Object
- - com.ibm.ima.plugin.util.ImaJson

-     public class ImaJson
      extends Object

  The ImaJson class is used to parse a JSON string. This is a high speed parser designed to limit the creation of Java objects while parsing.

  The object can be reused by calling parse with a new string.

  The ImaJson class also provides a set of helper methods to create JSON.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class | Description
    --- | --- | ---
    `class` | `ImaJson.Entry` | A JSON entry.
    `static class` | `ImaJson.JObject` | JSON object entry type.

  - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `static String` | `COPYRIGHT` |

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `ImaJson()` | Create a JSON parser object.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `static StringBuffer` | `escape​(StringBuffer to, String from)` | Copy a string to an output JSON buffer with escapes.
    `static String` | `fromMap​(Map<String,​Object> map)` | Create JSON object from a Map.
    `boolean` | `getBoolean​(String name, boolean deflt)` | Get a boolean from a named JSON item.
    `ImaJson.Entry[]` | `getEntries()` | Get the array of entries after a parse.
    `ImaJson.Entry` | `getEntry​(int i)` |
    `int` | `getEntryCount()` | Get the count of entries after a parse.
    `int` | `getInt​(String name, int default_value)` | Get an integer from a named JSON item.
    `int` | `getLine()` | Return the line position after the parse.
    `int` | `getPosition()` | Return the position after the parse.
    `String` | `getString​(String name)` | Get a string from a named JSON item.
    `Object` | `getValue​(int entnum)` | Return the value of an item as an object.
    `void` | `parse​(File file)` |
    `int` | `parse​(String jsonstr)` | Parse a JSON message.
    `static void` | `put​(StringBuffer buf, Object obj)` | Put out a Java object in JSON form.
    `static void` | `putString​(StringBuffer buf, String str)` | Put out a set of bytes with JSON string escapes.
    `void` | `setAllowComments​(boolean allowComments)` | Allow comments.
    `String[]` | `toArray​(int entnum)` | Return a string array from a parsed JSON array.
    `Map<String,​Object>` | `toMap​(int entnum)` | Make a Java map object from a JSON object.
    `String` | `toString()` |

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- - ### Field Detail

    - #### COPYRIGHT

          public static final String COPYRIGHT

      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### ImaJson

          public ImaJson()

      Create a JSON parser object.

  - ### Method Detail

    - #### setAllowComments

          public void setAllowComments​(boolean allowComments)

      Allow comments. There is no comment form in JSON, but when JSON is used for configuration it is useful to source comments. Java and C style comments (slash-star and slash-slash) are allowed whereever white space is allowed.
      Parameters:
        `allowComments` - If true allow comments

    - #### getPosition

          public int getPosition()

      Return the position after the parse. This position can be used when framing of messages is done. Only the first object or array within the source is parsed and the position after parse indicates the source position after parse. Trailing whitespace but not comments are skipped. #return The source position after parse

    - #### getLine

          public int getLine()

      Return the line position after the parse. The line is relative to the start of the source and atarts at 1. This can be used to indicate where an error occurred.
      Returns:
        The line position

    - #### getEntryCount

          public int getEntryCount()

      Get the count of entries after a parse. This is the same value which is returned on the parse() method.
      Returns:
        The number of used entries

    - #### getEntry

          public ImaJson.Entry getEntry​(int i)

    - #### getEntries

          public ImaJson.Entry[] getEntries()

      Get the array of entries after a parse. These will change in value if parse is called again. The array may be larger than the number of used entries.
      Returns:
        An array of entries.

    - #### parse

          public int parse​(String jsonstr)

      Parse a JSON message. The specified string is parsed as a JSON object or array. If this succeeds the count of entries is returned, otherwise an error is returned. A return of -1 indicates that the JSON object is incomplete. Therefore by adding more chracters you could get a valid JSON object or array. A return code of -2 indicates that the JSON object is invalid and cannot be fixed by adding additional characters. This difference is used for framing a stream containing JSON objects deliminated by the end of the object.
      Parameters:
        `jsonstr` - A JSON string containing an object or array
      Returns:
        The count of entries if zero or positive, -1=incomplete, -2-invalid.

    - #### parse

          public void parse​(File file)
                     throws Exception

      Throws:
        `Exception`

    - #### escape

          public static StringBuffer escape​(StringBuffer to,
                                            String from)

      Copy a string to an output JSON buffer with escapes.

      Escape the double quote, backslash, and all C0 control characters (0x00 - 0x1F).

    - #### putString

          public static void putString​(StringBuffer buf,
                                       String str)

      Put out a set of bytes with JSON string escapes.

      In JSON all strings are surrounded by double quotes, and the characters double quote, backslash, and control characters in the C0 range (0x00 - 0x1F) are required to be escaped.

      Parameters:
        `buf` - The buffer to write to
        `str` - The String to write

    - #### put

          public static void put​(StringBuffer buf,
                                 Object obj)

      Put out a Java object in JSON form.

      The Java object can be null, or can be an instance of String, Number, or Boolean. Number includes all of the common numeric types.

      Parameters:
        `buf` - The string buffer to write to
        `obj` - The object to write (null, String, Number, or Boolean).

    - #### getString

          public String getString​(String name)

      Get a string from a named JSON item.

      This is used to find simple items within a single level JSON object. It finds the item with the specified name within the outermost object in the parsed JSON object. If this item is not an string, it attempts to convert it to a string. If the item is missing or cannot be converted to a string, return null.

      Parameters:
        `name` - The name of the property
      Returns:
        An string value for the item or null

    - #### getInt

          public int getInt​(String name,
                            int default_value)

      Get an integer from a named JSON item.

      This is used to find simple items within a single level JSON object. It finds the item with the specified name within the outermost object in the parsed JSON object. If this item is not an integer, it attempts to convert it to integer. If the item is missing or cannot be converted to integer, return the default value.

      Parameters:
        `name` - The name of the property
        `default_value` - The default value to return if the named property is missing or cannot be converted to a integer.
      Returns:
        An integer value for the item or the default value.

    - #### fromMap

          public static String fromMap​(Map<String,​Object> map)

      Create JSON object from a Map.
      Parameters:
        `map` - The map to convert to a JSON object
      Returns:
        A String representing the JSON object

    - #### getValue

          public Object getValue​(int entnum)

      Return the value of an item as an object.
      Parameters:
        `entnum` - The entry number in the parsed object
      Returns:
        The value of the entry as a Java object.

    - #### toArray

          public String[] toArray​(int entnum)

      Return a string array from a parsed JSON array.

      The specified entry in the parsed JSON object must be an array. The value of each object in the array is returned as an array of Strings. The items in the array are converted as required but must not be objects or arrays.

      Parameters:
        `entnum` - The entry number within the parsed object.

    - #### getBoolean

          public boolean getBoolean​(String name,
                                    boolean deflt)

      Get a boolean from a named JSON item.

      This is used to find simple items within a single level JSON object. It finds the item with the specified name within the outermost object in the parsed JSON object. If this item is not a boolean, it attempts to convert it to boolean. If the item is missing or cannot be converted to boolean, return the default value.

      Parameters:
        `name` - The name of the property
        `default_value` - The default value to return if the named property is missing or cannot be converted to a boolean.
      Returns:
        A boolean value for the item or the default value.

    - #### toMap

          public Map<String,​Object> toMap​(int entnum)

      Make a Java map object from a JSON object.
      Parameters:
        `entnum` - The entry number in the parsed Java object. This must be a JSON object.
      Returns:
        A map or null to indicate an error

    - #### toString

          public String toString()

      Overrides:
        `toString` in class `Object`