[xwiki-dev] Difference Engine Refactoring and Improvements

[Ludovic Dubost]

Vincent Massol a écrit :
>
> On May 2, 2007, at 10:13 AM, Ludovic Dubost wrote:
>
> [snip]
>
>>>
>>> I don't understand. I would have used something like:
>>>
>>> List<Difference> getDifferences(XWikiDocument, XWikiDocument)
>>> List<Difference> getDifferences(XObject, XObject)
>>> List<Difference> getDifferences(String, String)
>> Ok.. I can look at changing these APIs. However the return of 
>> getDifferences(XWikiDocument,XWikiDocument) or 
>> getDifferences(XObject, XObject) can be quite complex in terms of 
>> Java structure.
>
> Without thinking a lot about it, I would see something like this for 
> the Difference object:
>
> - Context information (String). This would be the property for example 
> when comparing 2 objects. It could be "page" when comparing the 
> content of a page, etc.
> - Old value (String).
> - New value (String).
> - Location: some information where the change appears, possibly also 
> the text surrounding the difference, etc
>
> I think we need both StringDifference and ObjectDifference which both 
> implement Difference, so getDifferences(XWikiDocument, XWikiDocument) 
> would return a list of both, getDifferences(XObject, XObject) would 
> return a list of ObjectDifference and getDifferences(String, String) a 
> list of StringDifference.
>
We already have a glimpse of this in the current code

public class ObjectDiff extends Object
public class MetaDataDiff extends Object

and we have some function which construct a JRCS Delta object with 2 
strings..

I don't think we necessarly need more than that because which you seem 
to ask would move presentation decisions inside the APIs or would make 
the API results more complex than actually needed.
We could still do it with the current APIs. We could add a ContentDiff 
object and implement a Diff interface for all three objects
This interface would have a function to return a "presented" diff for 
Objects, MetaData and Content.
All three would rely on a velocity template for the presentation 
(diffcontent.vm diffmetadata.vm diffobject.vm)
This would simplify the default changes page which would only call the 3 
diffs with the parameters..
The ContentDiff object could have some constructors to decide wether the 
Diff is Wiki or Rendered, if it's showing changes only or the whole 
document..

>>> Also, I think it's critical that in an API we should only use our 
>>> own classes/interfaces and no external ones, so I think we should 
>>> have our own Difference class and not use JRCS'. It could possibly 
>>> wrap it if necessary.
>>>
>> The wrapping would require quite a lot of cloning work. The result of 
>> the JRCS engine is a Delta object which contains a list of Chunks 
>> which contains a list of Strings. These objects are quite plain.
>> I would not see what to do except completely cloning them and write a 
>> copy function from JRCS to XWiki.
>
> What about the Difference object as summarily described above? If 
> internally we have JRCS objects, we could always construct our own 
> Difference object, no? I think it's really much safer from an API 
> point of view as we're not convinced we'll stay with JRCS I think. 
> Also (and even more importantly) the interface is meant so that 
> someone else can implement a different diff algorithm. I'm not sure it 
> would be good to force them to use JRCS objects, especially as we 
> don't control JRCS.
What the JRCS objects contain we need to make a great diff 
presentation.. The object is not that simple and I don't see how it 
would be different.. It's only good for a text diff.
>
> I haven't looked at the current API. I guess we could keep a 
> XWikiDocument getDifferences(XWikiDocument) api in XWikiDocument. It 
> would use the Diff plugin.

I'm not sure what to do with the current APIs in XWikiDocument. Some are 
still useful but could be moved to the DiffPlugin. Some would now be 
hidden as private methods in the DiffPlugin..
>
> We're talking about the same thing. I also prefer a wiki markup diff. 
> I was under the impression that the current diff representation was a 
> rendered version of the textual diff.
Yes currently it's the case. I think it can often break display. There 
are URL params to change the behavior.. In the new skin they are no 
links anymore to switch to wiki view for example.

Ludovic

-- 
Ludovic Dubost
Blog: http://www.ludovic.org/blog/
XWiki: http://www.xwiki.com
Skype: ldubost GTalk: ldubost 
AIM: nvludo Yahoo: ludovic