1.0rc1 WSDL issues (create node params)

[Dave Morris]

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.

1) CreateNode takes a mandatory target URI of the new node, rather than 
the optional string name.
The target URI cannot be null, and the service does not automatically 
generate new names.
It is up to the client to create and encode the target URI correctly.
If the server receives an invalid URI, it throws an Exception.

2) The two import methods also take a single URI parameter to identify 
the target node.
The target URI cannot be null, and the service does not automatically 
generate new names.
It is up to the client to create and encode the target URI correctly.
If the server receives an invalid URI, it throws an Exception.
If the target node already exists, then its contents will be replaced by 
the import.
If the target node does not exist, then the import methods will create a 
new node and import the data into that.
(this also implies that the <replace> flag is no longer needed either)

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