Hands on exercise for

Transcription

1 Hands on exercise for João Miguel Pereira 2011

2 0 Prerequisites, assumptions and notes Have Maven 2 installed in your computer Have Eclipse installed in your computer (Recommended: Indigo Version) I m assuming you re running the exercises in Ubuntu It s recommended that you place all Maven exercises under a common directory. For example: ${user.home}/javatraining/maven During the exercises I will refer this directory as ${maven.exercises.folder} In every exercise I will refer the directory where you are working as ${project.dir}. This directory is where you have your pom.xml 1 Quick Start Exercise In this exercise you will explore a simple maven project. You will start to create a simple Hello World Java program from scratch only with the essential configuration. You will call this project Scratch. At the end of this exercise you should have the basic understand about Maven. You will also use the build lifecycles, learn how to import a Maven project into Eclipse and how to generate and install artifacts. 1.1 Create the file pom.xml The pom.xml is the Project Object Model and gives Maven the directives to test, build, package and deploy your project. Is a XML file that requires a minimum configuration, including: project root modelversion should be set to groupid the id of the project's group. artifactid the id of the artifact (project) version the version of the artifact under the specified group João MIguel Pereira 2011 Page 2 of 25

3 1. Create a new directory in your ${maven.exercises.folder}called scratch. mkdir ${maven.exercises.folder}/scratch 2. Within the directory, you ve create in step 1, create a new file called pom.xml with the following contents: <project xmlns=" xmlns:xsi=" xsi:schemalocation=" <modelversion>4.0.0</modelversion> <groupid>pt.trainings.maven</groupid> <artifactid>scratch</artifactid> <version>1.0-snapshot</version> <packaging>jar</packaging> <name>scratch</name> </project> NOTE: You are creating a new project and the resulting artifact will be a jar file, because you re specifying that the packaging is jar, which is the default. If you haven t specified anything for <packaging>, the resulting file is still a jar file. you re done! You ve learned how to create the simplest POM file possible. The configuration you provided into the pom.xml is the minimum required to have a valid Maven project. 1.2 Create the Java source directory for the project. The source directory will contain the java code for your project. To know what directory Maven is expecting as source directory, try to run: mvn help:effective-pom This command will output the effective POM, including the directory Maven is expecting to have the Java source code. Look, at the beginning of the listing, for the tag <sourcedirectory>. Generally, the directory is: ${project.dir}/src/main/java Create the Java Source directory, as expected by Maven João MIguel Pereira 2011 Page 3 of 25

4 mkdir ${project.dir}/src/main/java you re done! You ve leaned how to see the effective POM for your project. Although you only provide the minimum information, maven has a lot of defaults that you can see in the effective POM. You also leaned the basic structure of directories Maven expects from your project. 1.3 Import project into Eclipse Now, you have the basic skeleton for your project. You will use Eclipse to develop your first Java class. You can use the Maven Eclipse Plugin ( eclipse plugin/) to help us with this task. You will need to invoke a goal in the Maven Eclipse Plugin. The syntax to invoke a goal in a plug in is: mvn <plugin-name>:<goal> 1. Generate an eclipse project configuration, in your ${project.dir}, run: mvn eclipse:eclipse 2. Import the generated Eclipse project into your Eclipse workspace 2.1. Open Eclipse in a new Workspace. I recommend using the folder ${maven.exercises.folder} to store your workspace Go to File >Import, expand General and select Existing Projects into Workspace 2.3. Browse for the directory where you have your pom.xml (${project.dir}). Eclipse should be able that the directory contains a project named Scratch 2.4. Select finish. you re done! You ve leaned how to import an existing Maven project into Eclipse. João MIguel Pereira 2011 Page 4 of 25

5 1.4 Create the HelloWorld Class With the maven project created, let s create a simple java class. Open Eclipse for this exercise. 1. Press CTRL+N and start writing package to filter the options. 2. Select Package and click Next 3. Enter pt.trainings.maven.scratch 4. In Package Explorer View, select the package you just created (if the Package Explorer view is not visible, try SHIFT+ALT+Q then press P) 5. Press CTRL+N and type class to filter the available options. Select Class and click Next. 6. Enter HelloWorld for the name of the class and let eclipse generate a main method for you. Tick public static void main(string args[]). 7. Complete the class. The body of main will output the string Hello World!! package pt.trainings.maven.scratch; public class HelloWorld { /** args */ João MIguel Pereira 2011 Page 5 of 25

6 public static void main(string[] args) { System.out.println("Hello World!!!"); } } 8. Try to run the program in Eclipse. Press ALT+SHIFT+X and the press J. You should see in the Console view the output Hello World. you re done! 1.5 Package your application and create an artifact Now that you have a Java application running, it s time to package it. 1. Got to directory ${project.dir} 2. Call the phase package mvn package NOTE: As you recall, when you invoke a phase, all previous phases also run. You also know that, by default, there are plug in goals bound to each phase. From the output of mvn package, you can see that there were several goals, from different plug ins, that were automatically invoked. [INFO] [resources:resources {execution: default-resources}] [INFO] [compiler:compile {execution: default-compile}] [INFO] [resources:testresources {execution: default-testresources}] [INFO] [compiler:testcompile {execution: default-testcompile}] [INFO] [surefire:test {execution: default-test}] [INFO] [jar:jar {execution: default-jar}] 3. In the directory ${project.dir} you now should have a new directory called target. Go to that directory. cd ${project.dir}/target Within the directory ${project.dir}/target you find a file named scratch-1.0-snapshot.jar. This file is the artifact Maven João MIguel Pereira 2011 Page 6 of 25

7 produced for your project. Remember that you configured the packaging as jar? 4. You can run your java application to check that everything is ok. In folder ${project.dir}/target, run: java -cp scratch-1.0-snapshot.jar pt.trainings.maven.scratch.helloworld You should see the output correctly: Hello World!!! you re done! You ve leaned how package your application and create an artifact from it. 1.6 Install your artifact Now that you have your application being packaged correctly, you can install it in your local repository. By installing the artifact in your local repository, other projects, developed in your machine, will have access to this artifact. 1. In ${project.dir} run: mvn install 2. Go to ${user.home}/.m2/repository (if you have changed the location for the local repository, go to that location instead) and locate the directory ${user.home}/.m2/repository/pt/trainings/maven/scratch In this directory you find one directory named after the version of you artifact. If you recall, in step 1.1, you configured the version of your artifact with 1.0 SNAPSHOT. <version>1.0-snapshot</version> NOTE: Maven created a directory, using the values of GroupId, ArtifactId and Version, to store the artifact in local repository. João MIguel Pereira 2011 Page 7 of 25

8 The artifact can also be copied to a remote repository this is called deploying the artifact. To deploy your artifact, you need to configure a remote repository in your POM.xml and then invoke the phase deploy: mvn deploy For more information about deploying artifacts and configuring remote repositories, see: deploy plugin/ you re done! You ve leaned how to install your artifact in a local repository and got hints on how to deploy it to remote repositories. 1.7 Change the name of the artifact As you saw in exercise 1, task 1.5, by default, the name of your artifact follows a naming convention consisting of: <artifactid>-<version> You can change this name in you pom.xml. You will use the same project as previous exercise Use a static name for artifact In this task you will rename the artifact to a static name: artifactname. When you package your project, you will end with a file called artifactname.jar 1. Go to folder ${project.dir} and open the file pom.xml. You can also open this file from Eclipse. 2. Edit the file pom.xml and add the following information: <build> <finalname>artifactname</finalname> </build> 3. Go to directory ${project.dir} and run: João MIguel Pereira 2011 Page 8 of 25

9 mvn package 4. Check that a new file named artifactname.jar was created under the directory ${project.dir}/target Use a semi static name for artifact I mean semi static because there is a part of the name that is static, while the other name s part will use the version of the project. You can define properties, or variables, in Maven. You will define a new property containing the static part of the name and then concatenate this value with the version. 1. Edit the pom.xml and add a new property, as follows (add the new content after the tag <name>) : <properties> <artifactfinalnameprefix>scratchapplication</artifactfinalnameprefix> </properties> 2. Change the tag <finalname> to use the property we defined and the version of the project. <build> <finalname>${artifactfinalnameprefix}-${project.version}</finalname> </build> NOTE: You can refer to properties/variables using the Velocity Formal Reference Notation, i.e., using ${nameoftheproperty}. You can see the more about Velocity Formal Reference Notation here: 1.5/userguide.html#formalreferencenotation There are some built in variables available in Maven. You can see them here: to thepom.html#available_variables 3. Generate the artifact by invoking the package phase, on default lifecycle João MIguel Pereira 2011 Page 9 of 25

10 mvn package 5. Check that the file scratchapplication-1.0-snapshot.jar was created in folder ${project.dir}/target You re done! You ve leaned how to use variables in your pom and how you can override the default name of your artifact. 2 Add dependencies One of the selling points of Maven is that it handles the dependencies for you. You should not worry about copying the dependencies to your dev machine and configure their locations. Moreover, you can easily manage the versions of project dependencies without any fuss. Maven uses a dependency resolution mechanism that allows you to focus only on the dependencies needed by your project. I.e., some libraries have their own dependencies but you should not worry about them, Maven, through its transitive dependency management, will manage those dependencies for you. Consider the following scenario: Your Project JUnit Log4J Hamcrest core oro mail Other Libraries Figure In 1 Example of transitive dependencies João MIguel Pereira 2011 Page 10 of 25

11 In the previous scenario, your project depends on two external libraries: JUnit and Log4j. JUnit depends on hamcrest core library, which by its turn can depend on other libraries to function correctly. Log4J follows the same pattern as JUnit, it needs other libraries, which depends on more libraries, and so on, to function correctly. In short, in order to your project function as expected, you will need not only the dependencies you require directly for your project, but all the dependencies required by your primary dependencies!! Ok, this can be a quite laborious to manage by hand and very error prone. A dependency nightmare for big projects! Maven helps you managing those dependencies for you. You just have to declare JUnit and Log4J as dependencies and Maven will deal with the remaining dependencies. 2.1 Add JUnit as dependency You will use the same project you did in exercise 1. A project without tests isn t a real project, right? So let s add some tests to our project. We will use JUnit for this. JUnit is the original framework for unit testing, initiated by Kent Beck, the creator of extreme Programming and Test Driven Development methodologies. To know more about JUnit, XP and TDD see the following links: driven_development You will add some refactorings to you code in order to have something to test. Your application, from exercise 1, consists only of one class that print Hello World!! in the screen. You will add a new class called Greetings and its function is to say hello to someone. Trivial, right? Redesign the application to add the Greetings class 1. Open eclipse, with the project scratch you imported in exercise 1 opened. João MIguel Pereira 2011 Page 11 of 25

12 2. Press CTRL+SHIFT+T and start writing helloworld, just to filter the types available, and select the class pt.trainings.maven.scratch.helloworld 3. Modify the method main(string[] args)as follows: public static void main(string[] args) { Greetings greetings = new Greetings(); System.out.println(greetings.sayHello(args.length>0?args[0]:null)); } 4. Place the cursor in Greetings and press CTRL+1 5. Select Create class Greetings from the options 6. Press Finish to create the new class Greetings under the same package as HelloWorld João MIguel Pereira 2011 Page 12 of 25

13 7. Press CTRL+W to close the editor of class Greetings. 8. In class HelloWorld, place the cursor on method sayhello (which should me marked with compilation error) and press CTRL+1 9. Select Create method sayhello(string) in type Greetings 10. Code the class Greetings as follows: public class Greetings { private static final String GREETING = "Hello "; } public String sayhello(string string) { return GREETING + (string!= null? string : "Jonh Doe"); } Add JUnit as a dependency You are now in shape to create some tests. You created the business logic before created the test, but you should strive to develop first the tests then the business logic, following the Test Driven Development practice. The first step is to add JUnit dependency to your project. Then you have to create the directories where Maven is expecting to have the tests. 1. Open pom.xml and add the following XML code snippet: João MIguel Pereira 2011 Page 13 of 25

14 <dependencies> <dependency> <groupid>junit</groupid> <artifactid>junit</artifactid> <version>4.9</version> <scope>test</scope> </dependency> </dependencies> NOTE: You just added a dependency to your project with scope test. This dependency will be used only when compiling and running tests. 2. Create the directories where Maven is expecting to find your tests. mkdir ${project.dir}/src/test/java Hint: You can see the directories Maven is expecting to find you tests and other files by checking the effective POM. NOTE 2: At this point you have added another directory to your project and Eclipse should recognize it as a Source folder in its build path. The easiest way to configure the new directory to be part of build path of Eclipse is to regenerate the Eclipse project. 3. Regenerate the Eclipse project mvn eclipse:eclipse 4. Go to Eclipse, press ALT+SHIFT+Q, then press P to open the Package Explorer view. 5. Select the project scratch and press F5 to refresh the project. Now you have your project having the new directory as part of the build path, but you have also problems with the project. 6. Press ALT+SHIFT+Q the press X to open the Problems View You just added a new dependency, JUnit that have a transitive dependency with hamcrest core. Eclipse is expecting to find these two libraries in the build path. You have to add the variable M2_REPO to Java Build Path of eclipse. João MIguel Pereira 2011 Page 14 of 25

15 2.1.3 Add variable M2_REPO by hand, to Java Build Path of Eclipse You will configure Eclipse project to locate the dependencies cached in local maven repository. 1. Press ALT+SHIFT+Q and then press P to open Package Explorer view 2. In Project Explorer view, select the project scratch and press ALT+Enter 3. Select Java Build Path, in the tree at left, then click on Add Variable 4. On the window New Variable Classpath Entry, click Configure Variables João MIguel Pereira 2011 Page 15 of 25

16 5. Click New and add M2_REPO as the variable name, then select the folder where your local repository is located (usually in ${user.home}/.m2/repository ) and click Ok 6. Click Ok again and then select Yes to build the project. Click Ok until all windows are closed. João MIguel Pereira 2011 Page 16 of 25

17 Now you should have no errors in your Eclipse Project Add two simple JUnit tests You should strive to have one test class for each class, so you will create a new test class for class Greetings you developed in Maven, more specifically maven surefire plugin, is expecting, by default, to find you tests under directory ${project.dir}/src/test/java. 1. Press ALT+SHIFT+Q then press P to open Package Explorer view 2. Select the folder src/test/java 3. Press CTRL+N to open the Select Wizard for new resource window 4. Select Class and press next 5. Enter pt.trainings.maven.scratch for package name and GreetingsTest for class name. João MIguel Pereira 2011 Page 17 of 25

18 6. Press Finish to create the new Test Class 7. Code two tests, as shown bellow: package pt.trainings.maven.scratch; import static org.junit.assert.*; import org.junit.test; public class GreetingsTest { private static final String DEFAULT_NAME = "Jonh Doe"; private static final String GREETINGS_MESSAGE = "Hello "; public void testnullnameshouldprintdefaultname() { Greetings objectundertest = new Greetings(); String expectedstring = GREETINGS_MESSAGE+DEFAULT_NAME; assertequals(expectedstring, objectundertest.sayhello(null)); public void testshouldprintcorrectgreeting() { Greetings objectundertest = new Greetings(); String expectedstring = GREETINGS_MESSAGE+"Bob"; assertequals(expectedstring, objectundertest.sayhello("bob")); } 8. With the GreetingsTest editor opened, press ALT+SHIFT+X and then T to run the unit tests within Eclipse. You should have both tests green. 9. Open a console, go to the root directory of your project (${project.dir}) and run the tests with Maven. mvn test You should see that every test passed T E S T S Running pt.trainings.maven.scratch.greetingstest Tests run: 2, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: sec Results : Tests run: 2, Failures: 0, Errors: 0, Skipped: 0 [INFO] [INFO] BUILD SUCCESSFUL [INFO] João MIguel Pereira 2011 Page 18 of 25

19 [INFO] Total time: 5 seconds [INFO] Finished at: Tue Sep 20 00:58:42 BST 2011 [INFO] Final Memory: 7M/17M [INFO] You re done! You ve leaned how to use variables in your pom and how you can override the default name of your artifact. 3 Use Archetypes In short, Archetype is a Maven project templating toolkit. An archetype is defined as an original pattern or model from which all other things of the same kind are made. The names fits as we are trying to provide a system that provides a consistent means of generating Maven projects. Archetype will help authors create Maven project templates for users, and provides users with the means to generate parameterized versions of those project templates. Using archetypes provides a great way to enable developers quickly in a way consistent with best practices employed by your project or organization. Within the Maven project we use archetypes to try and get our users up and running as quickly as possible by providing a sample project that demonstrates many of the features of Maven while introducing new users to the best practices employed by Maven. In a matter of seconds a new user can have a working Maven project to use as a jumping board for investigating more of the features in Maven. We have also tried to make the Archetype mechanism additive and by that we mean allowing portions of a project to be captured in an archetype so that pieces or aspects of a project can be added to existing projects. A good example of this is the Maven site archetype. If, for example, you have used the quick start archetype to generate a working project you can then quickly create a site for that project by using the site archetype within that existing project. You can do anything like this with archetypes. You may want to standardize J2EE development within your organization so you may want to provide archetypes for EJBs, or WARs, or for your web services. Once these archetypes are created and deployed in your organization's repository they are available for use by all developers within your organization. From: to archetypes.html João MIguel Pereira 2011 Page 19 of 25

20 In this exercise you will create the same application as you did in exercise 1, but now you will use Maven Archetype plug in to achieve the same result. 1. Go to your ${maven.exercises.folder} 2. Invoke the goal generate in maven archetype plugin mvn archetype:generate 3. Accept the default number for the archetype to use. The default is a simple Java Application. NOTE: You can see that there is a big list of available archetypes, depending on the repositories you have configured. 4. Accept the default value for version 5. Enter pt.trainings.maven.templating for groupid property 6. Enter sample for artifactid property 7. Accept the default value of 1.0-SNAPSHOT for version property 8. Accept the default value of pt.trainings.maven.templating for package property 9. Review and accept the values by typing Y at the end You now have a new project created. All the steps you followed in exercise 1 were done automatically. Even a dependency with JUnit was added for you. 1. Generate the eclipse project 2. Import the project into eclipse 3. Update the version of JUnit from version to Re generate the Eclipse project to update the reference to the new version of JUnit You re. You have leaned how to use archetypes to get you ready to code in one minute. 4 Use POM Inheritance and Aggregation To better manage your projects and reduce the maintainability effort, you should strive to use inheritance and aggregation in your Maven projects. Usually a project consists of various modules that are being developed by João MIguel Pereira 2011 Page 20 of 25

21 different teams. A big and complex project will certainly introduce challenges at communication level, at maintainability of common attributes and at synchronization of dependencies of all modules that form the project. In this exercise you will create a typical JEE project that shows the uses both inheritance and aggregation with Maven. You will first create the parent POM that will also behave as the aggregator for all modules. 1. Go to the folder where you have your maven projects (${maven.exercises.folder}) 2. Run the goal generate of maven archetype plugin mvn archetype:generate 3. Enter pom to filter the options. We are aiming to create a project that consists only in a POM. This will be the parent POM and the aggregator POM at the same time. Choose a number or apply filter (format: [groupid:]artifactid, case sensitive contains): 131:pom 4. Select the appropriate option. In the version of Maven I m using, the value is 1 1: remote -> org.codehaus.mojo.archetypes:pom-root (Root project archetype for creating multi module projects) 5. Accept the default value for the version of the archetype 6. Enter pt.training.maven.jee for groupid property 7. Enter jee-parent for artifactid property 8. Accept 1.0-SNAPSHOT for version property João MIguel Pereira 2011 Page 21 of 25

22 9. Accept pt.training.maven.jee for package property 10. Review and accept the values by typing Y at the end You have just created the parent POM for the project. You can see that maven created a new directory containing a single file, pom.xml. Go to the directory ${maven.exercises.folder}/jee-parent and review the created pom.xml. Now you will create the ejb module for the JEE project. 1. Go to the directory that Maven created for you in the last steps. cd ${maven.exercises.folder}/jee-parent 2. Run the goal generate of maven archetype plugin mvn archetype:generate 3. Type weld-jsf-jee-minimal to filter the available options and select 1 4. Enter pt.training.maven.jee for groupid property 5. Enter ejb for artifactid property 6. Accept 1.0-SNAPSHOT for version property 7. Enter pt.training.maven.jee.ejb for package property 8. Review and accept the values by typing Y at the end You have created the module where you will implement the business logic for the application. You are using an archetype that will also include JSF API as a dependency, but you can remove it after completing the creation of all modules. Now you will create the web client for the application. The web client will be based on JSF, so we will use another archetype from JBoss. 1. Go to the directory where the parent POM is located. cd ${maven.exercises.folder}/jee-parent 2. Run the goal generate of maven archetype plugin mvn archetype:generate João MIguel Pereira 2011 Page 22 of 25

23 3. Type jboss-jsf-weld-servlet-webapp to filter the available options and select 1 4. Enter pt.training.maven.jee for groupid property 5. Enter web for artifactid property 6. Accept 1.0-SNAPSHOT for version property 7. Enter pt.training.maven.jee.web for package property 8. Review and accept the values by typing Y at the end Now, you created the module that will be the web interface for the JEE application. Since you decided to use JSF (Or your manager ) as the main technology for the web, you used another archetype from JBoss. It s time to create the last module. This last module is the model, i.e., your domain classes that will be persisted in some database using JPA (Java Persistence API). 1. Go to the directory where the parent POM is located. cd ${maven.exercises.folder}/jee-parent 2. Run the goal generate of maven archetype plugin mvn archetype:generate 3. Type weld-jsf-jee to filter the available options and select 1 4. Enter pt.training.maven.jee for groupid property 5. Enter model for artifactid property 6. Accept 1.0-SNAPSHOT for version property 7. Enter pt.training.maven.jee.model for package property 8. Review and accept the values by typing Y at the end For this module you used the archetype weld-jsf-jee that will also include the dependencies for JSF and EJB3.1, additionally to JPA. You can remove these extraneous dependencies to clean the project afterwards. If you check the directory ${maven.exercises.folder}/jee-parent you will see that now you have (or should have) three new directories. Each of these directories is a module of your project. Maven is smart enough to guess what you want, so it added each of these modules to the parent POM. Open the pom.xml, in ${maven.exercises.folder}/jee-parent João MIguel Pereira 2011 Page 23 of 25

24 <project xmlns=" xmlns:xsi=" xsi:schemalocation=" <modelversion>4.0.0</modelversion> <groupid>pt.training.maven.jee</groupid> <artifactid>jee-parent</artifactid> <version>1.0-snapshot</version> <packaging>pom</packaging> <name>jee-parent</name> <modules> <module>ejb</module> <module>web</module> <module>model</module> </modules> </project> Note that in the pom.xml, located at ${maven.exercises.folder}/jee-parent, Maven added each of the modules automatically. With this configuration, if you call some goal on the aggregator pom, i.e, in the directory ${maven.exercises.folder}/jee-parent,maven will call that goal for each of the modules. You can try to generate the eclipse project for each of the modules. 1. Go to the directory of the multi project cd ${maven.exercises.folder}/jee-parent 2. Run the goal eclipse on eclipse plug in. (This can take some minutes because all dependencies will be downloaded) mvn eclipse:eclipse 3. Open Eclipse and import the three projects. Just need to select the directory ${maven.exercises.folder}/jee-parent and Eclipse will find the three projects. 4. Open the pom.xml for each of the modules to see that Maven automatically added the jee-parent and parent POM. <parent> <artifactid>jee-parent</artifactid> <groupid>pt.training.maven.jee</groupid> <version>1.0-snapshot</version> </parent> João MIguel Pereira 2011 Page 24 of 25

25 If you imported the modules into Eclipse, you will notice that there are some errors. This is because Maven could not find some dependencies in the central repository. To solve this problem, just add JBoss repositories to you modules. 1. Open pom.xml for project jee-parent, located at ${maven.exercises.folder}/jee-parent 2. Add the following repositories to the POM <repositories> <repository> <id>jboss-public-repository-group</id> <name>jboss Public Maven Repository Group</name> <url> <layout>default</layout> <releases> <enabled>true</enabled> <updatepolicy>never</updatepolicy> </releases> <snapshots> <enabled>true</enabled> <updatepolicy>never</updatepolicy> </snapshots> </repository> </repositories> <pluginrepositories> <pluginrepository> <id>jboss-public-repository-group</id> <name>jboss Public Maven Repository Group</name> <url> <layout>default</layout> <releases> <enabled>true</enabled> <updatepolicy>never</updatepolicy> </releases> <snapshots> <enabled>true</enabled> <updatepolicy>never</updatepolicy> </snapshots> </pluginrepository> </pluginrepositories> 3. Regenerate the eclipse projects 4. Refresh the project in Eclipse You can now start coding your modules! You re. You have leaned how create multi module projects with Maven and how inheritance works. João MIguel Pereira 2011 Page 25 of 25