When will I ever need to use @WebServiceRef?

Question

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?

Answer 1

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.

Answer 2

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:

• EJBs
• Servlets (under Servlet 3.0)
• JSF Managed Beans
• CDI Beans
• MDBs