[Gzz-commits] fenfire/docs/pegboard/swamp_rdf_api--tjl peg.rst

[Tuomas J. Lukka]

CVSROOT:        /cvsroot/fenfire
Module name:    fenfire
Changes by:     Tuomas J. Lukka <address@hidden>        03/04/07 06:53:07

Modified files:
        docs/pegboard/swamp_rdf_api--tjl: peg.rst 

Log message:
        More on this

CVSWeb URLs:
http://savannah.gnu.org/cgi-bin/viewcvs/fenfire/fenfire/docs/pegboard/swamp_rdf_api--tjl/peg.rst.diff?tr1=1.2&tr2=1.3&r1=text&r2=text

Patches:
Index: fenfire/docs/pegboard/swamp_rdf_api--tjl/peg.rst
diff -u fenfire/docs/pegboard/swamp_rdf_api--tjl/peg.rst:1.2 
fenfire/docs/pegboard/swamp_rdf_api--tjl/peg.rst:1.3
--- fenfire/docs/pegboard/swamp_rdf_api--tjl/peg.rst:1.2        Sun Apr  6 
11:18:05 2003
+++ fenfire/docs/pegboard/swamp_rdf_api--tjl/peg.rst    Mon Apr  7 06:53:06 2003
@@ -3,9 +3,9 @@
 =============================================================
 
 :Author:   Tuomas J. Lukka
-:Last-Modified: $Date: 2003/04/06 15:18:05 $
-:Revision: $Revision: 1.2 $
-:Status:   Incomplete
+:Last-Modified: $Date: 2003/04/07 10:53:06 $
+:Revision: $Revision: 1.3 $
+:Status:   Current
 
 This document outlines the main issues in the Jena api
 currently in use and proposes a lightweight api of our own
@@ -52,6 +52,34 @@
 
     RESOLVED: As immutable Literal objects, with several types of accessors.
 
+- What about literal typing? How do we support enfilades?
+
+    RESOLVED: For now, just get the raw string.
+
+- Do we want explicit Statement objects a la Jena?
+    
+    RESOLVED: No, they force a certain style of implementation which may not 
be the
+    most efficient. We need to minimize the number of Java objects created.
+    While an object for every resource and literal is just about unavoidable,
+    an object for each statement is not.
+
+- What would be the right characters for the search methods?    
+
+    RESOLVED: 1 for a given object, X for an unknown object. 
+    They are visually clearly separate, and X for the unknown is mnemonic.
+
+- Should bags, alts &c be supported explicitly in the API?
+
+    RESOLVED: Not yet. Many issues related e.g. to versioning.
+
+- That's a LOT of methods for all combinations. Couldn't we use wildcards
+  or something?
+
+    RESOLVED: No. It would be unnecessary inefficiency to look for them. 
+    Remember, this code is *the* inner loop. 
+
+    Quite likely code generation will be used.
+
 
 Problems with jena
 ==================
@@ -72,11 +100,120 @@
 that Statements and nodes were independent of the model. However,
 this was not the case.
 
+Efficiency is also important: in order for Fenfire to work properly,
+*ALL* searches within memory must be O(1). Jena makes no guarantees,
+since its goal is to support different implementations of Model.
+For us, the different implementations do not matter so much as raw
+efficiency of the memory-based implementation. This is quite different
+from most RDF uses, since the usual scenario is that there is not too much
+RDF (at least so far).
+
 Design
 ======
 
+The resource mapper
+-------------------
 
+The global resource mapper (has to be global since resources are 
model-agnostic)
+is simple: The name must be short because it's so widely used.
 
+    public class RMap {
+       public static Object toModel(String res);
+       public static Object toModel(String res, int offs, int len);
+       public static Object toModel(char[] res, int offs, int len);
+
+       public static String toString(Object res);
+
+       /** Append the string version of the resource to the given buffer.
+        * In order to avoid creating too many String objects
+        * when serializing a space, we
+       public static void appendToString(Object res, StringBuffer buf);
+    }
+
+The appendToString method solves one problem we had in Gzz:
+when saving, too many Strings were created for object names. Similarly, having
+the toModel method overloaded with different parameter types allows the most 
efficient
+creation of resources without conversions.
+
+We *may* want to make RMap internally redirectable in the future to allow
+alternate implementations; the static interface will not change.
+
+The model object
+----------------
+
+The ShortRDF class shows what a mess the query functions can easily become.
+To avoid this, we'll drop the semantics (subject,predicate,object) for now
+and name all methods according to a general scheme.
+
+    public interface ConstFirstOrderModel {
+       public Object find1_11X(Object subject, Object predicate);
+       public Object find1_X11(Object predicate, Object subject);
+       ...
+       public Iterator findN_11X(Object subject, Object predicate);
+       ...
+    }
+
+    public interface FirstOrderModel extends ConstFirstOrderModel {
+       public void set1_11X(Object subject, Object predicate, Object object);
+       public void set1_X11(Object subject, Object predicate, Object object);
+       ...
+
+       public void rm_1XX(Object subject);
+       public void rm_11X(Object subject, Object predicate);
+       public void rm_X11(Object predicate, Object object);
+       ...
+
+       /** Add the given triple to the model.
+        */
+       public void add(Object subject, Object predicate, Object object);
+    }
+
+The functions are built by the following format:
+first, the actual function type:
+
+    find1
+       Find a *single* triple fitting the given parts and return the part
+       marked X. If there is none, null is returned. If there are more than
+       one, an exception is thrown.
+
+       Only a single X may be used.
+      
+    findN
+       Return an iterator iterating through the triples fitting the given 
parts,
+       and return. Even if there are none, the iterator is created.
+       Only a single X may be used.
+
+    set1
+       Remove the other occurrences of the matching triples, replace them with 
the given
+       new one. For example, if triples (a,b,c) and (a,b,d) and (a,e,d) are in 
the model,
+       then after ::
+
+           set1_11X(a, b, g)
+
+       the model will have the triples (a,b,g) and (a,e,d).
+       Only a single X may be used (restriction may be lifted in the future).
+    
+    rm
+       Remove the matching triples from the model. Any amount of Xs may be 
used.
+
+and, after an underscore, the parameter scheme:
+
+    1
+       Given
+    X
+       Requested / set
+
+The uniqueness exception
+------------------------
+
+For debugging and possibly cool code hacks, the following error gives
+enough information to understand what was not unique.
+
+    public class NotUniqueError extends Error {
+       public final Object subject;
+       public final Object predicate;
+       public final Object object;
+    }