*** Developing Flex Applications with server side Java
*** MicroHowTo and MicroTutorial
*** Tomcat 5.5 with Flex 3 SDK Beta and LiveCycle Data Services ES Express on Ubuntu 7.04
*** mostly taken from installed documentation http://localhost:8180/tomcat-docs
*** and http://www.adobe.com/support/documentation/en/flex/2/install.html

- install Java 6 Developement Kit (jdk)
	- via synaptic the package is:
		sun-java6-jdk
		(i also installed all other sun-java6 available packages)
	- set predefined version
		sudo update-java-alternatives -s java-6-sun
	- check from terminal:
		java -version
			java version "1.6.0"
			Java(TM) SE Runtime Environment (build 1.6.0-b105)
			Java HotSpot(TM) 64-Bit Server VM (build 1.6.0-b105, mixed mode)
	- check JAVA_HOME environmental variable
		export
		- if JAVA_HOME it's not set, edit .bashrc file and add line:
			export JAVA_HOME="/usr/lib/jvm/java-6-sun-1.6.0.00/"
			- then apply changes with
				source .bashrc

- install Flex 3 SDK beta
	http://labs.adobe.com/technologies/flex/sdk/flex3sdk.html
	- download, unzip, and put it in a folder: in my case /opt/flex_sdk_3

- install tomcat
	sudo apt-get install tomcat5.5
	sudo apt-get install tomcat5.5-admin
	sudo apt-get install tomcat5.5-webapps

- set JAVA_HOME inside tomcat
	sudo vi /etc/default/tomcat5.5
	- uncomment:
		JAVA_HOME=/usr/lib/jvm/java-6-sun-1.6.0.00

- Repair file catalina.out:
	cd /var/log/tomcat5.5/
	sudo rm catalina.out
	sudo touch catalina.out
	sudo chown tomcat55:nogroup *
	sudo chmod 777 *

- create administration user
	sudo vi /usr/share/tomcat5.5/conf/tomcat-users.xml
	- and add these roles:
		<role rolename="manager"/>
		<role rolename="admin"/>
	- and an admin user with both roles:
		<user username="myuser" password="mypassword" roles="admin,manager"/>
	- final documt is like:
		<?xml version='1.0' encoding='utf-8'?>
		<!--
		  NOTE:  By default, no user is included in the "manager" role required
		  to operate the "/manager" web application.  If you wish to use this app,
		  you must define such a user - the username and password are arbitrary.
		-->
		<tomcat-users>
		  <role rolename="manager"/>
		  <role rolename="tomcat"/>
		  <role rolename="admin"/>
		  <role rolename="role1"/>
		  <user username="both" password="tomcat" roles="tomcat,role1"/>
		  <user username="tomcat" password="tomcat" roles="tomcat"/>
		  <user username="role1" password="tomcat" roles="role1"/>
		  <user username="myuser" password="mypassword" roles="admin,manager"/>
		</tomcat-users>


- configure the Ant custom tasks.
	- copy the JAR file named $CATALINA_HOME/server/lib/catalina-ant.jar to your Ant installation
	- if installed tomcat via apt-get in ubuntu, there is already the file (so skip this step):
		/usr/share/ant/lib/catalina5.5-ant.jar

- (re)start service
	sudo /etc/init.d/tomcat5.5 restart

- test
	http://localhost:8180/

- install LiveCycle Data Services ES Express (formerly Flex Data Services 2)
	(from http://www.adobe.com/support/documentation/en/flex/2/install.html#flexj2ee )
	(and from http://help.adobe.com/en_US/livecycle/es/lcds_installation.html )
	- create a folder for installation (we pre-create the default dir that will be prompted during installation)
		sudo mkdir /opt/lcds
		sudo chown federico /opt/lcds/
		- note: change federico with your username!!!
	- download the FDS war file:
		http://www.adobe.com/cfusion/tdrc/index.cfm?product=flex
		(note: must be registered to adobe site...)
	- put downloaded file on a temp dir
	- cd to the temp dir
	- start installation:
		chmod +x lcds251-lin.bin
		./lcds251-lin.bin -i console
		- keep default install dir /opt/lcds
		- choose "J2EE web application"
	- deploy WAR files
		- copy these 3 war files to the webapps folder:
			sudo cp /opt/lcds/flex.war /var/lib/tomcat5.5/webapps/.
			sudo cp /opt/lcds/flex-admin.war /var/lib/tomcat5.5/webapps/.
			sudo cp /opt/lcds/samples.war /var/lib/tomcat5.5/webapps/.
		- restart tomcat
			sudo /etc/init.d/tomcat5.5 restart
	- install JOTM Java Open Transaction Manager
		- stop tomcat
			sudo /etc/init.d/tomcat5.5 stop
		- download package from
			http://forge.objectweb.org/project/showfiles.php?group_id=19&release_id=1024
		- unpack it in a folder (i.e.: /opt/)
		- copy the JAR files from jotm-root/lib to {tomcat-root}/common/lib.
			- in my case:
			sudo cp /opt/jotm/lib/* /usr/share/tomcat5.5/common/lib/.
		- Create a context file for your web application and register JOTM using the Transaction element,
			- e.g. for the samples WAR create a [tomcat-root]/conf/Catalina/localhost/samples.xml file and add the following lines:
			<Context docBase="${catalina.home}/webapps/samples" privileged="true" antiResourceLocking="false" antiJARLocking="false">
			   <Transaction factory="org.objectweb.jotm.UserTransactionFactory" jotm.timeout="60"/>
			</Context>
		- increase memory used by tomcat
			- edit catalina.sh file ( in my case: sudo vi /etc/default/tomcat5.5 )
			- and add this line:
				JAVA_OPTS="-Djava.awt.headless=true -Xmx512m"
		- start tomcat
			sudo /etc/init.d/tomcat5.5 start
		- check if memory is correct:
			http://localhost:8180/manager/status
	- test via browser
		http://localhost:8180/flex/
		http://localhost:8180/flex-admin/
		http://localhost:8180/samples/
	- and learn how lcds work!
		http://localhost:8180/samples/testdrive/

- essential informations about tomcat
	- tomcat dirs:
		- $CATALINA_HOME = 										/usr/share/tomcat5.5/
		- tomcat admin webapps = 								/usr/share/tomcat5.5-webapps/
		- webapps = 											/var/lib/tomcat5.5/webapps/
		- Startup, shutdown, and other scripts =				/usr/share/tomcat5.5/bin/
		- configuration file server.xml (ex: port number) and tomcat-users.xml =	/usr/share/tomcat5.5/conf/
	- application dirs layout (valid for a WAR file)
		/var/lib/tomcat5.5/webapps/MyApplication/index.jsp
			- all client gui files
		/var/lib/tomcat5.5/webapps/MyApplication/WEB-INF/web.xml
			- the "web application deployment descriptor" file
		/var/lib/tomcat5.5/webapps/MyApplication/WEB-INF/classes/
			- all non-packed application classes
			- note: a Java class named com.mycompany.mypackage.MyServlet
					would need to be stored in a file named /WEB-INF/classes/com/mycompany/mypackage/MyServlet.class
		/var/lib/tomcat5.5/webapps/MyApplication/WEB-INF/lib/
			- all packed (jar) application classes
			- note: this dir contains JDBC drivers if necessary
	- common and shared classes dirs layout
		$CATALINA_HOME/common/lib
		$CATALINA_HOME/common/classes
			- files placed here are visible both to all web applications and internal Tomcat code
		$CATALINA_HOME/shared/lib
		$CATALINA_HOME/shared/classes
			- files placed here are visible to all web applications but not to internal Tomcat code
	- project source directory
		- note: this can be anyware outside of the tomcat installation dirs
		/
			- Here is the ant build file build.xml
		docs/
			- Documentation for your application, in whatever format your development team is using.
		src/
			- Java source files that generate the servlets, beans, and other Java classes that are unique to your application.
			- If your source code is organized in packages (highly recommended), the package hierarchy should be reflected as a directory structure underneath this directory.
			- For example, a Java class named com.mycompany.mypackage.MyClass.java should be stored in file src/com/mycompany/mypackage/MyClass.java
		web/
			- The static content of your web site (HTML pages, JSP pages, JavaScript files, CSS stylesheet files, and images) that will be accessible to application clients.
			- This directory will be the document root of your web application, and any subdirectory structure found here will be reflected in the request URIs required to access those files.
		web/WEB-INF/
			- The special configuration files required for your application, including the web application deployment descriptor web.xml
			- Even though this directory appears to be a subdirectory of your document root, the Servlet Specification prohibits serving the contents of this directory (or any file it contains) directly to a client request. Therefore, this is a good place to store configuration information that is sensitive (such as database connection usernames and passwords), but is required for your application to operate successfully.
	- temporary generated project source directory
		build/
			- When you execute a default build (ant), this directory will contain an exact image of the files in the web application archive for this application.
		dist/
			- When you execute the ant dist target, this directory will be created. It will create an exact image of the binary distribution for your web application, including an license information, documentation, and README files that you have prepared.
		- note: these two directories should NOT be archived in your source code control system, because they are deleted and recreated (from scratch) as needed during development. For that reason, you should not edit any source files in these directories if you want to maintain a permanent record of the changes, because the changes will be lost the next time that a build is performed.

- starting a new project
	(mainly from http://tomcat.apache.org/tomcat-5.5-doc/ )
	- create project dir and subdirs as explained above in "project source directory"
	- get a default build.xml file from here:
		http://localhost:8180/tomcat-docs/appdev/build.xml.txt
		http://tomcat.apache.org/tomcat-5.5-doc/appdev/build.xml.txt
	- configure build.xml file
		- update this line:
		<property name="catalina.home" value="/usr/share/tomcat5.5"/> <!-- UPDATE THIS! -->
	- create build.properties file
		- in same dir of build.xml
		- sample content:
			# Context path to install this application on
			app.name=ooogui2
			app.path=/ooogui2
			app.version=0.1-dev

			# Tomcat 5 installation directory
			catalina.home=/usr/share/tomcat5.5

			# Manager webapp username and password
			manager.username=myusername
			manager.password=mypassword
	- get a default web.xml file from here:
		http://217.133.115.195:8180/tomcat-docs/appdev/web.xml.txt
		http://tomcat.apache.org/tomcat-5.5-doc/appdev/web.xml.txt
	- configure web.xml file
		- put the default file in web/WEB-INF subfolder in project source directory
			- rename file to web.xml
		- change these lines at least:
			<display-name>oooGui 2</display-name>
			<description>
			  Obliquid Object Oriented Graphic User Interface.
			  It's an attempt to HEAVILY generalize the concept of Content Management System, and related user interfaces.
			  I did this cause I was so tired to explain customers how things work.
			  Written by Federico Carrara
			  dillo@federicocarrara.it
			  federico@obliquid.it
			  www.federicocarrara.it
			  www.obliquid.it
			</description>

			...
			
			<context-param>
			  <param-name>webmaster</param-name>
			  <param-value>dillo@federicocarrara.it</param-value>
			  <description>
				The EMAIL address of the administrator to whom questions
				and comments about this application should be addressed.
			  </description>
			</context-param>
			
- testing a project
	- Start Tomcat if needed
	- Compile your application
		- goto the "project source directory"
		- call ant:
			ant compile
			(or just ant, since this compile the default)
	- Install the application
		ant install
		- This tells Tomcat to immediately start running your app on the context path defined in the app.path build property. Tomcat does NOT have to be restarted for this to take effect.
	- Test the application
		- Using your browser or other testing tools, test the functionality of your application.
	- Create a release
		ant all
		ant dist
			- this command creates the WAR file
	- Deploy the WAR file via Tomcat Manager:
		http://localhost:8180/manager/html

- misc
	- to extract code from a WAR file
		jar -xvf sample.war




*** resources
	- tomcat & fds installation
		http://www.adobe.com/support/documentation/en/flex/2/install.html#tomcat
		http://www.adobe.com/support/documentation/en/flex/2/install.html#flexj2ee
		http://www.augitaly.com/flexgala/index.php?cmd=newsreader&id=32
		http://members.cox.net/midian/howto/flex+tomcat4.htm
		http://www.adobe.com/devnet/flex/articles/architecting_rias_02.html
		http://livedocs.adobe.com/flex/201/html/wwhelp/wwhimpl/js/html/wwhelp.htm?href=tutorial_data_service_027_01.html




*** notes

- install GlassFish
	- tested version is v2-b41d
	- download and follow installation instructions from
		https://glassfish.dev.java.net/public/downloadsindex.html
		- i used cluster enabled installation, but I don't use this feature right now
		- note: download the file to /usr/java/, so that installation will be done here
		- note: i did it as root, and then changed permissions:
			sudo java -Xmx256m -jar glassfish-installer-v2-b41d.jar
			sudo chmod -R 775 glassfish
			sudo chown -R federico glassfish
			sudo chgrp -R federico glassfish
			cd glassfish
			chmod -R +x lib/ant/bin
			lib/ant/bin/ant -f setup-cluster.xml
	- add the /usr/java/glassfish/bin/ directory to the PATH environment variable
		sudo scite /home/federico/.bashrc
		- add the line:
			export PATH=$PATH:"/usr/java/glassfish/bin/"
			- then apply changes with
				source .bashrc
	- start application server (via: https://glassfish.dev.java.net/downloads/quickstart/index.html)
		asadmin start-domain domain1
	- test
		http://localhost:4848
			user: admin
			pw: adminadmin
			- remember to change pw!
		http://localhost:8080
		https://localhost:8181
	- deploy a test application
		- Download hello.war from http://glassfish.dev.java.net/downloads/quickstart/hello.war
		mv /home/federico/Desktop/hello.war /usr/java/glassfish/domains/domain1/autodeploy/.
		- test it:
		http://localhost:8080/hello/
	- to stop server:
		asadmin stop-domain