PROPERTIES AND METHODS OF STRUCTURED DATA OBJECT
Web Services
|
PROPERTIES AND METHODS OF STRUCTURED DATA OBJECT |
Web Services |
|
The StructuredDataObject SSO defines an arbitrarily complex object holding primitives (strings and numbers), objects and arrays in any configuration and to any depth. At the simplest level, it holds a collection of named primitive properties. At the top level, the properties can be held either as an object or as an array. An object holds its properties with names in no particular order. An array holds its properties by number not by name. The first property in the array is at number one and not at number zero.
Many of the methods in this SSO use a path parameter to reference properties. The path is a string that identifies the property required in the complex object. For example if a StructruedDataObject (SDO) has a proerty called 'Customer' that is an object and that object holds a property called 'FirstName' then the path to the 'FirstName property is 'Customer/FirstName' or '/Customer/FirstName' (the initial slash is optional). The slash character is used to indicate that the previous part of the path is an object that holds further properties. If the object is an array then the path to reference an array property uses square brackets to hold the array property index (For example, '/Customer/PhoneNumbers[1]' where PhoneNumbers is an array object.
When using a path parameter in any of the 'set' methods that put data in the StructuredDataObject; you can reference objects that don't yet exist as the StructuredDataObject will automatically create any objects or arrays that don't exist.
appendString(path, value) - Appends the string value supplied to the string property resolved from the path parameter. If the path does not resolve to an existing property then the property and all non-existing objects in its path are created and the value is set. If the path resolves to an existing property then that existing property value is appended with the new value. If the path is illegal then no change is made to this object and last error is set. If the path resolves to an existing property but its value is not a string then no change is made to this object and last error is set. If the maxSizeInBytes property has been set and this addition would exceed the setting then the last error is set, the path will not be created and the value not set.
clear(path) - Clears the property resolved from the path parameter. If the property resolved by the path is an object or an array then this method clears all the properties (or array elements) from the object. If the property is a string it is set to the empty string and if a number it is set to 0. If the path cannot be resolved then no change is made to this object and last error is set.
clearNameMap() - Clears all previously loaded name mapping properties for the StructuredDataObject.
clearErrorExceptions() - Removes all errors from the list that generate PROIV SDO Exceptions. After this method is called no PROIV SDO Exceptions are generated from this object.
clearLastError() - Clears all the errors from the last error stack.
delete(path) - Deletes the property resolved from the path parameter. If the path cannot be resolved then no change is made to this object and last error is set.
getCount(path) - Returns the number of properties at the level resolved from the path parameter. If the path cannot be resolved then zero is returned and last error is set. If the path resolves to a string with a length greater than 2000 bytes then the return value will be that of the number of 2000 byte elements (chunks) the string contains. For a number or a string that is not greater than 2000 bytes, the return value will be one.
getJSON(path) - Returns a JSON string that represents the contents of the property resolved from the path parameter, with data encoded in UTF-8. If the path cannot be resolved then the empty string is returned and last error is set. Note that if the string is less than 2000 characters then this method is the same as the getString method but if there are more than 2000 characters, these methods do not break the string into chunks.
getMappedName(String name) - Returns the mapped name for the name parameter. If there is no mapped name then the name parameter is returned unchanged.
getNames(path) - Returns an array object whose content is the names of the properties at the level resolved from the path parameter. If the path can not be resolved or the resolved property is not an object or an array, then an empty array is returned and last error is set.
getNumber(path) - Returns the number value of the property resolved from the path parameter. If the path cannot be resolved then zero is returned and last error is set. If the property is a string that cannot be converted to a number or the property is an object then zero is returned and last error is set.
getObject(path) - Returns the property resolved from the path parameter as a StructuredDataObject. If the path cannot be resolved then the empty object is returned and last error is set. If the property is a string or number then the returned object will have one property with the property name and the property value and last error is not set. Note that both arrays and objects are classed as objects by this method as they are both StructuredDataObjects.
getString(path) - Returns the string value of the property resolved from the path parameter. If the path cannot be resolved then the empty string is returned and last error is set. An object’s string value is its JSON string. If the JSON string representation is less than 2000 characters it will be returned, if it is greater than 2000 characters then the empty string will be returned and the last error property will be set with a suitable error code and message. The characters greater than 2000 can be accessed using this same method by appending the chunk index notation to the path supplied (getString(’path(n)’) where the chunk index is specified in braces at the end of the path string). The number of 2000 character elements (chunks) available can be ascertained using the getCount() method.
getType(path) - Returns the type string ("String", "Number", "Object", "Array" or "Not Found") for the property resolved from the path parameter. If the path cannot be resolved or is illegal the response will be "Not Found" and last error will not be set.
isArray(path) - Returns 1 if the object resolved from the path parameter is an array at the top level. It returns zero in all other situations (a numeric boolean).
lastError() - Returns the code for the last error which will be zero if there is no error. The error code is a number and this method allows the developer to use ‘if’ statements in their error handling code.
lastErrorMsg(number) - Returns a string describing the last ‘n’ errors. If there is no error this will be the empty string. If the number is more than 1 then that number of error strings will be returned separated by a Return code. The errors are returned in reverse order with the last error at the top. Note that the stack of errors has a maximum size of 100 so you cannot get more than the last 100 errors.
log(prefixString) - Writes this object to the log as a JSON string. This is a helper method so that the developer can see what has been built. To aid in identification of who has logged what, the optional prefix string parameter can be specified and this will prefix the log entry.
loadNameMap(String filepath) - Loads a name mapping properties file for this object. The filepath parameter should be an absolute path in the file system. If the file does not exist then the name mapping is not changed in this object. If there are any problems then last error is set. The name map is a Java properties file with one name per line and is used to change the names of properties in the object.
prettyWriteToFile(String filepath) - Writes this object to a file in JSON format in a human readable format. The filepath parameter should be an absolute path in the file system. If the file does not exist, it is created. If there are any problems then the last error is set.
readFromFile(String filepath) - Reads a JSON file into this object replacing any current contents of this object. The filepath parameter must be an absolute path in the file system. If the file does not exist, this object is not changed. If there are any problems then the last error is set.
setErrorExceptions(errorCodes, errorGroupCodes) - Defines which errors in this object should generate PROIV SDO Exceptions. The errorCodes parameter is a comma separated list of error codes that should generate exceptions. The errorGroupCodes parameter is comma separated list of error code groups that should generate exceptions (all error codes in a group will generate exceptions). Either parameter can be empty. A PROIV SDO Exception will cause a PROIV runtime error and roll back any database changes.
setIsArray(path, isArray) - Sets the object resolved from the path parameter to be an array at the top level if the isArray parameter is true and an object if isArray is false. If the path cannot be resolved or the resolved property is not an object or an array, then no change is made to this object and last error is set. If an object is converted from an object to an array by this method then all the top level properties will be renamed to be an array index and the order will be determined by an alphabetic sort of the names. If an object is converted from an array to an object by this method then the index of the top level properties becomes the property name.
sizeInBytes() - Returns the number of bytes that the will be required to store the UTF-8 encoded result that would be supplied by a call to the getJSON() method.
setString(path, value) - Sets the string value supplied to the string property resolved from the path parameter. If the path resolves to an existing property then that property value is replaced by the new value. If the path does not resolve to an existing property then the property and all non-existing objects in its path are created. If the path is illegal then no change is made to this object and last error is set. If the maxSizeInBytes property has been set and this addition would exceed the setting then the last error is set, the path will not be created and the value not set.
setLogFile(String filepath) - Defines a log file that is used by the log method and any errors in this object. The filepath parameter must be an absolute path in the file system. If the file does not exist, it is created. A startup message is written to the file. If there are any problems, then the last error is set.
setNumber(path, value) - Sets the number value supplied to the number property resolved from the path parameter. If the path resolves to an existing property then that property value is replaced by the new value. If the path does not resolve to an existing property then the property and all non-existing objects in its path are created. If the path is illegal then no change is made to this object and last error is set. If the maxSizeInBytes property has been set and this addition would exceed the setting then the last error is set, the path is not created and the value not set.
setObject(path, value) - Sets the object value supplied to the object property resolved from the path parameter (note that the value will be another StructuredDataObject SSO so it may be either an object or an array). If the path resolves to an existing property then that property value is replaced by the new value. If the path does not resolve to an existing property then the property and all non-existing objects in its path are created. If the path is illegal then no change is made to this object and last error is set. If the maxSizeInBytes property has been set and this addition would exceed the setting then the last error is set, the path is not created and the value not set.
setFromJSON(path, jsonString) - Sets a property resolved from the path parameter to the value defined by the decoded JSON string (this can be either an object or an array). If the path resolves to an existing property then that property value is replaced by the new decoded value. If the path does not resolve to an existing property then the property and all non-existing objects in its path are created. If the decode fails then the property will be set to an empty object and last error will be set. If the path is illegal then no change is made to this object and last error is set. If the maxSizeInBytes property has been set and this addition would exceed the setting then the last error is set, the path will not be created and the value not set.
writeToFile(String filepath) - Writes this object to a file in JSON format. The filepath parameter must be an absolute path in the file system. If the file does not exist, it is created. If there are any problems, then the last error is set.
Topic ID: 400032