[Gzz] Swamp comments

[Benja Fallenstein]

> :Status:   Current, Partially preliminarily implemented (since in its own 
> package)

Current? There are at least three open issues?

Maybe we need a PEG state for 'put out for review, but not ready for 
being accepted'?

>     RESOLVED: Implicit observing, since we *can* wrap all parts
>     of the API without too much cost. If the API is non-object-oriented,
>     in the sense that the individual nodes and statements are not tied 
>     to any model/space, we only need to wrap O(1) objects.
>
>     Additionally, we can cheaply make "derived" models, 
>     e.g. when implementing the model_versions--tjl stuff.

What's a derived model? How is it related to observing? Why not 'Graph'?

> - How should resources and properties be represented?
>
>     RESOLVED: As hashable Objects with '==' comparison semantics.
>     The resources are mapped to and from Strings through a 
>     global resource name mapper / compressor.
>
>     We need to save memory and e.g. the URN-5 names
>     are too many and too long. The compressor would return either
>     strings with a prefix markup (i.e. a funny character and an index
>     to a prefix table) or an object with an integer (for the number part)
>     and an interned string for the shared part.
>
>     For properties and other such resources, interned strings should be 
> sufficient.

I think it would be a very bad idea if properties were represented in a 
different way than ordinary nodes, so that you'd need a converter from 
node to property...

Issue: How are anonymous nodes represented?

> - For returning multiple values, should we use Iterators or something
>   else?  ::
>
>       <benja> we could use Stepper-like stateful objects, or
>       <benja> have iterators with
>       <benja> a close() method or so
>       <benja> which allows the object to be re-used
>       <benja> so that graphs would cache a few, and only create new ones if too many in 
>       use simultaneously
>
>     Thinking.

(note: this is an inconsistent dedent; docutils should complain about 
it... you could put the '::' on the same level as 'Thinking.')

> - What about queries with more than one component? Say, "give me all triples",
>   or "give me all property-value pairs for the given subject node"

That question seems important.

This is a place where using Triple objects is nice...

>     public class Nodes {
>         public static Object get(String res);
>         public static Object get(String res, int offs, int len);
>         public static Object get(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.
>          */
>         public static void appendToString(Object res, StringBuffer buf);
>     }

We may also want methods to write a node to an OutputStream or Writer-- 
this would be more efficient than appendToString often.

> We *may* want to make Nodes internally redirectable in the future to
> allow alternate implementations; the static interface will not change.

I don't think this would be a good idea at all: it would mean that 
different users of the API couldn't use different implementations. A 
static interface shouldn't delegate.

>     public interface ConstGraph {
>         Object find1_11X(Object subject, Object predicate);
>         Object find1_X11(Object predicate, Object subject);
>         ...
>         Iterator findN_11X_Iter(Object subject, Object predicate);
>         ...
>     }

I'd prefer,

    get(subject, predicate, object)
    get_1XX(predicate, object)
    get_X11(subject)
    ...

    iter(subject, predicate, object)
    iter_1XX(predicate, object)
    ...

ISSUE: How do literals interact with this?

>     public interface Graph extends ConstGraph {
>         void set1_11X(Object subject, Object predicate, Object object);
>         void set1_X11(Object subject, Object predicate, Object object);
>         ...
>
>         void rm_1XX(Object subject);
>         void rm_11X(Object subject, Object predicate);
>         void rm_X11(Object predicate, Object object);
>         ...
>
>         /** Add the given triple to the model.
>          */
>         void add(Object subject, Object predicate, Object object);
>     }

I'd prefer,

    add(...)
    set(...)
    remove(...)

(similarity with Collections API)

>     rm
>         Remove the matching triples from the model. Any amount of Xs
>         may be used.

(trying to wrap my head around the characters -- shouldn't this be 'A'?)

> 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;
>     }
>
> The wildcards are set to null.

Could you give an example how this works?

> Literals
> --------
>
> For literals, we shall use immutable literal objects.

This doesn't really say enough. Do the find etc. methods above return 
literals? If so, how do I find out? Do I use 'instanceof Literal'? How 
do I find out something is *not* a literal? Do I use 'not instanceof 
Literal'? Can I search for a literal with a specific language tag?

I guess I can pass a Literal object to a find method, but I'd like this 
to be said here explicitly.

- Benja