Java

Concepts [1]:

• WebService: "Web services are network applications that use SOAP and WSDL to exchange information in the form of XML documents".
  Web services are truly platform-independent. Although Java RMI and CORBA IIOP also claim to be platform-independent, in fact these older technologies require their own platforms. To use Java RMI, you need a Java virtual machine and the Java programming language; a program written in Visual Basic or C++ can't interact with a Java program using RMI;
• SOAP 1.1: Simple Object Access Protocol (SOAP) is an XML grammar, developed by Microsoft, IBM, and others, that is currently under the auspices of the W3C. It's an application protocol used in both RPC and asynchronous messaging. SOAP is very flexible and extensible and, unlike its predecessors (DCE RPC, CORBA IIOP, Java RMI-JRMP, and DCOM), it's been endorsed and adopted by just about every major vendor. (If you're not familiar with XML, see Java and XML or XML in a Nutshell, both from O'Reilly.);
• WSDL 1.1: The Web Service Description Language (WSDL) is another XML grammar, developed by Microsoft and IBM under the auspices of the W3C. It is an XML-based Interface Definition Language (IDL) that can be used to describe web services, including the kind of message format expected, the Internet protocol used, and the Internet address of the web service;
• Service endpoint interface or service endpoint implementation (SEI): is a Java interface or class, respectively, that declares the methods that a client can invoke on the service. An interface is not required when building a JAX-WS endpoint. The web service implementation class implicitly defines an SEI.
• JAX-WS: Java API for XML Web Services (aka "big webservices");
• JAX-RS: Java API for RESTful Web Services;

---

Building Web Services with JAX-WS

Information extracted from the official JavaEE 6 tutorial:
Java API for XML Web Services (JAX-WS) is a technology for building web services and clients that communicate using XML. JAX-WS allows developers to write message-oriented as well as Remote Procedure Call-oriented (RPC-oriented) web services.

In JAX-WS, a web service operation invocation is represented by an XML-based protocol, such as SOAP. The SOAP specification defines the envelope structure, encoding rules, and conventions for representing web service invocations and responses. These calls and responses are transmitted as SOAP messages (XML files) over HTTP.

Although SOAP messages are complex, the JAX-WS API hides this complexity from the application developer. On the server side, the developer specifies the web service operations by defining methods in an interface written in the Java programming language. The developer also codes one or more classes that implement those methods. Client programs are also easy to code. A client creates a proxy (a local object representing the service) and then simply invokes methods on the proxy. With JAX-WS, the developer does not generate or parse SOAP messages. It is the JAX-WS runtime system that converts the API calls and responses to and from SOAP messages.

With JAX-WS, clients and web services have a big advantage: the platform independence of the Java programming language. In addition, JAX-WS is not restrictive: A JAX-WS client can access a web service that is not running on the Java platform, and vice versa. This flexibility is possible because JAX-WS uses technologies defined by the W3C: HTTP, SOAP, and WSDL. WSDL specifies an XML format for describing a service as a set of endpoints operating on messages.

---

Tools

---

Tutorials:

• Official Java Web Services Code Samples
• Official JavaEE6 tutorial (JAX-WS Webservices) (RESTfull Webservices with JAX-RS)
• How to create and consume a simple Web Service using JAX WS
• JAX-WS Five Minute Tutorial
• JAX-WS Hello World Example – RPC Style

---

Developing JAX-WS web services

1. Create the webservice class
   The starting point for developing a JAX-WS web service is a Java class annotated with the javax.jws.WebService annotation.
   The @WebService annotation defines the class as a web service endpoint.
   
   If you use Netbeans:  Right-click project -> New -> Webservice
   If you create the Webservice this way Netbeans will generate all the stub files needed to deploy it (and so you can skip the next step).
   
   Ex. webservice class:
   

   @WebService(serviceName = "BookSearchWS")
   public class BookSearchWS {
       @WebMethod(operationName = "procuraLivros")
       public List<Livro> procuraLivros(
               @WebParam(name = "queryTitulo") 
               String queryTitulo,
               @WebParam(name = "numPaginasAPesquisar") 
               int numPaginasAPesquisar) {
           BookSearchXML bookSearch = new BookSearchXML();
           return bookSearch.pesquisaLivrosNoGoogle(queryTitulo, numPaginasAPesquisar);
       }
   }

    
2. Generate Webservice stubs
   If you used Netbeans to create the Webservice class you can skip this step.
   
   In order to publish our class and its methods as web service we need to create appropriate stub files or artifacts for web service deployment and invocation. Fortunately Java provides a tool called "wsgen" which generates JAX-WS portable artifacts used in JAX-WS web services.
   You can use it through a console to generate the stub files using commands like:
   wsgen -cp bin -d bin com.theopentutorials.ws.calc.Calculator
    
3. Deploy the Webservice project to your application Server (ex. GlassFish)
   
   OR
   
   alternatively, if you don't want to use and application Server and just want to test your webservice you can use the static publish() method of the javax.xml.ws.Endpoint class to publish the class as a web service in the specified context root. Run that class as ‘Java Application’. When you run the application, the Java SE 6 platform has a small web application server that will publish the web service at the specified address while the JVM is running (see this tutorial for more instructions on this).
    
4. Test the webservice, see if its correctly deployed and working:
   If the webservice was deployed at:
   http://localhost:8080/BookSearchWebservice/BookSearchWS
   
   Add "?wsdl" to the url (if you can see the wsdl xml then the Webservice is correctly deployed)
   Ex.: http:// localhost :8080/BookSearchWebservice/BookSearchWS?wsdl
   
   If you are using glassfish application server you can add "?tester" to the url to test the webservice
   Ex.:  http://localhost:8080/BookSearchWebservice/BookSearchWS?tester()
    
5. Generate the client stubs (from the WSDL file)
   If you use Netbeans: Right-click project -> New -> Web Service Client...
   Netbeans uses the the jdk tool wsimport but you can also use it directly without Netbeans:
   This tool takes the webservice wsdl has parameter and generates java classes to allow the client to communicate with the webservice. After generation copy the generated package into your client project.
   
   Open a Console and type a command like:
   wsimport -verbose -keep http://localhost:8080/BookSearchWebservice/BookSearchWS?wsdl
   Notes: the "-keep" option leaves the java source code, otherwise they will be deleted leaving only the compiled classes.
    
6. Build the client
   Use the generated classes in the client to communicate with the ws.
   Ex. (red classes/methods were generated by the wsimport tool):
   

   BookSearchWS_Service service = new BookSearchWS_Service();
   BookSearchWS bookSearchWSPort = service.getBookSearchWSPort();
   List<Livro> livros = bookSearchWSPort.procuraLivros("something", 1);

---

Generating client classes from a Web Service WSDL:

NetBeans lets you generate client classes from existing WSDL (wsimport task). You can specify the WSDL url or existing java project.
To access the wizard:

• right click the project node inside NetBeans;
• select New
• select Web Service Client

The generated classes allows you to retrieves a proxy to the service, also known as a port.

---

The JavaEE tutorial example: A Web Service Example: helloservice implements a webservice through a stateless session bean.