Data Types/Structures in DivConq

DivConq Framework’s Schema and Structures

Linux Box
Windows
Java App w/ DivConq MUMPS
User w/
Web Browser MUMPS
Your Process
DivConq
Application
Database
Code MUMPS
Interface
External Process
App on
DivConq MUMPS
Linux
Web Server DivConq Schema Process
(HTTP + Web
Sockets)

There are many reasons to “why JSON?” – one of the best is interoperability with
web apps and other external applications. Through HTTP or WebSocket calls
JSON parameters can be sent and JSON results can be returned. To minimize
interoperability hassles DivConq favors JSON-like structures throughout.

Java App w/ DivConq

dcDB

dcRPC
dcSchema
Your
Application dcScripts
(“JSON”
Code
dcServiceBus Validation)

dcWeb

Many of the features of the framework use DivConq Schema to validate data
structures. When you learn how to use these structures you can use these
features. dcDB, dcWeb and dcServiceBus are especially important for most
developers using the framework.

JSON.org Term DivConq Term DivConq Class
Object Record RecordStruct
Array List ListStruct
Value Scalar ScalarStruct

(also)
Pair Field FieldStruct
Members Fields
Elements Items

Although DivConq uses different terms, it matches up with JSON very well (see
www.json.org).

JSON.org Type DivConq Name DivConq Class
String String StringStruct
Number Integer IntegerStruct (64 bit)
" BigInteger BigIntegerStruct (unlimited)
" Decimal DecimalStruct (unlimited)
" BigDecimal "
true Boolean BooleanStruct
false " "
null Null NullStruct
- Any AnyStruct
- Binary BinaryStruct
- DateTime DateTimeStruct
- BigDateTime BigDateTimeStruct

DivConq supports the same value types, plus a few more. JSON to DivConq
conversions are simple. String becomes string, number tries to fit into Integer or
BigInteger, but otherwise falls to Decimal. A true or false becomes a Boolean. A
null becomes a “null” in Java (though NullStruct could be used instead).

DivConq Name DivConq Class
Binary BinaryStruct
DateTime DateTimeStruct
BigDateTime BigDateTimeStruct

Converting from DivConq to JSON is fairly obvious for most of the types, except
those above.

Binary in DivConq is byte array data and JSON does not support byte arrays. So
when Binary is converted to JSON it becomes a base64 encoded string.

DateTime is also not in JSON (there are some adaptations though). When
DateTime is converted to JSON it becomes an ISO 8601 formatted string using
UTC (Z) timezone.

BigDateTime is a topic on to itself, it supports dates billions of years past and
future. The very short summary, format is: ‘t’YYYYYYYYYYYMMDDhhmmss

Classes for JSON-Like structures

Example

RecordStruct params = new RecordStruct();
params.setField("MinAge", 3);
params.setField("MaxAge", 8);

QueryRequest request = new QueryRequest("dctListPeople", params);

When working with the DivConq Struct classes we usually have a goal in mind.
In the example above we mean to create some parameters for a database query
request.

However, in the following examples we’ll create structures just for the sake of
learning, without the context of how they are used. Look for presentations on the
dcDb or dcServiceBus for specific examples of how Structs are used.

JSON
{ "Code": 5, "Message": "Problem with coolant system." }

Java
RecordStruct ex1 = new RecordStruct();
ex1.setField("Code", 5);
ex1.setField("Message", "Problem with coolant system.");

Scalar types are automatically inferred from java native types. When setting the
Code field above, 5 becomes an IntegerStruct and the message string becomes a
StringStruct.

JSON
{ "Code": 5, "Message": "Problem with coolant system." }

Java
ex1.setField("Code", new IntegerScalar(5));
ex1.setField("Message", new StringScalar("Problem with coolant system."));

You can be explicit, as above, but most of the time there is no need.

OK, you made a record – and presumably passed it to a service (or other
feature). How does that service access the data in the record?

Before answering, keep in mind the service may run in the same JVM as the
caller, or another JVM on running on a computer a thousand miles away. Either
way, DivConq is capable of delivering the data (as it was assembled in the last
side) if you use the built-in data types (except Any which has special handling).
There are no additional requirements or efforts for serialization.

RecordStruct ex1 = [as delivered to the service]

System.out.println("Code: " + ex1.getFieldAsString("Code"));

long code = ex1.getFieldAsInteger("Code");

System.out.println("Code Is Priority Level: " + (code < 3));

So back to the question – how do you access data? The answer – the way you
want it. As seen in the example above, you can access the field Code either as a
String or as an Integer. RecordStruct will attempt to return a value in the data
type you request, if it cannot then it returns null.

JSON
{ "Code": "5", "Message": "Problem with coolant system." }

Java
ex1.setField("Code", "5");

Note that in this example, the field Code contains a string not a number. But the
service’s code “long code = ex1.getFieldAsInteger("Code");” will still work. Again,
all the getFieldAs* methods attempt to deliver the data the way you need it,
regardless of the original type.

public Long getFieldAsInteger(String name)
public BigInteger getFieldAsBigInteger(String name)
public BigDecimal getFieldAsDecimal(String name)
public Boolean getFieldAsBoolean(String name)
public DateTime getFieldAsDateTime(String name)
public BigDateTime getFieldAsBigDateTime(String name)
public LocalDate getFieldAsDate(String name)
public LocalTime getFieldAsTime(String name)
public String getFieldAsString(String name)
public Memory getFieldAsBinary(String name)
public RecordStruct getFieldAsRecord(String name)
public ListStruct getFieldAsList(String name)
public CompositeStruct getFieldAsComposite(String name)
public Struct getFieldAsStruct(String name)
public XElement getFieldAsXml(String name)

These are the primary ways of accessing field values.

public boolean isEmpty()
- are there no fields in this record
public Iterable<FieldStruct> getFields()
- loop all fields
public int getFieldCount()
- get number of fields
public Struct getField(String name)
- get the Struct for the field (e.g. StringStruct)
public Object getFieldAsAny(String name)
- return the value, no mater what type it is
public boolean hasField(String name)
- check if field is present
public boolean isFieldEmpty(String name)
- check that field is not null, if field is a string also check
that it contains something other than whitespace

These methods also help with data access.

JSON
[ 0, 20, 50, 90, 140 ]

Java
ListStruct ex2 = new ListStruct();
ex2.addItem(0);
ex2.addItem(20);
ex2.addItem(50);
ex2.addItem(90);
ex2.addItem(140);

One way to make a list.

for (int i = 0; i < ex2.getSize(); i++) {
long code = ex2.getItemAsInteger(i);

System.out.println("Code " + code
+ " is priority level: " + (code < 73));
}

Just like the “getFieldAs” methods, there is a “getItemAs” method for all the types
recognized by DivConq.

JSON
[
{
"Code": 5,
"Message": "Problem with coolant system."
},
{
"Code": 53,
"Message": “Fan blade nicked."
}
]

We can combine list and records – a field of one record can hold a list or a record
for the value just like JSON. An item in a list may be a scalar or it may be another
list or a record. This example is a list of records.

Java (DivConq)
ListStruct ex3 = new ListStruct();

RecordStruct m1 = new RecordStruct();
m1.setField("Code", 5);
m1.setField("Message", "Problem with coolant system.");

ex3.addItem(m1);

RecordStruct m2 = new RecordStruct();
m2.setField("Code", 53);
m2.setField("Message", "Fan blade nicked.");

ex3.addItem(m2);

The equivalent in DivConq.

for (int i = 0; i < ex3.getSize(); i++) {
RecordStruct msg = ex3.getItemAsRecord(i);

System.out.println("Message #" + i);

System.out.println(" Code: " +
msg.getFieldAsString("Code"));

System.out.println(" Text: " +
msg.getFieldAsString("Message"));
}

Use the getItemAsRecord method to access the record.

Example 1
ListStruct ex2 = new ListStruct(0, 20, 50, 90, 140);

Example 2
ListStruct ex3 = new ListStruct(
new RecordStruct(
new FieldStruct("Code", 5),
new FieldStruct("Message", "Problem with coolant system.")
),
new RecordStruct(
new FieldStruct("Message", "Fan blade nicked.")
)
);

To make it easier to compose a complex structure, you can pass values right into
the constructor of ListStruct and RecordStruct.

Structure declaration and data validation

The code you have seen so far all works. Your application is not required to have
a declaration for all (or any) of your JSON-Like data structures you plan to use.
But it sure can help to have a shared reference for a data structure, especially if
you plan on exposing the data via a service (some services are also available as
web services).

The schema file is where you declare the structures you want to validate and
share. When building your application you’ll need your own schema file – more
importantly you’ll need your own package folder. These examples are part of the
“dcTest” package. If you are following along in the code, look in the dcTest
package.

You may find the schema file here:

divconq/template/packages/dcTest/all/schema

<Schema>
... Ignore Database and other elements, look for

<Shared>
<Record Id="Schema1Ex1">
<Field Name="Code" Type="Integer" />
<Field Name="Message" Type="String" />
</Record>
</Shared>

...
</Schema>

Shared is the element within Schema where you’ll put many of your structure
definitions. It is the common denominator, types defined here may be used by
stored procedures or services.

<Field Name="Code" Type="Integer" />
</Record>

Within the Shared element expect to see either List or Record elements. The
children of Shared will all have an Id attribute, this is the name by which the
structure is known within Java code.

Within a Record element expect to see a list of Field elements, each with a Type
attribute or a child Record or List element.

Before looking at some of the options, lets consider a simple validation.


System.out.println(ex1.validate("Schema1Ex1").toString());

Build a record and then validate by calling “validate” method and use the name of
the data type. Validate returns info about the success of the validation, a quick
way to see the results is to use “toString” to print all the validation messages.

ex1.setField("Code", "5");


Back to the case where “Code” is a string. This will work because the validation
methods check to see if the data can be accessed as the validating type – in this
case AsInteger. Since it can be accessed that way then all is fine.

ex1.setField("Code", "abc");


However, in this case AsInteger returns null. The schema demands that this field
be accessible as an Integer, since it is not, an error is returned.



Code is not marked as a required field in the Schema, so the above will pass
even though no Code field is present.

Schema
<Field Name="Code" Type="Integer" Required="True" />
</Record>

Java


Adding the Required attribute makes the field required. Now we get an error
message when we validate. Note the new schema Id – using “Ex2” not “Ex1”.



And now it validates without messages.

Schema
--- common examples ---

<List Id="str" Type="String" />

<List Id="int" Type="Integer" />

--- but lets consider ---

</Record>

<List Id="Schema1Ex3" Type="Schema1Ex2" />

Schema
--- could also be written as ---

<List Id="Schema1Ex3">
<Record>
</Record>
</List>

new RecordStruct(
),
new RecordStruct(
new FieldStruct("Message", "Fan belt cracked.")
),
new RecordStruct(
),
new RecordStruct(
new FieldStruct("Code", "abc"),
new FieldStruct("Message", "Fan bearing worn.")
)
);


The second and fourth records will fail the validation.

new RecordStruct(
),
new RecordStruct(
new FieldStruct("Message", "Fan belt cracked.")
),
new RecordStruct(
),
new RecordStruct(
new FieldStruct("Message", "Fan bearing worn.")
)
);


<StringType Id="ResultLevel">
<StringRestriction Enum="Error,Warn,Info,Exit" />
</StringType>

<Field Name="Level" Type="ResultLevel" />
</Record>

------------------
ex1.setField("Level", "Warn");


With StringType element (child of Shared like Record and List) you can create an
enumeration. In Schema1Ex4 we use that enum for the field Level.

<StringType Id="dcSmallString">
<StringRestriction MaxLength="250" />
</StringType>

<Field Name="Level" Type="ResultLevel" />
<Field Name="Message" Type="dcSmallString" />
</Record>

A StringType element may also have a max or min length. In Schema1Ex5 we
updated the Message field to have a max of 250 characters.

<StringType Id="dcHubId">
<StringRestriction Pattern="d{5}" />
</StringType>

<StringType Id="BigDateTime">
<StringRestriction Pattern="td{11,21}" />
</StringType>

<StringType Id="Id">
<StringRestriction Pattern="d{5}_d{15}" />
</StringType>

A StringType element may also have a pattern restriction. Above, the first must
be 5 digits (e.g. “00202”), the second must be a “t” literal followed by 11 to 21
digits, the third must be 5 digits followed by a “_” literal followed by 15 digits.

dcSchema is powerful, yet reasonably simple, way to validate JSON-Like data
structures in DivConq. Tables, stored procedures, services, scripts and many
other DivConq features rely on the schema for validation of parameters and
return values.

Data Types/Structures in DivConq

More Related Content

What's hot (18)

Similar to Data Types/Structures in DivConq (20)

Recently uploaded (20)

Data Types/Structures in DivConq