Project

General

Profile

FAQ » History » Version 6

Paula Gearon, 04/21/2009 08:11 PM
Fixed formatting

1 1 amit -
2 6 Paula Gearon
h1. Mulgara Developer FAQ
3
4
5 1 amit -
This contains administrative information for developers who wish to contribute
6
to the Mulgara Project.
7
8
IMPORTANT: Due to the licensing requirements in moving from the MPL to the OSL
9
we need to carefully document all changes to existing source files. This is
10
very important for developers contributing to the project. More details are
11
provided below.
12
13
14 6 Paula Gearon
h2. FAQ
15 1 amit -
16 6 Paula Gearon
17
*What does Mulgara mean?*
18
19
Like the "Kowari":http://www.australianfauna.com/kowari.php, the
20
"Mulgara":http://www.australianfauna.com/mulgara.php is an Australian marsupial, and
21 2 amit -
is listed as "vulnerable".
22 1 amit -
23 6 Paula Gearon
*What License is the code under?*
24 1 amit -
25
The OSL. This was chosen to be compatible with the original MPL license of
26
Kowari. The MPL specifies an organization must be an "initial contributor" for
27
the licensed code. Since Mulgara is entirely community driven, a more
28
appropriate license was needed.
29
30 6 Paula Gearon
*How do I get the source code?*
31 1 amit -
32
You need a version of Subversion which supports SSL (encryption). Subversion
33
is an open source tool, and is free to download. Not all versions of
34
Subversion feature SSL, so ensure you have one which supports this option.
35
36
The following command will get the latest version of Mulgara:
37
38 6 Paula Gearon
<pre>
39 1 amit -
svn co https://mulgara.org/svn/mulgara/trunk
40 6 Paula Gearon
</pre>
41 1 amit -
42
You can also browse the source code by pointing your browser directly at this
43
link.
44
45 6 Paula Gearon
*How do I contribute code?*
46 1 amit -
47
Please mail contributions to the developers' list in patch format with
48
comments and justification. One of the lead developers with add your code as
49
soon as it can be tested.
50
51 6 Paula Gearon
*How can I get read/write access to the source repository?*
52 1 amit -
53
Ask an administrator on the developers' mailing list. Once you have
54
established a good track record then we will consider giving you full
55
read/write access to the repository. We hope to have a more formal process in
56
place soon, so that the procedure will be open and accountable.
57
58 6 Paula Gearon
*How do I learn the architecture of Mulgara?*
59 1 amit -
60
Eventually this information will be posted in the Mulgara Wiki. In the
61
meantime, try the following:
62
63 6 Paula Gearon
* Download the source and read it. If code is not clear and comments are lacking, then please report it.
64
* Ask on the developers' mailing list.
65
* 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.
66 1 amit -
67
If you learn something that is not adequately documented, then please consider
68
adding it to the Wiki.
69
70 6 Paula Gearon
*Where is the documentation for Mulgara development?*
71 1 amit -
72
On the Development page in the Wiki. If something is missing, then let us
73
know, and we will endeavor to add it.
74
75 6 Paula Gearon
*How do I develop for Mulgara with Eclipse?*
76 1 amit -
77
Install Subclipse for Subversion in Eclipse, and check out Mulgara using the
78
address found in the download page.
79
80
Mulgara makes heavy use of 3rd party libraries, some of which generate code.
81
Eclipse will report errors until it sees all of the libraries and code already
82
available. To accomplish this we have an Ant task called ideSupport. Build
83
this from the command line, and then refresh the Eclipse project.
84
85
For more details see the HOWTO.
86 4 Paula Gearon
87 6 Paula Gearon
*What are the Interfaces for using Mulgara?*
88 1 amit -
89
The are 5 ways to talk to Mulgara. 2 of them are User Interfaces, and 3 are APIs.
90 4 Paula Gearon
91 1 amit -
User Interfaces
92 6 Paula Gearon
* _Shell/CLI_: Running the _querylang_ JAR file will bring up a terminal program. ie.
93 4 Paula Gearon
94 6 Paula Gearon
<pre>
95
96
   This program used to be in a graphical Swing Window. To get to this window, use the -g flag:
97
98
<pre>
99
* _Web UI_: Both 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
100
101 1 amit -
Programming Interfaces
102 6 Paula Gearon
* _RMI_: This 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 this has now been simplified by using an object called "Connection". See the example programs called "Sparql":http://mulgara.org/svn/mulgara/trunk/tools/src/org/mulgara/tools/Sparql.java and "Tql":http://mulgara.org/svn/mulgara/trunk/tools/src/org/mulgara/tools/Tql.java for examples on how to use Connections.
103
* _Embedded_: This is the situation where a Database is instantiated in the user's own program. The interfaces for this are identical to the RMI interfaces. In fact, once the Connection (or Session) has been established, there is no difference at all.
104
* _REST_: This is the newest API. While all CRUD operations are available through this interface, transactions have not yet been exposed. Documentation for this API can be found [[RESTInterface|here]].
105
* _JRDF_: This API has changed a little, and [[JRDF|the documentation]] has not kept pace. Please ask the mailing lists if you encounter problems with the API.
106 1 amit -
107 6 Paula Gearon
*What Happened to the "Jena":http://jena.sourceforge.net/ API?*
108 4 Paula Gearon
109
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 do not form part of the official interface.
110 5 Paula Gearon
111 4 Paula Gearon
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.
112 1 amit -
113 6 Paula Gearon
*Where did the "Session" Interface go?*
114 1 amit -
115
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.
116
117
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.
118
119 6 Paula Gearon
*Why is my question not answered here?*
120 1 amit -
121
Because I didn't know about the issue and no one has asked me about it yet.
122
Let one of the developers know, and we will put something up. Feel free to
123
harrass us if we take too long.
124
125 6 Paula Gearon
*Why do you sometimes mis-spell words?*
126 3 amit -
127
The project was started in Australia. Mulgaras are Australian, Kowaris are
128
Australian, and I'm Australian. I live in the USA now, so I try to remember to
129
use American spelling, but sometimes I forget.
130
131 6 Paula Gearon
* I am getting the following exception upon Mulgara startup running on my
132
Windows XP machine:*
133
<pre>
134
[java] INFO 11:59 [[MulgaraInternalTransaction]]> Committing Transaction: 4779445, state=ACTUNREF, inuse=1, using=0
135 3 amit -
[java] ERROR 12:00 XAStatementStoreImpl> I/O error while performing prepare.
136
[java] java.io.IOException
137
[java]     at java.nio.MappedByteBuffer .force0(Native Method)
138
[java]     at java.nio.MappedByteBuffer.force(MappedByteBuffer.java:144)
139
[java]     at org.mulgara.store.xa.MappedBlockFile.force(MappedBlockFile.java:218)
140
[java]     at org.mulgara.store.xa.ManagedBlockFile.force(ManagedBlockFile.java:147)
141
[java]     at org.mulgara.store.xa.AVLFile.force(AVLFile.java:170)
142
[java]     at org.mulgara.store.statement.xa.TripleAVLFile.force(TripleAVLFile.java:279)
143
[java]     at org.mulgara.store.statement.xa.XAStatementStoreImpl.prepare(XAStatementStoreImpl.java:817)
144
[java]     at org.mulgara.resolver.StringPoolSession.prepare(StringPoolSession.java:242)
145
 .
146
 .
147
 .
148 6 Paula Gearon
</pre>
149 3 amit -
150
The error you are seeing is happening while an uncommitted transaction
151
is being committed. (Did the system shut down cleanly?)  Once you get
152
it up and running it might be fine to continue as normal. If that's
153
the case, then forcing the system to NOT use file mappings should get
154
you going again.  Do this by updating the command line to include the
155
following:
156 6 Paula Gearon
<pre>
157 3 amit -
java -Dmulgara.xa.forceIOType=explicit -jar mulgara-1.x.x.jar
158 6 Paula Gearon
</pre>
159 1 amit -
160
If this works, then you can either continue running like this, or else
161
shut down cleanly and start up again normally.