RDD Resource Format

The RDD Resource Format is a resource and data storage format designed for simple and natural use. It is built around the circumflex (^) or hat as the escape character. Every escape sequence begins and ends with the hat. For example, to represent a line feed character, one would use the construct ^lf^. The escape sequence for the hat (^) itself is simply the hat doubled or ^^.  A general unicode character can be represented by ^NNNNN^ where NNNNN is the decimal value of the unicode character. Here is a list of some of the typical short hand escape sequences used in the RDD escape format.

• ^^ - The escaped version of ^
• ^lf^ - The escaped version of a line feed (ascii 10)
• ^sp^ - Space (ascii 32)
• ^hash^ - Hash (#)
• ^semi^ - Semicolon (;)
• ^colon^ - Colon (:)
• ^lparen^ - Left parenthesis (()
• ^rparen^ - Right parenthesis ())
• ^cr^ - Carriage return (ascii 13)
• ^tab^ - Tab (ascii 7)
• ^null^ - Null value (ascii 0)
• ^NNNNN^ - A unicode character with NNNNN being the decimal value

The hat is also used to declare the start of different types of data formats in a file. Here is a sample resource file with a name value pair and a table:

# This is a general comment and not attached to any field.

# This is an example name value pair, all space is trimmed around the key and the value. This
# comment is attached to this name value pair.
MyKey = An example value for MyKey

# This is an example table. All space is trimmed around the table name, column names and the row cell values.
# This comment is attached to this table declaration.
^table MyTable
Column1,         Column2
row1col1val,    row1col2val
row2col1val,    row2col2val
^end

In the example above, comments are started with a hash (#). Comments are retained when the file is parsed and attached to the name value pair or special data construct that they immediately precede up to the first line previous that is completely blank with only whitespace in it or is the end of another resource declaration. The hashes (#) are removed when the comment is parsed and put back in when the data is written back out. The idea is to allow a web interface to do focused editing on a particular resource declaration and maintain the general format of the file when it is written back out to persistent storage.

A table is declared by starting with ^table <NameOfTable> and ending with ^end. The first line of text after the ^table line is a comma separated list of column names. On the lines following that are the cell values of the table with the row values being comma separated and in the same order as the columns declared in the first line of table text.

All text in resource formats are trimmed. If you need an actual space value to precede or follow a string value, you can use the escape syntax ^sp^ for that space. This syntax does not allow for the natural use of line feeds in most of the resource formats (there is an exception for the full ^string declaration) so line feeds need to be escaped with ^lf^.

Resource declarations can have parameters applied to them. The parameters are formatted as name-value pairs using the equals symbol to assign a value and semicolon to separate values. The name-value pairs are put inside square brackets ([...]) immediately following the name of the resource.  The list of parameters supported are specific to the resource type. A complete list of such parameters is not available at this time because this feature is still under development. Two such parameters for the ^table resource are primaryKey and mergeBlanks. Here is an example.

# This table will use col1 as the column to merge against when the table is overlaid by another table and when it is used to overlay another table.
# If the primaryKey is not specified, then it defaults to the first column. The mergeBlanks means that any blank values will be merged into any
# table that this table overlays. Note that mergeBlanks is a boolean parameter and as such it is assumed to be true if no value for it is specified.
^table MyComplexMergingTable[primaryKey=rowName;mergeBlanks]
col1,  col2, rowName
 1.1,  1.2, row1
 2.1,  2.2, row2
^end

Preceding the name of a parameter by a tilde (~) will cause the value to be negated or removed from the parameter list when the resource is overlaid on another one.

The other often used resource format is the ^string declaration which looks like.

# An example error string. Note that {1} and {2} are standard substitution parameters for Java messaging syntax (though the substitution uses
# optimized custom code in the RDD library). The string name is preceded by a four letter acronym rdce which stands for Runtime Data Core Error. Generally
# different applications should create their own four letter acronym prefixes for all their resource names if the resource is meant to be specific
# to their application.
^string rdceExampleCoreErrorString
This is an expanded description of an error on a bad value {1} that occurred when doing {2}. The error
can have multiple lines so line feeds do not need to be escaped.
^end

If a hat (^) is followed by an unrecognized resource type, then it is assumed to be the name of a string and it begins a single line simple string format. The name has to be followed by an equals (=) before the value of the string is given. Here is an example:

# A short error string
^rdceBadParameter=The parameter {1} was bad.

Strings can also have parameters, much like table resources. For example, there is a parameter category which specifies what category the string falls into. You can also specify the language of the string by the lang parameter. An example would be:

# An example of a string that is categorized as being used for the web interface and is an English string (which is the default).
^rdcwTheHomeLink[category=web;lang=en]=This link takes you to the home web page

The usage of the category parameter is dependent on the actual application implementation and gets its greatest utility when trying to handle strings from separate component suites that have complex rules for when one string is preferred to another for the same basic lookup key.

This page is not a complete write up of all the supported resources. It is expected that the features supported by the RDD resource format will continue to grow over time and this page may not keep up with that growth.