Hi Paul,
Thanks for your replay. Great to find a mentor!
** Note this is not the formal proposal - this is an explanation and
answer to Paul questions.
Let me start with the second item - the framework is mature, but by far
not complete! The fact that a project is mature means that it is useful
in its current state, but in fact there is still a lot that can be done
to improve and leverage its potential. I have listed some of the things
I'd like to add to this project below.
As for your first question - what the framework is -
The framework is a POJO (Plain Old Java Object) to XML mapping, similar
in idea to Hibernate mapping POJOs to a DB.
The main theme of the framework is to write POJOs with as minimal
restrictions, while allowing to mapping to arbitrary XML format, with
support for the full XML schema features. The framework is to support
XML schema generation with all (or most) features.
Now, at this point you should be asking why is this different then JAXB
2? And am I writing a new XML parser?
JAXB 2 is designed from the view point of taking an XML schema and
generating from it the Java Code. While the opposite is possible, the
generated XML schema is trivial (no facets, basic XML types, 1:1 mapping
of Java model to the XML model). Now my framework is designed to work
the opposite - write any Java code, and generate from it the XML Schema.
With most XML Binding framework, a developer finds himself in a catch 22
- Java code is being generated form an XML schema, and the developer has
to decide between two suboptimal options
1. use the XML Binding code as is (Apache XmlBeans is a great tool for
this pattern), whereby information is being copied between the Java
business objects and the XML binding beans. Each time the XML changes,
not only does the developer need to re-generate the XML Binding classes,
he is also required to update the Business Object classes accordingly,
resulting in updating in three locations (the XML schema, and two
methods to read and write from the BOs to the XML Beans generated
classes).
For instance, consider a Person class (BO) with some members, an XML
representation of a person and an XmlPerson generated bean. The Person
class has the business methods and operations, and members for the
person data. The XmlPerson is the generated bean. In this case, the
Person class may have the methods toXML and fromXML that copy
information between the Person class and the XmlPerson class.
2. use the XML Binding generated code as a base for the Java Model (the
JAXB way), where the developer adds to the generated classes the
business methods. This way of working prevents the problem of having to
update the XML mapping in multiple locations, but introduces another
problem - how does one update the Java classes as the XML structure
changes? Re-generation of the classes deletes the business methods, but
manual update of the Java classes may be too complex at times.
Hence the catch 22.
It should be noted that both XmlBeans and JAXB allow both ways of
working, but it seems that each aims at a certain usecase. It should
also be noted that for simple updates of the XML model, JAXB is simple
enough to allow manual update of the Java model.
As for XML parser - I am using either Axiom or XmlBeans under the hood -
my framework is a wrapper around both frameworks, and can be used with
other XML parsers - I have abstracted the actual XML reading / writing
from the framework itself.
Main advantages of my framework:
================================
* with its ability to generate accurate and controllable XML Schema from
the Java classes, this framework has the potential of exposing Java
Beans as Web-Services while controlling the XML Schema embedded in the
WSDL (including facets, controlling the XML structure, XML types, etc).
One of the items in the TODO list is to implementing such an option of
exposing web services with Axis 2. This should not be too difficult
considering my framework can read and write to Axiom XML binding
objects.
* allows to map any Java object to XML using only annotations on the
code.
(The only current constraint is to have Java Beans like properties,
which is a good candidate to add to the TODO list - to remove the
constraint).
Note that JAXB requires the use of custom Java code, implementation of
some interfaces and the use of JAXBElement more than a few cases.
* allows to control the structure of the XML document, including
flattening trees of Java Beans (delegates) and introducing grouping XML
elements (JAXB 2 allows only the latter using the XmlElementWrapper
annotation).
1. flattening bean trees up to the boundary of collections.
2. introducing grouping XML elements.
3. control the names and ordering of XML elements, or using XML
attributes.
For example, the following Java classes can be mapped to the following
schemas (without change to the Java classes, except annotations):
public class Person {
private String firstName;
private String lastName;
private String middleName;
private Address address = new Address();
private Address address2 = new Address();
public String getFirstName() {...}
public void setFirstName(String firstName) {...}
public String getLastName() {...}
public void setLastName(String lastName) {...}
public String getMiddleName() {...}
public void setMiddleName(String firstName) {...}
public Address getAddress() {...}
public void setAddress(Address address) {...}
public Address getAddress2() {...}
public void setAddress2(Address address2) {...}
}
public class Address {
private String street;
private String city;
public String getStreet() {...}
public void setStreet(String street) {...}
public String getCity() {...}
public void setCity(String city) {...}
}
Simple case (trivial mapping):
<ex7:person
xmlns:ex7="http://example.abra.com/dependentObjectsProperty";>
<ex7:firstName>joe</ex7:firstName>
<ex7:lastName>smith</ex7:lastName>
<ex7:middleName>jun</ex7:middleName>
<ex7:address>
<ex7:street>hamasger</ex7:street>
<ex7:city>bat yam</ex7:city>
</ex7:address>
<ex7:address2>
<ex7:street>hamasger 2</ex7:street>
<ex7:city>bat yam 2</ex7:city>
</ex7:address2>
</ex7:person>
Now with some transformation -
1. The first address property was flattened to the root XML element
2. The firstName and lastName properties of the Person class are now
children of a new element called details (grouping) and the lastName is
now an attribute.
3. The middleName is now an attribute of the root element
<ex7:person xmlns:ex7="http://example.abra.com/dependentObjectsProperty";
ex7:middleName="john">
<ex7:street>hamasger</ex7:street>
<ex7:city>bat yam</ex7:city>
<ex7:details ex7:lastName="smith">
<ex7:firstName>joe</ex7:firstName>
</ex7:details>
<ex7:address2>
<ex7:street>hamasger 2</ex7:street>
<ex7:city>bat yam 2</ex7:city>
</ex7:address2>
</ex7:person>
We can even transform the XML to such form as to have properties from
both classes in the same XML element (personInfo)
<ex7:person2
xmlns:ex7="http://example.abra.com/dependentObjectsProperty";
ex7:lastName="smith">
<ex7:personInfo ex7:middleName="john">
<ex7:firstName>joe</ex7:firstName>
<ex7:street>hamasger</ex7:street>
<ex7:city>bat yam</ex7:city>
</ex7:personInfo>
<ex7:additionalAddress>
<ex7:street>hamasger 2</ex7:street>
<ex7:city>bat yam 2</ex7:city>
</ex7:additionalAddress>
</ex7:person2>
* allows to map any Java Value Object to an XML simple type, with no
requirement on the Java value object - no requirement that it extends or
implements any interface. For instance, one may map the
java.net.Inet4Address to a simple type easily.
* supports any constructor (with parameters), and does not require a
bean to have a default constructor. XML elements and attributes can be
mapped of both the Bean and the parent Bean (in a tree of Beans) can be
mapped as parameters to the constructor.
For example, the Address class above may have only one public
constructor of the form
Address(String firstName, String city) {...}
Where the firstName field is not a mapped property of the Address class
at all - it is mapped as part of the Person class (this example may not
be a realistic use-case, but it does demonstrate the functionality).
* supports any static factory, including factories with parameters (with
plans for context factories). JAXB supports only factories with no
parameters.
As with constructors, XML elements and attributes can be mapped of both
the Bean and the parent Bean (in a tree of Beans) can be mapped as
parameters to the constructor.
* Planned to add context factories - to use named instance factories,
not only static factories.
When reading objects from a stream, in complex environments such as web
services, one may be interested in using a specific instance of a
factory to create the instances of read objects (contextual factory -
the factory instance maybe related to a certain session or context).
I have the design of such a feature, but it is yet to be done.
* supports schema generation with facets -
1. min and max length for containers,
2. patterns, min and max length for strings (and derived types of
strings).
3. minExclusive, maxExclusive, minInclusive, minExclusive for numbers.
Note that JAXB does not support schema generation with facets.
* Supports mapping native Java types to XML.
1. The Date & Time types are mapped to Java.sql.Date, Java.sql.Time,
Java.util.date, Java.util.Calendar XML xml:DateTime, xml:Date, xml:Time,
xml:GYear, xml:GYearMonth, xml:GMonth and xml:GMonthDay (JAXB requires
the use of XMLGregorianCalendar).
2. Numbers are mapped directly to XML - short to xml:short and
xml:unsignedByte, BigInteger to xml:integer, xml:positiveInteger, etc.
JAXB requires the use of XmlJavaTypeAdapter annotation and an XmlAdapter
to map those types.
* Supports mapping to all built-in XML types.
* JAXB support for substitution groups require the use of the
JAXBElement class as a member of the bean mapped to XML. My framework
allows to support substitution groups without an equivalent case (TBD -
I have the design for this).
* Support for xml:union - a property of type Object or Number, or any
abstract value can be mapped to an XML union. For instance, one may have
a Java property which is a list of numbers or strings.
@MOProperty()
@MOPolymorphicAtomProperty({
@MOPolymorphicAtomType(Integer.class),
@MOPolymorphicAtomType(String.class)})
public List<Object> getPolymorphicList() {
return polymorphicList;
}
For which the equivalent xml schema is
<xs:element name="polymorphicList" minOccurs="0" maxOccurs="unbounded">
<xs:simpleType>
<xs:union>
<xs:simpleType>
<xs:restriction base="xs:int">
</xs:restriction>
</xs:simpleType>
<xs:simpleType>
<xs:restriction base="xs:string">
</xs:restriction>
</xs:simpleType>
</xs:union>
</xs:simpleType>
</xs:element>
Or (by adding the @MOXmlListStyle() annotation)
<xs:element name="polymorphicList">
<xs:simpleType>
<xs:list>
<xs:simpleType>
<xs:union>
<xs:simpleType>
<xs:restriction
base="xs:int">
</xs:restriction>
</xs:simpleType>
<xs:simpleType>
<xs:restriction
base="xs:string">
</xs:restriction>
</xs:simpleType>
</xs:union>
</xs:simpleType>
</xs:list>
</xs:simpleType>
</xs:element>
for my knowledge JAXB does not support union.
* when persisting collections, allows to control the order of the
collection items. While this feature may not seem important at first
hand for XML persistency, it is important when using a version control
system.
In many cases, XML files are stored in a version control system which
considers different ordering of XML elements as a change in the
document. Enforcing a certain order of the collection content while
writing the XML prevents this issue.
* I have probably forgotten some other advantages - but I think that you
get the general idea by...
What remains to be done:
========================
1. Beans inheritance, in choice and substitution group models.
2. the Map collection
3. Context Factories
3. override the annotations with external XML configuration
4. equivalent of JAXB XmlJavaTypeConverter
5. bean cycles handling
6. Axis 2 integration
7. remove the requirement of a bean to have getter and setter pair for
properties (allow direct field access and custom property accessors).
And as with all projects - documentation, samples, tutorials, etc. (I
fully understand that my first task on contributing this code to Apache
will be to provide some level of documentation and samples).
Cheers,
Yoav
-----Original Message-----
From: Paul Fremantle [mailto:[EMAIL PROTECTED]
Sent: Tuesday, January 15, 2008 7:21 PM
To: [EMAIL PROTECTED]; Yoav Avrahami
Cc: general@xml.apache.org
Subject: Re: Openning an XML to Java Mapping as Open Source
Yoav
You find the mentor here by sending the note - just as you did.
Let me make some comments.
Firstly - Apache is about openness - so I encourage you to start to
tell us why this framework is better and why we should be interested
in it.
Secondly, the maturity of the project is not always a good thing from
the perspective of the incubator. The aim of the incubator is twofold.
One is to solve the IP issues around donated code. In your case, if
you are the sole author that will be quite smooth. The second issue is
to build a community of committers and developers who will ensure that
the project is healthy and vital. The problem is that if the project
is "done" then it can be hard to encourage involvement. Developers
like to have meaty tasks they can get involved with.
As regards the XML project, that may be a good home for this, or you
may wish to eventually target a separate project. Without more details
about this code its hard to know what is appropriate.
Regards,
Paul
On Jan 15, 2008 4:20 PM, Yoav Avrahami <[EMAIL PROTECTED]> wrote:
> Hi all,
>
>
>
> I have a project which I have written and I am the sole owner of
rights
> for which I think about opening as Open Source code.
>
> The project itself is in a very mature state, and has some clear
> advantages over all existing XML to Java mapping frameworks (both from
> Apache and Sun - XmlBeans, Jaxb 2, etc.) which I will not go into
here.
> I am interested to know the process of opening such a project with
> Apache.
>
>
>
> The Incubator process seems quite confusing - I need to have a person
> (or persons) from the Apache foundation to help me write a proposal -
> but where do I find those persons?
>
>
>
> What about the Apache XML project - is it still active, or deprecated
by
> the incubator?
>
>
>
> Any help will be most appreciated.
>
>
>
> Cheers,
>
> Yoav.
>
>
>
>
> This message and the information contained herein is proprietary and
confidential and subject to the Amdocs policy statement,
> you may review at http://www.amdocs.com/email_disclaimer.asp
>
--
Paul Fremantle
Co-Founder and VP of Technical Sales, WSO2
OASIS WS-RX TC Co-chair
blog: http://pzf.fremantle.org
[EMAIL PROTECTED]
"Oxygenating the Web Service Platform", www.wso2.com
This message and the information contained herein is proprietary and
confidential and subject to the Amdocs policy statement,
you may review at http://www.amdocs.com/email_disclaimer.asp
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
