Makkelijk webservices ontwikkelen met JSR-181

JSR-181 zorgt ervoor dat een J2EE container Java geannoteerde bestanden makkelijk kan interpreteren als web services. Een hele zin, maar onderstaand voorbeeld laat zien hoe makkelijk het is om met JSR-181 een web service te ontwikkelen.

Dit artikel laat in 5 stappen zien hoe je een JSR-181 project van a tot z kunt opbouwen. Stap 1 en 2 illustreren hoe je m.b.v. Maven een project snel kunt inrichten. Als je Maven nog niet kent moet je daar zeker even na kijken. Mocht je Maven helemaal niks vinden begin dan bij stap 3. Alle gebruikte code en configuratie is te vinden in de AmbiSoft repository (ambisoft.nl/java/jws).

Stap 1 – Aanmaken van een project

Maven projecten hebben altijd dezelfde directory structuur. Dit heeft twee grote voordelen: Maven weet wat hij met het project kan doen en ontwikkelaars hebben snel door wat waar staat. Het automatisch genereren van een Maven project kan met het volgende commando.

mvn archetype:create -DgroupId=nl.ambisoft.jws -DartifactId=jws

Maven zal een aantal directories en een POM genereren. Aan de gegenereerde POM moet een dependency worden toegevoegd die het mogelijk maakt dat we in het project JSR-181 kunnen gaan gebruiken. Er zijn verschillende JSR-181 implementaties, maar voor dit voorbeeld voegen we de volgende dependency toe.

<dependency>
	<groupId>jboss</groupId>
	<artifactId>jboss-jaxws</artifactId>
	<version>1.2.1.GA</version>
</dependency>
...
<repository>
	<id>jboss</id>
	<url>http://repository.jboss.com/maven2</url>
</repository>

Stap 2 – Maak het project beschikbaar in Eclipse

Door het project beschikbaar te maken voor Eclipse kun je straks makkelijker gaan sleutelen aan de gemaakte webservice. Je maakt een maven project beschikbaar voor Eclipse met het volgende commando.

mvn eclipse:eclipse

Stap 3 – Informeer de J2EE container over de webservice

Net zoals een JSP binnen een J2EE container (uiteindelijk) als een servlet beschikbaar wordt gesteld, geldt dat ook voor een webservice. De J2EE container ziet de te maken webservice dus als een servlet. In de web.xml geef je aan waar de J2EE container de webservice kan vinden, de container zorgt er dan voor dat alles automatisch gaat werken. Vermeld voor het voorbeeld de volgende informatie in de web.xml

<servlet>
	<servlet-name>HelloWorldWebservice</servlet-name>
	<servlet-class>nl.ambisoft.jws.HelloWorldWebservice</servlet-class>
</servlet>
<servlet-mapping>
	<servlet-name>HelloWorldWebservice</servlet-name>
	<url-pattern>/HelloWorldWebservice</url-pattern>
</servlet-mapping>

Stap 4 – Het maken van de webservice

De webservice is een gewoon Java object waar je verder niets voor hoeft te doen. Je hoeft dus geen WSDL te maken (phuw), geen XSD’s, niets van dat. Maak een Java object aan met het volgende code fragment.

@WebService(name = "HelloWorldWebservice", targetNamespace = "http://www.ambisoft.nl/helloWorldWebservice")
public class HelloWorldWebservice {
	@WebMethod
	public String helloWorld(@WebParam(name = "message") String message) {
		return "Hello - " + message;
	}

De @WebService annotatie zorgt ervoor dat de J2EE container dit java object als webservice beschikbaar zal stellen. De webservice wordt gepubliseerd op /HelloWorldWebservice/HelloWorldWebservice. De WSDL wordt automatisch gegenereerd en is te vinden op /HelloWorldWebservice/HelloWorldWebservice?wsdl. Het eerste deel van de URI wordt bepaald door de servlet mapping in de web.xml, het tweede deel van de URI wordt bepaald door het ‘name’ attribuut uit de @webservice annotatie.

De @WebMethod annotatie zorgt ervoor dat de geannoteerde methode beschikbaar komt in de gegenereerde webserivce.

De @WebParam annotatie zorgt ervoor dat de input parameter een nette naam krijgt in de WSDL.

Zoals het voorbeeld laat zien is er dus niet veel nodig om van een gewoon Java object een webservice te maken. Dit voorbeeld laat 3 annotaties zien, maar er zijn er meer. De Standard JSR-181 JWS Annotations Reference geeft een goed overzicht van alle beschikbare JSR-181 annotaties.

Stap 5 – Activeer webservice

De laatste stap die uitgevoerd moet worden alvorens de webservice is te gebruiken is het deployen van het project in een J2EE container. Het volgende Maven commando genereert een war van het project.

mvn package

Deploy de gegenereerde war in de J2EE container. De webservice is nu beschikbaar op http://jouwserver/HelloWorldWebservice/HelloWorldWebservice?wsdl. Gebruik een webservice tool zoals SOAPUI om de webservice in actie te zien.