2009-10-30T15:21:05Z
7064
Arena-dev
68
1783
'''Arena PUJ - Development Environment Configuration'''
[http://fgaucho.dyndns.org:8080/hudson/job/arena-puj/ [[image: title.png|right]]]
[https://www.ohloh.net/p/arena-puj [[image: project_partner_badge.gif|right]]]
__TOC__
=Where is the project specification?=
Would you like to know more about the project before to ''put your hands in the code jar''? Here are the docs:
* [http://kenai.com/projects/puj The PUJ Competition] (the business case).
* [http://kenai.com/projects/puj/pages/Arena The Arena Project Specification].
=QuickStart - The code up and running in ~10 minutes=
The following instructions were tested in [http://www.ubuntu.com/ Linux Ubuntu 9.10], but we assume it will work in other operational systems as well. If you have questions or problems during your local setup, please feel free to send an email to fgaucho@gmail.com
==Environment Setup==
* Check if you have all software you need:
*# [http://java.sun.com/ Java 6.x]
*# [http://maven.apache.org/ Maven 2.x]
*# [http://www.mysql.com/ MySql 5.x]
*# [http://mercurial.selenic.com/wiki/ Mercurial] (if you are under some proxy try the mercurial 1.3.1 or newer)
*# [http://download.java.net/glassfish/v3/nightly/ Glassfish v3] (glassfish b69 at least)
* Put the $GLASSFISH_HOME/bin in your $PATH (%path% on windows). It is required by the Maven script;
* Create a file called $HOME/.passwords directory, containing the following properties:
ASADMIN_USER=admin
MAIL_HOST=''smtp.some email.com''
MAIL_USER=''user''
MAIL_FROM=''user@somemail.com''
MAIL_SMTP_USER=''user@somemail.com''
MAIL_SMTP_PORT=465
MAIL_SMTP_PASSWORD=''some_password''
MYSQL_USER=root
MYSQL_PASSWORD=adminadmin
DB_URL=jdbc\\:mysql\\://localhost\\:3306/arena
* If you are using Windows, create the file %USERPROFILE%\.passwords and copy the above properties, but please change the DB_URL to:
DB_URL=jdbc\:mysql\://localhost\:3306/arena
==Adding permissions to Reflection based frameworks==
==Adding the permissions to Reflection based frameworks ==
Add the below lines to the file $AS_HOME/domains/domain1/config/server.policy
grant codeBase "file:${com.sun.aas.installRoot}/domains/domain1/applications/arena-dwr/-" {
permission java.lang.reflect.ReflectPermission "suppressAccessChecks";
};
grant codeBase "file:${com.sun.aas.installRoot}/domains/domain1/applications/arena-vaadin/-" {
permission java.lang.reflect.ReflectPermission "suppressAccessChecks";
};
==Install MySql driver in Glassfish==
You need to copy the [http://dev.mysql.com/downloads/connector/j/5.1.html MySql Connector/J jar file] to the folder $AS_HOME/domains/domain1/lib/ext
This should be done manually and you should restart the server after copying the file. [http://docs.sun.com/app/docs/doc/820-4496/beaml?a=view more...]
* ''Please check if you are using the default domain1, otherwise modify the above command according your Server domain name''.
==Checkout and build the source code==
hg clone https://kenai.com/hg/puj~arena
cd puj~arena
mvn clean install eclipse:eclipse
Done! Now you can import the project in your preferred IDE and play around the source code.
==Start the MySql database==
If the MySql database is not yet running, please turn it on:
* '''Linux Users''': /etc/rc.d/init.d/mysqld start
* '''Windows Users''': C:\Program Files\MySQL\MySQL Server 5.0\bin\mysqld
==Building and deploying the application==
* '''Linux Users''': use the profile -Phudson:
cd puj~arena
asadmin start-domain
mvn clean install -Phudson
* '''Windows Users''': use the profile -PhudsonWin:
cd puj~arena
asadmin start-domain
mvn clean install -PhudsonWin
==Testing the application==
If everything worked fine, you should be able to access the following URLs:
* [http://localhost:8080/arena-http/application.wadl the service contract]
* [http://localhost:8080/arena-jsf20 the JSF web gui]
* [http://localhost:8080/arena-dwr the DWR web gui]
* [http://localhost:8080/arena-vaadin the Vaadin web gui]
=Quality assurance=
===Java Quality Assurance & Continuous integration===
Our project has a [http://fgaucho.dyndns.org:8080/hudson/job/arena-puj/ Continuous Integration Server] configured to check the quality of our work continuously. If there is any commit in the last hour, this server will build a clean copy of the source code and generates quality reports based on Findbugs and PMD. Please visit that server regularly to check if your code is sound and considered good quality.
Also, please be sure to have the following plugins installed in your preferred IDE:
* [http://findbugs.sourceforge.net FindBugs]
* [http://pmd.sourceforge.net/integrations.html PMD]
===Encoding===
Always use UTF-8 as the file encoding. If you will include HTML code in Java files, or other resources that will generate HTML output, please [http://www.stringfunction.com/html-encode.html convert special characters to HTML encoding].
===Web Resources Quality Assurance===
If you are producing a web-application, please install YSlow in the browser you use to validate the quality of your code. And other good practice is to do a functional test of your web-gui against the major browsers on the market (at least Firefox, IExplorer and Chrome). There are some online services to test a web application on different machine configurations and browser versions, like the popular ''browsershots.org''.
* [http://developer.yahoo.com/yslow/ YSlow]
* [http://browsershots.org/ browsershots.org] (or [http://litmusapp.com/ Litmus], or [http://www.thumbalizr.com/ thumbalizr])
'''Web resources validation''': a good quality indicator about our web resources are the W3C validations. Please apply your documents for validation and review the W3C warnings and recommendations before to commit the files:
[http://validator.w3.org/check?uri=http%3A%2F%2Ffgaucho.dyndns.org%3A8080%2Farena-jsf20%2F [[image: valid-xhtml10-blue.png]]] [http://jigsaw.w3.org/css-validator/validator?uri=http%3A%2F%2Ffgaucho.dyndns.org%3A8080%2Farena-jsf20%2Fresources%2Fcss%2Fpuj.css&profile=css3&usermedium=all&warning=2 [[image: vcss-blue.gif]]] [http://validator.w3.org/feed/check.cgi?url=fgaucho.dyndns.org%3A8080%2Farena-http%2Fatom [[image: valid-atom.png]]]
Other good tools for cleanup & enhance the quality of your web resources are:
* [http://services.immike.net/css-checker/ CSS Redundancy Checker]
* [http://csstidy.sourceforge.net/example.php CSSTidy]
* [http://www.jslint.com/ JSLint] (javascript validator)
* [http://websiteoptimization.com/services/analyze/ Web Page Analyzer]
=References=
==HTTP Protocol==
* [http://www.mnot.net/cache_docs/ Caching Tutorial ''for Web Authors and Webmasters'']
* [http://www.atomenabled.org/developers/syndication/ Atom Syndication Format]
* [http://www.ibm.com/developerworks/library/x-atompp1/ Getting to know the Atom Publishing Protocol]
==RESTful Web-Services==
* [http://www.infoq.com/articles/webber-rest-workflow How to GET a Cup of Coffee]
* [http://jcalcote.wordpress.com/2008/10/16/put-or-post-the-rest-of-the-story/ PUT or POST: The REST of the Story]
* [http://www.prescod.net/rest/mistakes/ Common REST Mistakes]
* [http://www.xfront.com/REST-Web-Services.html Building Web Services the REST Way]
==Java EE==
* [http://java.sun.com/javaee/6/docs/tutorial/doc/ The Java EE 6 Tutorial]
* [http://wikis.sun.com/display/Jersey/Main Jersey Framework]
* [https://www.sun.com/offers/details/Java_Jersey_Client.xml Jersey Client Programming]
==Tools==
* [http://www.sonatype.com/books/maven-book/reference/ Maven: The Definitive Guide]
* [http://wiki.glassfish.java.net/Wiki.jsp?page=GlassFishDocs Glassfish Documentation]
* [http://refcardz.dzone.com/refcardz/getting-started-glassfish?oid=hom14321 Glassfish V3 RefCard]
* [http://dev.mysql.com/doc/ MySql Documentation]
* [http://mercurial.selenic.com/wiki/MercurialBook The Mercurial Book]
<p><b>Arena PUJ - Development Environment Configuration</b>
</p><p><a class='external' href="http://fgaucho.dyndns.org:8080/hudson/job/arena-puj/"><?link_for_image title.png|right?></a><a class='external' href="https://www.ohloh.net/p/arena-puj"><?link_for_image project_partner_badge.gif|right?></a>
</p><div id='toc' class='toc'>
<div id='toctitle' class='toc-title'>
<span>Contents</span>
</div>
<div id='toccontents' class='toc-contents'><ul><li>1 <a href='#Where_is_the_project_specification?'>Where is the project specification?</a></li>
<li>2 <a href='#QuickStart_-_The_code_up_and_running_in_~10_minutes'>QuickStart - The code up and running in ~10 minutes</a></li>
<ul><li>2.1 <a href='#Environment_Setup'>Environment Setup</a></li>
<li>2.2 <a href='#Adding_permissions_to_Reflection_based_frameworks'>Adding permissions to Reflection based frameworks</a></li>
<li>2.3 <a href='#Adding_the_permissions_to_Reflection_based_frameworks'>Adding the permissions to Reflection based frameworks </a></li>
<li>2.4 <a href='#Install_MySql_driver_in_Glassfish'>Install MySql driver in Glassfish</a></li>
<li>2.5 <a href='#Checkout_and_build_the_source_code'>Checkout and build the source code</a></li>
<li>2.6 <a href='#Start_the_MySql_database'>Start the MySql database</a></li>
<li>2.7 <a href='#Building_and_deploying_the_application'>Building and deploying the application</a></li>
<li>2.8 <a href='#Testing_the_application'>Testing the application</a></li>
</ul><li>3 <a href='#Quality_assurance'>Quality assurance</a></li>
<ul><ul><li>3.1 <a href='#Java_Quality_Assurance_&_Continuous_integration'>Java Quality Assurance & Continuous integration</a></li>
<li>3.2 <a href='#Encoding'>Encoding</a></li>
<li>3.3 <a href='#Web_Resources_Quality_Assurance'>Web Resources Quality Assurance</a></li>
</ul></ul><li>4 <a href='#References'>References</a></li>
<ul><li>4.1 <a href='#HTTP_Protocol'>HTTP Protocol</a></li>
<li>4.2 <a href='#RESTful_Web-Services'>RESTful Web-Services</a></li>
<li>4.3 <a href='#Java_EE'>Java EE</a></li>
<li>4.4 <a href='#Tools'>Tools</a></li>
</ul></ul></div>
</div><h1><a name='Where_is_the_project_specification?'></a>Where is the project specification?</h1>
<p>Would you like to know more about the project before to <i>put your hands in the code jar</i>? Here are the docs:
</p><ul><li> <a class='external' href="http://kenai.com/projects/puj">The PUJ Competition</a> (the business case).
</li><li> <a class='external' href="http://kenai.com/projects/puj/pages/Arena">The Arena Project Specification</a>.
</li></ul><h1><a name='QuickStart_-_The_code_up_and_running_in_~10_minutes'></a>QuickStart - The code up and running in ~10 minutes</h1>
<p>The following instructions were tested in <a class='external' href="http://www.ubuntu.com/">Linux Ubuntu 9.10</a>, but we assume it will work in other operational systems as well. If you have questions or problems during your local setup, please feel free to send an email to fgaucho@gmail.com
</p><h2><a name='Environment_Setup'></a>Environment Setup</h2>
<ul><li> Check if you have all software you need:
<ol><li> <a class='external' href="http://java.sun.com/">Java 6.x</a></li><li> <a class='external' href="http://maven.apache.org/">Maven 2.x</a></li><li> <a class='external' href="http://www.mysql.com/">MySql 5.x</a></li><li> <a class='external' href="http://mercurial.selenic.com/wiki/">Mercurial</a> (if you are under some proxy try the mercurial 1.3.1 or newer)
</li><li> <a class='external' href="http://download.java.net/glassfish/v3/nightly/">Glassfish v3</a> (glassfish b69 at least)
</li></ol></li></ul><ul><li> Put the $GLASSFISH_HOME/bin in your $PATH (%path% on windows). It is required by the Maven script;
</li></ul><ul><li> Create a file called $HOME/.passwords directory, containing the following properties:
</li></ul><pre> ASADMIN_USER=admin
MAIL_HOST=<i>smtp.some email.com</i>
MAIL_USER=<i>user</i>
MAIL_FROM=<i>user@somemail.com</i>
MAIL_SMTP_USER=<i>user@somemail.com</i>
MAIL_SMTP_PORT=465
MAIL_SMTP_PASSWORD=<i>some_password</i>
MYSQL_USER=root
MYSQL_PASSWORD=adminadmin
DB_URL=jdbc\\:mysql\\://localhost\\:3306/arena
</pre><ul><li> If you are using Windows, create the file %USERPROFILE%\.passwords and copy the above properties, but please change the DB_URL to:
</li></ul><pre> DB_URL=jdbc\:mysql\://localhost\:3306/arena
</pre><h2><a name='Adding_permissions_to_Reflection_based_frameworks'></a>Adding permissions to Reflection based frameworks</h2>
<h2><a name='Adding_the_permissions_to_Reflection_based_frameworks'></a>Adding the permissions to Reflection based frameworks </h2>
<p>Add the below lines to the file $AS_HOME/domains/domain1/config/server.policy
</p><pre> grant codeBase "file:${com.sun.aas.installRoot}/domains/domain1/applications/arena-dwr/-" {
permission java.lang.reflect.ReflectPermission "suppressAccessChecks";
};
grant codeBase "file:${com.sun.aas.installRoot}/domains/domain1/applications/arena-vaadin/-" {
permission java.lang.reflect.ReflectPermission "suppressAccessChecks";
};
</pre><h2><a name='Install_MySql_driver_in_Glassfish'></a>Install MySql driver in Glassfish</h2>
<p>You need to copy the <a class='external' href="http://dev.mysql.com/downloads/connector/j/5.1.html">MySql Connector/J jar file</a> to the folder $AS_HOME/domains/domain1/lib/ext
</p><p>This should be done manually and you should restart the server after copying the file. <a class='external' href="http://docs.sun.com/app/docs/doc/820-4496/beaml?a=view">more...</a>
</p><ul><li> <i>Please check if you are using the default domain1, otherwise modify the above command according your Server domain name</i>.
</li></ul><h2><a name='Checkout_and_build_the_source_code'></a>Checkout and build the source code</h2>
<pre> hg clone <a class='external' href="https://kenai.com/hg/puj~arena">https://kenai.com/hg/puj~arena</a>
cd puj~arena
mvn clean install eclipse:eclipse
</pre><p>
Done! Now you can import the project in your preferred IDE and play around the source code.
</p><h2><a name='Start_the_MySql_database'></a>Start the MySql database</h2>
<p>
If the MySql database is not yet running, please turn it on:
</p><ul><li> <b>Linux Users</b>: /etc/rc.d/init.d/mysqld start
</li><li> <b>Windows Users</b>: C:\Program Files\MySQL\MySQL Server 5.0\bin\mysqld
</li></ul><h2><a name='Building_and_deploying_the_application'></a>Building and deploying the application</h2>
<ul><li> <b>Linux Users</b>: use the profile -Phudson:
</li></ul><pre> cd puj~arena
asadmin start-domain
mvn clean install -Phudson
</pre><ul><li> <b>Windows Users</b>: use the profile -PhudsonWin:
</li></ul><pre> cd puj~arena
asadmin start-domain
mvn clean install -PhudsonWin
</pre><h2><a name='Testing_the_application'></a>Testing the application</h2>
<p>If everything worked fine, you should be able to access the following URLs:
</p><ul><li> <a class='external' href="http://localhost:8080/arena-http/application.wadl">the service contract</a>
</li><li> <a class='external' href="http://localhost:8080/arena-jsf20">the JSF web gui</a>
</li><li> <a class='external' href="http://localhost:8080/arena-dwr">the DWR web gui</a>
</li><li> <a class='external' href="http://localhost:8080/arena-vaadin">the Vaadin web gui</a>
</li></ul><h1><a name='Quality_assurance'></a>Quality assurance</h1>
<h3><a name='Java_Quality_Assurance_&_Continuous_integration'></a>Java Quality Assurance & Continuous integration</h3>
<p>Our project has a <a class='external' href="http://fgaucho.dyndns.org:8080/hudson/job/arena-puj/">Continuous Integration Server</a> configured to check the quality of our work continuously. If there is any commit in the last hour, this server will build a clean copy of the source code and generates quality reports based on Findbugs and PMD. Please visit that server regularly to check if your code is sound and considered good quality.
</p><p>Also, please be sure to have the following plugins installed in your preferred IDE:
</p><ul><li> <a class='external' href="http://findbugs.sourceforge.net">FindBugs</a></li><li> <a class='external' href="http://pmd.sourceforge.net/integrations.html">PMD</a></li></ul><h3><a name='Encoding'></a>Encoding</h3>
<p>Always use UTF-8 as the file encoding. If you will include HTML code in Java files, or other resources that will generate HTML output, please <a class='external' href="http://www.stringfunction.com/html-encode.html">convert special characters to HTML encoding</a>.
</p><h3><a name='Web_Resources_Quality_Assurance'></a>Web Resources Quality Assurance</h3>
<p>If you are producing a web-application, please install YSlow in the browser you use to validate the quality of your code. And other good practice is to do a functional test of your web-gui against the major browsers on the market (at least Firefox, IExplorer and Chrome). There are some online services to test a web application on different machine configurations and browser versions, like the popular <i>browsershots.org</i>.
</p><ul><li> <a class='external' href="http://developer.yahoo.com/yslow/">YSlow</a></li><li> <a class='external' href="http://browsershots.org/">browsershots.org</a> (or <a class='external' href="http://litmusapp.com/">Litmus</a>, or <a class='external' href="http://www.thumbalizr.com/">thumbalizr</a>)
</li></ul><p><b>Web resources validation</b>: a good quality indicator about our web resources are the W3C validations. Please apply your documents for validation and review the W3C warnings and recommendations before to commit the files:
</p><p><a class='external' href="http://validator.w3.org/check?uri=http%3A%2F%2Ffgaucho.dyndns.org%3A8080%2Farena-jsf20%2F"><?link_for_image valid-xhtml10-blue.png?></a> <a class='external' href="http://jigsaw.w3.org/css-validator/validator?uri=http%3A%2F%2Ffgaucho.dyndns.org%3A8080%2Farena-jsf20%2Fresources%2Fcss%2Fpuj.css&profile=css3&usermedium=all&warning=2"><?link_for_image vcss-blue.gif?></a> <a class='external' href="http://validator.w3.org/feed/check.cgi?url=fgaucho.dyndns.org%3A8080%2Farena-http%2Fatom"><?link_for_image valid-atom.png?></a>
</p><p>Other good tools for cleanup & enhance the quality of your web resources are:
</p><ul><li> <a class='external' href="http://services.immike.net/css-checker/">CSS Redundancy Checker</a></li><li> <a class='external' href="http://csstidy.sourceforge.net/example.php">CSSTidy</a></li><li> <a class='external' href="http://www.jslint.com/">JSLint</a> (javascript validator)
</li><li> <a class='external' href="http://websiteoptimization.com/services/analyze/">Web Page Analyzer</a></li></ul><h1><a name='References'></a>References</h1>
<h2><a name='HTTP_Protocol'></a>HTTP Protocol</h2>
<ul><li> <a class='external' href="http://www.mnot.net/cache_docs/">Caching Tutorial <i>for Web Authors and Webmasters</i></a></li><li> <a class='external' href="http://www.atomenabled.org/developers/syndication/">Atom Syndication Format</a></li><li> <a class='external' href="http://www.ibm.com/developerworks/library/x-atompp1/">Getting to know the Atom Publishing Protocol</a></li></ul><h2><a name='RESTful_Web-Services'></a>RESTful Web-Services</h2>
<ul><li> <a class='external' href="http://www.infoq.com/articles/webber-rest-workflow">How to GET a Cup of Coffee</a></li><li> <a class='external' href="http://jcalcote.wordpress.com/2008/10/16/put-or-post-the-rest-of-the-story/">PUT or POST: The REST of the Story</a></li><li> <a class='external' href="http://www.prescod.net/rest/mistakes/">Common REST Mistakes</a></li><li> <a class='external' href="http://www.xfront.com/REST-Web-Services.html">Building Web Services the REST Way</a></li></ul><h2><a name='Java_EE'></a>Java EE</h2>
<ul><li> <a class='external' href="http://java.sun.com/javaee/6/docs/tutorial/doc/">The Java EE 6 Tutorial</a></li><li> <a class='external' href="http://wikis.sun.com/display/Jersey/Main">Jersey Framework</a></li><li> <a class='external' href="https://www.sun.com/offers/details/Java_Jersey_Client.xml">Jersey Client Programming</a></li></ul><h2><a name='Tools'></a>Tools</h2>
<ul><li> <a class='external' href="http://www.sonatype.com/books/maven-book/reference/">Maven: The Definitive Guide</a></li><li> <a class='external' href="http://wiki.glassfish.java.net/Wiki.jsp?page=GlassFishDocs">Glassfish Documentation</a></li><li> <a class='external' href="http://refcardz.dzone.com/refcardz/getting-started-glassfish?oid=hom14321">Glassfish V3 RefCard</a></li><li> <a class='external' href="http://dev.mysql.com/doc/">MySql Documentation</a></li><li> <a class='external' href="http://mercurial.selenic.com/wiki/MercurialBook">The Mercurial Book</a></li></ul>
2010-01-24T08:55:37Z
11683