Created attachment 64368 [details]
Architecture document of the WebServices Project API

Created attachment 64369 [details]
JavaDoc of the Web Services Project API

Created attachment 64372 [details]
Netbeans module of Web Service Project API

I suggest Milos Kleint from the core team, Martin Grebac and Lukas Jungman. That would be good to have somebody from
REST - I suggest Peter Lieu.  

Some initial comments/questions (my web services knowledge is limited and that may explain some of my questions):

DK00: my main question is what useful can client do with this API? I read your usecases from ach document and your
WebServicesProjectApi page but having WebService instance I can show its node somewhere in UI but apart from that what
else can I do? There is a location in ServiceDescriptor but what does it point to?

DK01: WebServiceData implements hashCode and equals but are they really needed for something useful?
    
DK02: WebServiceData: should say which property changes you can listen to

DK03: WebService: if service is not isServiceProvider() then what is it? clarify Javadoc please.

DK04: are getRuntimeLocation and getRelativeURI mutually exclusive in ServiceDescriptorImplementation? if yes then
perhaps just one method returning possibly relative or absolute remote URI should be enough

DK05: ServiceDescriptor.getIdentifier - not sure what useful this would be for

DK06: WebServiceImplementation.getNode - I'm not sure about usage of Node in API; in general I do not think it is good
idea as clients do not have any control over the node appearance and its children and actions. But perhaps in this case
it is acceptable as node == service. Alternative implementation would be to have service descriptor class (containing
eg. service name, service icon, list of names of services provided, etc.) and client could build a node from descriptor
the way it suits them.

Thank You for the comment.
I'll try to answer some questions as I am a co-writer of those classes.
DK00: The API is designated for those who want to find web services and what WS Consumers (Clients) that are implemented
in a project.
The typical usecase :
Somebody wants to create a web service client for some web service implemented in a project.
1. WebServiceData.getWebServiceData(Project p); will be used to obtain WebServiceData object
2. WebServiceData.getServiceProviders(); will be used to find all Web Services implemented in project
   Note: WebServiceData.getServiceConsumers() is intended to obtain all WS Clients (consumers)
3. WebService.getServiceType(); is used to distinguish between SOAP and REST service.
4. WebService.getServiceDescriptor().getRuntimeLocation(); will be used to obtain the URL of WSDL(SOAP) or WADL(REST) file.
5. Finally the API client is able to create a web service client against the WSDL or WADL file.

DK01: The purpose of hashCode/equals is that there might be several instances of WebServiceData object that delegate to
one WebServiceDataProvider instance (the result of the LookupMerger class).  There is a legitimate requirement to handle
these multiple instances as the "same" object.

DK02: right this should be specified in javadoc. Another option is to implement a specific WebServiceListener with the
specific methods:
 - webServiceAdded(WebService service);
 - webServiceRemoved(WebService service);
 - webServiceChanged(WebService service);
 
DK03: right isServiceProvider() method distinguish Web Service(WS Provider) from Client. It might be a little confusing
with WebServiceDataProvider class.
DK04: no, those methods can return different locations : 
      - getRuntimeLocation() is the target location of WSDL/WADL file on the server for either Web Service or Client
      (for web service it is computed from the target server selected in project)
      - getRelativeURI() is the URI of WSDL/WADL in a project (e.g.
/xml-resources/web-services/HelloService/wsdl/HelloService.wsdl)
      - getRuntimeLocation(); may be renamed to getServerLocation();
DK05: Rico, please, explain this, it's also not clear to me.
DK06: I tend to agree with you. I think, the idea was to use this API to implement the NodeFactory for web services in
projects.

re DK05: should represent unique identifier for one particular service/client since getNode().getDisplayName() (which
could be also good candidate for this purpose) cannot be used - there can be two or more services/clients which will
have same getNode().getDisplayName()

re DK06: getNode() is there to be a helper when one wants to build UI - there are now three use-cases:
 1) display webservices/clients in project UI
 2) call ws operation dialog (show all web service clients from all opened projects from which are able to produce a jar
- Java SE, EJB)
 3) create new ws client wizard (show all web services from all opened projects)

 Ideally there should be one helper factory method for this purpose but the problem here is that there are currently 3
implementors of this (JAX-RPC, JAX-WS, Axis) and each of them needs to provide different icon, set of actions and lookup
content for its node and client of this API should be able to build UI from all these nodes.

DK01: can you describe usecase when equals/hashCode would be useful please. The way I see it is: user has one of more
projects; for each project they ask for WebServiceData; they perform some operations on WeSeDa; done.

DK03: still not sure what you mean; clarify that in Javadoc please

DK04: would it make sense to make methods more self-descriptive, eg. getServerWSDLLocation(); getProjectWSDLLocation();
and variations with WADL? or perhaps it could be just getRemoteDescriptorFile() and getLocalDescriptorFile() with
Javadoc saying it will be WADL for REST type and WSDL for .... etc. Btw. if they are not mutually exclusive than which
one should client use if both of them are available?

D01: the reason for WebServiceData (final class that delegates to WebServiceDataProvider) is separating SPI from API.
     SPI provider is putting WebServiceDataProvider instance into project lookup - so there is one
WebServiceDataProvider per project. The idea of equals/hashCode was to have "one" WebServiceData (API) object per
project as well. Though, I currently don't have any reasonable use case, for equals(), in my mind, I think it's a good
practice. And hashCode() should by implemented together with equals(). We can discuss that on review meeting.
David, I'd appreciate you to take part in the review meeting.

DK04: the names of the methods can be discussed on the meeting. 
To explain the difference: during the deployment, j2ee server creates the port information (URL for Web Service) and
inserts this information to WSDL/WADL file.

"Abstract" WSDL/WADL is the WSDL/WADL without the port information : this file is usually located somewhere in the project.
"Runtime" WSDL/WADL is one containing the final port information: this is available on web server through some URL.

There are use cases for both methods :
1. to create web service client from some WSDL/WADL, the Runtime WSDL/WADL is required.
   (for this case getRuntimeLocation() will be used)
2. To customize the service/client the "abstract" WSDL/WADL file will be used
   (getRelativeURI() will be used)
3. In SOA (BPEL) application web services are "orchestrating" based on "abstract" WSDL files (WSDL where the port
information is not assigned yet (getRelativeURI() will be used).

Planning to set up a review meeting on Wednesday next week (07/23) at 9am PDT (18:00 CET).

Suggesting these reviewers :

Peter Liu (REST)
Ayub Khan (REST)
Martin Grebac (METRO)
David Konecny (J2EE projects)
Milos Klient (core)
Lukas Jungmann (QE)

This API is labelled as "Web Services Project API" but it does not cover complete WS integration with project type,
right? There is whole area of additional WS project API like WebServicesSupportImpl, JAXWSSupportImpl,
JAXWSClientSupportImpl, WebServicesClientSupportImpl, etc. Is there any plan to do something with these APIs or not? Why
I'm asking is that some of them are referring in method signatures directly to classes like AntProjectHelper which makes
API unusable for non-AntProjectHelper based project types like Maven for example.

Right, This API is a high level API that will be implemented on the top of those APIs.
See the example where WebServiceDataProvider is iplemented using JAXWSSupport.
( http://wiki.netbeans.org/WebServicesProjectApi )
Yes, we count with Maven Projects where the AntProjectHelper isn't relevant.

Obsolete?