<!--
  ~ Licensed to the Apache Software Foundation (ASF) under one
  ~ or more contributor license agreements. See the NOTICE file
  ~ distributed with this work for additional information
  ~ regarding copyright ownership. The ASF licenses this file
  ~ to you under the Apache License, Version 2.0 (the
  ~ "License"); you may not use this file except in compliance
  ~ with the License. You may obtain a copy of the License at
  ~
  ~ http://www.apache.org/licenses/LICENSE-2.0
  ~
  ~ Unless required by applicable law or agreed to in writing,
  ~ software distributed under the License is distributed on an
  ~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
  ~ KIND, either express or implied. See the License for the
  ~ specific language governing permissions and limitations
  ~ under the License.
  -->

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta name="generator" content=
"HTML Tidy for Windows (vers 14 June 2007), see www.w3.org" />
<title>ADB Tweaking Guide</title>
</head>
<body lang="en" xml:lang="en">
<h1>ADB Tweaking Guide</h1>
<p>This document explains the mechanisms available to extend ADB
and possibly adopt it to compile schemas to support other
languages.</p>
<h2>Content</h2>
<ul>
<li><a href="#intro">Introduction</a></li>
<li><a href="#config">Know the Configuration</a></li>
<li><a href="#first_tweak">The First Tweak - Generate Plain Java
Beans</a></li>
<li><a href="#advanced_tweak">A More Advanced Tweak - Generate Code
for Another Language</a></li>
</ul>
<a name="intro" id="intro"></a>
<h2>Introduction</h2>
<p>ADB was written with future extensibility in mind, with a clear
and flexible way to extend or modify its functionality. Available
mechanisms to extend ADB and possibly adopt it to compile schemas
to support other languages are described below.</p>
<a name="config" id="config"></a>
<h2>Know the Configuration</h2>
<p>The configuration for the ADB framework is in the
<strong>schema-compile.properties</strong> file found in the
<strong>org.apache.axis2.schema</strong> package. This properties
file has the following important properties</p>
<ul>
<li>schema.bean.writer.class
<p>This is the writer class. This is used by the schema compiler to
write the beans and should implement the
<strong>org.apache.axis2.schema.writer.BeanWriter</strong>
interface. The schema compiler delegates the bean writing task to
the specified instance of the BeanWriter.</p>
</li>
<li>schema.bean.writer.template
<p>This specifies the template to be used in the BeanWriter. The
BeanWriter author is free to use any mechanism to write the classes
but the default mechanism is to use a xsl template. This property
may be left blank if the BeanWriter implementation does not use a
template.</p>
</li>
<li>schema.bean.typemap
<p>This is the type map to be used by the schema compiler. It
should be an implementation of the
<strong>org.apache.axis2.schema.typemap.TypeMap</strong> interface.
The default typemap implementation encapsulates a hashmap with type
QName to Class name string mapping.</p>
</li>
</ul>
<a name="first_tweak" id="first_tweak"></a>
<h2>The First Tweak - Generate Plain Java Beans</h2>
<p>The first, most simple tweak for the code generator could be to
switch to plain bean generation. The default behavior of the ADB
framework is to generate ADBBeans, but most users, if they want to
use ADB as a standalone compiler, would prefer to have plain java
beans. This can in fact be done by simply changing the template
used.</p>
<p>The template for plain java beans is already available in the
<strong>org.apache.axis2.schema.template</strong> package. To make
this work replace the
<strong>/org/apache/axis2/databinding/schema/template/ADBBeanTemplate.xsl</strong>
with the
<strong>/org/apache/axis2/databinding/schema/template/PlainBeanTemplate.xsl</strong>
in the schema-compile.properties<strong>.</strong></p>
<p>Congratulations! You just tweaked ADB to generate plain java
beans.</p>
<p>To generate custom formats, the templates need to be modified.
The schema for the xml generated by the JavaBeanWriter is available
in the source tree under the Other directory in the codegen module.
Advanced users with knowledge of XSLT can easily modify the
templates to generate code in their own formats.</p>
<a name="advanced_tweak" id="advanced_tweak"></a>
<h2>A More Advanced Tweak - Generate Code for Another Language</h2>
<p>To generate code for another language, there are two main
components that need to be written.</p>
<ul>
<li>The BeanWriter
<p>Implement the BeanWriter interface for this class. A nice
example is the
<strong>org.apache.axis2.schema.writer.JavaBeanWriter</strong>
which has a lot of reusable code. In fact if the target language is
object-oriented (such as C# or even C++), one would even be able to
extend the JavaBeanWriter itself.</p>
</li>
<li>The TypeMap
<p>Implement the TypeMap interface for this class. The
<strong>org.apache.axis2.schema.typemap.JavaTypeMap</strong> class
is a simple implementation for the typemap where the QName to class
name strings are kept inside a hashmap instance. This technique is
fairly sufficient and only the type names would need to change to
support another language.</p>
</li>
</ul>
<p>Surprisingly, this is all that needs to be done to have other
language support for ADB. Change the configuration and you are
ready to generate code for other languages!</p>
<p>This tweaking guide is supposed to be a simple guideline for
anyone who wishes to dig deep into the mechanics of the ADB code
generator. Users are free to experiment with it and modify the
schema compiler accordingly to their needs. Also note that the
intention of this section is <em>not</em> to be a step by step
guide to custom code generation. Anyone who wish to do so would
need to dig into the code and get their hands dirty!</p>
</body>
</html>