Mulgara

= Mulgara Developer FAQ =

This contains administrative information for developers who wish to contribute

to the Mulgara Project.

IMPORTANT: Due to the licensing requirements in moving from the MPL to the OSL

we need to carefully document all changes to existing source files. This is

very important for developers contributing to the project. More details are

provided below.

== FAQ ==

'''What does Mulgara mean?'''

Like the [http://www.australianfauna.com/kowari.php Kowari], the

[http://www.australianfauna.com/mulgara.php Mulgara] is an Australian marsupial, and

is listed as "vulnerable".

'''What License is the code under?'''

The OSL. This was chosen to be compatible with the original MPL license of

Kowari. The MPL specifies an organization must be an "initial contributor" for

the licensed code. Since Mulgara is entirely community driven, a more

appropriate license was needed.

'''How do I get the source code?'''

You need a version of Subversion which supports SSL (encryption). Subversion

is an open source tool, and is free to download. Not all versions of

Subversion feature SSL, so ensure you have one which supports this option.

The following command will get the latest version of Mulgara:

{{{

svn co https://mulgara.org/svn/mulgara/trunk

}}}

You can also browse the source code by pointing your browser directly at this

link.

'''How do I contribute code?'''

Please mail contributions to the developers' list in patch format with

comments and justification. One of the lead developers with add your code as

soon as it can be tested.

'''How can I get read/write access to the source repository?'''

Ask an administrator on the developers' mailing list. Once you have

established a good track record then we will consider giving you full

read/write access to the repository. We hope to have a more formal process in

place soon, so that the procedure will be open and accountable.

'''How do I learn the architecture of Mulgara?'''

Eventually this information will be posted in the Mulgara Wiki. In the

meantime, try the following:

 * Download the source and read it. If code is not clear and comments are lacking, then please report it.

 * Ask on the developers' mailing list.

 * Read Paul's blog. Many of the relevant entries may be quite old. Ask him to write about something if you need specific information. In recent months he hasn't been writing regularly, but he is still there and willing to answer most questions in detail.

If you learn something that is not adequately documented, then please consider

adding it to the Wiki.

'''Where is the documentation for Mulgara development?'''

On the Development page in the Wiki. If something is missing, then let us

know, and we will endeavor to add it.

'''How do I develop for Mulgara with Eclipse?'''

Install Subclipse for Subversion in Eclipse, and check out Mulgara using the

address found in the download page.

Mulgara makes heavy use of 3rd party libraries, some of which generate code.

Eclipse will report errors until it sees all of the libraries and code already

available. To accomplish this we have an Ant task called ideSupport. Build

this from the command line, and then refresh the Eclipse project.

For more details see the HOWTO.

'''How are the legal change files being created?'''

We are using some simple scripts on the Subversion repository. These may be

modified as the management of the project becomes more complex. It is because

this is a semi-automatic process that we need to ensure all commit comments

are accurate. The basic information for the first release is based on the

output of:

{{{

CURRENT_TX=`sudo svnlook youngest /opt/svn/mulgara`

LAST_TX=1

for i in `seq $CURRENT_TX -1 $LAST_TX`;

    do sudo svnlook changed /opt/svn/mulgara --revision $i >> KOWARI-MODIFICATIONS.txt

    sudo svnlook info /opt/svn/mulgara --revision $i >> KOWARI-MODIFICATIONS.txt

    echo >> KOWARI-MODIFICATIONS.txt

done

}}}

'''Why is my question not answered here?'''

Because I didn't know about the issue and no one has asked me about it yet.

Let one of the developers know, and we will put something up. Feel free to

harrass us if we take too long.

'''Why do you sometimes mis-spell words?'''

The project was started in Australia. Mulgaras are Australian, Kowaris are

Australian, and I'm Australian. I live in the USA now, so I try to remember to

use American spelling, but sometimes I forget.

''' I am getting the following exception upon Mulgara startup running on my

Windows XP machine:'''

{{{

[java] INFO 11:59 MulgaraInternalTransaction> Committing Transaction: 4779445, state=ACTUNREF, inuse=1, using=0

[java] ERROR 12:00 XAStatementStoreImpl> I/O error while performing prepare.

[java] java.io.IOException

[java]     at java.nio.MappedByteBuffer .force0(Native Method)

[java]     at java.nio.MappedByteBuffer.force(MappedByteBuffer.java:144)

[java]     at org.mulgara.store.xa.MappedBlockFile.force(MappedBlockFile.java:218)

[java]     at org.mulgara.store.xa.ManagedBlockFile.force(ManagedBlockFile.java:147)

[java]     at org.mulgara.store.xa.AVLFile.force(AVLFile.java:170)

[java]     at org.mulgara.store.statement.xa.TripleAVLFile.force(TripleAVLFile.java:279)

[java]     at org.mulgara.store.statement.xa.XAStatementStoreImpl.prepare(XAStatementStoreImpl.java:817)

[java]     at org.mulgara.resolver.StringPoolSession.prepare(StringPoolSession.java:242)

 .

 .

 .

}}}

The error you are seeing is happening while an uncommitted transaction

is being committed. (Did the system shut down cleanly?)  Once you get

it up and running it might be fine to continue as normal. If that's

the case, then forcing the system to NOT use file mappings should get

you going again.  Do this by updating the command line to include the

following:

{{{

java -Dmulgara.xa.forceIOType=explicit -jar mulgara-1.x.x.jar

}}}

If this works, then you can either continue running like this, or else

shut down cleanly and start up again normally.