[RFC] RDF metadata API draft

[Michael Stahl-3]

[X-posted to xml-dev & bibliographic-dev;
  please send reply to interface-discuss]

hello interface-discuss!

i am currently designing an API that would be used for implementing the
ODF metadata specification (part of ODF 1.2) [1].
this spec (and, consequently, this API) allows for attaching meta data in
RDF (Resource Description Framework [2]) to ODF packages, and to ODF
content elements.
so i would be especially interested in input from people who would like to
use ODF metadata: does this API do what you need?

[1]
http://www.oasis-open.org/committees/documents.php?wg_abbrev=office-metadata
[2] http://www.w3.org/RDF/

until now, i have tried to only put in stuff that i think is really
necessary. so this API is, in some sense, rather minimalistic.
a major missing feature would be inference based on schemas, whether RDFS
or OWL, but i am not sure whether we really need that?

another missing feature would be support for transactions. that would
depend on the backend anyway, and would be optional.

also, note that this stuff does not pass idlc yet...
oh, and please refrain from telling me i need to split this up into
multiple files, i _know_ that.

for some interfaces i cannot seem to come up with a name that i like.
i believe naming things adequately is important for usability of the API.
if someone can suggest a better name, i would be happy.
note that points for which input is especially valued are conveniently
marked with FIXME :)

i've dumped the draft API on the OOo wiki:
http://wiki.services.openoffice.org/wiki/Metadata_API

regards,
michael stahl


--
"Name ist Schall und Rauch."
  -- Johann Wolfgang Goethe, "Faust: Der Tragödie erster Teil" (3457)

---------------------------------------------------------------------
To unsubscribe, e-mail: interface-discuss-unsubscribe@...
For additional commands, e-mail: interface-discuss-help@...

[frank.schoenheit]

Hi Michael,

> so i would be especially interested in input from people who would
> like to use ODF metadata: does this API do what you need?

I don't know :), but have some other feedback (always "IMO")

- Pair< T, U > clearly belongs into css.beans
  (yes, that's nasty, since you need to add udkapi to your CWS then :)
- css.rdf is perfectly okay for the types - I wouldn't put them below
  another module, finally, the interfaces can probably be used for other
  purposes later.
- Re: "FIXME: hmmm, does it make sense to allow creating arbitrary blank
  nodes?"
  Not sure about "blank" here. Mozilla's API, which I used some year
  ago, has something like "createAnonymousNode", IIRC (My memory
  might *completely* fool me here). If that's a same as a "blank" node,
  then I think such a thing might be useful - at least I used anonymous
  nodes in my only encounter with RDF so far.
- Re "FIXME: would a base RDFException make sense?"
  I tend to answering "no" here, since transforming the question would
  be "Are there use cases where a client would be interested in catching
  the RDFException only, without evaluating the actual derived
  exception?" Since *all* information in all the RDF*Exceptions is in
  their type, and not in their members, I suppose there are no such use
  cases.
- RDF*Exception;
  If they all are in the namespace css.rdf, then the RDF in the name
  might be considered superfluous. For instance, the
  RDFRepositoryException could better be a
  css.rdf.(Illegal)RepositoryException, and the like.
- XRDFRepository::importGraph:
  I'd suggest throwing a WrappedTargetException here, instead of the
  IOException. IMO (but that might be only me) this better separates
  errors in the stream usage (i.e. an externally-supplied component)
  from "internal" errors, and errors in the arguments.
  Similar for other methods of this interface.

Ciao
Frank

--
- Frank Schönheit, Software Engineer         frank.schoenheit@... -
- Sun Microsystems                      http://www.sun.com/staroffice -
- OpenOffice.org Base                       http://dba.openoffice.org -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

---------------------------------------------------------------------
To unsubscribe, e-mail: interface-discuss-unsubscribe@...
For additional commands, e-mail: interface-discuss-help@...

[Stephan Bergmann]

Some more input:

> Hi Michael,
>
>> so i would be especially interested in input from people who would
>> like to use ODF metadata: does this API do what you need?
>
> I don't know :), but have some other feedback (always "IMO")
>
> - Pair< T, U > clearly belongs into css.beans
>   (yes, that's nasty, since you need to add udkapi to your CWS then :)

Agreed, beans might be suitable.

- Not sure if the modifying methods of XRDFNamedGraph are necessary (or
if they are only added to allow implementing XRDFRepository together
with an "alien" XRDFNamedGraph implementation; in which case some
private protocol between an XRDFRepository and the XRDFNamedGraph
objects it creates might be better)---but I am absolutely not a domain
expert with RDF.

- I vaguely remember I had some reason to consider UNOIDL constants,
esp. "complex" ones like strings or (not even implemented) structs, as
not useful, but unfortunately cannot remember the reason any longer...

- Minor stylistic stuff:
-- XRDFURI vs. XRdfUri etc. (I personally prefer the latter, but the
former is also widely used).
-- If you are in module rdf, the "RDF" in exception, interface, and
service names might be unnecessary.

-Stephan

---------------------------------------------------------------------
To unsubscribe, e-mail: interface-discuss-unsubscribe@...
For additional commands, e-mail: interface-discuss-help@...

[Juergen Schmidt-3]

Stephan Bergmann wrote:

> Some more input:
>
>> Hi Michael,
>>
>>> so i would be especially interested in input from people who would
>>> like to use ODF metadata: does this API do what you need?
>>
>> I don't know :), but have some other feedback (always "IMO")
>>
>> - Pair< T, U > clearly belongs into css.beans
>>   (yes, that's nasty, since you need to add udkapi to your CWS then :)
>
> Agreed, beans might be suitable.
>
> - Not sure if the modifying methods of XRDFNamedGraph are necessary (or
> if they are only added to allow implementing XRDFRepository together
> with an "alien" XRDFNamedGraph implementation; in which case some
> private protocol between an XRDFRepository and the XRDFNamedGraph
> objects it creates might be better)---but I am absolutely not a domain
> expert with RDF.
>
> - I vaguely remember I had some reason to consider UNOIDL constants,
> esp. "complex" ones like strings or (not even implemented) structs, as
> not useful, but unfortunately cannot remember the reason any longer...

as far as i remember they should be avoided especially string constants.
In C++ they become static strings and i remember a performance issue
with the static constructor.

Juergen

>
> - Minor stylistic stuff:
> -- XRDFURI vs. XRdfUri etc. (I personally prefer the latter, but the
> former is also widely used).
> -- If you are in module rdf, the "RDF" in exception, interface, and
> service names might be unnecessary.
>
> -Stephan
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: interface-discuss-unsubscribe@...
> For additional commands, e-mail: interface-discuss-help@...
>

--
Sun Microsystems GmbH        Juergen Schmidt
Nagelsweg 55                 Technical Lead Programmability
20097 Hamburg, Germany

Registered Office: Sun Microsystems GmbH, Sonnenallee 1, D-85551
Kirchheim-Heimstetten
Commercial register of the Local Court of Munich: HRB 161028
Managing Directors: Thomas Schroeder, Wolfgang Engels, Dr. Roland Boemer
Chairman of the Supervisory Board: Martin Haering

---------------------------------------------------------------------
To unsubscribe, e-mail: interface-discuss-unsubscribe@...
For additional commands, e-mail: interface-discuss-help@...

[Michael Stahl-3]

Hi Frank,

thanks for taking the time to review this!

Frank Schönheit - Sun Microsystems Germany wrote:
> Hi Michael,
>
>> so i would be especially interested in input from people who would
>> like to use ODF metadata: does this API do what you need?
>
> I don't know :), but have some other feedback (always "IMO")
>
> - Pair< T, U > clearly belongs into css.beans
>   (yes, that's nasty, since you need to add udkapi to your CWS then :)

ok.

> - css.rdf is perfectly okay for the types - I wouldn't put them below
>   another module, finally, the interfaces can probably be used for other
>   purposes later.

ok. (i thought maybe we already have too many top-level modules...)

> - Re: "FIXME: hmmm, does it make sense to allow creating arbitrary blank
>   nodes?"
>   Not sure about "blank" here. Mozilla's API, which I used some year
>   ago, has something like "createAnonymousNode", IIRC (My memory
>   might *completely* fool me here). If that's a same as a "blank" node,
>   then I think such a thing might be useful - at least I used anonymous
>   nodes in my only encounter with RDF so far.

hmm, the question was more like do we have a create() that can only
generate fresh and unique blank nodes, or create(String nodeid), which
would allow creating arbitrary blank nodes, even ones that already exist
in the repository (with potentially unintended aliasing effects).

but since we can hardly implement "fresh and unique blank nodes" in a
_service constructor_ that does not know any actual repository, the point
seems kind of moot.
or we introduce a factory at the repository just to be able to create
"fresh and unique blank nodes"...

> - Re "FIXME: would a base RDFException make sense?"
>   I tend to answering "no" here, since transforming the question would
>   be "Are there use cases where a client would be interested in catching
>   the RDFException only, without evaluating the actual derived
>   exception?" Since *all* information in all the RDF*Exceptions is in
>   their type, and not in their members, I suppose there are no such use
>   cases.

ok.

> - RDF*Exception;
>   If they all are in the namespace css.rdf, then the RDF in the name
>   might be considered superfluous. For instance, the
>   RDFRepositoryException could better be a
>   css.rdf.(Illegal)RepositoryException, and the like.

ok.

> - XRDFRepository::importGraph:
>   I'd suggest throwing a WrappedTargetException here, instead of the
>   IOException. IMO (but that might be only me) this better separates
>   errors in the stream usage (i.e. an externally-supplied component)
>   from "internal" errors, and errors in the arguments.
>   Similar for other methods of this interface.

hmm, good point. i had mistakenly assumed that the X*Stream methods throw
only IOException, but they actually throw 3 different exceptions.
err, wait a minute, on closer examination it seems that IOException is a
common supertype of all 3 exception types...
in _that_ case, i would argue that since X*Stream is a published, stable
interface, wrapping a WrappedTargetException around the IOExceptions
introduces an unnecessary indirection and obfuscation.

> Ciao
> Frank
>

mfg,
Michael

---------------------------------------------------------------------
To unsubscribe, e-mail: interface-discuss-unsubscribe@...
For additional commands, e-mail: interface-discuss-help@...

[Michael Stahl-3]

Stephan Bergmann wrote:
> Some more input:
>
[snip]
>
> - Not sure if the modifying methods of XRDFNamedGraph are necessary (or
> if they are only added to allow implementing XRDFRepository together
> with an "alien" XRDFNamedGraph implementation; in which case some
> private protocol between an XRDFRepository and the XRDFNamedGraph
> objects it creates might be better)---but I am absolutely not a domain
> expert with RDF.

if by "modifying methods" you mean addStatement, removeStatement, then
yes, those are the only methods that actually allow to change repository
contents :)

note that XRDFRepository and XNamedGraph implementations will be tightly
coupled and not interchangeable.
basically, XNamedGraph can be implemented as just the graph name and a
pointer to the underlying repository implementation.
note further that (hopefully) there is no method in either interface which
takes an object of the type as parameter :)

> - I vaguely remember I had some reason to consider UNOIDL constants,
> esp. "complex" ones like strings or (not even implemented) structs, as
> not useful, but unfortunately cannot remember the reason any longer...

stdin(905) : Missing type or illegal syntax following CONST keyword: parse
error

umm, strings are also not allowed as constants? argh...

> - Minor stylistic stuff:
> -- XRDFURI vs. XRdfUri etc. (I personally prefer the latter, but the
> former is also widely used).
> -- If you are in module rdf, the "RDF" in exception, interface, and
> service names might be unnecessary.
>
> -Stephan

mfg,
michael


--
"I hate leaving Windows95 boxes publically accessible, so shifting
  even to NT is a blessing in some ways.  At least I can reboot them
  remotely in a sane manner, rather than having to send them malformed
  packets." -- http://bofhcam.org/journal/journal.html, 20/06/2000

---------------------------------------------------------------------
To unsubscribe, e-mail: interface-discuss-unsubscribe@...
For additional commands, e-mail: interface-discuss-help@...

[Stephan Bergmann]

Michael Stahl wrote:

> Stephan Bergmann wrote:
>> Some more input:
>>
> [snip]
>>
>> - Not sure if the modifying methods of XRDFNamedGraph are necessary
>> (or if they are only added to allow implementing XRDFRepository
>> together with an "alien" XRDFNamedGraph implementation; in which case
>> some private protocol between an XRDFRepository and the XRDFNamedGraph
>> objects it creates might be better)---but I am absolutely not a domain
>> expert with RDF.
>
> if by "modifying methods" you mean addStatement, removeStatement, then
> yes, those are the only methods that actually allow to change repository
> contents :)

And it is intended that client code calls these modifying methods?
(This is still not clear to me from what you write.  I had initially
asked, because if the methods are not really needed for client use, it
might be better to make XRDFNamedGraph objects immutable.)

> note that XRDFRepository and XNamedGraph implementations will be tightly
> coupled and not interchangeable.
> basically, XNamedGraph can be implemented as just the graph name and a
> pointer to the underlying repository implementation.
> note further that (hopefully) there is no method in either interface
> which takes an object of the type as parameter :)
>
>> - I vaguely remember I had some reason to consider UNOIDL constants,
>> esp. "complex" ones like strings or (not even implemented) structs, as
>> not useful, but unfortunately cannot remember the reason any longer...
>
> stdin(905) : Missing type or illegal syntax following CONST keyword:
> parse error
>
> umm, strings are also not allowed as constants? argh...

Yep, looks like only a very restricted handful are allowed,
idlc/source/parser.y:1.17 l. 1552 ff.

-Stephan

---------------------------------------------------------------------
To unsubscribe, e-mail: interface-discuss-unsubscribe@...
For additional commands, e-mail: interface-discuss-help@...

[Michael Stahl-3]

Stephan Bergmann wrote:

> Michael Stahl wrote:
>> Stephan Bergmann wrote:
>>> Some more input:
>>>
>> [snip]
>>>
>>> - Not sure if the modifying methods of XRDFNamedGraph are necessary
>>> (or if they are only added to allow implementing XRDFRepository
>>> together with an "alien" XRDFNamedGraph implementation; in which case
>>> some private protocol between an XRDFRepository and the
>>> XRDFNamedGraph objects it creates might be better)---but I am
>>> absolutely not a domain expert with RDF.
>>
>> if by "modifying methods" you mean addStatement, removeStatement, then
>> yes, those are the only methods that actually allow to change
>> repository contents :)
>
> And it is intended that client code calls these modifying methods? (This
> is still not clear to me from what you write.  I had initially asked,
> because if the methods are not really needed for client use, it might be
> better to make XRDFNamedGraph objects immutable.)

yes, these two methods are basically the reason why we have this API :)

now, if XRDFNamedGraph is implemented as described below, then it would
indeed be immutable, and just forward the actual work to an underlying
implementation-specific repository object that is not immutable.

>> note that XRDFRepository and XNamedGraph implementations will be
>> tightly coupled and not interchangeable.
>> basically, XNamedGraph can be implemented as just the graph name and a
>> pointer to the underlying repository implementation.
>> note further that (hopefully) there is no method in either interface
>> which takes an object of the type as parameter :)

in other words, there is one underlying repository implementation object,
and this is represented in the api by one XRDFRepository object and a
bunch of XRDFNamedGraph objects.


--
"A programming language is low level when its programs require
  attention to the irrelevant." -- Alan Perlis

---------------------------------------------------------------------
To unsubscribe, e-mail: interface-discuss-unsubscribe@...
For additional commands, e-mail: interface-discuss-help@...