From the client side, if I want to access a web service, I would simply generate a proxy for it using wsimport. That is my web service reference.
Where then does the annotation @WebServiceRef come into play? Is it meant to be used at the server side only, to obtain injected references to web services hosted in the same environment?
Not necessarily, but it really is something that depends on the server implementation. e.g. To access a remote service, it requires to have access to generated client and optionally to the WSDL documents and schemes files (by convention
should be in WEB-INF/wsdl), so that
public class HelloServlet extends HttpServlet {
@WebServiceRef(HelloMessengerService.class) // class with @WebServiceClient
private HelloMessenger port; // the SEI
...
}
The HelloMessengerService class is the stub and has the @WebServiceClient annotation which has a
wsdlLocation attribute (points to local o remote WSDL document).
But you can have something like that
@WebServiceRef(wsdlLocation = "META-INF/wsdl/AnyService/Any.wsdl")
private HelloMessengerService service;
or
@WebServiceRef
public HelloMessengerService service;
If you use a handler chain to alter incoming and outgoing SOAP messages:
@WebServiceRef(HelloMessengerService.class)
@HandlerChain(file="handler-chain.xml")
private HelloMessenger port;
The use of the @WebServiceRef annotation must be applied to JAX-WS-managed clients, like a Servlet, EJB, or another Web service.
Just to add to Paul Vargas' answer, the @WebServiceRef annotation is a tool to complete the evolution of the Java EE platform to a wholly managed environment. Think about it this way:
Almost every component within the Java EE stack is injectable by some means, EJBs, JSF managed beans, CDI beans, @Resources etc. Why not be able to inject a webservice reference? With the ability to inject a webservice reference using this annotation, the following are ready injection targets:
