Creating a Working Environment for Tapestry
From InstallationWiki
| Official Page |
| Project Documentation |
| Download |
|
To create a working environment for Tapestry development, we need to:
- Download and install the Java Development Kit (JDK), as we are going to do Java development.
- Download and install Maven. Maven is a very popular project management tool, and Tapestry 5 projects use this tool extensively for many purposes, from compilation of source code to deploying the complete application to a server.
- Download and install an Integrated Development Environment (IDE). There are two excellent free IDEs, NetBeans and Eclipse. NetBeans is easier for beginners, as creating a working environment with it involves fewer moving parts. However, Eclipse is more popular. If you have chosen Eclipse, you will also have to download and install a servlet container. Tomcat is the most popular servlet container. NetBeans comes with bundled Tomcat, so you don't have to install a servlet container if you have chosen NetBeans.
Contents |
[edit] Install a JDK
You might already have a JDK on your computer say, if you were doing any kind of Java programming before, or if you are running Mac OS X that comes with a preinstalled JDK. Even so, you will need to check the version of the JDK that you have. Tapestry 5 makes an extensive use of annotations, and this feature appeared in the Java language only in version 1.5 (also known as Java 5). So you need to make sure that your version is not older than that.
Fortunately, you can check both things whether you have a JDK at all, and which version it is by using just one command. Open the command prompt or a terminal window, and enter the command:
javac -version
Your computer may report something like this:
javac 1.6.0
This means that everything is fine. However, if it responds by saying that there is no such command, or if you see that the version is older than 1.5, then, for a Linux or Windows computer, go to http://java.sun.com/javase/downloads/index. jsp, download the latest version of the JDK (not JRE! JRE is a runtime environment, it doesn't contain the tools required for development) and install it following the instructions available on that website.
For Mac, you can get Java 5 update from the Mac OS X Updates page
(http://www.apple.com/downloads/macosx/apple/macosx_updates). At the time of this writing, the available package for Mac is J2SE 5.0 Release 4, you need to pick the one for your platform, Intel or PPC.
Next, you need to make sure that the required environment variables are set correctly. This will enable other elements of our working configuration to find the JDK successfully. This step is platform-specific. Here we will have instructions for Windows and Mac OS X. Linux instructions would be very similar to those for Mac, and besides, if you are running Linux, you are probably familiar with the basic technicalities of your distribution.
[edit] Configuring the Environment for Windows
First of all, you need to find out where the JDK was installed on your hard drive. Most probably, you will find it at C:\Program Files\Java, and the folder name will depend on the version of the JDK, you have installed. It might be something like C:\Program Files\Java\jdk1.6.0_02.
We need to do two things:
- Make this folder known to your machine as JAVA_HOME environment variable.
- Add its \bin subdirectory to the PATH environment variable.
On Windows XP, select Start | Control Panel | System, and then select the Advanced tab in the System Properties dialog.
On Windows Vista, select Start | Control Panel | System and Maintenance | System, and then, in the left pane, Advanced system settings.
In both cases, you will see a dialog similar to the one shown in the following figure:
Press the Environment Variables button, and you will see the Environment Variables dialog, similar to the one shown in the following figure:
Check if in the lower pane of the latter dialog, System variables, there is a variable named JAVA_HOME. If there is no such a variable, click on the New button below to add it. If there is, click on the Edit button and make sure that this variable reflects precisely the path to your JDK folder. In both cases, the result should be similar to this:
Next, find the PATH variable in the same lower pane (the case doesn't matter). Probably, it will already have some value, so you can append the path to the \bin subdirectory of the JDK, separating it from the other paths by semicolon, as shown in the following figure:
Close all dialogs by pressing OK. If everything was done properly, you should be able now to check the version of javac, as explained above.
[edit] Configuring environment for Mac OS X
You will need to edit the .bash_profile file which is located in your home directory (something like /Users/YourUserName/.bash_profile). The dot in front of the file name means that it is a hidden file, so Finder will not display it.
There are different ways to edit this file. The one that we prefer is to use the TextWrangler editor that can be downloaded for free from http://barebones.com/products/textwrangler/.
Start TextWrangler and in the menu select File | Open Hidden..., and you will be able to find, open and edit your .bash_profile easily.
All you will need to do is to add this single line of code:
export JAVA_HOME=/usr
This is where Java is installed by default on Mac OS X.
Now everything is ready for the next step, installing Maven.
[edit] Installing Maven
You can get Maven 2.0.5 at http://archive.apache.org/dist/maven/binaries/. Choose the package that is most convenient for you, like maven-2.0.5-bin.zip, download it, unpack and copy the resulting directory to a convenient place on your computer. It can become /Users/YourUserName/maven-2.0.5 on a Mac or C:\ maven-2.0.5 on a Windows machine.
Finally, add the path to Maven's bin directory to the PATH variable of your system. On a Windows machine, the addition to the PATH variable should look like, C:\maven-2.0.5\bin. On a Mac, add the following string to .bash_profile (but replace YourUserName with your actual user name):
export PATH=${PATH}:/Users/YourUserName/maven-2.0.5/bin
Finally, to check if everything was set up properly, enter the following command:
mvn -version
The output should be similar to this:
Maven version: 2.0.5
Now we are ready to use Maven to download and make available everything that is required for a Tapestry project, including all the dependencies.
[edit] Create a Skeleton Tapestry project
It is convenient to have a special directory for the project skeletons created by Maven. So please create such a directory (say, C:\tapestry5\work) and open the command prompt or a terminal window into it.
Enter the following command (it should be all on one line and is broken into several lines only because it would not fit into the page width otherwise):
'''mvn archetype:create -DarchetypeGroupId=org.apache.tapestry -Darchety peArtifactId=quickstart -DgroupId=com.packtpub -DartifactId=t5first -DpackageName=com.packtpub.t5first -Dversion=1.0.0-SNAPSHOT'''
In this command we are asking Maven to do the following:
archetype:create: We ask Maven to create a new project using an existing project template (or archetype, as Maven calls it).
DarchetypeGroupId=org.apache.tapestry: This is one of the Tapestry archetypes; now Maven knows in which group of archetypes to look for it.
DarchetypeArtifactId=quickstart: The actual name for the archetype.
DgroupId=com.packtpub: This is a group to which the new project will belong. I have given it the reversed URL of the publisher's website, but you can use any other name if you wish.
DartifactId=t5first: The name for the project itself. Again, use another one if you wish.
DpackageName=com.packtpub.t5first: The package into which the project's Java classes will be placed. It is logically made of the two preceding pieces of information, but not necessarily so.
Dversion=1.0.0-SNAPSHOT: This is not required, but it gives the future application some reasonable version number.
You will need to enter this command every time you want to create a new Tapestry project, but there is no need to memorize it or to type it by hand. One of the ways to simplify things is to have a text file with different versions of this command. You can easily change the details, like package name, and then just copy the command and paste it into the command line. In fact, you do not even need to create such a text file yourself, as we have already created it for you and put it into the code package for this chapter under the mvn_commands.txt name. When the command is entered, Maven begins its work. It downloads all the required files and stores them in a repository on your computer, then creates a skeleton of the Tapestry project. Naturally, you need to be connected to the Internet at this time. The output will look like this:
You can see that there might be some warnings, but that is fine as far as the final message is BUILD SUCCESSFUL.
The process will take quite some time, but this is only so for the first project. Creating every next project will take much less time as all the necessary files will be already stored on your computer and there will be no need to download them.
If you now check the contents of the recently created C:\tapestry5\work directory, you will find a subdirectory named \t5first (or whatever you named the artifactId in that long Maven command). In this subdirectory you will already find some files and more subdirectories, but before looking at them in more detail,let's ask Maven to bring together everything that is required for the new project.
At the command prompt, navigate to the new project directory (so that the current directory become C:\tapestry5\work\t5first) and enter the following command:
mvn package
Again, Maven will download a number of files and take a noticeable amount of time, but finally you will see the output as follows:
This means that the command was executed successfully. Now let's have a look at the contents of the project just created. Refer to the following screenshot:
As you can see, there is plenty of everything. Note the items that will be most important for us in the beginning.
First of all, there are two subdirectories under \t5first \src and \target.
The \src subdirectory, as you can guess, contains the source code of the application, including Java files, template files, and the standard deployment descriptor, web. xml (if you are new to Java web applications' terminology, please read Appendix A, which provides an overview of the most essential concepts).
Note that there are two files with the name Start, but with different extensions. The Start.java source file is located in \main\java subdirectory, under the structure of subdirectories reflecting its package name (com.packtpub.t5first.pages), while the Start.tml file is located in the \main\webapp subdirectory. These are two parts of the same Tapestry page.
[ Note : There is actually more than one copy of the Start.tml file in the contents of these directories because Maven did its work in two steps. It first created all the necessary files under the \src subdirectory and then created the structure of the future application under the \target subdirectory. You will follow my logic more easily if you spend some time looking at the picture of the directories, and compare it with the structure you've got on your computer. Under the \target subdirectory, we will find the result of building and packaging the application by Maven. There is already the end product, t5first.war file. We can take it and deploy it on a Java-enabled web server (like Tomcat). It has everything required for a Tapestry Web application.]
However, there are also the intermediate results of Maven's work. The \classes subdirectory contains compiled Java classes, while under \t5first, you will find a familiar template file, Start.tml, and under \t5first\WEB-INF, the deployment descriptor web.xml. Most remarkably, the \t5first\WEB-INF\lib subdirectory contains all the necessary libraries downloaded for us by Maven from across the Internet. We didn't have to figure out what is required and where to get it.
At this point, we can thank Maven for its service as we are going further. The next step is to start working with the source of the application, building it and deploying to a server. This is where a contemporary IDE will be very helpful.
[edit] Installing NetBeans
Even if you decided to use Eclipse, we still recommend you to read this section as starting a new project in NetBeans is significantly simpler.
Go to http://www.netbeans.info/downloads and download the latest package for your platform. Install it with all the default options. Your working environment is ready.
Now let us use NetBeans to work with the project created for us by Maven.
Start the IDE and in its menu choose File | New Project... (or press the second from the left button on the toolbar). You will see the New Project dialog opened. In it, select Web under Categories and Web Application with Existing Sources under Projects, as shown in the following figure, and click on Next:
In the next dialog, click on the Browse... button next to Location, and navigate to the directory of the new project created by Maven (C:\tapestry5\work\t5first, if you accepted my choice of naming). Select this directory and press Open. Make sure that Bundled Tomcat is selected for the server and all the other settings are the same as in the following figure:
Click on Next, to see the following dialog:
You don't have to change anything as NetBeans should be able to find out all the necessary details automatically. Click on the Finish button, and the new NetBeans project will be created for you.
NetBeans structures the project as shown in the following figure:
You can see that the structure of the project as recreated by NetBeans is much closer to the structure of a standard Java web application .
All the libraries are already in place, and if you want to edit Java classes, their source code can be found in the Source Packages folder. However, in this chapter we only need to make sure that working configuration was created successfully, so let's just run the project and see what will happen.
Hit the F6 key (or press the third from the right button on the toolbar). In the Output window you will have to wait for Tomcat startup, but then in a few seconds the default browser's window will open, and in it you will see the Tapestry application running, as shown in the following figure:
Click on the refresh link a few times to make sure the page is live, and displays the current time each time after each refresh.
Now let's try to make some changes. Double-click the Start.java file in the Projects view and it will open in the code editor. You will see that this class contains just one method, getCurrentTime() that it returns a Date, and this method contains just one line of code. Let's change it to look like this:
public String getCurrentTime()
{
Date date = new Date();
String message = ". Tapestry is cool!";
return date + message;
}
Save the changes, hit the F6 key, and you will see that the application reflects the changes you have just made. Let's try another experiment.
Double-click on the Start.tml file to open it in the code editor and make some changes to it. For example, change the heading:
<h1>t5first Start Page</h1>
to:
<h1>Tapestry Start Page</h1>
Save the file and hit F6 as before. You will notice this time that the last change is not reflected by the application. This is because NetBeans keeps track of changes in Java files only when we have changed a page template. No Java file was changed, so NetBeans decided that there is actually nothing to update.
The simplest way to deal with this little misconduct is to make some change to a Java file each time you make a change to an HTML file. If there is nothing to change, just add or remove a space somewhere where it doesn't make difference in any Java file.
In this case, after pressing F6, NetBeans will reload the whole application, including HTML files, and so every change will be picked up.
[ Note : The extension of page template files in Tapestry, beginning from version 5.0.6, is tml, which is for Tapestry Markup Language. NetBeans doesn't know which editor to use for editing files with such an extension and so it uses a simple text editor. This means that we'll have no syntax highlighting and no other convenient features of advanced NetBeans editors. However, Tapestry template files are XML documents and also they are very close to XHTML files. It will make sense to edit them using either HTML editor or XML editor, and we can easily teach NetBeans which editor to use when dealing with files having tml extension.
In NetBeans' menu open Tools Options, and then at the bottom of the dialog that appears press the Advanced Options button. In the tree view on the left hand side navigate to IDE Configuration System Object Types. Then, depending on which editor you prefer to use for page templates, select either HTML Objects or XML Objects. Then in the Properties pane on the right hand side press the small button against Extensions and MIME Types, enter tml into the Item box, press Add and then close all dialogs. Now NetBeans will always open page templates in the editor you've chosen. ]
Now you know enough to start working on a project of your own. I hope you enjoyed dealing with NetBeans. Could it be easier, indeed? But how about debugging an application? Can you believe that debugging a Web application can be not more difficult than debugging a desktop application? Let's try then.
[edit] Debugging in NetBeans
Let's return to the Start.java file, it is probably still opened in the code editor. Click on the left margin of the code editor against the last line of code (the return statement) to place a breakpoint there. The code should look then like this:
Press F5, or the second button from the right on the toolbar, to debug the project. The application startup will begin as usual, but then it will stop at the breakpoint, so that you can observe the current state of the variables. For this, you can use the Local Variables view, as shown below:
There are other useful tools available for debugging in NetBeans, but we are not going to look at them in detail for now, as my aim was just to show how easy it can be to debug a Web project in a contemporary IDE.
Press Ctrl + F5 to allow the application to continue running, and you will see a familiar page opened in the default web browser. Click the refresh link, and again, the application will stop at the breakpoint and wait for your further instructions. To complete the debugging session, press Shift+F5.
Working with NetBeans is quite easy. Creating a working configuration with Eclipse involves more steps, but, this process is pretty straight-forward too.
[edit] Installing Eclipse
Eclipse by itself is a universal platform, starting from which you can create an IDE for just any imaginable purpose using existing building blocks (plug-ins). Sounds exciting, but in fact, we do not want to start building an IDE from scratch, as mutual dependencies between different plug-ins can make this endeavor time and effort consuming.
Instead, recommended is to download a ready to use package created by Web Tools Platform project, let's call it Eclipse WTP. This package can be downloaded from http://download.eclipse.org/webtools/downloads/ (look for something like "WTP all-in-one package"). You can download either the latest version 2 or the previous version 1.5, they should be equally good for our purposes, but please note that when testing version 2 on Linux, I got some unexpected behavior from it.
Eclipse WTP has quite a number of benefits over the bare-bones Eclipse, including the following:
- It has source code editors for different Web-related formats, including HTML and XML.
- It is aware of Web and Java EE standard project structures and so can create such projects, import, export them, and so on.
- It has convenient tools for working with servers.
- It makes debugging easy.
In fact, if you had any experience with a commercial Eclipse-based development environment, like Rational Application Developer, you will recognize many of its convenient features in Eclipse WTP.
To install Eclipse WTP, simply unpack the downloaded package and put the resulting directory somewhere on your hard drive (as an example, it can become C:\eclipse).
You will also need to decide where you are going to store your Eclipse projects, since, at the first startup Eclipse will ask you to select a directory for this. It can be something like C:\workspace in the simplest case.
To run Eclipse, double-click on the eclipse.exe file that can be found in the C:\eclipse directory (on a Mac, the file name is Eclipse.app, you will find it by its nice Eclipse icon).
Unlike NetBeans, Eclipse doesn't have a servlet container bundled with it, so we have to download Tomcat separately.
[edit] Installing Tomcat
To install Tomcat, simply download a binary distribution from http://tomcat. apache.org and unpack it into some directory, say, C:\apache-tomcat-6.0. The most recent version 6 should work fine, but if there are problems, version 5.5 is a very well tested alternative.
Once Tomcat is downloaded, we need to tell Eclipse where we have put it but that will be done while configuring the project.
[edit] Configuring the Project in Eclipse
Start Eclipse and close the Welcome screen.
There are different ways of creating a web application from the existing skeleton in Eclipse. However, the one I find the simplest and most convenient is to import the WAR file created for us by Maven.
In the menu, select File | Import..., and in the dialog that opens select WAR file, as shown in the following screenshot, and click on Next.
In the next dialog, click on the Browse... button next to the WAR file text field, navigate to the t5first.war file created by Maven and select it.
Press New... next to Target runtime and in the dialog that opens, select the version of Tomcat that you have installed in the previous section, and click on Next. This is shown in the following screenshot:
In the next dialog, you need to tell Eclipse where exactly you have installed Tomcat. Click on the Browse... button, navigate to the installation directory, select it, and click on Finish.
The final result of the server selection should look like this:
Now click on Finish.
Eclipse will create the new project and suggest that you switch to the Java EE perspective, its default perspective for working with Web projects. Let's agree with this.
The project was created successfully, but if you check its structure, shown in the next screenshot, you will notice that one significant element is missing source files for Java classes used in the project. There are a few different ways how you can get to the existing source files into the project.
Here we will describe two of them; choose the one that you prefer.
The first option is to link to the existing source directory. Right-click on the t5first project in the Project Explorer and in the context menu, select Properties. Select Java Build Path in the left pane of the dialog which opens and the Source tab in the right pane, as shown in the following figure, and click on the Link Source... button.
In the next dialog, click on the Browse... button and navigate to the directory structure created by Maven as shown previously. Select the java subdirectory (its complete path will be perhaps C:\tapestry5\work\t5first\src\main\java). Click on Finish and then OK. You will see this java directory now linked with your project as shown in the following figure:
You could now delete the t5first/src directory as it won't be needed anymore, but better wait until you see another option of how to make source code available to the application.
Open the Start.java file in the code editor, and if you made any changes to it while playing with NetBeans in one of the previous sections, you will see those changes here, as this is exactly the same source file, now linked by Eclipse.
If you do not like the idea of sharing the source code, you can copy it into your Eclipse project instead. Right-click on the java directory in Project Explorer and click on Delete. Confirm your decision in the dialog that opens. Navigate in your file system to the directory structure created by Maven and copy the contents of that java subdirectory that we linked previously (these contents should consist of just one \com subdirectory, but with more subdirectories and files under it).
Now navigate to your Eclipse workspace, and find the \t5first subdirectory containing our new Eclipse project, and then under it the directory named \src. Paste the copied \com subdirectory into \src. Now we need to make sure that Eclipse knows about the addition, for which it is enough to just refresh the project. Click on the project name in Project Explorer and press F5, or alternatively right-click on the project name and click on Refresh. You will see how the code packages have appeared under the Java Resources: src folder.
Whichever approach you have chosen to add the source code, let's change the code of the Start.java file a little and see how the changes are reflected by the application when we run it. Change the source code to look like this:
package com.packtpub.t5first.pages;
import java.util.Date;
/**
* Start page of application t5first.
*/ public class Start
{
public String getCurrentTime()
{
Date date = new Date();
String message = ". Tapestry is cool! And Eclipse too!";
return date + message;
}
}
Right-click on the name of the project in Project Explorer and in the context menu select Run As | Run on Server. The first time you invoke this command, Eclipse will ask you to choose the server. Simply choose the existing server as shown in the next figure, tick the checkbox to always use this server for this project and click on Finish.
Finally, the application runs in the same way, as it did in NetBeans, although this time it is displayed in the built into Eclipse Web browser rather than an external one.
Notice that it does reflect the changes you have done to the code most recently.
Try to make a change to the Start.java file, it can be as simple as adding an extra exclamation mark somewhere in the message. Then save the file. If you keep an eye on the server in the servers view at the bottom of the IDE, you will notice that Tomcat will restart the application almost immediately. The console view will output a few lines like these:
Jul 10, 2007 8:07:10 AM org.apache.catalina.core.StandardContext reload
INFO: Reloading this Context has started
[INFO] TapestryFilter Startup time: 382 ms to build IoC Registry, 1,893
ms overall.
If you refresh the page in the browser now, you will notice that the change you have just made to the code is almost immediately reflected by the running application without any effort from your side. But is this always true?
Open the Start.tml file in the code editor and make some change to its text. For example, replace the current header:
<h1>t5first Start Page</h1>
with a new one:
<h1>My First Tapestry Application</h1>
Save the file and reload the page in the browser. You will see that the change you have made is not reflected by the running application, because you have changed an HTML file, and not Java code. Similar to NetBeans, Eclipse doesn't care about changes in HTML files.
One way to update the application in such case is to follow the advice given for NetBeans make a change, even if it is an insignificant one, to some Java file, and save the file. The application will be then reloaded automatically.
[ Note : Similar to NetBeans, Eclipse doesn't know which editor to use for files with a tml extension, Tapestry page templates. Let's teach Eclipse to open these files using either HTML or XML editor.
In the menu, open Window | Preferences and in the tree view on the left hand side navigate to General | Content Types. On the right hand side, in the Content types tree, expand the Text node and select the HTML item (or XML if you prefer). Below, in the File associations list box, you will see the list of extensions associated with this file type. Add *.tml to them by clicking the Add... button. Close all the dialogs by clicking on the OK button, and next time, when you open a file with a tml extension, it will be opened in an HTML Editor. ]
Another option is to restart Tomcat. Right-click the running server in the Servers view and select Restart | Run. The server will begin restarting, and you will see some output in the Console. Refresh the page in the web browser, as soon as you see a line similar to this:
INFO: Server startup in 3986 ms
Now you will see that the application reflects all the changes. You can also easily debug the application in Eclipse. Let's see how.
[edit] Debugging in Eclipse
Stop Tomcat by pressing the small red square on the right side above the Servers view as shown below.
In the Start.java file, place a breakpoint against the return statement. For this, double-click on the left margin of the code editor against the desired line. You will see that a small blue circle appears there as shown in the following screenshot:
Now click on the small bug icon on the right side above the Servers view to start Tomcat in debug mode. Click on the refresh link in the web browser. Eclipse will now suggest to switch into a Debugging perspective accept that. Very soon you will see something similar to what the following figure shows a rich array of information that you can use to debug the application. Note the Variables view at the top right that displays the values of the two currently available variables date and message.
When the debugging is over, press Ctrl + F2. You might want to switch back to the Java EE perspective (there is a control for switching perspectives in the top right corner of Eclipse's window).
From here, we can continue developing the application, debugging it when necessary.
[edit] Source
The source of this content is Chapter 2: Creating Your Working Environment of Tapestry 5: Building Web Applications by Alexander Kolesnikov (Packt Publishing, 2008).
