Paul Harrison wrote:
> On 14.06.2006, at 14:01, Dave Morris wrote:
>
>> However, when creating a new node, it was agreed that the client
>> would supply the name as a plain text string, and the server would
>> convert this into the URI encoded identifier.
>> This means that the server side code does the URI encoding, making
>> it easier to verify that we get it right.
>
>> The operations that create a new node (CreateNode, PushDataTo and
>> PullDataTo) take the name of the new node, not the identifier.
>> This gives us a way of distinguishing between import into an
>> existing node (node URI) and import into a new node (node name).
>
> also I think that there was also the idea that the server would
> generate a name automatically so the URI could point to a container...
>
>> The distinction still isn't as clear as I would like, but that is
>> what is in the current document.
>> If we want to change this, then we will need to modify the document.
>
> I think that the semantics of these operations are not still clear as
> currently implemented in the WSDL, and do need some work
I too was struggling with how to represent these multiple parameters in the experimental WSDL examples I posted last week. If they are causing problems, do we want to look at these again, and possibly simplify them.
Server generated identifiers :
The original reason for server generated identifiers dates back to when
we had two separate namespaces, VOSpace with user defined names, and
VOStore with server generated names.
The VOStore service needed to generate the names in order to ensure that
they were unique within that service.
Now that we have brought everything into one VOSpace namespace, I don't think we need the server generated names any more. In which case, unless anyone has a compelling use case for this, I vote we drop it.
Plain string name :
I proposed the idea of using the separate name and URI in methods that
created nodes, primarily because I wanted to make the server responsible
for encoding the URI correctly.
The client would just supply the name as a plain text string, and the
server would encode it to create the full URI identifier.
However, both of us have found problems trying to define a clear and concise WSDL that distinguishes between an import operation that creates a new node and one that imports data into an existing node. In which case, it looks like having the separate name parameter for creating a new node is causing us more problems than it is worth.
For VoSpace-1.0 I propose we drop both the server generated names and the separate name as string parameter.
Then, to make things symmetrical :
3) MoveNode takes two URIs, representing the source and destination.
The source URI cannot be null and must point to an existing node.
The destination URI cannot be null, and must NOT point to an existing node.
If a node already exists with the destination URI, then the method
throws a DuplicateNodeException.
It is up to the client to create and encode the destination URI correctly.
If the server receives an invalid URI, it throws an Exception.
4) CopyNode takes two URIs, representing the source and destination.
The source URI cannot be null and must point to an existing node.
The destination URI cannot be null, and must NOT point to an existing node.
If a node already exists with the destination URI, then the method
throws a DuplicateNodeException.
It is up to the client to create and encode the destination URI correctly.
If the server receives an invalid URI, it throws an Exception.
To support client encoded URIs :
5) We need to add MalformedIdentifierException to the list of exceptions for all the methods that take URI parameters.
Hopefully, this should make the service API and WSDL a lot clearer.
One caveat :
I would like to re-visit this when we look at v2.x, based on what we
find using v1.0 in real applications.
Matthew is right when he says that if we have any changes we should be discussing them in the document, and not the WSDL. The WSDL should reflect the specification as defined in the document, presenting it in a machine readable form.
So, based on the fact that both Paul and I have both found problems in creating a clear and concise WSDL to represent this part of the specification and that the original use cases for the extra parameters are either no longer valid or not worth the hassle. I propose we make the above changes to the specification document, and then update the WSDL to match.
Guy, Matthew, and Paul can you reply with 'accept' or 'reject' for the
five changes outlined above.
If everyone says yes, then we can update the document tomorrow and
publish it as v0.22.
I know this is a bit formal and possibly OTT, but I suspect that we will be making quite a few changes like this over the next few days. Making specific requests for individual changes to the document should make it easier to keep track of everything.
I know there is at least one case where I found the list of exceptions
was wrong on one of the methods, but right now I can't remember where it
was.
If I find it again I'll post another change request with the details.
There are also a couple of questions / suggestions I would like to raise
regarding data types and formats.
I'll post another change request when I have worked out the details.
Thanks,
Dave
Received on 2006-06-15Z02:54:25