blob: 420f1276a9279a3e08946511669072fc18d88399 [file] [log] [blame]
 Installing and Running @greenpages@ Installing and Running @greenpages@
Introduction @greenpages@ is a simple application that allows users to search an online email address directory. Each listing in the directory details the relevant email addresses and the name of the owner. @greenpages@ has only three screens: the search screen, the results screen and the listing detail screen. In the search screen, users can enter search criteria to be matched against the listings in the directory. The result screen displays any listings that match the criteria entered by the user. The listing detail screen shows all the data known about a given listing. Despite its simplicity, @greenpages@ is designed to demonstrate many different @webserv@ features and to act as a template from which other modular applications can be built. In particular, @greenpages@ demonstrates: bundle dependencies with Import-Package, load-time weaving with JPA and AspectJ, bundle classpath scanning, and service export, lookup and injection. In addition to demonstrating common @webserv@ features, @greenpages@ demonstrates integration with: Spring Framework 3.0; FreeMarker 2.3; EclipseLink 1.0.0; H2 1.0.71; and Commons DBCP 1.2.2. The @greenpages@ application is packaged as a PAR file containing four bundles. The greenpages.db bundle provides access to an external database and publishes a javax.sql.DataSource service. The greenpages.app bundle exports a greenpages package containing Directory and Listing interfaces. The greenpages.jpa bundle imports the greenpages package and uses the javax.sql.DataSource service to access the external database and publishes its contents as a greenpages.Directory service. The greenpages.web web application bundle imports the greenpages package and uses the greenpages.Directory service to respond to web requests.
Obtaining @greenpages@ This document provides instructions for building the complete @greenpages@ application and running it in @webserv@. To get the completed @greenpages@ application, including tests and explanatory skeleton parts: download the latest Zip file from @greenpages.download.url@ extract all the files from the Zip file to a convenient directory (preserving the directory structure). To extract the files on Windows: prompt> mkdir c:\springsource\samples prompt> cd c:\springsource\samples prompt> jar xf c:\path\to\@greenpages.zip.file@ prompt> set GREENPAGES_HOME=c:\springsource\samples\@greenpages.expanded.dir@ To extract the files on Unix systems: prompt$mkdir -p /opt/springsource/samples prompt$ cd /opt/springsource/samples prompt$unzip /path/to/@greenpages.zip.file@ prompt$ export GREENPAGES_HOME=/opt/springsource/samples/@greenpages.expanded.dir@ The environment variable GREENPAGES_HOME set here is not used by the projects, but is used as a shorthand in the instructions that follow. The @greenpages@ Zip file contains several directories with names that start greenpages. They contain the completed application which can be built and tested (as described in the next section).
Building and Installing @greenpages@
Building with @maven.full@ @greenpages@ uses @maven.full@ as its primary build system. Each bundle of the application can be built separately and the entire application can built and assembled into a PAR file from a single location. To build the application and assemble it into a PAR file: Make $GREENPAGES_HOME/ the current directory. Run the command mvn package. The first time this is run several files will be downloaded from @maven@ repositories. Subsequent runs will not need to do this. Verify that the greenpages-@greenpages.version@.par file exists in$GREENPAGES_HOME/greenpages/target.
Installing Dependencies into @webserv@ Unlike traditional Java EE applications, @greenpages@ does not package all of its dependencies inside its deployment unit. Instead, it relies on the mechanisms of OSGi to locate its dependencies at runtime. When running an OSGi application on @webserv@, these dependencies can be loaded into memory as needed, but first they must be made available to @webserv@. The Maven build included with @greenpages@ uses the dependency:copy-dependencies plugin to gather all the artifacts that @greenpages@ depends on that are not supplied by the @webserv@ runtime. These dependencies can then be installed into the @webserv@ repository. Dependencies are gathered automatically during the package phase. These dependencies can be found in $GREENPAGES_HOME/greenpages/target/par-provided. To install dependencies simply copy all the *.jar files from this directory into$SERVER_HOME/repository/usr (where $SERVER_HOME is the @webserv@ installation directory). Installing dependencies on Windows: prompt> cd %GREENPAGES_HOME%\greenpages prompt> copy target\par-provided\* %SERVER_HOME%\repository\usr Installing dependencies on UNIX: prompt$ cd $GREENPAGES_HOME/greenpages prompt$ cp target/par-provided/* $SERVER_HOME/repository/usr Notice that @webserv@ will not necessarily see these dependencies unless its repository indexes are rebuilt. Different repositories behave differently in this respect; some are passive (their indexes are built only once upon startup) and some are active (they can detect new files or files being removed dynamically). The usr repository is active so there is no need to restart @webserv@ when copying these files. The next time @webserv@ is started the -clean option will cause @webserv@ to re-scan the repository directories in any case. It is always safe to start @webserv@ with the -clean option. Starting and Configuring the Database @greenpages@ uses the H2 database to store all its data. Before starting the application, start the database server and populate the database with data. Change to the$GREENPAGES_HOME/db current directory. On Unix: prompt$cd$GREENPAGES_HOME/db On Windows: prompt> cd %GREENPAGES_HOME%\db Run the database startup script appropriate to the operating system. For Unix, this is run.sh, run in the background: prompt$sh run.sh & Press Return to continue. On Windows, run the run.bat command: prompt> run For both platforms, the command might invoke a browser window offering a connection to the database; close this window. Run the data population script appropriate to the operating system. For Unix, this is data.sh: prompt$ sh data.sh On Windows, run the data.bat command: prompt> data Run these commands once to start a database server for H2; the server will continue to run in the background.
Installing and Starting @greenpages@ PAR To install the @greenpages@ PAR into @webserv@ and start it: Copy the @greenpages@ PAR to the $SERVER_HOME/pickup directory. On Unix: prompt$ cd $SERVER_HOME prompt$ cp $GREENPAGES_HOME/greenpages/target/greenpages-@greenpages.version@.par pickup/ On Windows: prompt> cd %SERVER_HOME% prompt> copy %GREENPAGES_HOME%\greenpages\target\greenpages-@greenpages.version@.par pickup\ Start @webserv@ with the -clean option. On Unix: prompt$ $SERVER_HOME/bin/startup.sh -clean On Windows: prompt> "%SERVER_HOME%"\bin\startup.bat -clean Verify that @greenpages@ starts correctly by checking in the @webserv@ output for the log message: <DE0005I> Started par 'greenpages' version '@greenpages.version@'. Browsing the @greenpages@ Application Once installed and started, the @greenpages@ application can be accessed with a web browser using the address http://localhost:8080/greenpages. From the home page, a search query can be entered into the search box: After entering a query into the search box, the results page shows all the matches from the directory: Clicking on view, next to an entry in the search listing, displays the full details for that listing entry: Running @greenpages@ from Eclipse Using Eclipse and the @webserv@ tools, it is possible to run applications directly from the IDE. As changes are made to the application in the IDE, they can be automatically applied to the running application allowing for rapid feedback of changes in function. Importing the @greenpages@ Projects into Eclipse Before starting the @greenpages@ application from Eclipse, import the projects: Open the Import Wizard using FileImport. From the Import Wizard select GeneralExisting Projects into Workspace and click Next: Click Browse… and select$GREENPAGES_HOME/ as the root directory. In the Import Projects window, select all the projects which include greenpages in their name and click Finish: Validate that the imported projects appear in Package Explorer: There may be compilation errors at this stage.
Configuring @webserv@ Target Runtime Projects for @webserv@ are associated with a @virgo@ @webserv@ runtime environment in Eclipse. This is to allow launching and testing from within Eclipse, and also to allow classpath construction in Eclipse to mirror the dynamic classpath in the @webserv@ runtime. Compilation errors in the previous step will be resolved here. To configure a @webserv@ runtime environment: Open WindowShow ViewOther…. In the Show View dialog choose ServerServers to make the servers view visible: Right-click in the Servers (which may not be empty) view and select NewServer. In the New Server dialog, choose EclipseRTVirgo Web Server and click Next. Click Browse and select the $SERVER_HOME directory. Ensure that a JRE is selected supporting Java 1.6 or above. Click Finish to complete creation of the server: Select all projects (except Servers) in Package Explorer. Right-click on the projects and choose Close Project and then Open Project. It is possible that there remain spurious build errors from Eclipse (see the Problems view), in which case a project clean build may clear the problems. Select ProjectClean… from the main menu, and choose to Clean all projects. It may be necessary to repeat this on a few projects. (This process is sometimes known as the Eclipse dance.) Despite the dance steps outlined, there will remain some Warnings/Errors like this: It is safe to ignore these. When the @virgo@ Tooling starts the @webserv@ it uses a ‘warm start’ by default. It is useful to set the -clean option so that every server start is a clean one. This is done by an option on the @webserv@ Overview window, which is obtained by opening the @webserv@ entry in the Servers window. (Double-click, or right-click and choose Open.) The check box is labelled ‘Start server with -clean option’. Close the window before proceeding. Running @greenpages@ from Within Eclipse Now that @greenpages@ is successfully imported into Eclipse, run the project directly from within the IDE. If the @greenpages@ PAR file was previously copied to the pickup directory, be sure it is now removed so that it does not conflict with the deployment of the Eclipse project. On Unix: prompt$ cd $SERVER_HOME/pickup prompt$ rm greenpages-@greenpages.version@.par On Windows: prompt> cd %SERVER_HOME%\pickup prompt> del greenpages-@greenpages.version@.par Also, to prevent conflicts with the server configured in Eclipse, stop a currently-running @webserv@ by typing Control-C in the console window. To run @greenpages@ from within Eclipse: Right click on the @webserv@ instance in the Servers view and select the Add and Remove… menu item. Add greenpages (which is the containing project or PAR) to the server and finish. To start @webserv@ from within Eclipse right-click on the @webserv@ node in the Servers window and choose Start. The Servers view should now show the server and the added project: Verify that @greenpages@ is started correctly by checking for: <DE0005I> Started par 'greenpages' version '@greenpages.version@'. in the Console window. (If errors are shown implying that @greenpages@ failed to be installed, this may be because some dependencies were not copied to @webserv@, as described in . Check this.) Once installed and started @greenpages@ is again available from a web browser at the address http://localhost:8080/greenpages.