Hi Alex On 08/23/2010 07:21 PM, Alex Busenius wrote:

Hi Anca,

On 08/23/2010 01:26 PM, Anca Luca wrote:

...

Hi Alex,

my notes below, sorry for the late response.

First, ObjectReference is supposed to have, as name, some sort of a string reference to the object inside the document (the ObjectReference has a DocumentReference as a parent). Now, since we didn't really agree what "string reference for the object" means (it could mean giving names to objects as we give to documents, it could mean some composed name of class name and index, etc), and this implied more discussions and design of the new model we decided to leave it like this, a "blank" position, unspecified name of object, where subclassers could implement their own object naming policy. Such a subclass is the IndexedObjectReference, which uses an object name made of class name and optional, index (if the index is missing it means 0). It's not in the platform because we didn't decide if this is the naming model for objects that we want (I can look for the mails). This approach works very well when the code that reads the references is the same that writes them (as the annotations case is), since it holds the sole responsibility of defining what an object name means. To be short, IndexedObjectReference is not an extension of the ObjectReference, as in containing more information, but just an implementation of the concept, based on the current model (objects are idd by classname and index), and in general a subclass (because it limits the forms that the name can take).

Thanks for the explanation. I looked at the discussion about object references back then, but it turned out to be very lengthy and without clear outcome.

Anyway seeing the reason for the current situation does not make it any better. There are basically 3 approaches to name an object,

1. Old one (wiki, space, page, class, index), which isn't supposed to be used any more 2. Free name for each object, which is still a wild idea right now 3. Current mix (document reference, class document reference, index)

From a practical point of view, ObjectReference seems to be useless no matter which approach is used, because it simply does not store enough information and/or does not provide any way to extract it out of the name.

yes, until we find out what an object name is, ObjectReference is just a concept, it cannot really be used.

When I wrote this proposal I tried to use the existing reference classes in a more convenient way, but it seems that at least object references must be changed to be more useful first.

...

On 29.07.2010 12:54, Alex Busenius wrote:

...

Hi devs,

It seems that currently there is no good way to manipulate XWiki objects and properties in documents without depending on old core. DocumentAccessBridge defines some methods for changing properties, but they are very limited, in particular, there is no way to:

* add a new property (except the first one) * set a property of n-th object (getting it is possible) * remove an object * get the number of objects

Therefore I propose to add the following methods to DocumentAccessBridge:

// returns index of the new object int addObject(ObjectReference obj) throws Exception;

In the light of what I wrote above, what would the ObjectReference contain in this case? More precisely, what name of object would you use?

My idea (since there was no clear recommendation in the docs) was to use the document reference to the target document as parent and class name as name. This is not enough to access a specific object, an additional index is needed for that.

but in this case you don't need to access a specific object, with the current implementation, since you don't know which index is next, you will get that one as a result. And btw, this function could return an (Indexed)ObjectReference, of the newly created object.

...

...

// returns false if there was no object, throws on access error boolean removeObject(ObjectReference obj, int index) throws Exception;

Index should not be here, object reference (as all references in general) should identify the item precisely, without the need of additional info. If it's an indexed object reference, the object name would contain the index as well.

Well, it should, but it doesn't, unless the implementation of this method would make a case distinction between supported reference types and extract the index out of the name somehow.

This is solved if DocumentAccessBridge uses IndexedObjectReferences.

...

...

// number of objects of the given class int getObjectCount(ObjectReference obj);

This does not make that much sense, since an object reference (as any reference) currently identifies an item and not a list of items, so this count would return 1 always. I think we discussed about this too in the mails (references referring lists), when we were still thinking that className and index should be part of the model, and that giving a class name would return a list, but with the currently adopted model it's no longer the case.

Indeed, it should be something like ObjectType or ObjectClass, and it is only needed if the objects are stored in an array.

...

...

// returns index of the object that was modified, adds a new object if // index is out of range int setProperty(ObjectReference obj, int idx, String prop, Object val) throws Exception;

There is PropertyReference, which has the propertyName as name and an ObjectReference as a parent, so this would be:

int setProperty(PropertyReference obj, Object val) throws Exception;

If there would be methods to do things like

ObjectReference obj = prop.getObject(); String class = obj.getClass().toString(); int index = obj.getIndex();

I would completely agree, but right now implementing such method would be quite difficult.

There should be. getObject is easy, it should be there, as for the others, if propertyReference is using IndexedObjectReference, they should also be there (and you'd need to cast first). Now, since this cast might not always be possible (the object of the property reference is not an indexed version) you can use one of these 2 interpretations, which both make sense to me: either the function throws an exception (IllegalArgument, since what it received was not of the expected type) or it behaves as if it could not understand the reference to the object, the object could not be identified (which would probably mean returning 0 or something).

...

...

// just to have all needed methods taking object reference Object getProperty(ObjectReference prop, int index, String propertyName);

same,

Object getProperty(PropertyReference prop);

...

I've chosen ObjectReference because it contains (almost) all needed information, including class name and document reference.

No, the ObjectReference does not contain the classname, see the explanations above. IndexedObjectReference, indeed contains the classname at one point.

Ok, ObjectReference is an abstract notion that represents a name that refers to a specific object in a document. The parent of an ObjectReference is a document reference, and the name is the abstract object name of undefined format. The only working implementation capable of actually accessing objects and properties uses an array of objects, named by their class name.

So the idea for implementations of methods that take ObjectReference and need to know the class name and index (since this is the only way that works)

I wouldn't restrict it to this, I would say, in general, functions that actually need to fetch the object, not only pass around a name of it. Fetch, in the current implementation, means indeed having a classname and an index.

is to explicitly handle the case for IndexedObjectReference and fail otherwise?

On second thought, I would say if it's an indexed reference that function will process, then the param should be an indexed reference. Otherwise it would be a real mess for the caller. I am thinking of a possible future situation when we actually implement some names for objects so ObjectReference will make sense. Now these functions would expect an object reference and not try to process the passed refs as indexed. It would break all the code that calls functions with indexed reference, with not too many warnings.

Does it also make sense for DocumentAccessBridge methods (they exist only to access old implementation and are supposed to be removed once a better alternative is there, until then the callers of those methods will have to use indexed reference)?

I would say yes, for the DocumentAccessBridge, since it does use the old model, in a way, it would be fine to use the indexed flavour of object reference. Happy coding, Anca

Alex

...

...

It would be better to have the object index stored in the reference too, like in org.xwiki.annotation.reference.IndexedObjectReference, but this class is annotation-specific.

We could decide to move it, but I would say, whenever the case allows it, to put ObjectReference in the APIs and only implement it with Indexed, so that API would be stable when we have indeed a model for the ObjectReference. It could cause mess for the caller, indeed, on changing the object name policy.

Happy hacking, Anca

...

I need those methods to store certificates in user profile, see https://svn.xwiki.org/svnroot/xwiki/contrib/sandbox/xwiki-signedscripts

WDYT?

Thanks, Alex _______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs

_______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs

_______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs