Do It The jAPS Way
Copyright © 2011 Tzente s.r.l.
Legal Notice
Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the Appendix entitled "GNU Free Documentation License".
2011-03-03
| Revision History | ||
|---|---|---|
| Revision 1.6 | 2011-03-03 | MEM |
|
Update for jAPS 2.0 entando, version 2.2.0 | ||
| Revision 1.5 | 2010-03-17 | MEM |
|
Update for jAPS 2.0 entando, version 2.0.10 | ||
| Revision 1.4 | 2009-11-11 | WG |
|
Update for jAPS 2.0 entando, version 2.0.8 | ||
| Revision 1.3 | 2009-03-13 | WG |
|
English and docbook adoption This revision is a Release Candidate | ||
| Revision 1.2 | 2009-01-03 | ES, MD, WG |
First public release | ||
Abstract
The scope of this document is to introduce the development environment and to provide the guidelines for the extraction of a new instance of jAPS 2.0 entando from the source code hosted at SourceForge; thus obtaining the proper skeleton for the configuration of a new portal, ready to be developed.
Table of Contents
List of Examples
- 3.1. Tomcat: installation directory under Linux OS
- 3.2. Tomcat: installation directory under Windows
- 3.3. Enable trimSpaces
- 3.4. Tomcat:
libdirectory under Linux - 3.5. Tomcat:
libdirectory under Windows - 4.1.
build_newPortal.xml: a correct setting - 4.2.
context.xmlon Linux - 4.3. Database names for the project
myportal - 4.4.
resourceDiskRootFolder: a useful setting
Table of Contents
The scope of this document is to introduce the development environment and to provide the guidelines for the extraction of a new instance of jAPS 2.0 entando from the source code hosted at SourceForge; thus obtaining the proper skeleton for the configuration of a new portal, ready to be developed.
This document is for the ones who are going to develop a new portal using jAPS 2.0 entando, or at least are pondering about. Thus the preferred target audience are specialists of the presentation layer of web development, and Java developers.
In order to take the maximum advantage of the present document, it is necessary to have basic knowledge about: the Java platform, the Eclipse IDE, the Apache Tomcat servlet engine, the PosgreSQL DBMS.
Additional informations may be obtained through the official mailing-lists:
<japs-platform@googlegroups.com>, "japs-platform" Google Group, the jAPS 2.0 entando official Mailing List
Is it also possible to refer to the documentation found in the:
jAPS 2.0 entando is an Open Source, professional "Enterprise Accessible Information Platform" that makes easier aggregation, publishing, access, customization and integration of information, services, processes and resources, complying with accessibility requirements of W3C WCAG standards.
jAPS 2.0 entando Platform provides performance, reliability and scalability features typical of enterprise software (“Enterprise”), allows users with disabilities to access and manage information and services ("Accessible"), seeks to simplify content management ("Information") and it can be used as a framework ("Platform") to build vertical applications based on contents (Content Enabled Vertical Application).
Table of Contents
The development environment for jAPS 2.0 entando needs some previously installed software. In this chapter you will find the proper instructions.
The development environment for jAPS 2.0 entando can be installed in different OSes. In this document we will mainly refer to:
- GNU/Linux Ubuntu 8.10 (or later)
- Windows XP
pointing out the differences where needed. It will be rather easy to apply the concepts to different OSes. Before starting the installation under the chosen OS, you should check the existence of the right versions of the following needed software:
- Development platform
- Java 1.6.10 JDK (or later)
- Integrated Development Environment
- Eclipse 3.4 Ganymede (or later)
- Application Server
- Apache Tomcat 6.0.18 (or later)
- Database Management System
- PostgreSQL 8.3 (or later)
- JDBC driver for PostgreSQL
- the proper version for JDBC3
- (optional) Administration tool for PostgreSQL
- pgAdmin III 1.6.3 (or later)
Other versions may also work well with jAPS 2.0 entando. Later in this chapter you will find quick installation procedures for all the software requirements.
jAPS 2.0 entando has been reported of being successfully installed also on Application Server jBOSS 4.2.3 and the following Database Servers: MySql, Oracle 10g, and Hypersonic. In jAPS 2.0 entando (but this is true since version 0.1) you will find only ANSI SQL, so the compatibility with other DBMSes (which of course respect the standard) is expected and promoted.
The JDK - Java Development Kit - provides a compiler and other tools for the development in Java, and also the execution environment. The JDK can be downloaded from the SUN website. Please take note of the installation path for later use. After a successful installation you need to perform some configurations, described in the following paragraphs.
For Ubuntu 8.10 it is highly recommended to use the package sun-java6-jdk included
in the multiverse repository.
You need to configure the JAVA_HOME environment variable, setting the installation path saved as suggested in the
previous paragraph.
The setting of the JAVA_HOME environment variable
- Right mouse button on
My Computer, then chooseProperties - Choose the
Advancedtab and press theEnvironment Variablesbutton - In the
System variablesbox, press theNewbutton and set the variable as showed in the Figure
In order to instruct the system to use the right Java subsystem, you have to run the following shell command:
wiz@id:~$ sudo update-alternatives --config java [sudo] password for wiz: There are 2 alternatives for 'java'. Selection Alternative ----------------------------------------------- + 1 /usr/lib/jvm/java-6-openjdk/jre/bin/java * 2 /usr/lib/jvm/java-6-sun/jre/bin/java Press return for default[*] value, or insert the selection number
and choose the right version from the available ones (which as said before is the SUN one). You can then check the configuration with the command:
wiz@id:~$ java -version java version "1.6.0_10" Java(TM) SE Runtime Environment (build 1.6.0_10-b33) Java HotSpot(TM) Server VM (build 11.0-b15, mixed mode)
Eclipse is an open source integrated development environment, which you can download from the official site. The required version is the one called [Eclipse IDE for Java EE Developers], version 3.4 Ganymede or later.
To install Eclipse you just have to extract the package in the preferred directory and run the eclipse executable.
Ubuntu 9.10 comes with a working Eclipse 3.5 Galileo. You will need to manually add the software repositories and install the plugins needed for J2EE development, though.
Starting for the first time, Eclipse will ask you to create a directory called workspace. Accept; that will be the directory under which Eclipse
will store all of your projects.
You can download PostgreSQL from the official site. The suggested version is
8.3. It is available an installer (pgInstaller) wich provides an installation wizard.
During the installation you will be asked to choose a characted encoding: choose UTF8. Please also take carefully note of the
chosen credentials (username and password).
Usually the installer for Windows comes with pgAdmin III. If it doesn't seem to be installed after the wizard finishes its job, you can download pgAdmin III from its official site.
After the installation, do all the configurations explained in a proper paragraph later in this document.
Installing under Ubuntu 8.10 is just a matter of doing an:
wiz@id:~$ sudo apt-get install postgresql postgresql-client postgresql-contrib pgadmin3
PostgreSQL is in the main repository, and pgAdmin III in the universe one.
After the installation, run the following commands in order to assign password to the postgres user,
and then do all the configurations explained in a proper paragraph later in this document.
wiz@id:~$ sudo su - postgres
postgres@id:~$ psql
Welcome to psql 8.3.6, the PostgreSQL interactive terminal.
Type: \copyright for distribution terms
\h for help with SQL commands
\? for help with psql commands
\g or terminate with semicolon to execute query
\q to quit
postgres=# alter user postgres with password 'postgres';
ALTER ROLE
postgres=# \q
postgres@id:~$ exit
logout
wiz@id:~$
Now it's time to add an user to the database, which you will use for jAPS 2.0 entando. Launch pgAdmin III and follow these instructions:
-
Connect to the database with username
postgresand passwordpostgres(you may have to add a connection usingFilethenAdd server...) - Right mouse button on
Login Roles, chooseNew Role -
Set both the username and the password to
agile, check theCan create databasesprivilege setting, confirm withOk.
You can download Apache Tomcat from the official site. The suggested version is 6.0.18. We recommend you to download Apache Tomcat in the form of a compressed archive.
To install Tomcat you just have to extract the package in the preferred directory and run the startup.sh (Linux)
or startup.bat (Windows) executable.
Please notice that for our chosen development environment and best practices, we only need Tomcat correctly installed in our system but we need it not to run except for the cases you will find later in this document.
You have to setup URI encoding for the Tomcat Connectors and enable the automatic trimmer for the JspServlet
You have to edit this file: server.xml
Looking for the tag Connector, you'll find something like this for port 8080:
<Connector port="8080" protocol="HTTP/1.1" connectionTimeout="20000" redirectPort="8443" />
and something like this for port 8443
<Connector port="8443" protocol="HTTP/1.1" SSLEnabled="true" maxThreads="150" scheme="https" secure="true" clientAuth="false" sslProtocol="TLS" />
You have to add a new attribute URIEncoding="UTF-8" to the connector tags.
So you'll have in your file server.xml
<Connector port="8080" protocol="HTTP/1.1"
connectionTimeout="20000"
redirectPort="8443"
URIEncoding="UTF-8"/>
and for port 8443
<Connector port="8443" protocol="HTTP/1.1" SSLEnabled="true"
maxThreads="150" scheme="https" secure="true"
clientAuth="false" sslProtocol="TLS"
URIEncoding="UTF-8"/>
Edit the file web.xml in your tomcat installation directory.
Search for <servlet-name>jsp</servlet-name>, and write inside the tag servlet new init param. See example below.
Example 3.3. Enable trimSpaces
<servlet>
<servlet-name>jsp</servlet-name>
<servlet-class>org.apache.jasper.servlet.JspServlet</servlet-class>
<init-param>
<param-name>fork</param-name>
<param-value>false</param-value>
</init-param>
<init-param>
<param-name>xpoweredBy</param-name>
<param-value>false</param-value>
</init-param>
<init-param>
<param-name>trimSpaces</param-name>
<param-value>true</param-value>
</init-param>
<load-on-startup>3</load-on-startup>
</servlet>
The suggested driver is JDBC 3 for PostgreSQL 8.3, and you have to
put it under the lib directory of your Tomcat installation.
Table of Contents
Now we can proceed creating in Eclipse the project for the new Portal.
Some of the required steps are automagically performed, thanks to the build files for Ant. The previously installed Eclipse environment comes with all the necessary to run an Ant build. You can run Ant using the Eclipse GUI and the instructions in this document, even if it is the very first time for you with Ant and Eclipse.
Later on this chapter, you will find detailed instructions to create the new Project. It will be a Dynamic Web Project. We will discuss later about the Dynamic Web Projects, and give some tips and best practices. At the moment, the goal is to create a development environment also including a local execution environment, to be able to immediately check the progresses during the development.
First of all, we need the package jAPS2.0_entando-2.2.0-src-0.1.zip from SourceForge.
Note the the packeages are inside the folder jAPS 2.0 entando src and jAPS2.0_entando-2.2.0-src . Choose the version that fits your needs;
you may want the tar.gz package on GNU Linux environment.
Once donwloaded, choose a temporary location and extract the package.
Launch Eclipse and take the following steps in order to import jAPS 2.0 entando in the workspace:
File, thenImport...Choose
General, thenExisting Projects into Workspace, and press theNextbuttonBrowse and select the directory from which import the project. Obviously, the right directory is the temporary one where you previously extracted the
jAPS2.0_entando-2.2.0-srcpackage downloaded from SourceForgeCheck the
Copy projects into workspaceboxPress
Finish
When Eclipse finishes to import, in the Project Explore view of Eclipse will be a new project called jAPS2.
This project contains all the necessary to instantiate a new Portal project, as we are going to explain. Later you can delete
it, if you want.
From the Project Explorer, browse the project jAPS2 and open admin/build_newPortal.xml.
This file contains the instructions which Ant can use to create the new project. First of all, it is necessary to customize the
name of the source project and the name of the project to create. Find the following two rows:
<property name="newportal.name" value="myPortalName" /> <property name="newportal.source.name" value="jAPS2" />
Now insert the desired project name in place of myPortalName, and optionally the name of the source project which defaults
to jAPS2. Save the file.
Example 4.1. build_newPortal.xml: a correct setting
<property name="newportal.name" value="myportal" /> <property name="newportal.source.name" value="jAPS2" />
From this point on, we will assume that your new project is called myportal. Now extract the new project from jAPS 2.0 entando:
Open the Ant view:
Window,Show View,Ant,AntDrag the file
build_newPortal.xmland drop it in the Ant viewExpand the node
jAPS2 - Extract New PortalLaunch (i.e. with a double-click) the task
Create New Portal
Ant will extract the new project from the source project, and will place it in your workspace directory. Now you have to import it
into Eclipse, just as you previously did with jAPS2.0_entando-2.2.0-src:
File, thenImport...Choose
General, thenExisting Projects into Workspace, and press theNextbuttonBrowse and select the directory from which import the project
myportal.Check the
Copy projects into workspaceboxPress
Finish
When Eclipse finishes to import, in the Project Explore view of Eclipse there will be a new project called myportal.
In order to avoid any mistake or misunderstanding, now you should better close or delete the jAPS2 project.
Now it's time for some configurations.
Open the file buildProperties.xml, located in the root directory of the project. First of all properly comment
or uncomment the blocks of properties suited for Microsoft Windows or Linux, following the XML syntax for comments:
<!-- This sentence is commented out -->
I.e. if you are using Windows, you have to comment out the Linux block and uncomment the Windows one. And so on...
Then edit the following properties accordingly with your system settings:
- Name of the web application, the same as the name of the project
<property name="webappname" value="myportal" />- Username for the Database
<property name="postgres.username" value="agile" />- Password for the Database
<property name="postgres.password" value="agile" />- Path of the PostgreSQL executables
Windows:
<property name="postgres.bin.path" location="C:\Programmi\PostgreSQL\8.3\bin" />Linux:
<property name="postgres.bin.path" location="/usr/bin" />
Now edit some properties for the execution phase. Open the file /jAPS2/WebContent/META-INF/context.xml.
Edit the paths, URLs, and values.
Example 4.2. context.xml on Linux
<?xml version='1.0' encoding='utf-8'?> <Context path="/myportal" docBase="./myportal" debug="1" reloadable="true"> <Environment name="logName" value="japs" type="java.lang.String" override="false" /> <Environment name="logFilePrefix" value="/home/wiz/workspace/myportal/build/temp/japs_log" type="java.lang.String" override="false" /> <Environment name="logLevel" value="ALL" type="java.lang.String" override="false" /> <Environment name="logFileSize" value="200000" type="java.lang.String" override="false" /> <Environment name="logFilesCount" value="10" type="java.lang.String" override="false" /> <Environment name="configVersion" value="production" type="java.lang.String" override="false" /> <Environment name="applicationBaseURL" value="http://localhost:8080/myportal/" type="java.lang.String" override="false" /> <Environment name="resourceRootURL" value="/myportal/resources/" type="java.lang.String" override="false" /> <Environment name="protectedResourceRootURL" value="/myportal/protected/" type="java.lang.String" override="false" /> <Environment name="resourceDiskRootFolder" value="/home/wiz/workspace/myportal/WebContent/resources/" type="java.lang.String" override="false" /> <Environment name="protectedResourceDiskRootFolder" value="/home/wiz/workspace/myportal/WebContent/protected/" type="java.lang.String" override="false" /> <Environment name="indexDiskRootFolder" value="/home/wiz/workspace/myportal/build/temp/indexdir" type="java.lang.String" override="false" /> <Environment name="cacheDiskRootFolder" value="/home/wiz/workspace/myportal/build/temp/cache" type="java.lang.String" override="false" /> <Resource name="jdbc/portDataSource" auth="Container" type="javax.sql.DataSource" driverClassName="org.postgresql.Driver" maxActive="8" maxIdle="4" username="agile" password="agile" url="jdbc:postgresql://localhost:5432/myportalPort" /> <Resource name="jdbc/servDataSource" auth="Container" type="javax.sql.DataSource" driverClassName="org.postgresql.Driver" maxActive="8" maxIdle="4" username="agile" password="agile" url="jdbc:postgresql://localhost:5432/myportalServ" /> </Context>
jAPS 2.0 entando needs two databases, whose names are prefixed by the name of the project
and suffixed respectively by Port and Serv.
Ant can automagically create and populate the two databases for you:
Warning
The next procedure drops the two databases if already present.
Please consider doing a backup before proceeding further.
Drag the file
build.xmland drop it in the Ant view.Expand the main node and launch (i.e. with a double-click) the
Pg db full updatetask
Having created a dynamic web project the next step is to configure the servlet container that is going to host the web application during the development stage.
Choose
File,New,Other,Serverto launch the wizardSelect
Apache - Tomcat v6.0 server, then press theNextbuttonIn the window
Tomcat Serverset the Tomcat installation directory (i.e. the directory where you installed Apache Tomcat in [Chapter 3. Software Requirements]), the press theNextbutton againAdd
myportalto the list of projects configured on this server, then press theFinishbutton
If everything works fine, Eclipse compiles and deploys the web application in a directory of its own (which we are not interested
in knowing at the moment). From now on, you can launch the web application with right mouse button on the project then choosing Run As...,
Run on Server.
If a server selection window appears, select the server you just created. You can also get rid of this window checking the
Always use this server when running this project setting.
If everything is ok, you can see the homepage of your brand new portal pointing your preferred browser to http://localhost:8080/myportal/.
As hinted before, the project you have just created is a Dynamic Web Project. Eclipse allows you to incrementally deploy (and almost in real time)
the application as you progress during the development. That is, in order to see the results of the editing of Java class, or of a JSP page
or of a CSS you don't have to copy the modified objects into the execution environment (i.e. the webapps directory
of the Apache Tomcat installation path) nor to perform a restart of the server: Eclipse does it all in your place, and very well.
Another (hopefully) useful digression. Given a certain dimension of the project, a Portal is built by a team of developers each providing various skills, from Java to the information architecture. Usually, the work group shares the Portal components using a project repository (i.e. CVS or SVN). This requires order and organization. Each developer works in a local area (the Eclipse workspace) which is a replica, periodically synchronized, of the shared repository. In order to be able to share all the components of the project, it is required that they are located in the same working area.
From this, derive some other tips.
Backup the databases
The database records cannot be hosted directly in the workspace: instead, from time to time you can perform an export (i.e. backup)
using the Pg db backup Ant task. You brand new project has the proper directory, db/tar under which
Ant will store the backup. Just be sure to perform a refresh (i.e. F5 or right mouse button, then Refresh) on the directory
or on the whole project to make Eclipse aware of the modifications made by Ant.
Then commit on the project repository.
Best practice about resources saving
As you should know, jAPS 2.0 entando comes with a powerful and fully integrated CMS. To build a Portal using jAPS 2.0 entando also means to begin to populate
it with some images and attachments (which in jAPS 2.0 entando are called Resources). Being files, you can host them in the
project area (see the configuration of the parameter resourceDiskRootFolder). In order to be able to view this resources under
Tomcat, it is required for them to be located in deploy area of the application. And here it comes the Dynamic Web Project again:
if you save the resource in a proper directory under the project area, Eclipse will automagically deploy them in the execution area
for Tomcat. Everything goes really fine, with a warning: from time to time you must perform a refresh both of the project in Eclipse, to make
it aware of the new or modified resources, and of the page in the browser to make it aware of the incremental deploy done by Tomcat and
guided by Eclipse.
Example 4.4. resourceDiskRootFolder: a useful setting
resourceDiskRootFolder=/home/wiz/workspace/myportal/WebContent/resources/
The big picture is the following:
- The components of the project (that is, the web application) are in
workspace/myportal - Eclipse deploys them in a directory, say
DeployArea - Apache Tomcat runs the web application placed in the directory
DeployArea -
When the developer updates an object in
workspace/myportal, Eclipse copies it inDeployAreaand if it is necessary also restarts Tomcat -
Usually the developer keeps opened at the same time both Eclipse and the browser, on different windows, to verify in real time
the effects of his job. In Eclipse he works on the components in
workspace/myportal, using the browser he can use the web application Tomcat is executing in theDeployArea.
Let's see what happens when you upload a new Image resource using the CMS of jAPS 2.0 entando:
-
When you upload a new image, the web application stores it under the path specified in the configuration, which is a directory
in
workspace/myportal - With a refresh on the project window, Eclipse becomes aware of the new image file
- Eclipse then copies the image in the
DeployArea - If the page currently loaded in the browser contains a reference to the image, to make it show up it is necessary to perform a refresh in the browser window (i.e. reloading the page).
As you can imagine all these tips regard exclusively the development environment and not the final production environments, where only the execution area does exist.
Clean & Refresh before a commit
If you use a shared project repository please remember to perform a clean (there is the proper Ant task) and a refresh in Eclipse before every single commit, in order to allow Eclipse to correctly find and synchronize all the objects coming from the CMS, from the database, and from any other external software.
Compile soon after a clean
This is simple: after every clean performed by Ant as explained in the previous tip, and prior to start the integrated local execution
environment again, compile the sources again using the compile Ant task. Otherwise the execution will fail, because you just
cleaned away every compiled class!
