Mailing-List: contact derby-dev-help@db.apache.org; run by ezmlm
Precedence: bulk
Reply-To: "Derby Development" <derby-dev@db.apache.org>
Received-SPF: neutral (asf.osuosl.org: local policy)
Message-ID: <42B85082.1000100@sbcglobal.net>
Date: Tue, 21 Jun 2005 10:38:10 -0700
From: Army <qozinx@sbcglobal.net>
User-Agent: Mozilla/5.0 (Windows; U; Windows NT 5.0; en-US;
 rv:1.7.1) Gecko/20040707
MIME-Version: 1.0
To: Derby Development <derby-dev@db.apache.org>
Subject: Re: Little adv. XML support
References: <200506191846.22906@centrum.cz>
In-Reply-To: <200506191846.22906@centrum.cz>
Content-Type: text/plain; charset=us-ascii; format=flowed
Content-Transfer-Encoding: 7bit

medvjed@centrum.cz wrote:

> i'm completly new to derby, i got a task (at school) to 
> implement some XML techonoly in some open-source java based DB. 
> So i can do it on derby.

Hi Petr, and thanks for your interest in Derby!

> Can you give me some advices where to start?
> I know some little teoretical things about 
> how to implement XML stroring, but i would 
> like to know on which classes I should focus
> and any advice will be good for me :-)

In order to add a new implementation of XML to Derby, the class you should start 
looking at is org.apache.derby.iapi.types.XML.  In the XML.java file for that 
class, the methods are divided into the following sections (if you search for 
these section headers, you'll find out where each section begins).

1 - DataValueDescriptor interface
2 - Storable interface
3 - StreamStorable interface
4 - XMLDataValue interface

In order to be complete, your new XML implementation will have to define most of 
the methods under these four sections.  The methods that you will _not_ have to 
define for your new implementation (because they should be the same for all XML 
implementations) are:

- getTypeName()
- typePrecedence()
- compare()
- getTypeFormatId()

For these 4 methods, you're new implementation should just use the methods as 
they are already defined in XML.java.

So that said, these are probably the first steps you'll want to take:

1) Create a new class in the org.apache.derby.iapi.types package for your new 
XML implementation.  You may want your new class to extend XML.java, but that's 
up to you (doing so might affect #4 below).

2) Pick a unique "implementation id" for your new XML implementation, and code 
that as static final short in your new class.  Since the default implementation 
(UTF-8) uses an id of "0", you could go ahead and use "1".

3) In your new class, write implementations for all of the methods found in 
XML.java under the four sections listed above.  When implementing these methods, 
feel free to add as many other methods/fields/etc to your new class as you want. 
  For the 4 specific methods given above (ex. getTypeName()), your new class 
should use the methods that are already defined in XML.java.

NOTE: In your "writeExternal" method, you must make sure that the first thing 
you write is the implementation id that you created in step 2 above.  And in 
your "readExternal" method, the first thing you read should be the 
implementation id, as well.  This implementation id is important because it will 
allow us to figure out what XML implementation is being used for a specific XML 
value (which plays a role in #4 below).

4) Once you have completed #3, the next thing you'll probably need to do is 
modify the XML.java file so that it can create (and use) instances of your new 
XML implementation class.  This is the tricky part :)  Since you're the first 
person to work on a new XML implementation, you'll have to make some design 
decisions regarding how Derby will load/handle multiple XML implementations.  I 
think we can probably put this discussion off until you complete #3, but if 
you'd like more details now, let me know.  To give you a general idea, what we 
ultimately want is the following:

   * Derby should be able to read and process both XML implementations: that is
     to say, both the current UTF-8 one and also your new implementation.

   * Some kind of version-based support for XML, so that all Derby releases after
     some version (ex. Derby 10.2) will use your new implementation of XML, but
     at the same time will be able to read and process any XML that was written
     from earlier (ex. 10.1) versions.

   * The solution you come up with should be flexible so that it can be
     easily grown in the future to support more Derby versions and more
     XML implementations (if needed).

Note that even though I wrote "you" in a lot of places in this email, you should 
always feel free to post questions/comments/ideas to this derby-dev mailing list 
to get feedback/input from the rest of us :)

I think the bulk of the work (at least to begin with) is going to be #3, so I'd 
say work on #1 - #3 first.  When you're satisfied with that, we can start 
looking at #4...

Thanks again for your interest in working with Derby, and I look forward to 
hearing from you as you work on this project.  And of course, if you have 
questions, please do ask!

Army