Maven heeft een release plugin ontwikkeld waarmee makkelijk releases gemaakt kunnen worden. Zeker als je vaak releases maakt kan deze plugin werk uit handen nemen. De plugin helpt bij het aanpassen van versienummers, het taggen van code in de source repository, het copieren van een release naar de maven repository en nog een aantal zaken. Toen wij de maven release plugin gingen gebruiken kwamen we er achter dat onze manier van releasen niet helemaal te verenigen was met hoe de maven release plugin werkt. De documentatie over de plugin houdt helaas niet over en daardoor kan het onduidelijk zijn hoe je de plugin moet gebruiken. Dit artikel laat zien hoe je een maven project moet inrichten om met de release plugin te kunnen werken.

Snapshot versus Stable

Maven gebruikt twee soorten versies: snapshot en stable versies. Een project wordt gemarkeerd als snapshot versie wanneer deze in ontwikkeling is. Andere projecten die gebruik maken van een snapshot versie zullen altijd de laatste snapshot gebruiken, hierdoor hebben deze projecten altijd de nieuwste versie tot hun beschikking. Snapshot versies zijn handig op het moment dat code in ontwikkeling is. Een stable versie daarentegen is een versie die stabiel (af) is. Deze versie verandert niet meer. Andere projecten die op een stable versie dependen zullen altijd gebruik maken van dezelfde code. In de development- omgeving zul je vaak gebruik maken van snapshot versies. In test, acceptatie en productie wordt doorgaans met stable versies gewerkt. Het is in die omgevingen immers van belang dat een project niet zomaar verandert.

Release strategie

Veel projecten gebruiken hun eigen release strategieën en dat is natuurlijk prima. Het enige probleem is dat als je de maven release plugin wilt gaan gebruiken je een strategie moet gebruiken die samengaat met hoe de plugin werkt. Onderstaand figuur laat een mogelijke strategie zien die prima samengaat met de release plugin.

Het voorbeeld laat zien dat je begint te ontwikkelen met een snapshot versie (het zou mooi zijn als je project af is zo gauw je er aan begint . Nadat de gewenste functionaliteit is ontwikkeld en het project alle technische tests doorstaat kan de versie als stable worden bestempeld. De stable versie wordt vervolgens op de test-omgeving gezet waar men kan beginnen met het testen van de release. Bovenstaand figuur laat zien dat de 1.0 release fouten bevat en wordt afgekeurd. De ontwikkelaars, die al met de volgende 1.1-snapshot versie bezig zijn, kunnen de testbevindingen verwerken en een nieuwe stable release maken. Als de nieuwe versie weer door alle technische tests komt wordt deze gereleased en op test gezet. Als de tests goed gaan wordt de release doorgeschoven over acceptatie (niet in de figuur) en vervolgens naar productie. Als het testen lang duurt en de ontwikkelaars al bezig zijn met de volgende functionaliteiten dan kan het handig zijn om een branch te maken. Er kan ook voor gekozen worden om de bevindingen in de nieuwe release mee te nemen. Theoretisch is het maken van branches de netste manier van werken. In de praktijk is het werken met branches arbeidsintensief en vaak niet echt nodig. De maven release plugin heeft ook support voor branches.

Project voorbereiden

Om gebruik te kunnen maken van de Maven release plugin moet het project voorzien worden van informatie over de source repository en de lokatie van de maven repository. De volgende informatie moet aan de pom.xml worden toegevoegd.

<scm>
	<connection>scm:svn:http://ambisoft.nl/java/release/</connection>
</scm>
<distributionManagement>
	<repository>
		<id>ambirepo</id>
		<name>Ambisoft Repository</name>
		<url>scp:http://ambisoft.nl/repository</url>
	</repository>
 
	<snapshotRepository>
		<id>ambirepo</id>
		<name>Ambisoft Snapshot Repository</name>
		<url>scp:http://ambisoft.nl/snapshot-repository</url>
	</snapshotRepository>
</distributionManagement>

Gebruik van release plugin

Om te beginnen creëer een Maven project met het volgende commando.

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

Maven maakt nu een project aan met een standaard directory structuur en een standaard pom. De versie van het project wordt automatisch op release-1.0-SNAPSHOT gezet. Het project zal uitgebreid moeten worden met de informatie beschreven in de voorgaande stap. Een tip is om voor algemene functionaliteit een parent pom te maken zodat de instellingen voor alle projecten beschikbaar zijn.
Nu dat het Maven project klaar is kan er begonnen worden met ontwikkelen. Als alle functionaliteiten zijn geïmplementeerd en de technische tests falen niet dan kan een release gemaakt worden. Het releasen wordt gedaan met het volgende commando.

mvn release:prepare

Maven controleert of alle code in de source repository is ingecheckt. Vervolgens wordt de pom gecontroleerd op snapshot dependencies. Een stable release mag immers geen dependencies hebben op snapshot versies (want dan kan de release zelf nooit stable zijn). De versie in de pom wordt aangepast naar release-1.0. Vervolgens worden de technische tests uitgevoerd. Als dat allemaal goed gaat wordt de code gecommit in de source repository. De pom wordt weer aangepast zodat er verder gewerkt kan gaan worden met een release-1.1-snapshot. Een volledige lijst van wat het prepare commando doet is te vinden op de release:prepare voorbeeld pagina.

Het prepare commando zorgt ervoor dat er een nieuwe stable en een snapshot release gemaakt wordt. Om er nu voor te zorgen dat de stable release in de maven repository terecht komt kan het volgende commando gebruikt worden. Als het ontwikkelteam met maven sites werkt dan kan deze automatisch geupdate worden.

mvn release:perform

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.