/[fenfire]/fenfire/docs/pegboard/swamp_rdf_api--tjl/peg.rst
ViewVC logotype

Diff of /fenfire/docs/pegboard/swamp_rdf_api--tjl/peg.rst

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 1.2 by tjl, Sun Apr 6 15:18:05 2003 UTC revision 1.3 by tjl, Mon Apr 7 10:53:06 2003 UTC
# Line 5  PEG swamp_rdf_api--tjl: Line 5  PEG swamp_rdf_api--tjl:
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
# Line 52  Issues Line 52  Issues
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  ==================  ==================
# Line 72  to be too object-oriented: I first thoug Line 100  to be too object-oriented: I first thoug
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    

Legend:
Removed from v.1.2  
changed lines
  Added in v.1.3

savannah-hackers-public@gnu.org
ViewVC Help
Powered by ViewVC 1.1.26