Idea for improving HelloWorld WS sample's educational value

[Scott Kurz <sc...@gmail.com>]

A confusing aspect of the HelloWorld WS sample is the fact that certain
strings are repeated
in different contexts.   For example, looking at "HelloWorld WS Client", one
can see four
distinct usages of the string, "HelloWorldService".

1.  It is the name of the client-side SCA service, which is invoked by the
HelloWorldClient main() program.
2.  It is the type of the reference variable used in
HelloWorldServiceComponentImpl to invoke the ES over the WS binding
3.  It is the name of the externalService appearing in sca.module:
           <externalService name="HelloWorldService">
4.  It appears in the client-side WSDL URL in order to match the deployment
location of the EP-side Hello World WS WAR
           <wsdlsoap:address location="
http://localhost:8080/helloworldws-SNAPSHOT/services/HelloWorldService"/>

It is certainly instructive that you can overload the string in this way.
However, it is at the same time confusing to a
completely new user as he has to sort out which appearances of the
"HelloWorldService" string need to stay in synch
with which other uses, and which do not.

It might be educational to also provide a flavor of the HelloWorld WS sample
in which distinct names are used in each of these four locations,
e.g.:

HelloWorldClientService
HelloWorldWSInterface
HelloWorldES
HelloWorldService

Another alternative would be to include in the documenation and exercise
instructing the user to do just this.

Re: Idea for improving HelloWorld WS sample's educational value

[Jean-Sebastien Delfino <js...@apache.org>]

Scott Kurz wrote:
> A confusing aspect of the HelloWorld WS sample is the fact that certain
> strings are repeated
> in different contexts.   For example, looking at "HelloWorld WS Client", one
> can see four
> distinct usages of the string, "HelloWorldService".
>
> 1.  It is the name of the client-side SCA service, which is invoked by the
> HelloWorldClient main() program.
> 2.  It is the type of the reference variable used in
> HelloWorldServiceComponentImpl to invoke the ES over the WS binding
> 3.  It is the name of the externalService appearing in sca.module:
>            <externalService name="HelloWorldService">
> 4.  It appears in the client-side WSDL URL in order to match the deployment
> location of the EP-side Hello World WS WAR
>            <wsdlsoap:address location="
> http://localhost:8080/helloworldws-SNAPSHOT/services/HelloWorldService"/>
>
> It is certainly instructive that you can overload the string in this way.
> However, it is at the same time confusing to a
> completely new user as he has to sort out which appearances of the
> "HelloWorldService" string need to stay in synch
> with which other uses, and which do not.
>
> It might be educational to also provide a flavor of the HelloWorld WS sample
> in which distinct names are used in each of these four locations,
> e.g.:
>
> HelloWorldClientService
> HelloWorldWSInterface
> HelloWorldES
> HelloWorldService
>
> Another alternative would be to include in the documenation and exercise
> instructing the user to do just this.
>
>   

Great idea! Could you please create a JIRA issue for this? I think we 
should make these changes now for our May release. The more we can do to 
improve and simplify the samples the better. Do you already have a 
variation of the sample with your changes that you would like to contribute?

-- 
Jean-Sebastien