~~Title: Documentation: Structured Data Objects~~

<html><font color=#990000 size="+2"><b>Structured Data Objects</b></font></html>

This allows the application fabric to exchange structured data (not objects) between applications in a language-neutral fashion without sacrificing performance or usability.  Serial form objects are typically used ‘at the edge’, in the so-called last mile of communications between the fabric and the client application.

For example, Web Applications may define and use Structured Data Objects (SDO) to exchange information between themselves and application services hosted in the runtime.  They may also execute DSQL queries directly by using a JSON formatted SQLQuery objects and receive back JSON formatted RowSet results. Alternatively Web Applications may simply subscribe to JSON or XML streams of structured data.

\\

====Semantic Types====

Object definition in the application fabric uses a least-common denominator approach.  SDO are modeled as Java objects, allowing users full inspection, modification and replication of objects and their definitions across the SYSPLEX.  An SDO is essentially a Java class that may be aliased under different names within the application fabric, allowing for context sensitive data definitions to be implemented.  

Objects are aliased as Semantic Types with complex objects themselves potentially being comprised of different 
Type Definition
Defining semantic type aliases every time you need to use them for serialization can be an extremely involved procedure requiring a lot of additional coding.  Furthermore, as the number of semantic types within the sysplex increases, maintenance and synchronization of types cross the application fabric may quickly overwhelm developers.  To address this issue the service engine provides facilities for declaring persistent Semantic Type definitions and replicating such definitions automatically, reducing administrative overhead and ensuring that all fabric nodes in a sysplex have the appropriate definitions.  This further simplifies data serialization.

====Type Validators====
explain basics..


d
====Creating Data Objects====

The following syntax allow user to define new data objects and specify the namespace and archive they will be stored in.
Arhives are standard Java Archives (JAR) files that may be insspected with regular toools and will conatain the compiled
versions of the data object classes, auto-generated validator classes that are created when element validation rules are
specified, as well as the Java source for all the classes.  

Data Object libraries can be used independent of the StreamScape runtime by any Java application.  However, within the 
datra engine they are registered and replicated across the entire sysplx and may be serialized on-the-fly into binary,
XML or JSON format, used as Collection data types, API data structures or Event payload data objects.

<sxh dsql; gutter: false;>
  CREATE { DATA OBJECT | SDO } <ObjectName>
  [/** Comments and Tags */]
  (
   [LIST(] {INT | LONG | DOUBLE | BIGDECIMAL | STRING | DATE | SQL_DATE | SQL_TIMESTAMP  
       |   <SemanticType>}[)] <Element Name> 
    [= <Value> | (<value1>,... ) | '<Value>' | ('<value1>',... ) ] 
    [NOT NULL] [LENGTH <length>]
    [[VALUE] IN DOMAIN {<Domain Name> | (<value1>,... )}]
    [[VALUE] IN RANGE {<Range Name> | (<low_value> <high_value>,... )}]
    [[VALUE] MATCHES (<Regular Expression>)]
    [DESCRIPTION '<description>'],...,

    [LIST(]BINARY)[)] <Element Name> [= '0x1234'] [NOT NULL] [LENGTH <length>]   
    [DESCRIPTION '<description>'],...,

    MAP( {INT | LONG | DOUBLE | BIGDECIMAL | STRING | DATE | SQL_DATE | SQL_TIMESTAMP},
        {INT | LONG | DOUBLE | BIGDECIMAL | STRING | DATE | SQL_DATE | SQL_TIMESTAMP |  
          BINARY | <SemanticType>} ) <Element Name> [NOT NULL] 
    [DESCRIPTION '<description>'],...
  )
  [{NAMESPACE: | NS:} <Class Name space such as a Package or Assembly>]
  {ADD | REPLACE} ARCHIVE: <Archive Name>
  {ADD | REPLACE} PACKAGE: <Package Name>
  [ANCESTOR <SemanticType>]
  [INTERFACE {TRUE | FALSE}]
  [DESCRIPTION '<description>']
  [NO SOURCE]
  [NO TYPE]
  [NO DOC]
</sxh>


then..
===What happens internally===

By default command performs the following actions
-	Creates and compiles SDO and SDO Validator objects. 
SDO object class name: <namespace>.<ObjectName>.class. 
Validator object class name: <namespace>.validator.<ObjectName>.class. 
-	Puts SDO and Validator classes to archive with specified name
-	Adds archive to specified package
-	Creates semantic type with name equals to SDO name
-	Puts EDL statement in archive in <namespace>/edl/<ObjectName>.edl
-	Creates SDO and Validator java source codes and puts it in archive in <namespace>.<ObjectName>.java
-	Create SDO html doc and puts it in archive in <namespace>/html/<ObjectName>.edl


===Data Object Management===

SDO objects can be created/removed/modified in SLANG with command ‘create sdo’/’drop sdo’/’alter sdo’ commands.

SDO creation
Command syntax:

<sxh dsql; gutter: false;>

CREATE {DATA OBJECT | SDO} <ObjectName>
[/** Comments and Tags */]
(
 [LIST(] {INT | LONG | DOUBLE | BIGDECIMAL | STRING | DATE | SQL_DATE | SQL_TIMESTAMP  
     |   <SemanticType>}[)] <Element Name> 
  [= <Value> | (<value1>,... ) | '<Value>' | ('<value1>',... ) ] 
  [NOT NULL] [LENGTH <length>]
  
  [[VALUE] IN DOMAIN {  Domain Name> | (value1,... )}]
  
  [[VALUE] IN RANGE {<Range Name> | (<low_value> <high_value>,... )}]
  [[VALUE] MATCHES (<Regular Expression>)]
  [DESCRIPTION '<description>'],...,

  [LIST(]BINARY)[)] <Element Name> [= '0x1234'] [NOT NULL] [LENGTH <length>]   
  [DESCRIPTION '<description>'],...,
  
  MAP({INT | LONG | DOUBLE | BIGDECIMAL | STRING | DATE | SQL_DATE | SQL_TIMESTAMP},
      {INT | LONG | DOUBLE | BIGDECIMAL | STRING | DATE | SQL_DATE | SQL_TIMESTAMP |  
        BINARY | <SemanticType>}) <Element Name> [NOT NULL] 
  [DESCRIPTION '<description>'],...
)
[{NAMESPACE: | NS:} <Class Name space such as a Package or Assembly>]
{ADD | REPLACE} ARCHIVE: <Archive Name>
{ADD | REPLACE} PACKAGE: <Package Name>
[ANCESTOR <SemanticType>]
[INTERFACE {TRUE | FALSE}]
[DESCRIPTION '<description>']
[NO SOURCE]
[NO TYPE]
[NO DOC]
</sxh>

By default command performs the following actions
-	Creates and compiles SDO and SDO Validator objects. 
SDO object class name: <namespace>.<ObjectName>.class. 
Validator object class name: <namespace>.validator.<ObjectName>.class. 
-	Puts SDO and Validator classes to archive with specified name
-	Adds archive to specified package
-	Creates semantic type with name equals to SDO name
-	Puts EDL statement in archive in <namespace>/edl/<ObjectName>.edl
-	Creates SDO and Validator java source codes and puts it in archive in <namespace>.<ObjectName>.java
-	Create SDO html doc and puts it in archive in <namespace>/html/<ObjectName>.edl

Command parameters
Parameter	Required	Description
ObjectName	x	SDO object name
NAMESPACE	x	SDO class namespace
ADD ARCHIVE <archive name>	x	Add SDO object class to specified archive and throw exception if SDO already exists in specified archive
REPLACE ARCHIVE <archive name>	x	Add or replace SDO object class to specified archive
ADD PACKAGE <package name>	x	Add archive to specified package or throw exception if specified package already contains specified archive
REPLACE PACKAGE <archive name>	x	Add or replace archive to specified package
ANCESTOR <SemanticType>		Ancestor of semantic type that corresponds to  SDO.
INTERFACE {TRUE | FALSE}		Is created semantic type interface or not.
DESCRIPTION ‘<description>’		Semantic type description
NO SOURCE		Don’t generate source code
NO TYPE		Don’t generate semantic type
NO DOC		Don’t generate html documentation


Supported data types

Syntax type	Java type
INT	java.lang.Integer
LONG	java.lang.Long
DOUBLE	java.lang.Double
BIGDECIMAL	java.math.BigDecimal
STRING	java.lang.String
DATE	java.util.Date
SQL_DATE	java.sql.Date
SQL_TIMESTAMP	java.sql.Timestamp
BINARY	byte[]
SemanticType	Java class that corresponds to specified semantic type
LIST(<some simple type>)	java.util.ArrayList
MAP(<some simple type>, <some simple type>)	java.util.Map

===Filed Parameters===


Field parameters

Parameter	Description
<Element Name>	Field name
= <Value> | (<value1>,... ) | '<Value>'| ('<value1>',... )	Default value, applicable for all types except MAP and SemanticType.
NOT NULL	Specifies that value should be not null
LENGTH <length>
	Specifies maximum field length. Applicable for LIST, BINARY and STRING types only
[VALUE] IN DOMAIN {<Domain Name> | (<value1>,... )}
	Specifies the domain for field values, named or values collection. Applicable for all types except BINARY and semantic type.
[VALUE] IN RANGE {<Range Name> | (<low_value> <high_value>,... )}
  	Specifies the range for field values, named or values collection. Applicable for all types except BINARY, STRING and semantic type.
[VALUE] MATCHES (<Regular Expression>)
 
	Specifies regular expression for field value. Applicable for all types except BINARY, MAP and semantic type.
DESCRIPTION '<description>'	Filed description, will be in generated SDO html doc.

Methods generated for fields with name ‘filedName’
-	void setFieldName(<field type> value);
-	<filed type> getFieldName();
Methods generated for LIST(<type>) type field with name ‘fieldName’
-	void addToFieldName(<type> value);
-	void addToFieldNameAt(int index, <type> value) throws IndexOutOfBoundsException;
-	void removeFromFieldName(<type> value);
-	void removeFromFieldNameAt(int index, <type> value) throws IndexOutOfBoundsException;
-	<type> getFieldNameAt(int index) throws IndexOutOfBoundsException;
-	boolean isEmptyFieldName();
-	Iterator iterateFieldName();

Methods generated for MAP(<keyType>, <valueType>) type field with name ‘fieldName’
-	<valueType> putToFieldName(<keyType> key, <valueType> value);
-	<valueType> getFromFieldName(<keyType> key);
-	<valueType> removeFromFieldName(<keyType> key);

Examples:

<sxh dsql; gutter: false;>

create sdo Employee 
/**
*	<p>Employee object<p>
*	@author Nik
*	@version 1.1
*	@see {@link www.streamscape.com}
*/
(
	STRING firstname = '' NOT NULL DESCRIPTION 'Employee first name',
	STRING lastname,
	STRING sex IN DOMAIN ('MALE', 'FEMALE'),
	INT    age IN RANGE (20 45),
	SQL_DATE hiredate
)
NAMESPACE: com.employee
REPLACE ARCHIVE: employee
REPLACE PACKAGE: employee
DESCRIPTION 'Employee object'; 

create sdo Employees
/**
*	<p>List of <code>{@link Employee}</code> objects<p>
*	@author Nik
*	@version 1.1
*	@see {@link www.streamscape.com} {@link Employee}
*/
(
	LIST(Employee) employees NOT NULL DESCRIPTION 'Employee list'
)
NAMESPACE: com.employee
REPLACE ARCHIVE: employee
REPLACE PACKAGE: employee
DESCRIPTION 'Employees object'; 

SDO removal
Operation syntax
DROP {DATA OBJECT | SDO} <ObjectName>
[{NAMESPACE: | NS:} <Class Name space such as a Package or Assembly>]
[ARCHIVE: <ArchiveName>]
[CLEAN]

</sxh>

Command performs the following actions
-	Searching for semantic type with name <ObjectName> and gets SDO full class name.
o	If semantic type doesn’t operation suggests specify SDO namespace in statement and that SDO full class name will be <namespace>.<ObjectName>
-	Searching for archive that contain SDO class
o	If there are more than one archive is found, suggests to specify archive name in operation statement
-	Drops semantic type if it exists
-	Drops SDO and Validator classes and source codes, edl files and doc files from archive
-	Drops archive if it doesn’t contain more classes and remove archive from packages.
o	If CLEAN parameter specified drops packages if they don’t contain more archives




Command parameters
Parameter	Required	Description
ObjectName	x	SDO object name
{NAMESPACE: | NS:} <namespace>		SDO class namespace if semantic type doesn’t exist
ARCHIVE: <ArchiveName>		SDO class archive if there are more than one archive in the lib
CLEAN		Drops packages if they don’t contain more archives


Examples
	DROP SDO Employees;
DROP SDO Employee
		NAMESPACE: com.employee
		ARCHIVE: employee.jar
		CLEAN;

SDO modification
Operation syntax

ALTER {DATA OBJECT | SDO} <ObjectName>
[/** Comments and Tags */]
(
	EDL BODY SYNTAX LIKE IN CREATE SDO OPERATION
)
[{NAMESPACE: | NS:} <Class Name space such as a Package or Assembly>]
[ARCHIVE: <ArchiveName>]
[NO SOURCE]
[NO DOC]

By default operation performs the following actions
-	Searching for semantic type with name <ObjectName> and gets SDO full class name
o	If semantic type not found suggests specify namespace, than SDO full class name is <namespace>.<ObjectName>
-	Searching for archive with SDO
o	If archives more than one suggest specify archive name
-	Generates SDO and Validator classes, documentation and source codes and updates it in archive

Command parameters
Parameter	Required	Description
ObjectName	x	SDO object name
{NAMESPACE: | NS:} <namespace>		SDO class namespace if semantic type doesn’t exist
ARCHIVE: <ArchiveName>		SDO class archive if there are more than one archive in the lib
NO SOURCE		Don’t generate source codes or remove if exist
NO DOC		Don’t generate html documentation or remove if exist

Examples
	alter sdo Employee 
/**
*	<p>Altered employee object<p>
*	@author Nik
*	@version 1.1
*	@see {@link www.streamscape.com}
*/
(
	STRING firstname = '' NOT NULL DESCRIPTION 'Employee first name',
	STRING lastname,
	STRING address LENGTH 100, 
	STRING sex IN DOMAIN ('MALE', 'FEMALE'),
	INT    age IN RANGE (20 45),
	SQL_DATE hiredate
); 


SDO validation
SDO validation class should implements Validator interface and located in class <sdo package>.validator.<sdo name>. 
To validate SDO you need to use Validator.validate(Object) method.

ValidationFactory class manages all validators available in runtime. 
To find validator you need to use the following methods
-	lookupValidatorFor(String semanticTypeName)
-	lookupValidatorFor(Stirng className)



===Creating Enumerations===
xxx

===Creating Choice Elements===
xxx

===Altering Data Objects===

<sxh dsql>
  ALTER {DATA OBJECT | SDO} <ObjectName>
  [/** Comments and Tags */]
  (
          EDL BODY SYNTAX LIKE IN CREATE SDO OPERATION
  )
  [{NAMESPACE: | NS:} <Class Name space such as a Package or Assembly>]
  [ARCHIVE: <ArchiveName>]
  [NO SOURCE]
  [NO DOC]
</sxh>

===Dropping Data Objects===

<code>
DROP {DATA OBJECT | SDO} <ObjectName>
[{NAMESPACE: | NS:} <Class Name space such as a Package or Assembly>]
[ARCHIVE: <ArchiveName>]
[CLEAN]
</code>

Command performs the following actions
-	Searching for semantic type with name <ObjectName> and gets SDO full class name.
o	If semantic type doesn’t operation suggests specify SDO namespace in statement and that SDO full class name will be <namespace>.<ObjectName>
-	Searching for archive that contain SDO class
o	If there are more than one archive is found, suggests to specify archive name in operation statement
-	Drops semantic type if it exists
-	Drops SDO and Validator classes and source codes, edl files and doc files from archive
-	Drops archive if it doesn’t contain more classes and remove archive from packages.
o	If CLEAN parameter specified drops packages if they don’t contain more archives

===Serializing to/from XML===
xxx

===Serializing to/from JSON===
xxx

\\

