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 <f...@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
