JAK's API approach

h2. Java API for KML -JAK's API approach
{toc:minLevel=3|maxLevel=5|type=flat}

h3. API approach for XML dialects

{quote}
"Every API is a little language, and people must learn to read and write it.
If you get an API right, code will read like prose." {{JOSHUA BLOCH, 2008}}
{quote}

The traditional way to build an API for XML dialects is a two-layered approach ([Figure 1|#figure1]). The first layer is the XML to Java binding that is often automatically created from the XML schema. The second layer is the semantic model of the API and is built on top of the first layer. It is very common to handcraft the API to add or tweak things needed by it.

{anchor:figure1}
!Figure321_traditional_approach_to_build_api.png!
h6. Figure 1: The two layers of the traditional approach to build an API for XML dialects. The semantic model of the API enables a convenient access to the underlying 1st layer, but clients of the API are still able to access the 1st layer for more complex tasks.

One of the difficulties of this approach is that the generated and hand-written code needs to be treated differently. It is evident that it is never a good idea to edit the generated code by hand, as all changes will get lost during the next code generation cycle.

Usually the hand-written code is separated by inheritance from the generated code. Martin Fowler calls this the Generation Gap \[FOW09\]. The generated code can call all hand-written code using abstract methods, and the hand-written code is capable of calling every generated method. Clients of the API only refer to the hand-written classes of the 2nd layer, while the generated classes are effectively ignored.

This leads to an inheritance structure potentially based upon three classes ([Figure 2|#figure2]).

{anchor:figure2}
!Figure322_generation_gap.png!
h6. Figure 2: The Generation Gap leads to a quite complex class inheritance structure.

The interplay of code generation and hand-written code does lead to a more complex class structure, a price that usually has to be paid for the convenience of code generation.

The approach taken by this thesis is different. With its plugin mechanism, JAXB provides the ability to access the semantic information of the XML schema during the code creation process to determine what kind of classes and properties are going to be generated and has the ability to react to the requirements of an API. Thus, it opens up the possibility of generating the semantic application layer rather than coding it by hand. The _Java API for KML_ is not artificially divided into two layers anymore. They are merged together. As a result, the Generation Gap has disappeared.


h6. Bibliography

| \[FOW09\] | MARTIN FOWLER; Generation Gap; http://www.martinfowler.com/dslwip/GenerationGap.html |

{column}
{column:width=1%}
{column}
{column:width=19%}

{livesearch:id=1|spaceKey=jak}
[Java API for KML|Home] | [@Google|http://code.google.com/p/javaapiforkml/]
{pagetree}
{column}
{section}