Package org.webpki.json

Class JSONObjectReader

java.lang.Object

org.webpki.json.JSONObjectReader

All Implemented Interfaces:

Cloneable

public class JSONObjectReader
extends Object
implements Cloneable

JSON object reader.

Returned by the parser methods. Also provides built-in support for decoding JSF (JSON Signature Format) and JEF (JSON Encryption Format) constructs.

In addition, there are methods for reading keys supplied in the JWK (JSON Web Key) format.

See Also:

• JSONParser
• getObject(String)
• JSONArrayReader.getObject()
• JSONObjectWriter(JSONObjectReader)

Constructor Summary

Constructors

Constructor	Description
JSONObjectReader(JSONObjectWriter objectWriter)	Create a JSON object reader from of a writer.

Method Summary

Modifier and Type	Method	Description
void	checkForUnread()	Check for unread data.
JSONObjectReader	clone()	Deep copy of JSON object reader.
JSONArrayReader	getArray(String name)	Read a JSON array property.
BigDecimal	getBigDecimal(String name)	Read a BigDecimal property.
BigInteger	getBigInteger(String name)	Read a BigInteger property.
byte[]	getBinary(String name)	Read a base64url encoded JSON property.
ArrayList<byte[]>	getBinaryArray(String name)	Read an array of base64url encoded JSON strings.
byte[]	getBinaryConditional(String name)	Conditionally read a base64url encoded JSON property.
boolean	getBoolean(String name)	Read JSON boolean property.
boolean	getBooleanConditional(String name)	Conditionally read a JSON boolean property.
boolean	getBooleanConditional(String name, boolean defaultValue)	Conditionally read a JSON boolean property.
X509Certificate[]	getCertificatePath()	Read a certificate path in JSF format.
PublicKey	getCorePublicKey(AlgorithmPreferences algorithmPreferences)	Read and decode a public key in JSF (JWK) format.
GregorianCalendar	getDateTime(String name, EnumSet<ISODateTime.DatePatterns> constraints)	Read a JSON dateTime property in ISO format.
double	getDouble(String name)	Read a JSON double property.
JSONDecryptionDecoder	getEncryptionObject(JSONCryptoHelper.Options options)	Read an object in JEF format.
ArrayList<JSONDecryptionDecoder>	getEncryptionObjects(JSONCryptoHelper.Options options)	Read an object in JEF format intended for multiple recipients.
boolean	getIfNULL(String name)	Conditionally read a JSON null property.
int	getInt(String name)	Read a JSON integer property.
long	getInt53(String name)	Read a JSON long integer property.
JSONArrayReader	getJSONArrayReader()	Get root array reader.
KeyPair	getKeyPair()	Read a public and private key in JWK format.
KeyPair	getKeyPair(AlgorithmPreferences algorithmPreferences)	Read a public and private key in JWK format.
long	getLong(String name)	Read a JSON long integer property.
BigDecimal	getMoney(String name)	Read a Money property.
BigDecimal	getMoney(String name, int decimals)	Read a Money property.
ArrayList<JSONSignatureDecoder>	getMultiSignature(String signatureLabel, JSONCryptoHelper.Options options)
ArrayList<JSONSignatureDecoder>	getMultiSignature(JSONCryptoHelper.Options options)	Read and decode a JSF multi-signature object.
JSONObjectReader	getObject(String name)	Read a JSON object property.
String[]	getProperties()	Get JSON properties.
JSONTypes	getPropertyType(String name)	Get the native JSON type of a property.
PublicKey	getPublicKey()	Read and decode a public key in JSF (JWK) format.
PublicKey	getPublicKey(AlgorithmPreferences algorithmPreferences)	Read and decode a public key in JSF (JWK) format.
JSONSignatureDecoder	getSignature(String signatureLabel, JSONCryptoHelper.Options options)
JSONSignatureDecoder	getSignature(JSONCryptoHelper.Options options)	Read and decode a JSF signature object.
ArrayList<JSONSignatureDecoder>	getSignatureChain(String signatureLabel, JSONCryptoHelper.Options options)
ArrayList<JSONSignatureDecoder>	getSignatureChain(JSONCryptoHelper.Options options)	Read and decode a JSF chained-signature object.
String	getString(String name)	Read a JSON string property.
String[]	getStringArray(String name)	Read an array of JSON strings.
String[]	getStringArrayConditional(String name)	Conditionally read an array of JSON strings.
String	getStringConditional(String name)	Conditionally read a JSON string property. Note: This method is equivalent to getStringConditional(name, null).
String	getStringConditional(String name, String defaultValue)	Conditionally read a JSON string property.
boolean	hasProperty(String name)	Test if a property is present.
JSONObjectReader	removeProperty(String name)	Remove a property.
JSONObjectReader	scanAway(String name)	Scan a property.
byte[]	serializeToBytes(JSONOutputFormats outputFormat)	Serialize object reader to a Java byte[].
String	serializeToString(JSONOutputFormats outputFormat)	Serialize object reader to a Java String.
String	toString()	Pretty print JSON of object reader.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Details

JSONObjectReader

public JSONObjectReader(JSONObjectWriter objectWriter)

Create a JSON object reader from of a writer.

Parameters:

objectWriter - The writer object

Method Details

checkForUnread

public void checkForUnread()

Check for unread data. Throws an exception if any property or array element in the current object or child objects have not been read.

See Also:

• scanAway(String)
• getPropertyType(String)
• getProperties()

getString

public String getString(String name)

Read a JSON string property.

Parameters:

name - Property

Returns:

Java String

See Also:

• JSONObjectWriter.setString(String, String)

getInt

public int getInt(String name)

Read a JSON integer property.

This method only accepts true integer values. I.e. 10.4 would throw an exception.

Parameters:

name - Property

Returns:

Java int

See Also:

• JSONObjectWriter.setInt(String, int)

getInt53

public long getInt53(String name)

Read a JSON long integer property.

This method only accepts true integer values. I.e. 10.4 would throw an exception.

Note: Only 53 bits of precision is available, values outside this range throw exceptions.

Parameters:

name - Property

Returns:

Java long

See Also:

• JSONObjectWriter.setInt53(String, long)
• JSONObjectWriter.MAX_INTEGER
• getBigInteger(String)

getLong

public long getLong(String name)

Read a JSON long integer property.

This method only accepts true integer values. I.e. 10.4 would throw an exception.

Note: The value is put within quotes to maintain full 64-bit precision which does not have a native counterpart in JavaScript.

Parameters:

name - Property

Returns:

Java long

See Also:

• JSONObjectWriter.setLong(String, long)
• getBigInteger(String)
• getInt53(String)

getDouble

public double getDouble(String name)

Read a JSON double property.

Parameters:

name - Property

Returns:

Java double

See Also:

• JSONObjectWriter.setDouble(String, double)

getBoolean

public boolean getBoolean(String name)

Read JSON boolean property.

Parameters:

name - Property

Returns:

Java boolean

See Also:

• JSONObjectWriter.setBoolean(String, boolean)

getDateTime

public GregorianCalendar getDateTime(String name,
 EnumSet<ISODateTime.DatePatterns> constraints)

Read a JSON dateTime property in ISO format.

Note: Since JSON does not support a native dateTime type, this method builds on mapping.

Parameters:

name - Property

constraints - Required input format

Returns:

Java GregorianCalendar

See Also:

• ISODateTime.decode(String, EnumSet)
• JSONObjectWriter.setDateTime(String, GregorianCalendar, EnumSet)

getBinary

public byte[] getBinary(String name)

Read a base64url encoded JSON property.

Parameters:

name - Property

Returns:

Java byte[]

See Also:

• JSONObjectWriter.setBinary(String, byte[])

getBinaryConditional

public byte[] getBinaryConditional(String name)

Conditionally read a base64url encoded JSON property.

Parameters:

name - Property

Returns:

Java byte[] or null if property is not present

See Also:

• JSONObjectWriter.setBinary(String, byte[])

getMoney

public BigDecimal getMoney(String name)

Read a Money property.

Note: Since JSON does not support a native Money type, this method builds on mapping.

Parameters:

name - Property

Returns:

Java BigInteger

See Also:

• JSONObjectWriter.setMoney(String, BigDecimal)

getMoney

public BigDecimal getMoney(String name,
 int decimals)

Read a Money property.

Note: Since JSON does not support a native Money type, this method builds on mapping.

Parameters:

name - Property

decimals - Required number of fractional digits or null if unspecified

Returns:

Java BigDecimal

See Also:

• JSONObjectWriter.setMoney(String, BigDecimal, int)

getBigDecimal

public BigDecimal getBigDecimal(String name)

Read a BigDecimal property.

Note: Since JSON does not support a native BigDecimal type, this method builds on mapping.

Parameters:

name - Property

Returns:

Java BigInteger

See Also:

• JSONObjectWriter.setBigDecimal(String, BigDecimal)

getBigInteger

public BigInteger getBigInteger(String name)

Read a BigInteger property.

Note: Since JSON does not support a native BigInteger type, this method builds on mapping.

Parameters:

name - Property

Returns:

Java BigInteger

See Also:

• JSONObjectWriter.setBigInteger(String, BigInteger)

getJSONArrayReader

public JSONArrayReader getJSONArrayReader()

Get root array reader.

If the outermost part of the JSON structure is an array, this method must be called immediately after parsing in order to process the structure.

Returns:

Array reader if array else null

See Also:

• JSONArrayWriter()

getIfNULL

public boolean getIfNULL(String name)

Conditionally read a JSON null property.

Note: Only if the property contains a null the property is marked as "read".

Parameters:

name - Property

Returns:

true if null was found, else false

See Also:

• checkForUnread()

getObject

public JSONObjectReader getObject(String name)

Read a JSON object property.

Parameters:

name - Property

Returns:

Object reader

getArray

public JSONArrayReader getArray(String name)

Read a JSON array property.

Parameters:

name - Property

Returns:

Array reader

getStringConditional

public String getStringConditional(String name)

Conditionally read a JSON string property.
Note: This method is equivalent to getStringConditional(name, null).

Parameters:

name - Property

Returns:

The String if available else null

getStringConditional

public String getStringConditional(String name,
 String defaultValue)

Conditionally read a JSON string property.

Parameters:

name - Property

defaultValue - Default value including possibly null

Returns:

The String if available else defaultValue

getBooleanConditional

public boolean getBooleanConditional(String name)

Conditionally read a JSON boolean property.

Parameters:

name - Property

Returns:

The boolean if available else false

getBooleanConditional

public boolean getBooleanConditional(String name,
 boolean defaultValue)

Conditionally read a JSON boolean property.

Parameters:

name - Property

defaultValue - Default value

Returns:

The boolean if available else defaultValue

getStringArrayConditional

public String[] getStringArrayConditional(String name)

Conditionally read an array of JSON strings.

Parameters:

name - Property

Returns:

Array of String or null if property is not present

getStringArray

public String[] getStringArray(String name)

Read an array of JSON strings.

Parameters:

name - Property

Returns:

Array of String

getBinaryArray

public ArrayList<byte[]> getBinaryArray(String name)

Read an array of base64url encoded JSON strings.

Parameters:

name - Property

Returns:

ArrayList holding arrays of bytes

getProperties

public String[] getProperties()

Get JSON properties.

Returns:

All properties of the current object

hasProperty

public boolean hasProperty(String name)

Test if a property is present.

Parameters:

name - Property

Returns:

true if object is present, else false

See Also:

• getPropertyType(String)

getPropertyType

public JSONTypes getPropertyType(String name)

Get the native JSON type of a property.

Parameters:

name - Property

Returns:

JSON type

See Also:

• JSONTypes
• hasProperty(String)

getSignature

public JSONSignatureDecoder getSignature(JSONCryptoHelper.Options options)

Read and decode a JSF signature object.

Parameters:

options - Allowed/expected options

Returns:

An object which can be used to verify keys etc.

See Also:

• JSONObjectWriter.setSignature(JSONSigner)
• JSONCryptoHelper.Options

getSignature

public JSONSignatureDecoder getSignature(String signatureLabel,
 JSONCryptoHelper.Options options)

getMultiSignature

public ArrayList<JSONSignatureDecoder> getMultiSignature(JSONCryptoHelper.Options options)

Read and decode a JSF multi-signature object.

Parameters:

options - Allowed/expected options

Returns:

List with signature objects

getMultiSignature

public ArrayList<JSONSignatureDecoder> getMultiSignature(String signatureLabel,
 JSONCryptoHelper.Options options)

getSignatureChain

public ArrayList<JSONSignatureDecoder> getSignatureChain(JSONCryptoHelper.Options options)

Read and decode a JSF chained-signature object.

Parameters:

options - Allowed/expected options

Returns:

List with signature objects

getSignatureChain

public ArrayList<JSONSignatureDecoder> getSignatureChain(String signatureLabel,
 JSONCryptoHelper.Options options)

getPublicKey

public PublicKey getPublicKey(AlgorithmPreferences algorithmPreferences)

Read and decode a public key in JSF (JWK) format.

Parameters:

algorithmPreferences - JOSE or SKS notation expected

Returns:

Java PublicKey

See Also:

• JSONObjectWriter.setPublicKey(PublicKey)

getPublicKey

public PublicKey getPublicKey()

Read and decode a public key in JSF (JWK) format. This method is equivalent to getPublicKey(AlgorithmPreferences.JOSE).

Returns:

Java PublicKey

See Also:

• JSONObjectWriter.setPublicKey(PublicKey)

getCorePublicKey

public PublicKey getCorePublicKey(AlgorithmPreferences algorithmPreferences)

Read and decode a public key in JSF (JWK) format. Note: this method assumes that the current object only holds the actual public key structure (no property).

Parameters:

algorithmPreferences - JOSE or SKS notation expected

Returns:

Java PublicKey

See Also:

• JSONObjectWriter.createCorePublicKey(PublicKey,AlgorithmPreferences)

getKeyPair

public KeyPair getKeyPair(AlgorithmPreferences algorithmPreferences)

Read a public and private key in JWK format.

Note: this method assumes that the current object only holds a JWK key structure.

Parameters:

algorithmPreferences - JOSE or SKS notation expected

Returns:

Java KeyPair

getKeyPair

public KeyPair getKeyPair()

Read a public and private key in JWK format.

Note: this method assumes that the current object only holds a JWK key structure.

This method is equivalent to getKeyPair(AlgorithmPreferences.JOSE).

Returns:

Java KeyPair

getEncryptionObject

public JSONDecryptionDecoder getEncryptionObject(JSONCryptoHelper.Options options)

Read an object in JEF format.

Note: this method assumes that the current object only holds a JEF structure.

Parameters:

options - Restrictions and requirements

Returns:

An object which can be used to retrieve the original (unencrypted) data

See Also:

• JSONObjectWriter.createEncryptionObject(byte[],ContentEncryptionAlgorithms,JSONEncrypter)
• JSONCryptoHelper.Options

getEncryptionObjects

public ArrayList<JSONDecryptionDecoder> getEncryptionObjects(JSONCryptoHelper.Options options)

Read an object in JEF format intended for multiple recipients.

Note: this method assumes that the current object only holds a JEF structure.

Parameters:

options - Global restrictions and requirements

Returns:

An object which can be used to retrieve the original (unencrypted) data

See Also:

• JSONObjectWriter.createEncryptionObject(byte[],ContentEncryptionAlgorithms,JSONEncrypter)
• JSONCryptoHelper.Options

getCertificatePath

public X509Certificate[] getCertificatePath()

Read a certificate path in JSF format.

The array elements (base64url encoded certificates), must be supplied in strict issuance order where certificate[i] is signed by certificate[i + 1].

Returns:

Certificate path

See Also:

• JSONObjectWriter.setCertificatePath(X509Certificate[])

scanAway

public JSONObjectReader scanAway(String name)

Scan a property. This method scans a property regardless of its type and it useful for dealing with data where the type is unknown. It also marks the property as "read" including possible child objects and arrays.

Parameters:

name - Property

Returns:

Current instance of JSONObjectReader

See Also:

• checkForUnread()
• getPropertyType(String)
• getProperties()

removeProperty

public JSONObjectReader removeProperty(String name)

Remove a property.

Parameters:

name - Property

Returns:

Current instance of JSONObjectReader

serializeToBytes

public byte[] serializeToBytes(JSONOutputFormats outputFormat)

Serialize object reader to a Java byte[].

Parameters:

outputFormat - Any JSONOutputFormats

Returns:

JSON string data

serializeToString

public String serializeToString(JSONOutputFormats outputFormat)

Serialize object reader to a Java String.

Parameters:

outputFormat - Any JSONOutputFormats

Returns:

JSON string data

clone

public JSONObjectReader clone()

Deep copy of JSON object reader.

Overrides:

clone in class Object

toString

public String toString()

Pretty print JSON of object reader.

Overrides:

toString in class Object