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 <dlean...@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
