• descrierea tipurilor de servicii web ce pot fi dezvoltate folosind limbajul de programare Java și identificarea oportunității folosirii acestora;
• înţelegerea arhitecturii pe care o oferă tehnologia JAX-WS pentru dezvoltarea unui serviciu web, precum şi mecanismul prin care sunt împachetate obiectele spre a fi transmise prin infrastructura de comunicaţie;
• proiectarea unor structuri de date (clase) care să poată fi stocate sub formă de scheme XML;
• dezvoltarea unui serviciu web folosind tehnologia JAX-WS care să pună la dispoziție mai multe funcționalități la distanță, asigurând totodată persistența informațiilor;
• folosirea unui serviciu web dezvoltat prin tehnologia JAX-WS prin invocarea metodelor implementate;
• utilizarea unui server de aplicații care să găzduiască serviciul web.

serviciu web, JAX-WS, JAX-RS, XML, SOAP, WSDL, UDDI, HTTP, URI, MIME, AJAX, DWR, endpoint, SEI, JAXB, xjc, schemagen, XSD, GlassFish open-source server

TODO

Un serviciu web reprezintă o funcţionalitate implementată în cadrul unei aplicaţii, accesibilă printr-o reţea de calculatoare (cel mai frecvent prin Internet, folosind protocolul HTTP), oferind interoperabilitate între programe ce rulează pe platforme diferite. O caracteristică a serviciilor web este extensibilitatea şi descrierea funcţionalităţii într-un limbaj ce poate fi procesat automat, astfel încât să poată fi prelucrat cu uşurinţă. Asocierea (slab cuplată) a mai multor servicii web se urmăreşte pentru rezolvarea unor probleme complexe. Astfel, programe ca oferă funcţionalităţi de bază pot interacţiona pentru a oferi servicii sofisticate, cu valoare adăugată. Comunicaţia între entităţile implicate în procesul de implementare şi interogare a serviciilor web este realizată prin mesaje, ceea ce nu presupune cunoaşterea capabilităţilor de care dispun platformele pe care rulează acestea. De regulă, arhitectura după care sunt modelate serviciile web este cea de client-server.

Implementarea serviciilor web se poate face în mai multe moduri, distingându-se serviciile web de dimensiuni “mari” şi serviciile web fără stare (eng. RESTful web services).

Serviciile web de dimensiuni “mari”, implementate în Java prin tehnologia JAX-WS, folosesc pentru comunicaţie mesaje XML care respectă standardul SOAP (Simple Object Access Protocol) – spre a descrie arhitectura şi formatul mesajelor. Operaţiile pe care le pun la dispoziţie serviciile pot fi procesate în mod automat, întrucât interfeţele (care le conţin) sunt descrise în limbajul WSDL (Web Services Description Language). Acesta este un limbaj bazat pe XML prin intermediul căruia sunt definite din punct de vedere sintactic interfețele ce includ funcționalitățile implementate de serviciul web. Atât standardul SOAP folosit pentru formatul mesajelor cât şi limbajul de definire a interfeţelor WSDL au fost adoptate pe scară largă.

Un serviciu web modelat după standardul SOAP trebuie să conţină următoarele elemente:

• o interfaţă care descrie operaţiile pe care serviciul web le pune la dispoziţia utilizatorilor; se poate folosi WSDL pentru detalii cu privire la mesaje, operaţii, corespondenţe şi locaţia de la care se poate accesa serviciul web;

• arhitectura serviciului web trebuie să răspundă unor cerinţe complexe nonfuncţionale (spre exemplu: procesarea unor tranzacții, rezolvarea unor aspecte ce vizează securitatea, probleme de adresare, coordonare, încredere), stabilind o sintaxă pentru acestea;
• atât procesarea cât şi invocarea operaţiilor trebuie să se facă asincron; există standarde care oferă suport pentru această infrastructură, cum ar fi WSRM (Web Services Reliable Messaging) sau API-uri ca JAX-WS.

Serviciile web fără stare sunt adecvate unor scenarii de integrare ad-hoc, folosind standarde W3C sau IETF (ca HTTP, XML, URI, MIME) – deci o infrastructură mai accesibilă – ceea scade costul cu dezvoltarea, astfel că adoptarea lor impune mai puţine restricţii. Un test pentru a determina dacă un serviciu web este independent de stare constă în verificarea comportamentului acestuia în situația repornirii serverului care îl găzduiește. Sunt mai bine integrate cu HTTP decât serviciile bazate pe SOAP (nu mai sunt necesare mesaje în format XML sau descrieri ale serviciilor bazate pe WSDL). Serviciile web de tip REST-ful (eng. Representational State Transfer) includ informațiile cu privire funcționalitatea pe care o oferă în mesajele schimbate între client și server.

Situaţiile în care este utilă construirea unor servicii web fără stare este:

• performanţa poate fi îmbunătăţită printr-o infrastructură de stocare (eng. caching system) atâta timp cât informaţiile oferite de serviciul web nu sunt generate în mod dinamic;

• atât clientul cât şi serverul au o înţelegere (comună) cu privire la contextul şi conţinutul care este transmis în procesul de interacţiune dintre ele, întrucât nu există o interfaţă care să descrie (standardizat) informaţiile care sunt transmise;

• lăţimea de bandă limitată este un aspect care trebuie luat în considerare întrucât serviciile web fără stare sunt mai frecvent folosite pentru dispozitive cum ar fi telefoane mobile sau PDA-uri; în această situaţie surplusul de informaţii conţinut de mesajele bazate pe XML (obiectele SOAP) limitează performanţa, implicând şi costuri mai ridicate;
• integrarea cu diferite aplicaţii Internet se poate realiza cu uşurinţă folosind tehnologii precum JAX-RS sau AJAX (Asynchronous JavaScript with XML) ca şi utilitare ca DWR (Direct Web Remoting) spre a invoca serviciile dezvoltate; fiind expuse prin XML, serviciile web pot fi utilizate fără modificarea semnificativă a arhitecturii paginii Internet.

Serviciile web de dimensiuni mari sunt folosite în probleme specifice aplicaţiilor integrate pentru întreprinderi, având cerinţe mai complexe în privinţa calităţii serviciilor, în timp ce serviciile web fără stare sunt folosite pentru probleme de interfaţare prin reţea.

Tehnologia JAX-WS implementează cerinţe mai complexe referitoare la calitatea serviciilor (QoS – Quality of Service), frecvent întâlnite în aplicaţiile integrate pentru întreprinderi, oferind suport pentru mai multe protocoale care oferă standarde pentru securitate şi fiabilitate, asigurând interoperabilitatea între servere şi clienţi conforme cu aceste protocoale pentru servicii web.

Tehnologia JAX-RS facilitează procesul de dezvoltare a unor aplicaţii web conforme arhitecturii REST pentru a integra anumite proprietăţi în acestea precum: cuplarea slabă (dezvoltarea serverului se poate face fără afectarea clienţilor existenţi) sau scalabilitate, bazându-se pe o arhitectură simplă. Clienţii pot folosi o parte sau toate serviciile web puse la dispoziţie în timp ce serverul poate fi dezvoltat, integrându-le şi cu alte servicii web.

JAX-WS (Java API for XML Web Services) este o tehnologie Java folosită pentru dezvoltarea de servicii web şi de aplicaţii care le invocă, definit de JSR224, comunicaţia bazându-se pe XML. Utilizatorii pot dezvolta servicii web orientate pe mesaje sau pe apeluri la distanţă (RPC – Remote Procedure Call).

O invocare a unui serviciu web este realizată prin protocolul SOAP, care este bazat pe XML. Specificaţia SOAP include structura antetelor, regulile de codificare şi convenţiile pentru reprezentarea invocărilor şi răspunsurilor serviciului web. Astfel, invocările şi răspunsurile sunt transmise ca mesaje SOAP prin protocolul HTTP. Deşi mesajele SOAP sunt complexe, acest fapt este ascuns prin API-ul JAX-WS. Pe server sunt definite operaţiile serviciului web în cadrul unei interfeţe precum şi implementarea lor. Un client crează un obiect delegat (obiect local reprezentând serviciul) şi invocă metodele puse la dispoziţie de serviciul web prin intermediul acestuia. Programatorul nu trebuie să genereze mesaje SOAP şi nici să le analizeze, întrucât sistemul de execuţie JAX-WS converteşte invocările şi răspunsurile în şi din mesaje SOAP.

Avantajele JAX-WS constau în independenţa de platformă a limbajului de programare Java şi în faptul că entităţile implicate în dezvoltarea şi accesarea serviciului web nu trebuie ruleze pe o platformă Java, întrucât sunt folosite tehnologii definite de W3C: HTTP, SOAP şi WSDL. WSDL specifică un format XML pentru descrierea unui serviciu ca un set de noduri din reţea care realizează anumite operaţii asupra mesajelor.

Un serviciu web dezvoltat cu JAX-WS este o clasă Java adnotată cu însemnarea javax.jws.WebService, aceasta fiind desemnată ca entitatea care deserveşte serviciul web respectiv (eng. endpoint). Aşadar, structura prin care este descris un serviciu web (SEI – Service Endpoint Interface / Implementation) este o intefaţă sau o clasă Java unde sunt declarate metodele pe care un client le poate invoca pentru un serviciu.

BookManager.java

import javax.jws.WebMethod;
import javax.jws.WebParam;
import javax.jws.WebService;
 
@WebService(serviceName = "BookManager")
public class BookManager extends PersistentEntityManager<Book> implements BookManagerInterface {
 
  public BookManager() {
    super(Book.class);
  }
 
  @WebMethod(operationName = "getBooksList")
  @Override
  public List<BookInformation> getBooksList() {
    List<BookInformation> result = new ArrayList<>();
 
    // ...
 
    return result;
  }
 
  @WebMethod(operationName = "getBooksListWithStockpile")
  @Override
  public List<BookInformationDetailed> getBooksListWithStockpile(@WebParam(name = "stockpile") int stockpile) {
    List<BookInformationDetailed> result = new ArrayList<>();
 
    // ...
 
    return result;
  }
 
}

Structurile (clasele, interfeţele) care definesc un serviciu web folosind tehnologia JAX-WS trebuie să îndeplinească mai multe condiţii:

• clasa care implementează serviciul web trebuie să fie adnotată cu însemnările javax.jws.WebService sau javax.xml.ws.spi.Provider;
• clasa care implementează serviciul web poate referi în mod explicit interfaţa care descrie acest serviciu web prin elementul endpointInterface al însemnării @WebService, însă acest lucru nu este obligatoriu: dacă nu este întâlnit nici un element endpointInterface în însemnarea @WebService, interfaţa care descrie serviciul web este definită implicit;
• metodele ce implementează funcţionalitatea serviciului web trebuie să fie publice şi nu trebuie să fie declarate ca fiind static sau final;
• metodele ce implementează funcţionalitatea serviciului web, ce sunt accesibile utilizatorilor trebuie să fie adnotate cu însemnarea javax.jws.WebMethod;
• metodele ce implementează funcţionalitatea serviciului web trebuie să aibă parametrii şi rezultate întoarse de tipuri compatibile cu JAXB; acestea pot fi adnotate cu însemnările javax.jws.WebParam, respectiv javax.jws.WebResult;
• clasa care implementează serviciul web nu trebuie să fie declarată ca fiind final şi nu trebuie să fie abstractă;
• clasa care implementează serviciul web trebuie să implementeze un constructor public implicit;
• clasa care implementează serviciul web nu trebuie să conţină metoda finalize();
• clasa care implementează serviciul web poate folosi adnotaţiile javax.annotation.PostConstruct sau javax.annotation.PreDestroy pentru evenimente legate de ciclul de viaţă al serviciului web:
  • metoda @PreConstruct va fi invocată înainte ca structura care implementează serviciul web să răspundă la cereri din partea clienţilor;
  • metoda @PreDestroy va fi invocată înainte ca structura care defineşte serviciul web să fie îşi încheie activitatea.

În exemplu, clasa care implementează serviciul web, BookManager, este adnotată ca fiind un serviciu web, descriind operaţiile acestuia prin însemnarea @WebService(serviceName=“BookManager”). Clasa BookManager declară mai multe metode (getBooksList(), getBooksListWithStockpile()), fiecare fiind adnotate cu @WebMethod(operationName=“”) prin care acestea sunt făcute vizible către clienţi. Parametrii acestor metode accesibile la nivelul clienţilor trebuie să fie adnotate cu însemnarea @WebParam(name=“”), putându-se specifica un nume sugestiv pentru semnificaţia argumentelor. Totodată, este necesar ca implementarea să conţină şi un constructor implicit care va fi apelat atunci când un client face o invocare pentru o metodă asociată serviciului web respectiv. Preluarea informaţiilor dintr-o sursă externă (fişier) pentru obţinerea acestui element trebuie să ţină cont de faptul că în urma operaţiei de dezvoltare (eng. deployment) a serviciului web, aplicaţia este plasată într-un context al serverului de aplicaţii care va pune la dispoziţie respectivul serviciu web, astfel încât amplasarea sursei externe trebuie să fie cunoscută ca locaţie (server web sau sistem de fişiere) în mod absolut şi nu relativ la adresa unde se găsesc clasele.

Clasa javax.xml.ws.Endpoint pune la dispoziție mai multe metode statice prin intermediul cărora poate fi gestionat un serviciu web. Un astfel de obiect asociază o implementare a unui serviciu web, a cărui stare poate fi publicat sau nepublicat. Totodată, el încapsulează mai multe metadate, cum ar fi documentele WSDL și schemele XML, pe care le generează în funcție de adnotările din clasele ce conțin implementarea serviciului web, în cazul că acestea nu sunt furnizate explicit.

Crearea și publicarea unui obiect de tip Endpoint se face prin una dintre implementările metodei publice publish(), care primește ca parametrii locația la care va fi disponibilă descrierea serviciului web (locația fișierului WSDL) precum și implementarea propriu-zisă a serviciului web:

public static Endpoint publish(String address, Object implementor) {}

Un exemplu de utilizare a acestei metode poate fi:

Endpoint.publish("http://localhost:8080/bookstore/BookManager", new BookManager());

Un serviciu web care este publicat poate fi făcut indisponibil prin intermediul metodei stop() a clasei Endpoint.

JAXB (Java Architecture for XML Binding) oferă o modalitate de conversie între aplicaţii dezvoltate în limbajul de programare Java şi scheme XML. Poate fi folosit independent sau împreună cu JAX-WS, oferind o modalitate de transmitere a mesajelor în cazul utilizării unor servicii web. Astfel, JAX-WS deleagă către JAXB maparea tipurilor din limbajul de programare Java (pentru parametri şi valori întoarse) cu definiţii XML. Dezvoltatorii serviciilor web nu trebuie să cunoască detaliile acestei corespondenţe, însă trebuie să cunoască faptul că nu orice clasă din limbajul de programare Java poate fi folosită drept parametru sau valoare întoarsă în JAX-WS, întrucât limbajul de programare Java oferă un set de tipuri de date mult mai bogat decât schemele XML.

JAXB defineşte un set de adnotări astfel încât pentru clase definite de utilizator să se poată realiza conversia la un document XML:

JAXB pune la dispoziţie un utilitar pentru compilarea unei scheme XML într-o clasă Java – denumit xjc –, un utilitar de generare a unei scheme XML dintr-o clasă Java – denumit schemagen şi un cadru general de rulare. Astfel, se poate porni de la o definiţie a unei scheme XML (XSD – XML Schema Definition), creându-se obiecte JavaBeans corespunzătoare (folosind compilatorul pentru scheme XML xjc) sau se poate porni de la obiecte JavaBeans creându-se definiţiile unei scheme XML corespunzătoare (folosind utilitarul schemagen).

După stabilirea corespondenţei dintre schema XML şi clasele Java, conversia între ele este realizată în mod automat prin intermediul JAXB. Informaţiile reţinute în cadrul documentelor XML pot fi accesate fără a fi necesară înţelegerea structurii lor. Clasele Java rezultate pot fi folosite pentru accesarea serviciului web dezvoltat. Adnotările conţin toate datele necesare pentru ca JAXB să realizeze conversia dintr-un format într-altul, astfel încât obiectele să poată fi transmise prin infrastructura de comunicaţie. JAXB asigură împachetarea obiectelor Java spre documente XML şi despachetarea documentelor XML în instanţe ale claselor Java. Totodată, JAXB poate oferi validarea documentelor XML conform schemei generate, astfel încât acestea respectă constrângerile care au fost stabilite.

Prin urmare, JAXB reprezintă tehnologia standard utilizată pentru conversia datelor în cadrul serviciilor web de dimensiuni “mari” implementate prin JAX-WS. Totuşi, JAXB poate fi folosit şi independent de JAX-WS, atunci când se doreşte gestiunea conversiei dintre documente XML şi obiecte Java în cadrul unor aplicaţii informatice.

JAXB este folosit în implementarea serviciilor web prin tehnologia JAX-WS pentru a asigura transportul obiectelor Java (parametrii sau valori întoarse ale metodelor), utilizând un format universal (XML) – independent de platformă, dar şi pentru a asigura un mecanism de persistenţă (prin documente XML), fără a face apel la JPA (Java Persistance API), adecvat stabilirii unei corespondenţe între clase Java şi baze de date relaţionale. Deşi este mai rudimentar, această soluţie este folosită atunci când starea obiectelor trebuie să fie reţinută, iar dimensiunea acestora nu este foarte voluminoasă.

În cazul exemplului de mai sus, este necesar ca obiectele cu tipul BookInformation respectiv BookInformationDetailed să fie transportate prin infrastructura de comunicaţie, motiv pentru care definiţia clasei trebuie să indice acest lucru:

BookInformation.java

import javax.xml.bind.annotation.XmlElement;
import javax.xml.bind.annotation.XmlRootElement;
import javax.xml.bind.annotation.XmlType;
 
import ro.pub.cs.aipi.lab07.entities.PersistentEntity;
 
@XmlRootElement
@XmlType(name = "BookInformation")
public class BookInformation extends PersistentEntity {
 
  protected Long id;
  protected String title;
  protected String writers;
  protected String collection;
  protected String publishingHouse;
  protected Long edition;
  protected Long printingYear;
  protected String country;
 
  public BookInformation() {
  }
 
  public BookInformation(Long id, String title, String writers, String collection, String publishingHouse,
    Long edition, Long printingYear, String country) {
    this.id = id;
    this.title = title;
    this.writers = writers;
    this.collection = collection;
    this.publishingHouse = publishingHouse;
    this.edition = edition;
    this.printingYear = printingYear;
    this.country = country;
  }
 
  public Long getId() {
    return id;
  }
 
  public void setId(Long id) {
    this.id = id;
  }
 
  @XmlElement
  public String getTitle() {
    return title;
  }
 
  public void setTitle(String title) {
    this.title = title;
  }
 
  @XmlElement
  public String getWriters() {
    return writers;
  }
 
  public void setWriters(String writers) {
    this.writers = writers;
  }
 
  @XmlElement
  public String getCollection() {
    return collection;
  }
 
  public void setCollection(String collection) {
    this.collection = collection;
  }
 
  @XmlElement
  public String getPublishingHouse() {
    return publishingHouse;
  }
 
  public void setPublishingHouse(String publishingHouse) {
    this.publishingHouse = publishingHouse;
  }
 
  @XmlElement
  public Long getEdition() {
    return edition;
  }
 
  public void setEdition(Long edition) {
    this.edition = edition;
  }
 
  @XmlElement
  public Long getPrintingYear() {
    return printingYear;
  }
 
  public void setPrintingYear(Long printingYear) {
    this.printingYear = printingYear;
  }
 
  @XmlElement
  public String getCountry() {
    return country;
  }
 
  public void setCountry(String country) {
    this.country = country;
  }
 
}

BookInformationDetailed.java

import javax.xml.bind.annotation.XmlElement;
import javax.xml.bind.annotation.XmlRootElement;
import javax.xml.bind.annotation.XmlType;
 
import ro.pub.cs.aipi.lab07.entities.PersistentEntity;
 
@XmlRootElement
@XmlType(name = "BookInformationDetailed")
public class BookInformationDetailed extends PersistentEntity {
 
  protected Long id;
  protected String title;
  protected String subtitle;
  protected String writers;
  protected String categories;
  protected String formats;
  protected String languages;
 
  public BookInformationDetailed() {
  }
 
  public BookInformationDetailed(Long id, String title, String subtitle, String writers, String categories,
    String formats, String languages) {
    this.id = id;
    this.title = title;
    this.subtitle = subtitle;
    this.writers = writers;
    this.categories = categories;
    this.formats = formats;
    this.languages = languages;
  }
 
  public Long getId() {
    return id;
  }
 
  public void setId(Long id) {
    this.id = id;
  }
 
  @XmlElement
  public String getTitle() {
    return title;
  }
 
  public void setTitle(String title) {
    this.title = title;
  }
 
  @XmlElement
  public String getSubtitle() {
    return subtitle;
  }
 
  public void setSubtitle(String subtitle) {
    this.subtitle = subtitle;
  }
 
  @XmlElement
  public String getWriters() {
    return writers;
  }
 
  public void setWriters(String writers) {
    this.writers = writers;
  }
 
  @XmlElement
  public String getCategories() {
    return categories;
  }
 
  public void setCategories(String categories) {
    this.categories = categories;
  }
 
  @XmlElement
  public String getFormats() {
    return formats;
  }
 
  public void setFormats(String formats) {
    this.formats = formats;
  }
 
  @XmlElement
  public String getLanguages() {
    return languages;
  }
 
  public void setLanguages(String languages) {
    this.languages = languages;
  }
 
}

Prin folosirea adnotării @XmlAccessorType, se indică faptul că toate atributele clasei vor fi serializate, motiv pentru care nu mai este necesară implementarea interfeţei java.io.Serializable. Serializarea este realizată prin intermediul unor documente XML, tipul de date (specificat prin adnotarea @XmlType) fiind BookInformation / BookInformationDetailed. Se asigură totodată faptul că descrierea în limbaj WSDL va cuprinde definiţiile metodelor din această clasă, astfel încât ele vor putea fi folosite corespunzător în cadrul aplicaţiilor ce accesează funcţionalitatea oferită de serviciul web, fiind cuprinse în clasele generate la nivelul clientului.

De remarcat faptul că adnotarea @XmlElement va fi indicată pentru metoda getter asociată atributului respectiv şi nu pentru atributul în sine.

Pot exista situații în care instanțe ale obiectelor serializabile, implicate în metodele expuse sub formă de servicii web ca parametri sau valori întoarse să trebuiască să fie salvate / încărcate pe server sub forma unor fișiere XML, între invocări succesive ale acestora. O astfel de funcționalitate poate fi necesară în situația în care este utilizat un server de aplicații care nu menține obiectul asociat serviciului web și nici proprietățile pe care acesta le conține (acesta menținând o stare intermediară). În acest scop pot fi utilizate funcționalitățile puse la dispoziție de clasa javax.xml.bind.JAXBContext. Aceste obiecte sunt de regulă instanțiate pe constructorul clasei care implementează metodele serviciului web, folosindu-se una dintre implementările metodei statice newInstance().

JAXBContext contextBookInformation;
JAXBContext contextBookInformationDetailed;
 
public BookManager() {
  try {
    contextBookInformation = JAXBContext.newInstance(BookInformation.class);
    contextBookInformationDetailed = JAXBContext.newInstance(BookInformationDetailed.class);
  } catch (Exception exception) {
    System.out.println("An exception has occurred: " + exception.getMessage());
    if (Constants.DEBUG) {
      exception.printStackTrace();
    }
  }
  // ...
}

Operațiile de salvare / încărcare în / din fișier sunt realizate prin intermediul claselor javax.xml.bind.Marshaller, respectiv javax.xml.bind.Unmarshaller, instanțe ale acestora fiind furnizate prin intermediul metodelor marshal() și unmarshal().

public final void packBookInformation(BookInformation object, String file) {
  try {
    Marshaller conversion = contextBookInformation.createMarshaller();
    conversion.marshal(object, new FileOutputStream(file));              
  } catch (Exception exception) {
    System.out.println("An exception has occurred: " + exception.getMessage());
    if (Constants.DEBUG) {
      exception.printStackTrace();
    }
  }
}
 
public final void packBookInformationDetailed(BookInformationDetailed object, String file) {
  try {
    Marshaller conversion = contextBookInformationDetailed.createMarshaller();
    conversion.marshal(object, new FileOutputStream(file));              
  } catch (Exception exception) {
    System.out.println("An exception has occurred: " + exception.getMessage());
    if (Constants.DEBUG) {
      exception.printStackTrace();
    }  
  }
}       
 
public final BookInformation unpackBookInformation(String file) {
  try {
    Unmarshaller conversion = contextBookInformation.createUnmarshaller();
    return (BookInformation)conversion.unmarshal(new FileInputStream(file));  
  } catch (Exception exception) {
    System.out.println("An exception has occurred: " + exception.getMessage());
    if (Constants.DEBUG) {
      exception.printStackTrace();
    }
  }
  return null;
}
 
public final BookInformationDetailed unpackBookInformationDetailed(String file) {
  try {
    Unmarshaller conversion = contextBookInformationDetailed.createUnmarshaller();
    return (BookInformationDetailed)conversion.unmarshal(new FileInputStream(file));  
  } catch (Exception exception) {
    System.out.println("An exception has occurred: " + exception.getMessage());
    if (Constants.DEBUG) {
      exception.printStackTrace();
    }
  }
  return null;
}

Pe baza fişierului WSDL care descrie serviciul web sunt generate clasele ce permit invocarea funcţionalităţii puse la dispoziţie de acesta. Pentru generarea unui serviciu web se foloseşte comanda wsgen, în timp ce pentru importarea unui serviciu web (spre a putea fi invocat) se foloseşte comanda wsimport.

wsgen [options] <SEI>

unde

• options

• SEI - reprezintă clasa Java conținând implementarea serviciului web

Exemplu:

wsgen -cp . ro.pub.cs.aipi.lab07.businesslogic.BookManager -wsdl -servicename {http://localhost:8080/bookstore/}BookManager

wsimport [options] <WSDL_URI>

unde

• options

iar extensiile suportate sunt:

• WSDL_URI - reprezintă locația fișierului WSDL care conține descrierea serviciului web

Exemplu:

wsimport -s ../src http://localhost:8080/bookstore/BookManager?wsdl

Astfel, pentru fiecare metodă implementată de serviciul web (definită ca operation în secţiunea binding a fişierului WSDL) sunt generate clasele Operation şi OperationResponse, responsabile cu transmiterea cererilor și răspunsurilor prin infrastructura de comunicație:

• clasa Operation oferă metode pentru transferul parametrilor metodelor accesibile la distanță;
• clasa OperationResponse oferă metode pentru transferul valorilor întoarse ale metodelor accesibile la distanță.

De asemenea, este furnizată și o fabrică de obiecte (ObjectFactory) pentru crearea unor instanțe ale acestor clase.

Totodată, sunt generate şi clasele corespunzătoare obiectelor transmise ca parametrii sau rezultate întoarse, în care tipul atributelor este însă transformat astfel încât să poată fi transmise prin infrastructura de comunicaţie.

Invocările metodelor implementate în cadrul serviciului web se fac printr-un obiect local care funcţionează ca un delegat pentru serviciul la distanţă. Acesta este obţinut ca port al unei alte clase generate pe baza serviciului web în care sunt definite metodele, având denumirea sufixată de _Service.

BookManagerClient.java

public class BookManagerClient{
 
  @WebServiceRef(wsdlLocation = "META-INF/wsdl/localhost_8080/07-BookStore-JAXWS-Server/BookManager.wsdl")
  private static BookManager_Service service;
 
  public static void main(String[] args) {
    service = new BookManager_Service();
    BookManager port = service.getBookManagerPort();   
 
    Utilities.displayResults(port.getBooksList(), BookInformation.class);
    System.out.println("Enter stockpile: ");
    int stockpile = Integer.parseInt(bufferedReader.readLine());
    Utilities.displayResults(port.getBooksListWithStockpile(stockpile), BookInformationDetailed.class);
  }
 
}

Prin adnotarea @WsdlServiceRef se indică fișierul WSDL care conține descrierea serviciului web referit, acesta trebuind să existe la locația specificată de parametrul wsdlLocation.

Pe baza acestei descrieri, vor fi generate în mod automat clasele responsabile cu transportul parametrilor și valorilor întoarse ale metodelor accesibile la distanță.

În situația în care există mai multe servicii web care pun la dispoziție aceeași funcționalitate (aceleași metode accesibile la distanță), dar cu implementări diferite, există posibilitatea invocării dinamice (în momentul execuției), serviciul fiind obținut pe baza metodei statice create() din cadrul clasei javax.xml.ws.Service, primind ca parametrii denumirea sa și locația la care este disponibil documentul WSDL ce îi descrie funcționalitatea:

public static Service create(URL wsdlDocumentLocation, QName serviceName) throws javax.xml.ws.WebServiceException {}

Un exemplu de instanțiere a unui astfel de serviciu ar putea fi:

try {
  URL wsdlDocumentLocation = new URL("http://localhost:8080/bookstore/BookManager?wsdl");
  QName serviceName = new QName("http://businesslogic.lab07.aipi.cs.pub.ro/BookManager", "BookManager");
  Service service = Service.create(wsdlDocumentLocation, serviceName);
} catch (MalformedURLException malformedURLException) {
  System.out.println("An exception had occurred: " + malformedURLException.getMessage());
  if (Constants.DEBUG) {
    malformedURLException.printStackTrace();
  }
}

Ulterior, funcționalitatea îi poate fi invocată prin intermediul metodei getPort() a obiectului de tip Service, care primește ca parametru clasa pe care o reprezintă (la care va fi convertit):

public <T> T getPort(Class<T> serviceEndpointInterface) throws javax.xml.ws.WebServiceException {}

Un exemplu de obținere a unui port pentru care pot fi invocate ulterior serviciile pot fi:

BookManager port = service.getPort(BookManager.class);

Se creează un proiect de tip Java Web → Web Application.

În situația în care Java Enterprise Edition nu este inițializată pentru NetBeans, această operație este realizată în acest moment, putând dura, după caz, o perioadă de timp mai mare.

Pentru aplicația web se precizează o denumire, precum și locația unde va fi amplasat proiectul corespunzător.

Este indicat tipul de server de aplicații care va fi utilizat (GlassFish Server 4.1), versiunea Java Enterprise Edition (în cazul de față Java EE 7 Web), precum și contextul din care va putea fi accesat serviciul web (/07-BookStore-JAXWS-Server).

Pot fi specificate și alte tehnologii cu care să fie integrat serviciul web (Spring Web MVC, Java Server Faces, Struts, Hibernate).

Proiectul va conține o resursă de tip Web Service…, accesibilă din meniul contextual prin selectarea opțiunii New.

Pentru serviciul web trebuie completate atribute precum:

• denumirea;
• proiectul din care face parte;
• localizarea;
• pachetul în care este inclus codul sursă corespunzător implementării;
• modul de creare al serviciului web:
  • de la zero;
  • pornind de la o componentă de tip Session Bean (pentru care se indică locația);
• posibilitatea de a implementa un comportament de componentă Java Beans de tip sesiune fără stare.

După implementarea funcţionalităţii puse la dispoziţie, aceasta poate fi vizualizată din modul Design.

Sunt indicate aici numele şi tipul parametrilor acceptaţi de metodele serviciului web, tipul rezultatului întors, excepţiile care pot fi generate precum şi o descriere a funcţionalităţii respective.

Modulul permite gestiunea operațiilor pe care serviciul web le pune la dispoziția utilizatorilor (adăugare, modificare, ștergere) precum și controlul unor atribute ce țin de calitatea serviciului:

• optimizarea transferului datelor binare;
• fiabilitatea transmiterii mesajelor;
• securitate.

În momentul în care este lansat în execuţie serviciul web (opţiunea Deploy din meniul contextual corespunzător proiectului), este pornit şi serverul de aplicaţii GlassFish.

Ulterior, modificările asupra codului sursă sunt reflectate la nivelul serverului de aplicaţii în mod automat atunci când acesta este salvat (codul sursă este compilat, iar clasele sunt plasate în contextul serverului GlassFish).

Accesând consola serverului de aplicaţii GlassFish (la adresa http://localhost:4848), poate fi vizualizat serviciul web dezvoltat în secţiunea Applications sub denumirea care a fost indicată la crearea lui.

Legătura ViewEndpoint corespunzătoare componentei serviciului web trimite către fişierul WSDL care conţine descrierea serviciului web (la adresa http://localhost:8080/ReservationService/Reservation?wsdl), permiţând şi testarea funcţionalităţii acestuia.

BookManager.wsdl

This XML file does not appear to have any style information associated with it. The document tree is shown below.
<!--
 Published by JAX-WS RI (http://jax-ws.java.net). RI's version is Metro/2.3.1-b419 (branches/2.3.1.x-7937; 2014-08-04T08:11:03+0000) JAXWS-RI/2.2.10-b140803.1500 JAXWS-API/2.2.11 JAXB-RI/2.2.10-b140802.1033 JAXB-API/2.2.12-b140109.1041 svn-revision#unknown. 
-->
<!--
 Generated by JAX-WS RI (http://jax-ws.java.net). RI's version is Metro/2.3.1-b419 (branches/2.3.1.x-7937; 2014-08-04T08:11:03+0000) JAXWS-RI/2.2.10-b140803.1500 JAXWS-API/2.2.11 JAXB-RI/2.2.10-b140802.1033 JAXB-API/2.2.12-b140109.1041 svn-revision#unknown. 
-->
<definitions xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd" xmlns:wsp="http://www.w3.org/ns/ws-policy" xmlns:wsp1_2="http://schemas.xmlsoap.org/ws/2004/09/policy" xmlns:wsam="http://www.w3.org/2007/05/addressing/metadata" xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" xmlns:tns="http://businesslogic.lab07.aipi.cs.pub.ro/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="http://schemas.xmlsoap.org/wsdl/" targetNamespace="http://businesslogic.lab07.aipi.cs.pub.ro/" name="BookManager">
  <types>
    <xsd:schema>
      <xsd:import namespace="http://businesslogic.lab07.aipi.cs.pub.ro/" schemaLocation="http://aipi2015:8080/07-BookStore-JAXWS-Server/BookManager?xsd=1"/>
    </xsd:schema>
  </types>
  <message name="getBooksList">
    <part name="parameters" element="tns:getBooksList"/>
  </message>
  <message name="getBooksListResponse">
    <part name="parameters" element="tns:getBooksListResponse"/>
  </message>
  <message name="getBooksListWithStockpile">
    <part name="parameters" element="tns:getBooksListWithStockpile"/>
  </message>
  <message name="getBooksListWithStockpileResponse">
    <part name="parameters" element="tns:getBooksListWithStockpileResponse"/>
  </message>
  <portType name="BookManager">
    <operation name="getBooksList">
      <input wsam:Action="http://businesslogic.lab07.aipi.cs.pub.ro/BookManager/getBooksListRequest" message="tns:getBooksList"/>
      <output wsam:Action="http://businesslogic.lab07.aipi.cs.pub.ro/BookManager/getBooksListResponse" message="tns:getBooksListResponse"/>
    </operation>
    <operation name="getBooksListWithStockpile">
      <input wsam:Action="http://businesslogic.lab07.aipi.cs.pub.ro/BookManager/getBooksListWithStockpileRequest" message="tns:getBooksListWithStockpile"/>
      <output wsam:Action="http://businesslogic.lab07.aipi.cs.pub.ro/BookManager/getBooksListWithStockpileResponse" message="tns:getBooksListWithStockpileResponse"/>
    </operation>
  </portType>
  <binding name="BookManagerPortBinding" type="tns:BookManager">
    <soap:binding transport="http://schemas.xmlsoap.org/soap/http" style="document"/>
    <operation name="getBooksList">
      <soap:operation soapAction=""/>
      <input>
        <soap:body use="literal"/>
      </input>
      <output>
        <soap:body use="literal"/>
      </output>
    </operation>
    <operation name="getBooksListWithStockpile">
      <soap:operation soapAction=""/>
      <input>
        <soap:body use="literal"/>
      </input>
      <output>
        <soap:body use="literal"/>
      </output>
    </operation>
  </binding>
  <service name="BookManager">
    <port name="BookManagerPort" binding="tns:BookManagerPortBinding">
      <soap:address location="http://aipi2015:8080/07-BookStore-JAXWS-Server/BookManager"/>
    </port>
  </service>
</definitions>

Se creează un proiect de tip Java Desktop Application care va conține un client al unui serviciu web (New → Web Service Client din meniul contextual).

Se indică locația (URL-ul) la care se găsește specificația WSDL a serviciului web (http://localhost:8080/07-BookStore-JAXWS-Server/BookManager?wsdl), pe baza căreia vor fi generate clasele care descriu operațiile ce pot fi invocate.

Pentru a genera clasele corespunzătoare serviciului web, din meniul contextual asociat referinței la serviciul web, se accesează opțiunea Refresh. O astfel de operație este necesară atunci când se modifică funcționalitatea serviciului web (semnăturile metodelor accesibile la distanță, NU și implementarea lor, care este transparentă pentru client).

De asemenea, este necesar să se bifeze opțiunea Also replace local wsdl file with original wsdl located at:, astfel încât să se descarce definiția serviciului web (fișierul WSDL) de la locația în care a fost publicat de către server:

Clasele generate sunt vizibile în secțiunea Generated Sources (jax-ws).

Operaţiile pot fi testate din consola serverului de aplicaţii GlassFish, disponibile la http://localhost:8080/07-BookStore-JAXWS-Server/BookManager?Tester. Invocarea unei funcţionalităţi în acest caz este întotdeauna însoţită de mesajele SOAP care sunt schimbate între client şi server, fiind descrise cererea (invocarea metodei din cadrul serviciului web) precum şi răspunsul (rezultatul execuţiei operaţiei respective în contextul serverului unde rulează serviciul web).

Pentru exemplul considerat, în cazul metodelor getBooksList(), getBooksListWithStockpile() pot fi vizualizate referinţe (adrese) către obiecte de tip BookInformation / BookInformationDetailed. În situația în care metodele ar fi primit ca parametri tipuri de date derivate din java.lang.Object, o astfel de consolă nu ar putea fi utilizată, întrucât ar trebui furnizate referințele către aceste obiecte.

Pentru operaţia getBooksList(), formatul mesajelor SOAP interschimbate între client şi server este următorul:

• SOAP Request

  <?xml version="1.0" encoding="UTF-8"?><S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/" xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
    <SOAP-ENV:Header/>
    <S:Body>
      <ns2:getBooksList xmlns:ns2="http://businesslogic.lab07.aipi.cs.pub.ro/"/>
    </S:Body>
  </S:Envelope>

• SOAP Response

  <?xml version="1.0" encoding="UTF-8"?><S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/" xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
    <SOAP-ENV:Header/>
    <S:Body>
      <ns2:getBooksListResponse xmlns:ns2="http://businesslogic.lab07.aipi.cs.pub.ro/">
        <return>
          <id>1</id>
          <collection>My Best Series Books</collection>
          <country>Russia</country>
          <edition>3</edition>
          <printingYear>1957</printingYear>
          <publishingHouse>XoXo Publishing a Ninni Group Inc</publishingHouse>
          <title>Consuming Ocean Island</title>
          <writers>Dora APEL</writers>
        </return>
        <!-- other results -->
      </ns2:getBooksListResponse>
    </S:Body>
  </S:Envelope>
   

Pentru operaţia getBooksListWithStockpile(), primind ca parametru un stoc egal 500, formatul mesajelor SOAP interschimbate între client şi server este următorul:

• SOAP Request

  <?xml version="1.0" encoding="UTF-8"?><S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/" xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
    <SOAP-ENV:Header/>
    <S:Body>
      <ns2:getBooksListWithStockpile xmlns:ns2="http://businesslogic.lab07.aipi.cs.pub.ro/">
        <stockpile>500</stockpile>
      </ns2:getBooksListWithStockpile>
    </S:Body>
  </S:Envelope>

• SOAP Response

  <?xml version="1.0" encoding="UTF-8"?><S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/" xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
    <SOAP-ENV:Header/>
    <S:Body>
      <ns2:getBooksListWithStockpileResponse xmlns:ns2="http://businesslogic.lab07.aipi.cs.pub.ro/">
        <return>
          <id>1</id>
          <categories>Basketball</categories>
          <formats>50 × 75, EPUB, Plucker</formats>
          <languages>Afar, Afrikaans, Vietnamese</languages>
          <subtitle>Stories of People and Phosphate from Banaba</subtitle>
          <title>Consuming Ocean Island</title>
          <writers>Dora APEL</writers>
        </return>
        <!-- other returns -->
      </ns2:getBooksListWithStockpileResponse>
    </S:Body>
  </S:Envelope>

0. Să se cloneze în directorul de pe discul local conținutul depozitului la distanță de la https://www.github.com/aipi2015/Laborator07. În urma acestei operații, directorul Laborator07 va trebui să conțină subdirectorul labtasks, fișierele README.md și LICENSE.

student@aipi2015:~$ git clone https://www.github.com/aipi2015/Laborator07.git

1. Să se ruleze, folosind MySQL Workbench (sau alt utilitar similar), scripturile Laborator07c.sql și Laborator07l.sql, localizate în directorul scripts din cadrul proiectului 07-BookStore-JAXWS-Server. Acesta instalează baza de date bookstore.

2. Să se modifice credențialele (nume de utilizator și parolă), astfel încât să se poată accesa informațiile din baza de date MySQL.

Este suficient să se modifice proprietățile javax.persistence.jdbc.user, respectiv javax.persistence.jdbc.password din fișierul persistence.xml, localizat în directorul src/META-INF, întrucât în această situație este folosit un server local, iar accesul la sistemul de gestiune pentru baze de date se realizează din contextul acestuia.

În cazul în care accesul la sistemul de gestiune pentru baze de date se realizează din contextul unui server de aplicații (GlassFish 4.1), este necesar să se definească o resursă la nivelul acestuia, referința către aceasta fiind identificată prin intermediul JNDI (Java Naming and Directory Interface).

În acest sens, în fișierul persistence.xml vor fi realizate următoarele modificări:

• atributul transaction-type din cadrul elementului persistence-unit va avea valoarea JTA;
• informațiile cu privire la conexiunea la sistemul de gestiune pentru baze de date vor fi specificate printr-o resursă JNDI, a cărui referință este indicată în cadrul elementului jta-data-source;
• nu mai sunt necesare proprietățile javax.persistence.jdbc.url, javax.persistence.jdbc.user, javax.persistence.jdbc.password, javax.persistence.jdbc.driver, acestea fiind conținute în resursa definită la nivelul serverului de aplicație;
• în secțiunea de proprietăți, se va defini proprietatea hibernate.transaction.jta.platform cu valoarea org.hibernate.service.jta.platform.internal.SunOneJtaPlatform.

Definirea unei resurse JDBC în cadrul serverului de aplicație GlassFish implică următoarele etape:

a. se accesează secțiunea JDBC Connection Pools disponibilă în Resources → JDBC și se apasă butonul New pentru a se defini un nou set de conexiuni:

b. se specifică proprietățile:

• Pool Name, va avea o valoare definită de utilizator, spre exemplu: MySQLConnectionPool;
• Resource Type, trebuie să aibă valoarea javax.sql.DataSource selectată din lista de opțiuni;
• Database Driver Vendor, trebuie să aibă valoarea MySQL selectată din lista de opțiuni;

Se apasă butonul Next.

În secțiunea Aditional Properties, trebuie specificate următoarele proprietăți:

• ServerName cu valoarea localhost;
• Port cu valoarea 3306;
• User cu valoarea numelui de utilizator prin intermediul căruia se va realiza conexiunea (root);
• Password cu valoarea parolei prin intermediul căreia se va realiza conexiunea (StudentAipi2015);
• DatabaseName cu valoarea bazei de date care va fi exploatată (bookstore).

Se apasă butonul Finish.

Noul set de conexiuni va fi vizibil în secțiunea Resources → JDBC → JDBC Connection Pools.

Se accesează resursa creată în panoul Advanced.

În secțiunea Connection Validation se specifică următoarele proprietăți, necesare datorită faptului că driver-ul de conexiune la sistemul de gestiune pentru baze de date Connector/J nu suportă optimizarea interogărilor pentru validare:

• Connection Validation: Required;
• Validation Method: se selectează valoarea table din lista de opțiuni;
• Table Name: se introduce valoarea DUAL.

Se apasă butonul Save astfel încât modificările realizate să fie preluate.

Pentru a se verifica starea conectivității la sistemul de gestiune pentru baze de date, în panoul General, se apasă butonul Ping. În situația în care rezultatul furnizat este Ping Succeeded, conexiunea a fost configurată corect.

c. se accesează secțiunea JDBC Resources disponibilă în Resources → JDBC și se apasă butonul New pentru a se defini o nouă resursă:

d. se specifică proprietățile:

• JNDI Name, va avea o valoare definită de utilizator, spre exemplu: jdbc/MySQLDataSource; aceeași valoare trebuie să fie specificată și în elementul jta-data-source din fișierul persistence.xml;
• Pool Name, va referi setul de conexiuni definit anterior (spre exemplu, MySQLConnectionPool), disponibil într-o listă de opțiuni.

Se apasă butonul Ok.

Noua resursă va fi vizibilă în secțiunea Resources → JDBC → JDBC Resources.

3. Să se ruleze proiectul corespunzător serverului (07-BookStore-JAXWS-Server).

Proiectul se rulează ca aplicație Java (Run As… → Java Application). Nu este necesară definirea unei configurații de rulare dedicate, întrucât nu trebuie specificați nici argumente în linia de comandă și nici parametrii ai mașinii virtuale. Aplicația va rămâne în execuție întrucât metoda Endpoint.publish() creează o instanță a unui server local, prin intermediul căruia vor fi expuse metodele corespunzătoare serviciului web.

Proiectul este instalat la nivelul serverului de aplicații GlassFish 4.1 prin intermediul opțiunii Deploy disponibilă la nivelul meniului contextual asociat. Aceasta lansează în execuție serverul de aplicații (dacă acesta nu rulează deja) și copiază în contextul său resursele necesare astfel încât funcționalitățile corespunzătoare serviciului web să fie disponibile la distanță. O astfel de operație poate dura o perioadă de timp semnificativă.

4. Să se ruleze proiectul corespunzător unuia dintre clienți (07-BookStore-JAXWS-Client-BookManager). Să se testeze funcționalitățile expuse prin intermediul serviciului web.

Anterior, trebuie să se genereze clasele care conțin definiția serviciului web (clasa _Service), definițiile metodelor la distanță (clasele Operation, respectiv OperationResponse, pentru fiecare funcționalitate în parte), definițiile entităților transmise ca parametrii sau valori întoarse ale acestora precum și fabrica de obiecte (clasa ObjectFactory).

Este necesar să se ruleze script-ul client[.bat|.sh] care rulează comanda wsimport necesară generării claselor necesare pentru accesarea metodelor expuse prin intermediul serviciului web:

wsimport -s ../src http://localhost:8080/bookstore/BookManager?wsdl

Se indică locația la care este publicat fișierul WSDL conținând definiția serviciului web precum și locația la care va fi plasat codul sursă, prin intermediul opțiunii -s.

Este necesar să se creeze un client pentru serviciul web (definirea unei resurse de tip Web Service Client din secțiunea New a meniului contextual asociat proiectului). Aceasta va specifica adresa Internet la care a fost publicat fișierul WSDL (http://localhost:8080/07-BookStore-JAXWS-Server/BookManager?wsdl). Ulterior, generarea codului sursă se face prin accesarea opțiunii Refresh din meniul contextual asociat referinței la serviciul web. Se va folosi opțiunea Also replace local wsdl file with original wsdl located at. Clasele generate vor fi evidențiate prin plasarea lor în secțiunea Generated Sources (jax-ws).

După ce au fost generate clasele necesare, astfel încât proiectele să nu mai aibă erori, rularea proiectului se face obișnuit (Run As… → Java Application, pentru Eclipse, respectiv Run folosind configurația de rulare implicită, pentru NetBeans).

5. Să se expună metodele corespunzătoare clasei BookPresentationManager din pachetul ro.pub.cs.aipi.lab07.businesslogic, astfel încât acestea să fie accesibile la distanță prin intermediul unui serviciu web același denumire. Să se relanseze în execuție serverul, astfel încât acesta să expună și funcționalitățile serviciului web BookPresentationManager.

<spoiler|Indicații de Rezolvare> a) Se adnotează clasa BookPresentationManager precum și metodele care vor fi expuse la distanță (cu parametrii lor):

1. clasa BookPresentationManager se adnotează folosind însemnarea @WebService(serviceName = “BookPresentationManager”);
2. metodele care vor fi expuse la distanță se adnotează folosind însemnarea @WebMethod(operationName = “…”):

   @WebMethod(operationName = "updateBookPresentationPriceForBooksWithMultipleFormats")
   @WebMethod(operationName = "makeSupplyOrderBasedOnStockpile")

3. parametrii metodelor care vor fi expuse la distanță se adnotează folosind însemnarea @WebParam(name = “…”):

   public List<BookPresentationInformation> updateBookPresentationPriceForBooksWithMultipleFormats(@WebParam(name = "numberOfFormats") int numberOfFormats, @WebParam(name = "amount") double amount);
   public List<SupplyOrderInformation> makeSupplyOrderBasedOnStockpile(@WebParam(name = "stockpile") int stockpile);

</spoiler>

b) Se adnotează clasele BookPresentationInformation și SupplyOrderInformation, ale căror instanțe vor fi transmise prin rețea, sub formă de documente XML, astfel încât JAXB să cunoască mecanismul prin care obiectele Java pot fi transformate în scheme XML și invers:

1. clasele BookPresentationInformation și SupplyOrderInformation vor fi adnotate folosind însemnările @XmlRootElement și @XmlType(name=“…”):

   @XmlRootElement
   @XmlType(name="BookPresentationInformation")
   public class BookPresentationInformation extends PersistentEntity {
    
     // ...
    
   }

2. toate metodele de tip getter (cu excepția celei care furnizează identificatorul, getId()) vor fi adnotate folosind însemnarea @XmlElement.

c) Este necesar să se publice serviciul web BookPresentationManager printr-un apel al metodei Endpoint.publish(). Pentru fiecare serviciu web publicat, trebuie să se folosească un port dedicat.

Endpoint.publish("http://localhost:8081/bookstore/BookPresentationManager", new BookPresentationManager());
System.out.println("[BookPresentationManager] successfully registered!");

c) Nu este necesar să se realizeze nici o acțiune suplimentară, întrucât clasele adnotate cu însemnarea @WebService sunt detectate automat ca servicii web (vizibile în secțiunea Web Services) al căror conținut este instalat în contextul serverului de aplicații în momentul în care se accesează opțiunea Deploy.

6. Să se construiască un client care să acceseze funcționalitățile corespunzătoare serviciului web BookPresentationManager. Să se testeze metodele expuse la distanță prin intermediul serviciului web.

<spoiler|Indicații de Rezolvare> a) Se creează un proiect Java.

b) Se generează definițiile de clase necesare pentru accesarea funcționalităților expuse de serviciul web.

În directorul scripts aferent proiectului, se creează un script client[.bat|.sh] care rulează comanda wsimport necesară generării claselor necesare pentru accesarea metodelor expuse prin intermediul serviciului web:

wsimport -s ../src http://localhost:8081/bookstore/BookPresentationManager?wsdl

Se indică locația la care este publicat fișierul WSDL conținând definiția serviciului web precum și locația la care va fi plasat codul sursă, prin intermediul opțiunii -s.

Este necesar să se creeze un client pentru serviciul web (definirea unei resurse de tip Web Service Client din secțiunea New a meniului contextual asociat proiectului). Aceasta va specifica adresa Internet la care a fost publicat fișierul WSDL (http://localhost:8081/07-BookStore-JAXWS-Server/BookPresentationManager?wsdl). Ulterior, generarea codului sursă se face prin accesarea opțiunii Refresh din meniul contextual asociat referinței la serviciul web. Se va folosi opțiunea Also replace local wsdl file with original wsdl located at. Clasele generate vor fi evidențiate prin plasarea lor în secțiunea Generated Sources (jax-ws).

c) Se definește clasa BookPresentationManagerClient în pachetul ro.pub.cs.aipi.lab07.main, conținând metoda main():

1. se creează obiectele de tip Service, respectiv port corespunzătoare serviciului web:

   BookPresentationManager_Service service = new BookPresentationManager_Service();
   BookPresentationManager port = service.getBookPresentationManagerPort();

2. se accesează metodele la distanță, expuse prin intermediul serviciului web:

   System.out.println("Enter number of formats: ");
   int numberOfFormats = Integer.parseInt(bufferedReader.readLine());
   System.out.println("Enter percent amount: ");
   double amount = Double.parseDouble(bufferedReader.readLine());
   port.updateBookPresentationPriceForBooksWithMultipleFormats(numberOfFormats, amount);
   System.out.println("Enter stockpile: ");
   int stockpile = Integer.parseInt(bufferedReader.readLine());
   port.makeSupplyOrderBasedOnStockpile(stockpile)

d) Pentru afișarea rezultatelor, poate fi util să se definească metoda displayResults care primește ca parametri o listă de obiecte (derivate din PersistentEntity) precum și clasa care conține tipul propriu-zis, afișând conținutul tuturor câmpurilor, prin intermediul metodelor puse la dispoziție de pachetul java.lang.Reflect. </spoiler>

7. (opțional) Să se expună metodele corespunzătoare clasei WriterManager din pachetul ro.pub.cs.aipi.lab07.businesslogic, astfel încât acestea să fie accesibile la distanță prin intermediul unui serviciu web având aceeași denumire. Să se relanseze în execuție serverul, astfel încât acesta să expună și funcționalitățile serviciului web WriterManager.

8. (opțional) Să se construiască un client care să acceseze funcționalitățile corespunzătoare serviciului web WriterManager. Să se testeze acest metodele expuse la distanță prin intermediul serviciului web.

Eric Jendrock, Ricardo Cervera- Navarro, Ian Evans, Kim Haase, William Markito - The Java EE 7 Tutorial - capitolele 27, 28
Getting Started with JAX-WS Web Services
Java Architecture for XML Binding (JAXB)
JAXB - Tutorial
Using Connector/J with GlassFish
Developing JAX-WS Web Services with Annotations

TODO