svn commit: r1783338 - /felix/trunk/converter/schematizer/readme.txt

[dl...@apache.org]

Author: dleangen
Date: Fri Feb 17 07:44:31 2017
New Revision: 1783338

URL: http://svn.apache.org/viewvc?rev=1783338&view=rev
Log:
Introduction of README file to explain the objective of this experimental module

Signed-off-by: David Leangen <dl...@apache.org>

Added:
    felix/trunk/converter/schematizer/readme.txt   (with props)

Added: felix/trunk/converter/schematizer/readme.txt
URL: http://svn.apache.org/viewvc/felix/trunk/converter/schematizer/readme.txt?rev=1783338&view=auto
==============================================================================
--- felix/trunk/converter/schematizer/readme.txt (added)
+++ felix/trunk/converter/schematizer/readme.txt Fri Feb 17 07:44:31 2017
@@ -0,0 +1,71 @@
+# Apache Felix Converter - Schematizer module
+
+## Overview
+
+The Schematizer follows the concept of "DTO-as-Schema", meaning the idea that
+the DTO describes the data schema, and using this idea to make the schema a
+first-class citizen in the design and implementation of a domain model.
+
+## DTO-as-Schema
+
+DTO-as-Schema (DaS) takes a step away from common Object Oriented (OO) design principles.
+When learning OO programming, common convention was to "hide away" the data in 
+order to "protect" it from the wild. Instead of accessing a field directly, the
+idea was to make a field private, and provide "getters" and "setters". The getters
+and setters were supposed to ensure the invariants of the object. Often, however,
+we would end up with code like this:
+
+```java
+public class SomeClass {
+    private String value;
+
+    public String getValue() {
+        return value;
+    }
+
+    public void setValue( String aValue ) {
+        value = aValue;
+    }
+}
+```
+
+The above is really just a complicated and misleading way of doing this:
+
+```java
+public class SomeClass {
+    public String value;
+}
+```
+
+Even when OO-style classes are well written, it can be argued that the idea of data-hiding
+is a farce anyway when dealing with distributed systems. The reason is because the classes
+need to be serialized before they are put on the wire, and deserialzed again by the remote system.
+This requires exposing the system in the form of an "API", these days usually as a REST API.
+So, when the system is seen as a whole, we recognize that it is simply not possible to have
+a working complex system while "hiding" the core data.
+
+DaS is based on this admission. We admit that there are really *two* interfaces: 
+a *programmatic API* and a *data API*.
+
+In the [WHICH?] OSGi specification, DTOs were introduced as a convention for describing objects
+and transferring their state between system sub-parts. It so happens that the rules for DTOs
+describe a schema, in Java code, for the data objects being transferred. By taking advantage of this
+schema and elevating it as a first-class citizen during the design and implementation of domain
+objects, we can elegantly expose both the programmatic API and the data API in code, and reap a few
+other benefits as well, as described below.
+
+Building also on other ideas, notably some of the ideas emerging from functional programming,
+it is possible to develop domain models with a leaner--and thus more productive--code base.
+
+# STATUS
+
+This module is highly experimental and is *not* recommended for production.
+
+# Coding conventions
+
+[TODO]
+
+# Topics to Explore
+
+## Schema transforms
+## Lenses
\ No newline at end of file

Propchange: felix/trunk/converter/schematizer/readme.txt
------------------------------------------------------------------------------
    svn:eol-style = native