[oslc-core] Updated ChangeLog Proposal
Martin Nally
nally at us.ibm.com
Fri Mar 18 14:56:48 EDT 2011
A GET on https://.../ChangeLog needs to return the whole changelog, as
specified in the core spec. If the server doesn't think that's a good idea,
it can reply with a 302 redirect to the first page instead, as described in
the core spec, but it should not just unilaterally respond with the first
page. If the client doesn't want the whole changelog in one response, it
should do a GET on https://.../ChangeLog?oslc:paging=true instead. See
http://open-services.net/bin/view/Main/OslcCoreSpecification?sortcol=table;table=up#Resource_Paging .
There have been discussions at the W3C of ways of passing the fragment
identifier to the server in a header on GET - I'm not sure if there is a
spec. If that existed, then a server that was asked for
https://.../ChangeLog#b1 could decide to return a 302 redirect to the
changelog page that includes triples for b1.
Best regards, Martin
Martin Nally, IBM Fellow
CTO and VP, IBM Rational
tel: +1 (714)472-2690
|------------>
| From: |
|------------>
>--------------------------------------------------------------------------------------------------------------------------------------------------|
|Frank Budinsky/Toronto/IBM at IBMCA |
>--------------------------------------------------------------------------------------------------------------------------------------------------|
|------------>
| To: |
|------------>
>--------------------------------------------------------------------------------------------------------------------------------------------------|
|Martin Nally/Raleigh/IBM at IBMUS |
>--------------------------------------------------------------------------------------------------------------------------------------------------|
|------------>
| Cc: |
|------------>
>--------------------------------------------------------------------------------------------------------------------------------------------------|
|oslc-core at open-services.net, RELM Development |
>--------------------------------------------------------------------------------------------------------------------------------------------------|
|------------>
| Date: |
|------------>
>--------------------------------------------------------------------------------------------------------------------------------------------------|
|03/18/2011 02:39 PM |
>--------------------------------------------------------------------------------------------------------------------------------------------------|
|------------>
| Subject: |
|------------>
>--------------------------------------------------------------------------------------------------------------------------------------------------|
|Re: Updated ChangeLog Proposal |
>--------------------------------------------------------------------------------------------------------------------------------------------------|
Just like GET https://.../ChangeLog only returns the first page of the
ChangeLog, as opposed to the entire ChangeLog, presumably GET
https://.../ChangeLog#b1 would just return the particular page that b1 is
on. If so, I wonder if clients that request b1 might also likely request
some others, so given ETags, it might not be too bad to always return a
page worth of entries anyway. I guess the question is, what do we think the
use case for retrieving individual change entries is anyway?
Frank.
|------------>
| From: |
|------------>
>--------------------------------------------------------------------------------------------------------------------------------------------------|
|Martin Nally/Raleigh/IBM at IBMUS |
>--------------------------------------------------------------------------------------------------------------------------------------------------|
|------------>
| To: |
|------------>
>--------------------------------------------------------------------------------------------------------------------------------------------------|
|Frank Budinsky/Toronto/IBM at IBMCA |
>--------------------------------------------------------------------------------------------------------------------------------------------------|
|------------>
| Cc: |
|------------>
>--------------------------------------------------------------------------------------------------------------------------------------------------|
|oslc-core at open-services.net, RELM Development |
>--------------------------------------------------------------------------------------------------------------------------------------------------|
|------------>
| Date: |
|------------>
>--------------------------------------------------------------------------------------------------------------------------------------------------|
|03/18/2011 02:01 PM |
>--------------------------------------------------------------------------------------------------------------------------------------------------|
|------------>
| Subject: |
|------------>
>--------------------------------------------------------------------------------------------------------------------------------------------------|
|Re: Updated ChangeLog Proposal |
>--------------------------------------------------------------------------------------------------------------------------------------------------|
One more tiny tweak on this. In my example I used @prefix : <
https://.../ChangeLog#>. This causes the lists to have URLs like
https://.../ChangeLog#b1, https://.../ChangeLog#b2 and so on. This is OK,
and it would be the right thing to do for a changelog implementer who did
not want to bother with providing access to individual change entries,
because a GET of https://.../ChangeLog#b1 will actually do a GET of
https://.../ChangeLog, which is the whole changelog. A changelog provider
that wanted to allow clients GET access to individual entries would modify
this to be @prefix : <https://.../ChangeLog/>. This causes the lists to
have URLs like https://.../ChangeLog/b1, https://.../ChangeLog/b2 and so
on.. This provides convenient client access to individual changes (or
rather the list entries that reference them).
Best regards, Martin
Martin Nally, IBM Fellow
CTO and VP, IBM Rational
tel: +1 (714)472-2690
|------------>
| From: |
|------------>
>--------------------------------------------------------------------------------------------------------------------------------------------------|
|Frank Budinsky/Toronto/IBM at IBMCA |
>--------------------------------------------------------------------------------------------------------------------------------------------------|
|------------>
| To: |
|------------>
>--------------------------------------------------------------------------------------------------------------------------------------------------|
|Martin Nally/Raleigh/IBM at IBMUS |
>--------------------------------------------------------------------------------------------------------------------------------------------------|
|------------>
| Cc: |
|------------>
>--------------------------------------------------------------------------------------------------------------------------------------------------|
|oslc-core at open-services.net, RELM Development |
>--------------------------------------------------------------------------------------------------------------------------------------------------|
|------------>
| Date: |
|------------>
>--------------------------------------------------------------------------------------------------------------------------------------------------|
|03/18/2011 01:16 PM |
>--------------------------------------------------------------------------------------------------------------------------------------------------|
|------------>
| Subject: |
|------------>
>--------------------------------------------------------------------------------------------------------------------------------------------------|
|Re: Updated ChangeLog Proposal |
>--------------------------------------------------------------------------------------------------------------------------------------------------|
Hi Martin,
Very interesting idea. Instead of pages of "partial lists of change
entries", we have pages of "list entries". I guess it's a little harder for
clients to know when to check for a next page (i.e., a broken reference
ends the pages entries, instead of a nil reference) but otherwise it's much
cleaner.
> Pagination of this resource according to our standard algorithm is a
trivial exercise left to the reader.
Here it is, just to make sure I'm capable of doing the trivial exercise :-)
>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
>>>>>>>>>>>>>>>> PAGE 1
>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
@prefix oslc: <http://open-services.net/ns/core#> .
@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
@prefix : <https://.../ChangeLog#>.
<https://.../ChangeLog?oslc.paging=true>
oslc:nextPage <https://.../ChangeLog?pageno=2> .
<https://.../ChangeLog> oslc:changes :b1.
:b1 rdf:first
[ a oslc:create ;
oslc:changed <https://.../com.ibm.team.workitem.WorkItem/23> ;
oslc:at "103"^^xsd:int
] ;
rdf:rest :b2 .
:b2 rdf:first
[ a oslc:update ;
oslc:changed <https://.../com.ibm.team.workitem.WorkItem/22> ;
oslc:at "102"^^xsd:int
] ;
rdf:rest :b3 .
:b3 rdf:first
[ a oslc:delete ;
oslc:changed <https://.../com.ibm.team.workitem.WorkItem/21> ;
oslc:at "101"^^xsd:int
] ;
rdf:rest :b4 .
>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
>>>>>>>>>>>>>>>> PAGE 2
>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
@prefix oslc: <http://open-services.net/ns/core#> .
@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
@prefix : <https://.../ChangeLog#>.
<https://.../ChangeLog?pageno=2>
oslc:nextPage rdf:nil . <<<<<<<<< or omit the nextPage property
entriely
:b4 rdf:first
[ a oslc:create ;
oslc:changed <https://.../com.ibm.team.workitem.WorkItem/20> ;
oslc:at "100"^^xsd:int
];
rdf:rest rdf:nil .
Thanks,
Frank.
|------------>
| From: |
|------------>
>--------------------------------------------------------------------------------------------------------------------------------------------------|
|Martin Nally/Raleigh/IBM at IBMUS |
>--------------------------------------------------------------------------------------------------------------------------------------------------|
|------------>
| To: |
|------------>
>--------------------------------------------------------------------------------------------------------------------------------------------------|
|Frank Budinsky/Toronto/IBM at IBMCA |
>--------------------------------------------------------------------------------------------------------------------------------------------------|
|------------>
| Cc: |
|------------>
>--------------------------------------------------------------------------------------------------------------------------------------------------|
|oslc-core at open-services.net, RELM Development |
>--------------------------------------------------------------------------------------------------------------------------------------------------|
|------------>
| Date: |
|------------>
>--------------------------------------------------------------------------------------------------------------------------------------------------|
|03/18/2011 11:27 AM |
>--------------------------------------------------------------------------------------------------------------------------------------------------|
|------------>
| Subject: |
|------------>
>--------------------------------------------------------------------------------------------------------------------------------------------------|
|Re: Updated ChangeLog Proposal |
>--------------------------------------------------------------------------------------------------------------------------------------------------|
This may seem like a small, arcane point, but it's been bugging me. It
concerns pagination of the changelog.
OSLC's normal strategy for pagination is very simple and elegant. Every RDF
resource's state is composed of a graph of triples. "Graph" is just RDF's
name for what any middle-school math student would call a set (don't ask,
I've no idea). Sets can be divided arbitrarily into discrete subsets, so if
you want to paginate an RDF resource, all you do is divide up the triples
into discrete subsets and return each subset in the representation of a
page. The beauty is that the triples themselves are totally unchanged. The
Page itself is not the subject of any triples except nextPage (and maybe a
description).
The wrinkle in this approach is caused by blank nodes. Blank nodes cannot
be referenced outside the page they are on, so if any of those triples
includes a blank node as its subject or object, it has to go on the same
page (in the same subset) as every other triple that references the same
blank node. Because of the way RDF lists are represented, the lists
themselves are almost always blank nodes (a list has only two references,
to "first", which is a useful node, and to "rest" which is another list
containing the rest of the conceptual list). Because the blank nodes point
to each other in a chain, they cannot be split across pages, and so the
whole list ends up in the same page.
The way we resolved this in Frank's ChangeLog design was to make each page
of the changelog have a list of change entries. This clearly works, but it
means the triples for the pages are different from the triples for the
changelog itself, which is a more complex and less pleasing pattern.
It occurred to me this morning that there is a way to use our standard
pagination technique to paginate the changelog without introducing a new
mechanism. It works like this.
Normally the changelog whose URL is <https://.../ChangeLog#> looks like
this:
@prefix oslc: <http://open-services.net/ns/core#> .
@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
<https://.../ChangeLog>
oslc:changes (
[ a oslc:create ;
oslc:changed <https://.../com.ibm.team.workitem.WorkItem/23> ;
oslc:at "103"^^xsd:int
]
[ a oslc:update ;
oslc:changed <https://.../com.ibm.team.workitem.WorkItem/22> ;
oslc:at "102"^^xsd:int
]
[ a oslc:delete ;
oslc:changed <https://.../com.ibm.team.workitem.WorkItem/21> ;
oslc:at "101"^^xsd:int
]) .
This is Turtle shorthand for the following. Note that I'm not changing
anything here, I'm just expanding the shorthand:
@prefix oslc: <http://open-services.net/ns/core#> .
@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
<https://.../ChangeLog> oslc:changes _:b1.
_:b1 rdf:first
[ a oslc:create ;
oslc:changed <https://.../com.ibm.team.workitem.WorkItem/23> ;
oslc:at "103"^^xsd:int
].
_:b1 rdf:next _:b2
_:b2 rdf:first
[ a oslc:update ;
oslc:changed <https://.../com.ibm.team.workitem.WorkItem/22> ;
oslc:at "102"^^xsd:int
].
_:b2 rdf:next _:b3
_:b3 rdf:first
[ a oslc:delete ;
oslc:changed <https://.../com.ibm.team.workitem.WorkItem/21> ;
oslc:at "101"^^xsd:int
].
_:b3 rdf:next rdf:nil .
Since I have not changed anything, this still can't be paginated in the
usual manner. However, if I make the following change, it can be:
@prefix oslc: <http://open-services.net/ns/core#> .
@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
@prefix : <https://.../ChangeLog#>.
<https://.../ChangeLog> oslc:changes :b1.
:b1 rdf:first
[ a oslc:create ;
oslc:changed <https://.../com.ibm.team.workitem.WorkItem/23> ;
oslc:at "103"^^xsd:int
].
:b1 rdf:rest :b2
:b2 rdf:first
[ a oslc:update ;
oslc:changed <https://.../com.ibm.team.workitem.WorkItem/22> ;
oslc:at "102"^^xsd:int
].
:b2 rdf:rest :b3
:b3 rdf:first
[ a oslc:delete ;
oslc:changed <https://.../com.ibm.team.workitem.WorkItem/21> ;
oslc:at "101"^^xsd:int
].
:b3 rdf:rest rdf:nil .
Pagination of this resource according to our standard algorithm is a
trivial exercise left to the reader. The only special rule of pagination
for ChangeLog would be that the entries on a particular page are all older
than the entries on the previous page and younger than the ones on the
following page. This notation is slightly harder for a human to read than
Turtle's () notation, but is neither better nor worse for a computer to
read - it produces the same pattern of triples.
Note that this change causes https://.../ChangeLog#b1 through b3 to become
legitimate URLs. This does not necessarily mean that the OSLC implementer
has to honor a GET on these URLs - it's perfectly OK for the URLs to be
used in the list but not actually be independently GETable - but the
implementation may also choose to honor a GET. This also gives a different
and maybe more satisfactory way for a changelog to make a real resource out
of each change entry. Frank did the obvious thing of allowing the entry
itself to be a resource, but this creates some ambiguities and special
rules, as I pointed out in my last note. If instead it was the list nodes
that are given URLs, and the entries remain always as blank nodes, it might
be easier to understand. In practice, an implementation would be more
likely to use https://.../ChangeLog#b103 through https://.../ChangeLog#b101
as URLs for the lists corresponding to entries of the matching sequence
number.
Best regards, Martin
Martin Nally, IBM Fellow
CTO and VP, IBM Rational
tel: +1 (714)472-2690
|------------>
| From: |
|------------>
>--------------------------------------------------------------------------------------------------------------------------------------------------|
|Frank Budinsky/Toronto/IBM at IBMCA |
>--------------------------------------------------------------------------------------------------------------------------------------------------|
|------------>
| To: |
|------------>
>--------------------------------------------------------------------------------------------------------------------------------------------------|
|oslc-core at open-services.net |
>--------------------------------------------------------------------------------------------------------------------------------------------------|
|------------>
| Cc: |
|------------>
>--------------------------------------------------------------------------------------------------------------------------------------------------|
|Martin Nally/Raleigh/IBM at IBMUS, RELM Development |
>--------------------------------------------------------------------------------------------------------------------------------------------------|
|------------>
| Date: |
|------------>
>--------------------------------------------------------------------------------------------------------------------------------------------------|
|03/17/2011 11:57 AM |
>--------------------------------------------------------------------------------------------------------------------------------------------------|
|------------>
| Subject: |
|------------>
>--------------------------------------------------------------------------------------------------------------------------------------------------|
|Updated ChangeLog Proposal |
>--------------------------------------------------------------------------------------------------------------------------------------------------|
Hi All,
I've uploaded the latest version of the OSLC change log proposal here:
http://open-services.net/pub/Main/IndexingProposals/OSLC_indexing_0316.doc
It includes changes to reflect discussion and decisions made during the
first round of review, including the following:
A section to describe the motivating use case.
Description of a formal "Indexing Profile" which defines the
capabilities that a service provider MUST support in order to be
indexable.
Proposed formal scope of indexing/changeLog.
ChangeLog entry timestamps changed to sequence numbers.
ChangeLog entries can optionally be referenced URI-addressable
resources.
Please send comments and issues to the mailing list. We're also tentatively
scheduled to discuss this during the OSLC Core Workgroup call, next week,
so hopefully we can hash out most of the remaining issues by then.
Thanks,
Frank.
More information about the Oslc-Core
mailing list