5 |
:Author: Tuomas J. Lukka |
:Author: Tuomas J. Lukka |
6 |
:Last-Modified: $Date$ |
:Last-Modified: $Date$ |
7 |
:Revision: $Revision$ |
:Revision: $Revision$ |
8 |
:Status: Incomplete |
:Status: Current |
9 |
|
|
10 |
This document outlines the main issues in the Jena api |
This document outlines the main issues in the Jena api |
11 |
currently in use and proposes a lightweight api of our own |
currently in use and proposes a lightweight api of our own |
52 |
|
|
53 |
RESOLVED: As immutable Literal objects, with several types of accessors. |
RESOLVED: As immutable Literal objects, with several types of accessors. |
54 |
|
|
55 |
|
- What about literal typing? How do we support enfilades? |
56 |
|
|
57 |
|
RESOLVED: For now, just get the raw string. |
58 |
|
|
59 |
|
- Do we want explicit Statement objects a la Jena? |
60 |
|
|
61 |
|
RESOLVED: No, they force a certain style of implementation which may not be the |
62 |
|
most efficient. We need to minimize the number of Java objects created. |
63 |
|
While an object for every resource and literal is just about unavoidable, |
64 |
|
an object for each statement is not. |
65 |
|
|
66 |
|
- What would be the right characters for the search methods? |
67 |
|
|
68 |
|
RESOLVED: 1 for a given object, X for an unknown object. |
69 |
|
They are visually clearly separate, and X for the unknown is mnemonic. |
70 |
|
|
71 |
|
- Should bags, alts &c be supported explicitly in the API? |
72 |
|
|
73 |
|
RESOLVED: Not yet. Many issues related e.g. to versioning. |
74 |
|
|
75 |
|
- That's a LOT of methods for all combinations. Couldn't we use wildcards |
76 |
|
or something? |
77 |
|
|
78 |
|
RESOLVED: No. It would be unnecessary inefficiency to look for them. |
79 |
|
Remember, this code is *the* inner loop. |
80 |
|
|
81 |
|
Quite likely code generation will be used. |
82 |
|
|
83 |
|
|
84 |
Problems with jena |
Problems with jena |
85 |
================== |
================== |
100 |
that Statements and nodes were independent of the model. However, |
that Statements and nodes were independent of the model. However, |
101 |
this was not the case. |
this was not the case. |
102 |
|
|
103 |
|
Efficiency is also important: in order for Fenfire to work properly, |
104 |
|
*ALL* searches within memory must be O(1). Jena makes no guarantees, |
105 |
|
since its goal is to support different implementations of Model. |
106 |
|
For us, the different implementations do not matter so much as raw |
107 |
|
efficiency of the memory-based implementation. This is quite different |
108 |
|
from most RDF uses, since the usual scenario is that there is not too much |
109 |
|
RDF (at least so far). |
110 |
|
|
111 |
Design |
Design |
112 |
====== |
====== |
113 |
|
|
114 |
|
The resource mapper |
115 |
|
------------------- |
116 |
|
|
117 |
|
The global resource mapper (has to be global since resources are model-agnostic) |
118 |
|
is simple: The name must be short because it's so widely used. |
119 |
|
|
120 |
|
public class RMap { |
121 |
|
public static Object toModel(String res); |
122 |
|
public static Object toModel(String res, int offs, int len); |
123 |
|
public static Object toModel(char[] res, int offs, int len); |
124 |
|
|
125 |
|
public static String toString(Object res); |
126 |
|
|
127 |
|
/** Append the string version of the resource to the given buffer. |
128 |
|
* In order to avoid creating too many String objects |
129 |
|
* when serializing a space, we |
130 |
|
public static void appendToString(Object res, StringBuffer buf); |
131 |
|
} |
132 |
|
|
133 |
|
The appendToString method solves one problem we had in Gzz: |
134 |
|
when saving, too many Strings were created for object names. Similarly, having |
135 |
|
the toModel method overloaded with different parameter types allows the most efficient |
136 |
|
creation of resources without conversions. |
137 |
|
|
138 |
|
We *may* want to make RMap internally redirectable in the future to allow |
139 |
|
alternate implementations; the static interface will not change. |
140 |
|
|
141 |
|
The model object |
142 |
|
---------------- |
143 |
|
|
144 |
|
The ShortRDF class shows what a mess the query functions can easily become. |
145 |
|
To avoid this, we'll drop the semantics (subject,predicate,object) for now |
146 |
|
and name all methods according to a general scheme. |
147 |
|
|
148 |
|
public interface ConstFirstOrderModel { |
149 |
|
public Object find1_11X(Object subject, Object predicate); |
150 |
|
public Object find1_X11(Object predicate, Object subject); |
151 |
|
... |
152 |
|
public Iterator findN_11X(Object subject, Object predicate); |
153 |
|
... |
154 |
|
} |
155 |
|
|
156 |
|
public interface FirstOrderModel extends ConstFirstOrderModel { |
157 |
|
public void set1_11X(Object subject, Object predicate, Object object); |
158 |
|
public void set1_X11(Object subject, Object predicate, Object object); |
159 |
|
... |
160 |
|
|
161 |
|
public void rm_1XX(Object subject); |
162 |
|
public void rm_11X(Object subject, Object predicate); |
163 |
|
public void rm_X11(Object predicate, Object object); |
164 |
|
... |
165 |
|
|
166 |
|
/** Add the given triple to the model. |
167 |
|
*/ |
168 |
|
public void add(Object subject, Object predicate, Object object); |
169 |
|
} |
170 |
|
|
171 |
|
The functions are built by the following format: |
172 |
|
first, the actual function type: |
173 |
|
|
174 |
|
find1 |
175 |
|
Find a *single* triple fitting the given parts and return the part |
176 |
|
marked X. If there is none, null is returned. If there are more than |
177 |
|
one, an exception is thrown. |
178 |
|
|
179 |
|
Only a single X may be used. |
180 |
|
|
181 |
|
findN |
182 |
|
Return an iterator iterating through the triples fitting the given parts, |
183 |
|
and return. Even if there are none, the iterator is created. |
184 |
|
Only a single X may be used. |
185 |
|
|
186 |
|
set1 |
187 |
|
Remove the other occurrences of the matching triples, replace them with the given |
188 |
|
new one. For example, if triples (a,b,c) and (a,b,d) and (a,e,d) are in the model, |
189 |
|
then after :: |
190 |
|
|
191 |
|
set1_11X(a, b, g) |
192 |
|
|
193 |
|
the model will have the triples (a,b,g) and (a,e,d). |
194 |
|
Only a single X may be used (restriction may be lifted in the future). |
195 |
|
|
196 |
|
rm |
197 |
|
Remove the matching triples from the model. Any amount of Xs may be used. |
198 |
|
|
199 |
|
and, after an underscore, the parameter scheme: |
200 |
|
|
201 |
|
1 |
202 |
|
Given |
203 |
|
X |
204 |
|
Requested / set |
205 |
|
|
206 |
|
The uniqueness exception |
207 |
|
------------------------ |
208 |
|
|
209 |
|
For debugging and possibly cool code hacks, the following error gives |
210 |
|
enough information to understand what was not unique. |
211 |
|
|
212 |
|
public class NotUniqueError extends Error { |
213 |
|
public final Object subject; |
214 |
|
public final Object predicate; |
215 |
|
public final Object object; |
216 |
|
} |
217 |
|
|
218 |
|
|
219 |
|
|