RESTful Web Services and XML Parsing

In this post I describe the basic techniquies for implementing SOA components using the REST paradigm. REST stands for REpresentational State Transfer.

REST and SOAP are quite different. SOAP is a messaging protocol, whereas REST is a style of software architecture for distributed hypermedia systems; that is, systems in which text, graphics, audio, and other media are stored across a network and interconnected

through hyperlinks. A resource in the RESTful sense is anything that has an URI; that is, an identifier that satisfies formatting requirements. The formatting requirements are what make URIs uniform. Recall, too, that URI stands for Uniform Resource Identifier; hence, the notions of URI and resource are intertwined. In practice, a resource is an informational item that has hyperlinks to it. In the Web, HTTP is both a transport protocol and a messaging system because HTTP requests and responses are messages. The payloads of HTTP messages can be typed using the MIME type system, and HTTP provides response status codes to inform the requester about whether a request succeeded and, if not, why.

In a RESTful request targeted at a resource, the resource itself remains on the service machine. The requester typically receives a representation of the resource if the request succeeds. It is the representation that transfers from the service machine to the requester machine.

RESTful web services require not just resources to represent but also client-invoked operations on such resources. RESTful services are stateless; each request from client to server must contain all the information necessary to understand the request, and cannot take

advantage of any stored context on the server.

At the core of the RESTful approach is the insight that HTTP, despite the occurrence of Transport in its name, is an API and not simply a transport protocol. HTTP has its well-known verbs, officially known as methods. In the REST model, the only verbs allowed are GET, POST, PUT, and DELETE.

HTTP verb                Meaning in CRUD terms

POST                     Create a new resource from the request data

GET                       Read a resource

PUT                       Update a resource from the request data

DELETE                  Delete a resource

HTTP also has standard response codes, such as 404 to signal that the requested resource

could not be found, and 200 to signal that the request was handled successfully.

In short, HTTP provides request verbs and MIME types for client requests and status

codes (and MIME types) for service responses.

A key guiding principle of the RESTful style is to respect the original meanings of the HTTP verbs. In particular, any GET request should be side effect-free because a GET is a read rather than a create, update, or delete operation.

The RESTful approach tries to simplify matters by taking what HTTP, with its MIME type system, already offers: built-in CRUD operations, uniformly identifiable resources, and typed representations that can capture a resource’s state. REST as a design philosophy tries to isolate application complexity at the endpoints, that is, at the client and at the service.

A service may require lots of logic and computation to maintain resources and to generate

adequate representation of resources—for instance, large and subtly formatted XML documents—and a client may require significant XML processing to extract the desired information from the XML representations transferred from the service to the client. Yet the RESTful approach keeps the complexity out of the transport level, as a resource representation is transferred to the client as the body of an HTTP response message. 

XML and @WebServiceProvider

The @WebServiceProvider signals that the exchanged messages will be XML documents of some type, a notion captured in the phrase raw XML. In a RESTful request/response service, the service response is raw XML but the incoming request might not be XML at all. A GET request does not have a body; hence,
arguments sent as part of the request occur as attributes in the query string, a collection of key/value pairs. Here is a sample:

http://127.0.0.1:8080/movies?title=Constantine&year=2007

The question mark (?) begins the query string, and the attributes are key/value pairs separated by ampersands (&). The order of attributes in the query string is arbitrary; for instance, the year attribute could occur first in the query string without changing the meaning of the request.
By contrast, a POST request does have a body, which can be an arbitrary XML document instead of a SOAP envelope.

The structure of the XML is critical for defining how applications interact with each other in an SOA-style Web Services infrastructure.
It is a fundamental principle of systems integration design that applications must interact across well-defined interfaces.In my example that comes next you can see how XML Schema can be used to define the structure of a Movie. In this manner, any system that needs to insert a new Movie can map whatever form
their data is in to the movies.xsd schema and send it as a message to the movies service. The following two concepts provide the foundation for SOA-style integration using Web Services:

1. XML documents are used to exchange messages between applications.
2. XML Schema documents define the application interfaces.

Point (2) tells you that, even when using RESTful services (without WSDL and SOAP), the schema of the XML documents being exchanged between SOA components can be used to define interfaces for the services. Unfortunately, this use of XML Schema to formalize interfaces for RESTful services is not universally accepted as part of the REST framework.

In my RESTful service I followed an XML Schema that defines the types allowed to be exchanged from client and service. When developing SOA systems based on XML, it is important to employ XML Schema to validate documents. Just as a relational database management system allows you to impose constraints on data values and format within the database schema, so XML Schema can be used to validate the integrity of XML documents. XML Schema is important for maintaining data quality and integrity when sharing information among multiple systems. Next picture shows the XML Schema to exchange data between client and service:

As you can see, the XML Schema defines three complexType elements: actor that I than use in a list to compose the cast of a movie, movie that defines the stored informations about a movie and movies that is the global type containing a list of movies.

Following this Schema elements I created the associated Java classes: the Movie and the Actor classes:

package com.faeddalberto.restfulmovies.movie.types;

import java.util.List;

public class Movie {
 
    private String title;
    private String director;
    private String genre;
    private List actors;
    private Integer year;
 
 
    public String getTitle() {
        return title;
    }
    public void setTitle(String title) {
        this.title = title;
    }
    public String getDirector() {
        return director;
    }
    public void setDirector(String director) {
        this.director = director;
    }
    public String getGenre() {
        return genre;
    }
    public void setGenre(String genre) {
        this.genre = genre;
    }
        public List getActors() {
        return actors;
    }
    public void setActors(List actors) {
        this.actors = actors;
    }
    public Integer getYear() {
        return year;
    }
    public void setYear(Integer year) {
        this.year = year;
    }
 
}



package com.faeddalberto.restfulmovies.movie.types;

public class Actor {
 
    private String name;
    private String surname;
    private String nationality;
 
 
    public String getName() {
        return name;
    }
    public void setName(String name) {
        this.name = name;
    }
    public String getSurname() {
        return surname;
    }
    public void setSurname(String surname) {
        this.surname = surname;
    }
    public String getNationality() {
        return nationality;
    }
    public void setNationality(String nationality) {
        this.nationality = nationality;
    }
}

Both are simple Java POJO classes containing instance variables and getter & setter methods. The Movie class has a List of Actors and some other simple variables related to a Movie and the Actor class has some simple instance variables related to Actor.

A service annotated with @WebServiceProvider implements the Provider interface, which requires that the invoke method:

public Source invoke(Source request)

be defined. This method expects a Source of bytes (for instance, the bytes in an XML document that represents the service request) and returns a Source of bytes (the bytes in the XML response). When a request arrives, the infrastructure dispatches the request to the invoke method, which handles the request in some service-appropriate way.

The next picture shows an example of xml containing movies informattions belonging to the elements defined in the XML Schema that I showed you previously:

Note the use of namespaces in this example. The Movies element is from the namespace http://faeddalberto.com/movie/schemas. When developing SOA systems with XML, it is important to
use namespaces, because documents originating from different systems may use the same tags (e.g., “movie”), and it is important to interpret the tag in the proper context.

A RESTful Movies Service
The RESTful service that I am going to show you honors GET and POST requests.
The service is a container of movies informations stored in the XML file that I showed you previously.
In the next pictures I'll show you the code divided in different pieces, from the class declaration and annotations, the invoke method, the methods that serve the client requests, methods used to create the responses to the clients, the XML parsing. Than I'll show you the client used to query the service and how to deploy the service in a Application Server.

Let's start with the web service class declaration:

@WebServiceProvider
@ServiceMode(value = javax.xml.ws.Service.Mode.MESSAGE)
@BindingType(value = HTTPBinding.HTTP_BINDING)
public class RESTfulMoviesService implements Provider {
 
    @Resource
    WebServiceContext wsCtx;
 
    private static final String fileName = "movies.xml";
 
    private Map moviesMap;
    private List movies;
 
    private byte[] moviesBytes;
 
    public RESTfulMoviesService() {
        readMoviesFromFile();  // read the raw file bytes from movies.xml
        deserialize();   // deserialize to a List
    }

The class below is a WebServiceProvider rather than the more usual SOAP-based WebService. The service implements the generic Provider interface rather than a customized SEI with designated @WebMethods. There are two ServiceModes: PAYLOAD, the default, signals that the service wants access only to the underlying message payload (e.g., the body of an HTTP POST request); MESSAGE signals that the service wants access to entire message (e.g., the HTTP headers and body).
The HTTP_BINDING for the Binding Type opposed to the SOAP_BINDING used for SOAP web services to annunce that the web service deals with raw XML instead of SOAP over HTTP.

We have also the Injection of the resource WebServiceContext that is useful to extract the message context of the user request.
The other instance variables are useful to load and store the Movies from the XML document during the deserialization process that starts during web service initialization. Next picture shows the methods involved in the deserialization and intialization process:

private void deserialize() {
  
    URI nsURI = null;
  
    try {
        nsURI = new URI("fa:movies");
    }
    catch(URISyntaxException e) { System.err.println(e); }

    Source source = new StreamSource(new ByteArrayInputStream(moviesBytes));
  
    movies = new MoviesParser().parseMovies(source, nsURI.toString());
  
    moviesMap = Collections.synchronizedMap(new HashMap());
  
    for(Movie movie: movies) 
        moviesMap.put(movie.getTitle(), movie);
}
 
private void readMoviesFromFile() {
    try {
        String path = getFilePath();
        int len = (int) new File(path).length();
        moviesBytes = new byte[len];
        new FileInputStream(path).read(moviesBytes);
    } catch(IOException e) {
        System.err.println("IOException " + e);
    }
}
 
private String getFilePath() {
    String cwd = System.getProperty("user.dir");
    String sep = System.getProperty("file.separator");
    return "resources" + sep + fileName;
}

The method readMoviesFromFile() loads the file and reads its input stream to be stored in the byte array moviesBytes. In the deserialize() method we create a Source object containing the previously loaded byte array of movies. Calling the MovieParser class I then parse the Source object and create the List and Map storing the movies loaded from file. I'll show you later the MovieParser class used to read the movies informations. Let's now start giving a view on how the invoke method looks like:

public Source invoke(Source request) {
 
    if(wsCtx == null) 
        throw new RuntimeException("Error injecting web service context");
  
    MessageContext msgCtx = wsCtx.getMessageContext();
 
    String httpVerb = (String) msgCtx.get(MessageContext.HTTP_REQUEST_METHOD);
 
    httpVerb = httpVerb.trim().toUpperCase();

    if(httpVerb.equals("GET"))   return doGet(msgCtx);
    else if(httpVerb.equals("POST"))  return doPost(request);
    else throw new HTTPException(405);  //method not allowed
  
}

This method handles incoming requests and generates the response. I get the MessageContext to find the request method (GET or POST) and then call the associate method to serve the client request.
Let's see how I handle the GET request:

private Source doGet(MessageContext msgCtx) {
  
    String queryString = (String) msgCtx.get(MessageContext.QUERY_STRING);
  
    // get all DVDs
    if(queryString == null) 
        return new StreamSource(new ByteArrayInputStream(moviesBytes));
  
    else {
        String title = getValueFromQs("title", queryString);
  
        if(!moviesMap.containsKey(title))
            throw new HTTPException(404);  // movie not found
   
        Movie movie = moviesMap.get(title);
   
        // generate XML and return
        ByteArrayInputStream is = new ByteArrayInputStream(responseXMLMovies(movie));
   
       return new StreamSource(is);
    }  
}

private byte[] responseXMLMovies(Movie movie) {
  
    Document doc = new MoviesParser().createXMLMovies(movie);
  
    return encodeToStream(doc);
}
 
private byte[] encodeToStream(Document doc) {
  
    Source source = new DOMSource(doc);
    ByteArrayOutputStream out = null;
  
    try {
        out = new ByteArrayOutputStream();
 
        Result result = new StreamResult(out);
        TransformerFactory factory = TransformerFactory.newInstance();
   
        Transformer transformer = factory.newTransformer();
        transformer.transform(source, result);
   
    } catch (TransformerConfigurationException e) {
        System.err.println("TransformerConfigurationException " + e);
    } catch (TransformerException e) {
        System.err.println("TransformerException " + e);
    }
    
    return out.toByteArray();
  
}

private String getValueFromQs(String attribute, String queryString) {
    String[] parts = queryString.split("=");
  
    if(!parts[0].equalsIgnoreCase(attribute))
        throw new HTTPException(400);  // bad request
  
    return parts[1].trim();
}

The first method in the picture is the doGet which I pass the MessageContext object to get the query string. If no query string has been used to query the web service, I do return the entire XML file content that I previously stored in the byte array after creating a StreamSource from it.
If a query string exists I get the value of the "title" parameter, using the getValueFromQs() method, that represents the Movie title. Once had its value, I check if that title exist on the stored Map:

• if it does not exist I do throw an HTTPException(404): movie not found. 
• if it exists, I get the stored Movie informations from the Map and call the responseXMLMovies() method which uses the MovieParser class to create an XML document and returns it as DOMSource, created by the encodeToStream() method, to be sent as response to the client.

Let's now see how the POST request from the client will be handled by my service:

private Source doPost(Source request) {
    if(request == null) throw new HTTPException(400); // bad request
  
    URI nsURI = null;
  
    try {
 nsURI = new URI("fa:movies");
    }
    catch(URISyntaxException e) { System.err.println(e); }
  
    List newMovie = new ArrayList();
    newMovie = new MoviesParser().parseMovies(request, nsURI.toString());
  
    if(moviesMap.containsKey(newMovie.get(0).getTitle()))
        throw new HTTPException(400); // bad request
  
    // add the new movie to the in-memory map and save the list into the file
    movies.add(newMovie.get(0));
  
    moviesMap.put(newMovie.get(0).getTitle(), newMovie.get(0));
  
    serialize();
  
    ByteArrayInputStream is = new ByteArrayInputStream(
            responseConfirmation("Movie - " + newMovie.get(0).getTitle() + " - created"));
  
    return new StreamSource(is);
}
 
private byte[] responseConfirmation(String msg) {
 
    Document doc = new MoviesParser().createXMLConfirmation(msg);
  
    return encodeToStream(doc);
}
 
private byte[] encodeToStream(Document doc) {
  
    Source source = new DOMSource(doc);
    ByteArrayOutputStream out = null;
  
    try {
        out = new ByteArrayOutputStream();

        Result result = new StreamResult(out);
        TransformerFactory factory = TransformerFactory.newInstance();
   
        Transformer transformer = factory.newTransformer();
        transformer.transform(source, result);
   
    } catch (TransformerConfigurationException e) {
        System.err.println("TransformerConfigurationException " + e);
    } catch (TransformerException e) {
        System.err.println("TransformerException " + e);
    }
    return out.toByteArray();
  
}

private void serialize() {
  
    Document doc = new MoviesParser().createXMLMovies(movies);
  
    try {
        Source dom = new DOMSource(doc);
   
        String path = getFilePath();
        File file = new File(path);
   
        Result result = new StreamResult(file);
   
        //write the DOM document to the file
        Transformer xmlSaver = TransformerFactory.newInstance().newTransformer();
        xmlSaver.transform(dom, result);
  
    }catch (TransformerConfigurationException e) {
        System.err.println("TransformerConfigurationException " + e);
    } catch (TransformerException e) {
        System.err.println("TransformerException " + e);
    }
  
}

The first method in the picture above is the doPost which I pass the Source parameter because the HTTP POST request has a body containing the user request to be treated as a Create. Inside the body request I have a new Movie to be saved into the XML file therefore I need to parse the Source object to get it.
Before parsing the Source object I create a Namespace URI which the movies elements belong to.
Once parsed I create a List of Movies containing the Movie passed by the client and add it into the Map before serializing all its content into the movies.xml file. Once the serialization process is done I return a confirmation to the client as a confirmation creating a new DOMSource containing only a confirmation string tag with the inserted Movie title. To create this source I do use the same encodeToStream() method used for the GET request.

Parsing XML

Now that I showed you how to handle GET and POST requests, I want to show you the class MovieParser used to parse the XML file and load Movie informations and to create DOM Document to be used as responses to be sent to the clients. I used JAX-P APIs to read and write XML documents.

The first code snapshot that I show you is used to parse and get Movie informations from an XML document: 

public List parseMovies(Source result, String uri) {
    DOMResult domResult = new DOMResult();

    List movies = new ArrayList();
  
    String movieTitle = null, movieDirector = null, movieGenre = null,
        actorName = null, actorSurname = null, actorNationality = null;
    Double movieYear = null;
  
    try {
        Transformer trans = TransformerFactory.newInstance().newTransformer();
        trans.transform(result, domResult);
  
        XPathFactory xpf = XPathFactory.newInstance();
        XPath xp = xpf.newXPath();
   
        xp.setNamespaceContext(new NSResolver("fa", uri));
        NodeList resultList = (NodeList)xp.evaluate("movies/movie", 
                                    domResult.getNode(), XPathConstants.NODESET);
   
        int len = resultList.getLength();
        for(int i = 0; i < len; i++) {
            Movie movie = new Movie();
            List actors = new ArrayList();
    
            Node movieNode = resultList.item(i);
    
            if (movieNode.getNodeType() == Node.ELEMENT_NODE) {
           
                Element movieElmnt = (Element) movieNode;
            
                movieTitle = getNodeValue(movieElmnt, "title");
                movieDirector = getNodeValue(movieElmnt, "director");
                movieGenre = getNodeValue(movieElmnt, "genre");
      
                NodeList actorsList = movieElmnt.getElementsByTagName("actor");
    
                for(int j = 0; j < actorsList.getLength(); j++) {
                    Node actorsNode = actorsList.item(j);
                    Actor actor = new Actor();
                    if (movieNode.getNodeType() == Node.ELEMENT_NODE) {
             
                        Element actorElmnt = (Element) actorsNode;
        
                        actorName = getNodeValue(actorElmnt, "name");
                        actorSurname = getNodeValue(actorElmnt, "surname");
                        actorNationality = getNodeValue(actorElmnt, "nationality");
          
                        actor.setName(actorName); 
                        actor.setSurname(actorSurname); 
                        actor.setNationality(actorNationality);
          
                        actors.add(actor);
                   }
               }

               movieYear = Double.parseDouble(getNodeValue(movieElmnt, "year"));
    }       
        } 
    
        movie.setTitle(movieTitle); 
        movie.setDirector(movieDirector); 
        movie.setGenre(movieGenre); 
        movie.setActors(actors); 
        movie.setYear(movieYear.intValue());
    
        movies.add(movie); 
    }
   
    }catch(TransformerConfigurationException e) {
        System.err.println("TransformerConfigurationException " + e.getMessage());
    }catch(TransformerException e) {
        System.err.println("TransformerException " + e.getMessage());
    }catch(XPathExpressionException e) {
        System.err.println("XPathExpressionException " + e.getMessage());
    }  
  
    return movies;
} 

private String getNodeValue(Element elem, String nodeName) {
    NodeList nodeElmntLst = elem.getElementsByTagName(nodeName);
    Element nodeElmnt = (Element) nodeElmntLst.item(0);
    NodeList nodeLs = nodeElmnt.getChildNodes();
    String nodeValue = ((Node) nodeLs.item(0)).getNodeValue();

    return nodeValue;
}

After transforming a Source object to a DOMResult object using the Transformation APIs from JAX-P I create an XPath object to read informations from the DOMResult just created.
Using the xpath evaluate() method I get a list of movies from the document treating those as a NodeList through which I iterate to get the informations of each movie found.
Inside the cycle I iterate over the NodeList and get the value for every node using the getNodeValue() method which I pass the name of the Element I want to get the value of and the Element itself.
Iterating over the NodeList I also get another NodelList which is the one having movie Actors informations. This method returns a List of movies containing all the movies informations read from the file included Actors informations for every movie read.

Next task that I am going to show you is how to create a DOM Document from a List of Movies.
This method is used to create a response to be sent to the clients that require informations of a Movie or all the movies stored in the XML file in a GET request:
  

public Document createXMLMovies(List movies) {
  
    Element rootElement = null;
    Document xmlDoc = null;
    try {
        DocumentBuilderFactory factory = DocumentBuilderFactory.newInstance();
        DocumentBuilder builder = factory.newDocumentBuilder();
        DOMImplementation impl = builder.getDOMImplementation();
  
        xmlDoc = impl.createDocument(null, "movies", null);
   
        rootElement = xmlDoc.getDocumentElement();
   
        for(int j = 0; j < movies.size(); j++) {
   
            Element movieElem = xmlDoc.createElementNS(null, "movie");
    
            Element title = createElementWithValue( xmlDoc, 
                         "title", movies.get(j).getTitle()); 
            
            Element director = createElementWithValue( xmlDoc, 
                         "director", movies.get(j).getDirector());
            
            Element genre = createElementWithValue( xmlDoc, 
                         "genre", movies.get(j).getGenre());
            
            Element year = createElementWithValue( xmlDoc, 
                         "year", ""+movies.get(j).getYear());
    
            Element movieActors = xmlDoc.createElementNS(null, "actors");
    
            for (int i = 0; i < movies.get(j).getActors().size(); i++) {

                Element actor = xmlDoc.createElementNS(null, "actor");

                Element name = createElementWithValue( xmlDoc, "name", 
                              movies.get(j).getActors().get(i).getName()); 

                Element surname = createElementWithValue( xmlDoc, "surname", 
                              movies.get(j).getActors().get(i).getSurname());

                Element nationality = createElementWithValue( xmlDoc, "nationality";
              
                movies.get(j).getActors().get(i).getNationality());

                actor = createElement(actor, name, surname, nationality);

                movieActors.appendChild(actor);
            } 
    
            movieElem = createElement(movieElem, title, 
                        director, genre, movieActors, year);

            rootElement.appendChild(movieElem);
        } 
   
    } catch (ParserConfigurationException e) {
        System.err.println("ParserConfigurationException " + e.getMessage());
    }
 
    //printDomDoc(xmlDoc);
  
    return xmlDoc;
}

private Node createNode(Document xmlDoc, String name, String value) {
  
    Node node = xmlDoc.createTextNode(name); 
    node.setNodeValue(value);
    return node;
}
 
private Element createElementWithValue(Document xmlDoc, String name, String value) {
 
    Element elem = xmlDoc.createElementNS(null, name);
    elem.appendChild(createNode(xmlDoc, name, value));
  
    return elem;
}
 
private Element createElement(Element elem, Node... nodes) {
  
    for (Node node: nodes) {
        elem.appendChild(node);
    }
  
    return elem;
}

In the first method I create a new DOM document with a "movies" element as root and with a for interation over the movies List passed as argument I create the elements to add as root element children, the "movie" elements.
The other methods are all utility methods that I use to create the elements and set a value on those using the DOM APIs.  After having created all the elements to put into the file I use the appendChild() method to append every movie to the root element of the created document.

The Dispatch Client

Now that I showed you how to parse the XML document and read informations from it, I show you the client that I use to query the web service. It uses the counterpart of the Provider interface: the Dispatcher that has at its own time a invoke method used to manage the request to be sent to the service:

public class DispatchMoviesClient {

    private List movies = new ArrayList();
 
    public static void main(String[] args) {
        new DispatchMoviesClient().setupAndTest();
    }

    private void setupAndTest() {
        // create identifying name for service and port
        URI nsURI = null;
  
        try {
            nsURI = new URI("fa:movies");
        }
        catch(URISyntaxException e) { System.err.println(e); }
  
        QName serviceName = new QName("dvdService", nsURI.toString());
        QName portName = new QName("dvdPort", nsURI.toString());
        String endpoint = "http://127.0.0.1:8080/movies?title=Cloverfield";
  
        // Now create a service dispatcher
        Service service = Service.create(serviceName);
        service.addPort(portName, HTTPBinding.HTTP_BINDING, endpoint);
        Dispatch dispatch = service.createDispatch(portName, 
                     Source.class, Service.Mode.PAYLOAD);

        // send some requests:
  
        // GET request to view the dvd list
        invoke(dispatch, "GET", nsURI.toString(), null);
  
        // POST request to insert a new movie
        invoke(dispatch, "POST", nsURI.toString(), createMovie());
    }

    private void invoke(Dispatch dispatch, String verb,
        String uri, Movie data) {
  
        Map requestContext = dispatch.getRequestContext();
  
        requestContext.put(MessageContext.HTTP_REQUEST_METHOD, verb);

        Source source = null;
  
        if(data != null) {
            source = makeMovieStreamSource(data);
        }
    
        // invoke
        Source result = dispatch.invoke(source);
  
        if(data == null) {
   
            movies = new MoviesParser().parseMovies(result, uri);
   
            displayGETResult();
        }
  
        else {
            System.out.println("\nNew movie request: ");
            displayPOSTResult(result, uri);
        }
    }

    private Source makeMovieStreamSource(Movie movie) {

        Document doc = new MoviesParser().createXMLMovies(movie);
        Source source = new DOMSource(doc);
  
        return source;
    }

    private void displayGETResult() {
        if(movies.size() != 0)
            System.out.println("Movies: ");
  
        for (int i = 0; i < movies.size(); i++) {
            System.out.println("Movie " + i);
            System.out.println("\tTitle: " + movies.get(i).getTitle() + 
                 ", Director: " + movies.get(i).getDirector() + 
                 ", Genre: " + movies.get(i).getGenre() + 
                 ", Year: " + movies.get(i).getYear());
   
            System.out.println(" Actors: ");
            for(int j = 0; j < movies.get(i).getActors().size(); j++) {
                System.out.println("\tName: " + movies.get(i).getActors().get(j).getName()
                 + ", Surname " + movies.get(i).getActors().get(j).getSurname()
                 + ", Nationality: " + movies.get(i).getActors().get(j).getNationality());
            }
        }
  
    }
 
    private void displayPOSTResult(Source result, String uri) {
  
        MoviesParser parser = new MoviesParser();
  
        String confirm = parser.parseConfirmation(result, uri);
  
        System.out.println(confirm);
    }
 
    private Movie createMovie() {
        Movie movie = new Movie();
        movie.setTitle("The Job"); 
        movie.setDirector("Kenny Golde");
        movie.setGenre("Thriller");

        Actor actor1 = new Actor(); 
        actor1.setName("Brad"); 
        actor1.setSurname("Renfro"); 
        actor1.setNationality("American");

        Actor actor2 = new Actor(); 
        actor2.setName("Dominique"); 
        actor2.setSurname("Swain"); 
        actor2.setNationality("American");

        Actor actor3 = new Actor(); 
        actor3.setName("Eric"); 
        actor3.setSurname("Mabius"); 
        actor3.setNationality("American");

        List actors = new ArrayList(); 
        actors.add(actor1); 
        actors.add(actor2); 
        actors.add(actor3);

        movie.setActors(actors);
        movie.setYear(2003);
        return movie;
    }

}

Skipping the main method that calls the setupAndTest() method, we have the first instructions setting up the informations about the web service to be called. It creates identifying QName instances for a service and a port, creates a service object and adds a port, and then creates a Dispatch proxy associated with the port. This client-side dispatch object can dispatch XML documents as requests to the service as XML Source instances. A document is sent to the service through an invocation of the invoke method.
After these settings we have two requests against the web service: the first is a GET without parameters that receive all the movies stored in the XML file, while the second is a POST request that sends a Movie to be stored. In the invoke method, before invoking the web service through the dispatcher object, I set up the request context inserting the request method (GET or POST), if it is a GET request I don't need to prepare a Source to be sent because the GET request has not a body while if it is a POST request I create the Source to be sent using the same MovieParser that I used for the web service.
Using the dispatch object I call the web service using the invoke method and passing the source object just created, creating a source object into which put the response of the web service.
The other methods of this class are just utility methods used to display the results and to parse the source object using the MovieParser class.

Publishing the WS

Now we need only to publish the web service to allow clients send requests against it. If we want to publish the web service into an application server, differently from the SOAP web service that does not require a web.xml, we need to create a web.xml and another file called sun-jaxws.xml  under the WEB-INF folder to publish it.

This is the web.xml:

In the web.xml file I create a  listener using a Web Service Listener that waits for calls to the web service and a servlet called RestfulProviderD that then I declare in the sun-jaxws.xml telling it to refer to my web service for HTTP_BINDING requests.
That's all for my RESTful Web Service post. 

JAX-WS SOAP Web Services - code first

In this post I am going to show you how to create a simple Java SOAP Web Service.

As the name suggests, a web service is a kind of webified application, that is, an application typically delivered over HTTP (Hyper Text Transport Protocol). A web service is thus a distributed application whose components can be deployed and executed on distinct devices.

Web services can be divided into two groups, SOAP-based and REST-style.
SOAP originally stood for Simple Object Access Protocol but, by serendipity, now may stand for Service
Oriented Architecture (SOA) Protocol. Whatever SOA may be, web services play a central role in the SOA approach to software design and development.  For now, SOAP is just an XML (EXtensible Markup Language) dialect in which documents are messages. In SOAP-based web services, the SOAP is mostly unseen infrastructure. For example, in a typical scenario, called the request/response message exchange pattern (MEP), the client’s underlying SOAP library sends a SOAP message as a service request, and the web service’s underlying SOAP library sends another SOAP message as the corresponding service response. The client and the web service source code may provide few hints about the underlying SOAP.

Except in test mode, the client of either a SOAP-based or REST-style service is rarely a web browser but rather an application without a graphical user interface. The client may be written in any language with the appropriate support libraries. Indeed, a major appeal of web services is language transparency: the service and its clients need not be written in the same language. Language transparency is the key to web service
interoperability; that is, the ability of web services and requesters to interact seamless despite differences in programming languages, support libraries, and platforms.

If a SOAP-based web service written in Java can have a Perl or a Ruby consumer, there must be an intermediary that handles the differences in data types between the service and the requester languages.
XML technologies, which support structured document interchange and processing, act as the intermediary. For example, in a typical SOAP-based web service, a client transparently sends a SOAP document as a request to a web service, which transparently returns another SOAP document as a response.


Calculator Web Service Example:


This is a simple SOAP web service that exposes four methods that are the main calculation operation. All the required libraries to compile, execute and consume Web Services are part of Standard Java 6, that supports JAX-WS (Java API for XML-Web Services).

A SOAP-based web service could be implemented as a single Java class but, following best practices, there should be an interface that declares the methods, which are the web service operations, and an implementation, which defines the methods declared in the interface. The interface is called the SEI: Service Endpoint Interface. The implementation is called the SIB: Service Implementation Bean. The SIB can be either a POJO or a Stateless Session EJB (Enterprise Java Bean).

The picture below shows the SEI (Service Endpoint Interface) for the Calculator Web Service.
It exposes the four web service's methods: add, substract, multiply, divide.

The annotation @WebService signals that this is the SEI (Service Endpoint Interface).
@WebMethod signals that each method is a service operation.

The @SOAPBinding annotation impacts the under-the-hood construction of the service contract, the WSDL  (Web Services Definition Language) document. In my interface I used default values for this annotation, so it could be omitted. It specifies message style (DOCUMENT or RPC), encoding (LITERAL or SOAP ENCODED) and parameter style (WRAPPED or BARE).

Next picture shows the SIB (Service Implementation Bean) that implements the methods listed by the previous interface:

The @WebService property endpointInterface links the SIB (this class) to the SEI (com.faeddalberto.calculator.CalculatorWSImpl). Note that the method implementations are not annotated as @WebMethods because those were already defined as web service methods in the interface.

The two files are compiled in the usual way from the current working directory, which in this case is immediately above the subdirectory "com". The symbol % represents the command prompt:

% javac com/faeddalberto/calculator/*.java

Now that we have successful compiled our web service we need to invoke, from the working directory,  the wsgen utility that comes with Java 6: 

% wsgen –cp . com.faeddalberto.calculator.CalculatorWSImpl

This utility generates some artifacts: java types needed by the Endpoint.publish to generate the service’s WSDL.

 The simplest way to publish a web service in a development/test environment is using a simple Java SE Application.

This application publishes the web service whose SIB is com.faeddalberto.calculator.CalculatorWSImpl. For now, the service is published at network address 127.0.0.1., which is localhost, and the publication path is /calculator, an arbitrary name.

The Endpoint class has an overloaded publish method. In this two-argument version, the first argument is the  publication URL as a string and the second argument is an instance of the service SIB, in this case  com.faeddalberto.calculator.CalculatorWSImpl.

The application runs indefinitely, awaiting service requests. It needs to be terminated at the command prompt with control-C  or the equivalent.

Once the applicatation is started, open a browser to the URL  http://127.0.0.1/calculator?wsdl  to view the service contract, the WSDL document. This is an easy test to determine whether the service has deployed successfully. If the test succeeds, a client then can be executed against the service.

If everything is going well during the web service publication, you will see the following WSDL (Web Service Descriptor Language) on your browser page: 

In one of my next posts I'll describe the various parts of an WSDL document.

Associated to the Web Service contract there is also an XSD document describing the types for every request and response. If you open a browser to the URL http://127.0.0.1/calculator?xsd=1 you can see this: 

The types defined by the previou XSD are add, substract, multiply and divide (for the requests) and the same type name with the string Response attached for the web service responses. 

If you scroll above in the post you'll see that the wsgen utility used to create artifacts has created these types as Java classes: it means that that utility uses JAX-B to create java types associated to xsd elements needed by the web service to create the WSDL document and to marshal and unmarshal requests and responses. 

In full production mode, a Java Application Server such as BEA WebLogic, GlassFish, JBoss, or WebSphere might be used. To deploy our web service into an application server we need to create the WAR (Web Archive), and to do so we need to invoke the jar utility:

% jar cvf calculator.war WEB-INF

in which calculator.war is the name of the war we are creating and WEB-INF is the folder into which we have our class files to put into the war. Once created we can deploy it in the application server we choose and restart it. As we've done with our simple Jave SE application, once the applicatation server is started, open a browser to the URL  http://127.0.0.1/calculator?wsdl  to view the service contract, the WSDL document. This is an easy test to determine whether the service has deployed successfully.

Now that we have our web service up and running its time to call it and verify that it works.

We need now to create a web service client, and we can do it in different ways.

I show you a dynamic client and a static client both developed as a simple Java SE application but the same clients could also be used in a Java EE application Servlet or another utility class.

Dynamic client:

The first client I show you Is the dynamic solution:

This java class uses a URL object with a query string pointing to the WSDL location.

It then creates an XML qualified name, which has the syntax namespace URI:local name. A URI is a Uniform Resource Identifier and differs from the more common URL in that a URL specifies a location, whereas a URI need not specify a location. In short, a URI need not be a URL. In this example, the namespace URI is provided in the WSDL, and the local name is the SIB class name CalculatorWSImpl  with the word Service appended. The local name occurs in the service section, the last section of the WSDL document.

Once the URL and QName objects have been constructed and the Service.create method has been invoked, the statement of interest:

CalculatorWS calculator = service.getPort(CalculatorWS.class);

executes. In the WSDL document, the portType section describes, in the style of an interface, the operations included in the web service. The getPort method returns a reference to a Java object that can invoke the portType operations. The port object reference is of type com.faeddalberto.calculator.CalculatorWS, which is the

SEI type.

The Java client invokes the web service methods; and the Java libraries generate and process the SOAP messages exchanged transparently to enable the successful method invocations.

Static client:

In this section we will develop a standalone, static web service client to the Calculator web service

developed above. First all the static artifacts needed are generated using the wsimport tool. Note that the Calculator web service must be running when generating the artifacts, in order for wsimport to be able to access the WSDL document of the service.

% wsimport -p com.faeddalberto.calculator.staticclient -keep http://127.0.0.1/calculator?wsdl

This utility generates various classes in the subdirectory com.faeddalberto.calculator.staticclient (the -p flag stands for package). These classes make it easier to write a client against the service.

The list of the generated artifacts: 

Three points about these generated source files deserve mention. First, the interface CalculatorWS declares the very same methods as the original SEI. The methods are the web service operation add, substract, multiply, divide. Second, the class CalculatorWSImplService has a no-argument constructor that constructs the very same Service object as the original Java client DynamicCalculatorClient. Third, CalculatorWSImplService encapsulates the getcalculatorWSImplPort method, which returns an instance of type CalculatorWS, which in turn supports invocations of the four web service operations. Together the two generated types, the interface CalculatorWS and the class CalculatorWSImplService, ease the task
of writing a Java client against the web service. Next picture shows a client that uses the client-support code from the wsimport utility:

This client is functionally equivalent to the previous, but this client is far easier to write. In particular, trouble some yet critical details such as the appropriate QName and service endpoint now are hidden in the wsimport-generated class. The idiom that is illustrated here works in general for writing clients with help from WSDL-based artifacts such as CalculatorWS and CalculatorWSImplService:

• First, construct a Service object using one of two constructors in the wsimport generated class, in this example client.CalculatorWSImplService. The no-argument constructor is preferable because of its simplicity. However, a two-argument constructor is also available in case the web service’s namespace (URI) or the service endpoint (URL) have changed. Even in this case, however, it would be advisable to regenerate the WSDL-based Java files with another use of the wsimport utility.
• Invoke the get...Port method on the constructed Service object, in this example, the method getCalculatorWSImpllPort. The method returns an object that encapsulates the web service operations declared in the original SEI.

Next picture shows the result for this client:

This was just a simple web service. There are different other ways of writing web services and clients against them, I'll show you on my next posts. 

Spring 3 with Hibernate, Maven 2 and Apache Tiles

In this post I show you how to create a java mavenized application using Spring MVC 3 and Hibernate.
I am using Springsource Tool Suite (STS) that is an Eclipse-like IDE that semplifies the development of Mavenized applications with Spring framework.

Once created a new Maven Web project through the wizard, we need to modify the pom.xml file that is the Maven configuration file that allows us to define the application name, developers, company informations, etc.
But, most important, it allows us to define the libraries required to develope the application and some Maven plugins, such as the one that builds and compiles the application.

In the first part of the pom file we can find information such as the application name, version, and the developers that work on it.
Then, we have the dependencies, that are the libraries required to develop the application. Among these, there are Junit and Mokito (used for testing purposes), log4j used for logging purposes, Apache Tiles that is the apache library to create structured web pages made of "jsp fragments" (I will show you later how to define pages based on tiles). Then we have the validation library used by Hibernate to validate data inserted on web page forms.
We can then find a set of dependencies for the Spring framework (core, expressions, bean, aop, context, web, test, orm) used to control all the application tiers. After these, Hibernate library used for the Object Relational Mapping and query the database. Then we have AspectJ that is used to define aspects to control crosscutting concerns of the application.
Lastly I have defined the build plugin of maven that it uses to build the application and package it in the format defined in the first part of the pom.


Now that we have defined the libraries needed for the development of our application, we can define the web.xml file that handles the requests from the clients and defines other important files for the application management.

From the web.xml file we can see that the application is managed by Spring framework.
We have defined 2 listeners:

• the first is the Log4jConfigurationListener that loads the log4j configuration file which location is defined in the context-param named  "log4jConfigLocation" and its location is inside the devconn folder in the root path of the application server; 
• the second listener is the ContextLoaderListener that is used by Spring to load its configuration files. The associated context-param, loads a list of spring configuration files: applicationContext-aspect.xml in which I have defined some aspects that manage crosscutting concerns; applicationContext-data.xml in which I have defined beans that have to do with database (datasource, hibernate session factory, and dao classes); applicationContext-mail.xml which defines beans to send email. 

Under the definition of listeners, we find the definition of a servlet managed by the Spring DispatcherServlet  which is associated to another spring configuration file that defines the beans that manage the user requests and other web utilities who's name is spring-mvc-servlet.xml. 

Lastly I have defined the taglib location for the definition of tiles.

The next step is the definition of the spring-mvc-servlet.xml that manages the user requests: 

First of all we can see the import od XML Schema Definitions for the different Spring components used in the configuration file. Then we have the definition of the location for the static resources such as images, css... . 

Then we define that the mvc components are annotation-driven, it means that there is not the definition of Spring Controller beans in xml configuration files but those components are defined using Spring annotations (I will show you later). If we want automatic generation of proxies, we will use the tag <aop:aspectj-autoproxy/> through the AOP namespaces. 

After the definition of base-package we have the definition of  two beans about the configuration (which defines the configuration file) and resolution of Tiles. 

Lastly we have the definition of some beans about the message bundle and internationalization. 

The next step is the definition of a Spring Controller that is the handler for a user request, and I show you the controller for the user registration process: 

The first instruction in the above picture is the @Controller annotation that defines this class as a Spring controller. The second instruction defines the attributes that will be added to the HttpSession. 

Then we have another annotation, that is the @RequestMapping annotation and defines the path at which this controller will be called. 

The controller has three instance variables; these are injected to the controller as dependencies at construction time by the Spring framework that searches on his context configuration files for  beans definitions that have the same type and name of the one required by the controller. The constructor has the @Inject annotation that asks Spring to find and inject the required beans. 

Then we have two methods both preceded by the @RequestMapping annotation that defines the Http request method, and the first one answers to a GET request while the second answers to a POST request at the same address, that is the one defined above.

The first method inserts some attributes into the model object such as a new DevProfile object that has to be filled by the registration form and some other attributes containing objects needed to define the registration form. 

The second method receives the registration form, and has some input parameters related to the filled form. We can see the @Valid annotation before the DevProfile object that is used for validation purposes based on rules defined in the DevProfile entity class. If one or more of these validation rules is not satisfied the response returns to the input page showing the errors, else it saves the DevProfile into the database and after  sending a registration confirmation email, shows a login page as a result of a successful registration. 

Both the methods return a String that represents the name of the view to be showed. 

Spring searches the view definition corresponding to the returned String through the TilesViewResolver defined precedently in the spring-mvc configuration file. 

The next step is the definition of the tiles and the corresponding views made of jsp fragments. 

As we can see from the above image, every tile definition is made of many jsp fragments and other attributes such as CSS files and the page title. The first definition is called baseLayout and defines exactly a base layout that the other definition extend and modify based on their purposes. Continuing the analization of the baseLayout definition, we see that it defines a page template with a jsp page (that I show you later). The template is the definition of a page layout, that we can see in the picture below: 

The attributes added on the definition are the page title, the css style for the page content, the header of the page called top, the left side, the body called content and the footer.

The other tiles definitions, as I wrote earlier, extend this baseLayout definition and override values based on the content that has to be displayed on the resulting page. 

I show you now the jsp page template:

First of all at the top of the page there is the import of the tiles tag lib that we defined in the web.xml file.

As we can see, the image above also illustrates the attributes that we have defined precedently in the tiles configuration file. Inside the head tag, we have the page title attribute and the import of the css defined in the tiles configuration file and other default css files. 

Inside the body tag we can find the jsp fragments top, left, content and bottom. 

Now I show you the body part of the registration tile, that contains the registration form. 

At the top of the page we have the tag libs import (jsp core, spring, and spring form). Using the form tag of the spring form tag library we then define the registration form in which can find the modelAttribute that is the new DevProfile object we inserted into the model object in the RegistrationController and define the HTTP method attribute as POST that is used by the framework to call the method we've defined in the controller and annotated with the RequestMapping annotation with a POST value for the method. attribute. 

The message tag of the spring tag lib is used to show a label which value to be displayed is read from the message bundle defined in the spring context file. 

I have separated the personal information and account information with two fieldset. The first one contains personal informations such as name, surname, gender, date of birth in which name and surname are simple input text fields, while gender and birthday fields are made with spring select tags that use some of the attributes inserted into the model object on the RegistrationController class. 

The second fieldset contains account informations email and password for the user that wants to register. 

You can also find spring form errors tag for every field that requires validation. If the values inserted in the field does not pass the validation, the tag shows the error under that field. 

Lastly we have the confirmation button that once clicked sends the request to the RegistrationController's method. 

Now I show you the definition of a fragment of the DevProfile entity class that is a simple java POJO with validation annotation over some fields through which it is possible to manage validation on web forms.

As you can see, with simple annotations over the fields we can control form validation. There is not the need to tell you what the annotations mean because you can just read these and understand on your own that the name’s size must be between 3 and 25, Gender could not be empty, etc…

Now is the time to introduce AOP with Aspectj to control crosscutting concerns such as logging. I have, indeed, used an aspect to manage logging on controllers.

First of all, as you remember, in the web.xml I defined an applicationContext-aspect.xml configuration file into which I have defined aspect beans. Let's see the configuration file: 

The picture above shows the configuration of a bean used as an aspect for logging purposes.

We define aspects using the spring aop XML Schema components. Inside the <aop:config> tag we define the different components of an aspect: the pointcut tag defines where the advice should be called, in my case the expression “execution (* com.faeddalberto.devconn.controller.*.*(..)) “  tells aspectj to call the advice every time a method with any number of parameters of the classes in the com.faeddalberto.devconn.controller package is called. After the definition of the pointcut we find in the configuration the definition of the loggingAspect with two advices, one before and one after the execution of an application method, called joinpoint. We can obtain the same result using one only advice, called around that is called before entering the joinpoint method and after exiting it.

Let’s now give a look at the class defined as aspect:

 As you can see it is a simple Java class with two methods used for logging purposes. Both methods have a parameter that is JoinPoint. It has some utility methods that give us the opportunity to figure out which is the class that has been called and its method name and some other utilities.

Another application configuration file that I listed in the web.xml file is the applicationContext-data.xml that is used to define database related beans and Hibernate session factory bean. Let’s give it a look:

The first important thing in this context file is the jndi-lookup tag: it searches for a component with a name defined in the jndi-name attribute using jndi lookup. We are using this way to find and define the dataSource that configures the database connection.

Another important bean definition is the sessionFactory, that is the Hibernate most important bean to which we inject the datasource defined earlier and a list of mapping resources files (Object Relational Mapping), I am showing only two of the orm files I have in my project. We than define hibernate properties: I am only defining the dialect to be used to query the database. We know that in the java code we use HQL that is Hibernate Query Language to define queries; these queries are then translated using the dialect here into SQL to query the database in a language understandable by it.

After the definition of the session factory we define the transaction manager injecting the session factory bean.

Lastly I show you the definition of two beans, that are the DAO classes for two entities, into which we can find the methods used to perform CRUD operations.

In the next picture I’ll show you the ORM file for the DevProfile entity:

In the picture above I am mapping the DevProfile class to the profile database table defining the table columns associated with the java fields, the corresponding data type and the relations with other database tables mapped to other java classes using one-to-one or one-to-many or many-to-one tags and set tag to define a collection of related columns.

 The next part of the application that I want to show you is the implementation of DAO, let's start:

In the picture above we have the interface that lists the main operations on entities. The <T> is a placeholder for the type you pass in. In other words, whatever Tis when you declare the interface, that's what you can use with methods. Let's give a loot at the implementation of this interface: 

The picture above, shows the IDAO implementation, I called it AbstractDao because it is a common implementation that would be extended by the entities DAOs as needed. The EntityDAO will then have a constructor with 3 parameters: tableName, orderFieldName and entityClass. The methods in this class are simple methods that execute the Hibernate operations to Create, Read, Update, Delete, Flush, FindById, Merge, etc... 

Next I show you the extended DAO for the DevProfile entity: 

In the image above, I have created the DevProfileDao to execute the previous methods on the DevProfile entity, the only thing I did is creating a constructor passing the parameters to the super (AbstractDao) and if I need any other query, I do create new methods in this class. 

Next I show you the unit test for the RegistrationController: 

Finally I show you the registration page and the login page of the application:

Next is the registration page with error fields: 

The next picture is the login page, showed when registration is successfull: