chemistry-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Florian Müller <f...@apache.org>
Subject Re: CmisService interface
Date Mon, 05 Sep 2016 15:55:29 GMT
Hi Michael,

I have a few replies. :)


> - A major version bump is an ideal moment to make breaking changes.
Unfortunately, the release machinery was already running when you sent 
this email.


> - Actually adapting to the changes might not be that much work.
The createDocument method of the ObjectService interface is used 34 
times in the OpenCMIS code base and we have 6 create methods...
Checking, changing, testing, and documenting this is not done in a day.


> There have been other breaking changes in the past.
No, not in this area. All major interfaces have been stable in the past 
5 years. Those interfaces have been extended (for example to support 
CMIS 1.1) and new interfaces have been added, but always backwards 
compatible. The recommendation for server developers was always to 
extend the abstract classes and not to implement the interfaces 
directly. If you have used the abstract classes, these interface 
extensions should not have broke existing code.
There have been refactorings of internal interfaces but those should not 
have affected OpenCMIS users on the client or server side.

There are several other place where I (personally) would like to correct 
and streamline interfaces that has been accumulated in the last years. 
If we do breaking changes, we should collect them in branch and release 
them together. Breaking a little bit here and a little bit there in 
every release doesn't seem to be a good idea.


> - The webservices binding is not recommended as it is not performant. 
> Also it is being deprecated in future versions of the spec.
That's true, but not really relevant for OpenCMIS interfaces.


> - There is no easy way to send "extensions" (e.g. per request http 
> query params) for atompub/browser binding. Changing the CmisService 
> might accommodate that.
That's right, but there might be other ways to address that without 
changing the interface.
For example, we could add a method that is responsible for building the 
response of a create call. In fact, such a method already exists for the 
Browser binding, but it is currently private.

(Technically, you are already in full control of the response with the 
ProgressControlCmisService interface. I wouldn't call it the "easy way", 
though.)


> - The TCK should also be able to test responses from servers that do 
> not use chemistry.
 From an OpenCMIS development perspective, the TCK tests both, the client 
and server, to ensure compatibility. It also should detect domain model 
issues on the server.
The TCK doesn't test the raw response. Testing if, for example, the 
content of a document is delivered Base64 encoded (hello SharePoint 
2010!) is not possible and not intended.

(Technically, you can implement a custom binding that is derived from 
the Browser binding implementation. It could use the OpenCMIS 
infrastructure and parsers and extract the response of a create call. 
It's doable, but it takes a moment to implement it.)


> Also, getObject might indeed return different results, depending on the 
> timing. For example due to transactions or db/backend calculated 
> fields. I actually encountered an
> issue with server responses in practice, that was not detectable with 
> the java client.
Ok, that's a use-case for the TCK that I can understand.


> - Always doing an extra call client side to get the object details may 
> hurt performance.
It's up to the client, if it needs the details of the created object. 
There is not always an extra call.
If a client wants the convenience of the high-level interface (for 
example the Document interface) then the extra call is necessary because 
it cannot tell the server what to return after a create call. You might 
call that a limitation of the CMIS spec, but today OpenCMIS has no other 
way. It cannot rely on the response of the server. It might not been 
complete.


> The webservices binding is holding the others back here.
No, this has nothing to do with WebServices. This about OpenCMIS 
backwards compatibility.
Emulating a response that just consists of a cmis:objectId property is 
easy.


> That the extra data is optional, should just mean the extra call is 
> optional.
> If the server returns what is needed, that should be enough.
The client cannot know if the server response is enough. Let's assume 
the server does not return an ACL after the create call. What does it 
mean?
It could mean that there is no ACL, but it could also mean that the 
server just didn't sent the ACL. The client can't decide. It has to call 
again and explicitly request the ACL.
If the server doesn't return an ACL, then there is no ACL. If the server 
returns a ACL, then it was omitted in the create call response.


- Florian


> Hi,
> 
> I have no issue requiring this change.
> However, over some time, several things lead me to think that this 
> would be
> a good thing to change.
> 
> Some thoughts:
> 
> - A major version bump is an ideal moment to make breaking changes.
> 
> - Actually adapting to the changes might not be that much work.
> For example for the create methods, server implementations would need 
> to
> wrap the string in an object. Clients would need to call getId. For 
> methods
> now returning void, servers could just return null.
> There have been other breaking changes in the past.
> 
> - The webservices binding is not recommended as it is not performant. 
> Also
> it is being deprecated in future versions of the spec.
> 
> - There is no easy way to send "extensions" (e.g. per request http 
> query
> params) for atompub/browser binding. Changing the CmisService might
> accommodate that.
> 
> - The TCK should also be able to test responses from servers that do 
> not
> use chemistry.
> Also, getObject might indeed return different results, depending on the
> timing. For example due to transactions or db/backend calculated 
> fields. I
> actually encountered an issue with server responses in practice, that 
> was
> not detectable with the java client.
> 
> - Always doing an extra call client side to get the object details may 
> hurt
> performance.
> The webservices binding is holding the others back here.
> That the extra data is optional, should just mean the extra call is
> optional.
> If the server returns what is needed, that should be enough.
> 
> I do also have a concrete issue, but will make a separate proposal for 
> it
> requiring less changes.
> 
> Michael
> 
> On Tue, Aug 23, 2016 at 2:22 PM, Florian Müller <fmui@apache.org> 
> wrote:
> 
>> Hi Michael,
>> 
>> Changing this interface is rather difficult. It is composed of other
>> interfaces that are the core interfaces for the client and server
>> implementations. Changing the interfaces would break a lot in the 
>> OpenCMIS
>> code and would break applications currently using these interfaces.
>> 
>> What we could do is introducing a new additional low-level interface 
>> for
>> the Browser binding (and the AtomPub binding), which contains the 
>> methods
>> in question with a slightly different name and a new return data type.
>> 
>> On the client side, you would then have the choice of calling the old 
>> or
>> the new method. On the server side, the OpenCMIS code could check if 
>> the
>> new interface is implemented and if so, calls the new instead of the 
>> old
>> method.
>> 
>> But that's a lot of work. Could you explain your problem with the 
>> current
>> approach?
>> 
>> I understand that testing with the TCK is restricted - but not really. 
>> The
>> OpenCMIS server calls getObject after it created the object and 
>> testing
>> getObject is possible with the TCK. This is only an issue if the 
>> server
>> returns different data when getObject is called twice for the same 
>> object.
>> On the client side, you may save one getObject call after a create 
>> call -
>> but not reliably.  Servers may not return all data. They are only 
>> forced to
>> return the cmis:objectId property. Everything else is voluntary and 
>> beyond
>> the control of the client. To be save, the client must call getObject.
>> 
>> From a generic client of view, I don't see much value in introducing 
>> this
>> new interface.
>> 
>> - Florian
>> 
>> 
>> 
>> Hi,
>>> 
>>> Can the CmisService interface be changed to be more in line with the
>>> browser binding?
>>> 
>>> For example, the create methods could return ObjectData instead of 
>>> String.
>>> Or, alternatively, they could return an ObjectId and the server
>>> implementation can choose to return only an id or a full object; 
>>> similar
>>> to
>>> what was done with PropertyDataWithDefinition.
>>> 
>>> In general the service methods could return all the needed 
>>> information to
>>> construct the browser binding response.
>>> 
>>> This could also help solve the client side issue that the java client
>>> cannot access the response from services, and thus that they cannot 
>>> be
>>> tested (e.g. in the TCK).
>>> 
>>> Michael
>>> 
>> 

Mime
View raw message