Project

General

Profile

FAQ » History » Revision 4

Revision 3 (amit -, 04/24/2008 12:00 AM) → Revision 4/6 (Paula Gearon, 04/21/2009 08:08 PM)

= 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. 

 '''What '''How are the Interfaces for legal change files being created?''' 

 We are using Mulgara?''' 
 The are 5 ways to talk to Mulgara. 2 of them are User Interfaces, and 3 are APIs. 

 User Interfaces 
  * ''Shell/CLI'': Running some simple scripts on the ''querylang'' JAR file will bring up a terminal program. ie.[[BR]] 
    {{{    java -jar querylang-x.y.z.jar }}} 
    This program used to Subversion repository. These may be in a graphical Swing Window. To get to this window, use 
 modified as the -g flag: 
    {{{    java -jar querylang-x.y.z.jar -g }}} 
  * ''Web UI'': Both management of the standalone server and the Web Application file (mulgara-x.y.z.war) provide a Web base user interface. Unless configured otherwise, these can be found on http://localhost:8080/webui 

 Programming Interfaces 
  * ''RMI'': This project becomes more complex. It is the original API for communicating with Mulgara. In the past it was necessary to create a "Session" to talk to a Mulgara instance, but because 
 this has now been simplified by using an object called "Connection". See the example programs called [http://mulgara.org/svn/mulgara/trunk/tools/src/org/mulgara/tools/Sparql.java Sparql] and http://mulgara.org/svn/mulgara/trunk/tools/src/org/mulgara/tools/Tql.java Tql] for examples on how to use Connections. 
  * ''Embedded'': This is the situation where a Database is instantiated in the user's own program. The interfaces for this are identical semi-automatic process that we need to the RMI interfaces. In fact, once the Connection (or Session) has been established, there is no difference at all. 
  * ''REST'': This is the newest API. While ensure all CRUD operations commit comments 
 are available through this interface, transactions have not yet been exposed. Documentation accurate. The basic information for this API can be found [wiki:RESTInterface here]. 
  * ''JRDF'': This API has changed a little, and [wiki:JRDF the documentation] has not kept pace. Please ask first release is based on the mailing lists if you encounter problems with the API. 
 output of: 

 '''What about the [http://jena.sourceforge.net/ Jena] API?''' {{{ 
 This API required the use of too many internals from Jena. This was not really Jena's fault, but rather because a lot of programmers started talking to Jena using classes that CURRENT_TX=`sudo svnlook youngest /opt/svn/mulgara` 
 LAST_TX=1 
 for i in `seq $CURRENT_TX -1 $LAST_TX`; 
     do not form part of the official interface. 

 The end result was a system that had to store data both in a local Jena store, as well as running the overhead of storing data in the Mulgara database. There were no benefits to this approach, and so Jena support was dropped. 

 '''Where did the "Session" Interface go?''' 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 
 It's still there, but it is now wrapped in the "Connection" interface. This interface takes care of a lot of the work needed to set up sessions. 

 If you really need to, then Sessions can be used just like they always have been. However, we'd like you to consider moving to Connections. 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.