Webbtjänster i Java SE, del 2: Skapa SOAP-webbtjänster
JAX-WS stöder SOAP-baserade webbtjänster. Del 2 i denna fyrdelarserie på Java SE-webbtjänster definierar en SOAP-baserad enhetskonvertering webbtjänst, bygger och verifierar sedan denna webbtjänst lokalt via standardlättvikts HTTP-server (diskuteras i del 1), tolkar tjänstens WSDL-dokument och får åtkomst till tjänsten från en enkel klient.
Definiera en webbtjänst för omvandling av enheter
Enhetens omvandling webbtjänst, som jag har kallat UC, består av fyra funktioner för att konvertera mellan centimeter och tum och mellan grader Fahrenheit och grader Celsius. Även om detta exempel skulle kunna arkiveras som en enda Java-klass har jag valt att följa bästa praxis genom att arkivera det som ett Java-gränssnitt och en Java-klass. Listning 1 visar webbtjänstens UC
gränssnitt.
Listning 1. UC-webbtjänstens Service Endpoint Interface
package ca.javajeff.uc; import javax.jws.WebMethod; import javax.jws.WebService; @WebService public interface UC { @WebMethod double c2f(double degrees); @WebMethod double cm2in(double cm); @WebMethod double f2c(double degrees); @WebMethod double in2cm(double in); }
UC
beskriver ett Service Endpoint Interface (SEI) , vilket är ett Java-gränssnitt som exponerar ett webbtjänstgränssnitts operationer i termer av abstrakta Java-metoder. Kunder kommunicerar med SOAP-baserade webbtjänster via sina SEI.
UC
förklaras vara ett SEI via @WebService
anteckningen. När ett Java-gränssnitt eller en klass antecknas följer @WebService
alla public
metoder vars parametrar, returvärden och deklarerade undantag reglerna som definieras i avsnitt 5 i JAX-RPC 1.1-specifikationen webbtjänståtgärder. Eftersom endast public
metoder kan deklareras i gränssnitt, det public
är reserverat ord inte nödvändigt när förklara c2f()
, cm2in()
, f2c()
, och in2cm()
. Dessa metoder är implicit public
.
Varje metod antecknas också @WebMethod
. Även om det @WebMethod
inte är nödvändigt i detta exempel, förstärker dess närvaro det faktum att den kommenterade metoden exponerar en webbtjänst.
Listning 2 presenterar webbtjänstens UCImpl
klass.
Listing 2. UC-webbtjänstens Service Implementation Bean
package ca.javajeff.uc; import javax.jws.WebService; @WebService(endpointInterface = "ca.javajeff.uc.UC") public class UCImpl implements UC { @Override public double c2f(double degrees) { return degrees * 9.0 / 5.0 + 32; } @Override public double cm2in(double cm) { return cm / 2.54; } @Override public double f2c(double degrees) { return (degrees - 32) * 5.0 / 9.0; } @Override public double in2cm(double in) { return in * 2.54; } }
UCImpl
beskriver en Service Implementation Bean (SIB) , som ger en implementering av SEI. Denna klass förklaras vara en SIB via @WebService(endpointInterface = "ca.javajeff.uc.UC")
anteckningen. Den endpointInterface
del förbinder detta SIB till sin SEI, och är nödvändigt för att undvika odefinierade typ port fel när du kör programmet klienten presenteras senare.
Den implements UC
klausulen är inte absolut nödvändigt. Om denna klausul inte finns UC
ignoreras gränssnittet (och är överflödigt). Det är dock en bra idé att behålla implements UC
så att kompilatorn kan verifiera att SEI: s metoder har implementerats i SIB.
SIB: s metodrubriker är inte antecknade @WebMethod
eftersom den här anteckningen vanligtvis används i SEI-sammanhanget. Men om du skulle lägga till en public
metod (som överensstämmer med reglerna i avsnitt 5 i JAX-RPC 1.1-specifikationen) till SIB, och om den här metoden inte exponerar en webbtjänstoperation, skulle du kommentera metodhuvudet @WebMethod(exclude = true)
. Genom att tilldela true
till @WebMethod
's exclude
element, hindra dig denna metod från att associeras med en operation.
Denna webbtjänst är redo att publiceras så att den kan nås från klienter. Listning 3 presenterar en UCPublisher
applikation som utför denna uppgift i samband med standardlättvikts HTTP-servern.
Listing 3. Publicering UC
import javax.xml.ws.Endpoint; import ca.javajeff.uc.UCImpl; public class UCPublisher { public static void main(String[] args) { Endpoint.publish("//localhost:9901/UC", new UCImpl()); } }
Att publicera webbtjänsten innebär att ringa ett enda samtal till EndPoint
klassens Endpoint publish(String address, Object implementor)
klassmetod. De address
parameter identifierar URI tilldelats webbtjänst. Jag har valt att publicera den här webbtjänsten på den lokala värden genom att ange localhost
(motsvarar IP-adress 127.0.0.1) och portnummer 9901
(vilket sannolikt är tillgängligt). Jag har också godtyckligt valt /UC
som publiceringsväg. De implementor
parameter konstateras ett fall av UC
s SIB.
Den publish()
metod skapar och publicerar en slutpunkt för det angivna implementor
objektet i den givna address
och använder implementor
's anteckningar för att skapa Web Services Definition Language (WSDL) och XML Schema-dokument. Det gör att den nödvändiga serverinfrastrukturen skapas och konfigureras av JAX-WS-implementeringen baserat på någon standardkonfiguration. Dessutom gör denna metod att applikationen körs på obestämd tid. (På Windows-maskiner trycker du samtidigt på Ctrl och C för att avsluta applikationen.)
Bygga och verifiera webbtjänsten
Det är inte svårt att bygga den tidigare definierade UC-webbtjänsten. Först måste du skapa en lämplig katalogstruktur som innehåller lämpliga filer. Utför denna uppgift genom att utföra följande steg:
- Skapa en katalog i den aktuella
ca
katalogen. Inomca
, skapa enjavajeff
katalog. Slutligen, inomjavajeff
, skapa enuc
katalog. - Kopiera Listing 1 till en
UC.java
källfil och lagra den här filen ica/javajeff/uc
. - Kopiera Listing 2 till en
UCImpl.java
källfil och lagra den här filen ica/javajeff/uc
. - Kopiera Listing 3 till en
UCPublisher.java
källfil och lagra den här filen i den aktuella katalogen, som innehållerca
katalogen.
Nästa uppgift är att kompilera dessa källfiler. Antag att du inte har bytt katalog, kör följande kommando för att kompilera dessa källfiler i Java SE 9 (utelämna --add-modules java.xml.ws
i Java SE 6, 7 eller 8):
javac --add-modules java.xml.ws UCPublisher.java
Om dessa källfiler kompileras framgångsrikt kör du följande kommando för att köra det här programmet i Java 9 (utelämna --add-modules java.xml.ws
i Java SE 6, 7 eller 8):
java --add-modules java.xml.ws UCPublisher
Medan applikationen körs, använd en webbläsare för att verifiera att den här webbtjänsten fungerar korrekt och för att få åtkomst till WSDL-dokumentet. Starta din favoritwebbläsare och ange följande rad i adressfältet:
//localhost:9901/UC
Figur 1 visar den resulterande webbsidan i webbläsaren Google Chrome.
Figur 1. UC: s webbsida ger detaljerad information om den publicerade webbtjänsten
Figur 1 visar webbtjänstens slutpunkts kvalificerade service- och portnamn. (Observera att paketnamnet har inverterats - uc.javajeff.ca
istället för ca.javajeff.uc
). En klient använder dessa namn för att komma åt tjänsten.
Figur 1 visar också adressen URI för webbtjänsten, platsen för webbtjänstens WSDL-dokument (webbtjänstens URI efterfrågad av ?wsdl
frågesträngen) och det paketkvalificerade namnet på implementeringsklassen för webbtjänsten.
Tolkar webbtjänstens WSDL-dokument
Platsen för UC-webbtjänstens WSDL-dokument presenteras som en länk. Klicka på den här länken för att se WSDL-dokumentet, vars innehåll presenteras i Listing 4.
Listning 4. UC: s WSDL-dokument
Ett WSDL-dokument är ett XML-dokument med ett definitions
rotelement, vilket gör ett WSDL-dokument inte mer än en uppsättning definitioner. Detta element innehåller olika xmlns
attribut för att identifiera olika standardnamnområden, tillsammans med targetNameSpace
och name
attribut:
- The
targetNamespace
attribute creates a namespace for all user-defined elements in the WSDL document (such as thec2f
element defined via themessage
element with this name). This namespace is used to distinguish between the user-defined elements of the current WSDL document and user-defined elements of imported WSDL documents, which are identified via WSDL'simport
element. In a similar fashion, thetargetNamespace
attribute that appears on an XML Schema-based file'sschema
element creates a namespace for its user-defined simple type elements, attribute elements, and complex type elements. - The
name
attribute identifies the Web service and is used only to document the service.
Nested within definitions
are types
, message
, portType
, binding
, and service
elements: