core/org.eclipse.stem.ui.ge/doc/readme_servlet.txt - stem/org.eclipse.stem - Git at Google

 org.eclipse.stem.ge.servlet

 Overview:

 This plugin provides a servlet based interface for displaying the
 STEM map as an overlay on GoogleEarth.

 There are 2 parts.  Using the STEM GoogleEarth interface View,
 STEM can be instructed on each cycle (or on every Nth
 cycle) to write the map data to a specified directory as a KML file.

 As STEM is producing KML files or as a later step, one starts the
 process to display the STEM results on GoogleEarth.
 The Servlet interface includes a HTML file and StartServlet that will
 send a NetworkLink file to GoogleEarth that tells it to every N seconds
 to issue a request to SlideShowServlet to get the KML file for the next cycle.

 SlideShowServlet.java
   This is a Java Servlet to interface to GoogleEarth
   to display KML files generated by STEM.

 StartServlet.java
   This is a Servlet that based on user input will send a
   NetworkLink.kml file to GoogleEarth.

 ImageServlet.java
   This is a Servlet that based on user input will create an image
   file that can be sent to GoogleEarth.  The image will have
   whatever text is specified.
   This is used to display text messages on the GoogleEarth screen.

 VerifyServlet.java
   This is a servlet that is used by VerifyClient to provide
   a way for the client to verify that the web server is active
   and that the servlet interface is deployed correctly.

 VerifyClient
   This utility class holds a verify method that will try to
   access the VerifyServlet to check that it is up and running.
      String url = "http://localhost:8080/SlideShow/verify"
      VerifyClient vc = new VerifyClient();
      boolean ok = vc.verify(url)
      if (! ok) {
         System.out.println(vc.getError());
         return;
      }


 The installation of this interface involves the following:
   - Installing the TomCat web server.
   - Installing the servlets on Tomcat
   - Installing Google Earth
   - Installing and running STEM
   - Invoking the SlideShow.html

 These steps are described in detail below.


   To install this servlet so it will run on your own Windows PC,
   do the following with:
    <path>=your stem workspace folder.
    <project>=<path>.org.eclipse.stem.ge.servlet
    This is for Windows systems only at the current time.
    Linux instatallation will be documented when it is available.

   - Checkout the org.eclipse.stem projects from
       svn.opensource.ibm.com/svn/stem/trunk

   - Install Tomcat (version 5) on your Windows PC.
       http://tomcat.apache.org

      - download current 5.5 executable and invoke it.
      - Take the defaults and assign a user and password for admin.
      - After it starts, click on the Tomcat tray icon and
        specify "start service"
      - From your browser goto http://localhost:8080
        and select "Tomcat Manager" from Administration.
   -  Alternative is to use the Tomcat server embedded in Eclipse.

      The preferences for gE have a checkbox that can be set
      to use the embedded server.  This works fine for running
      GoogleEarth and STEM together but can not be used for
      offline display of STEM data.

   -  Run ant to generate a WAR file.
        cd <project>
        ant war
      This builds the war file in
        <project>/WEB-INF/SlideShow.war

   -  Use the Tomcat Manager to deploy SlideShow.war
       URL http://localhost:8080/manager/html/upload
        - click "undeploy" for existing slideshow (if present)
        - Under "WAR file to deploy"
          - browse to <project>/build/war/SlideShow.war
          - click "deploy"

   - To verify the installation, enter the following URL in your browser"
        http://localhost:8080/SlideShow/image
     You should get a small image with text "default" displayed in your browser

   -  Copy <project>slideshow.html to <Tomcat>\webapps\ROOT


   To run this servlet you need to do the following:

   - Install GoogleEarth   http://earth.google.com/
      Insure that GoogleEarth runs on your system.  There may be issues with
      firewalls or 3D video drivers that will prevent GoogleEarth from
      running.  The current version of GESlideShow runs with
      GoogleEarth V4 beta.

   - To run the existing STEM demo on HII003.almaden.ibm.com,
     select the following url.
      http://hii003.almaden.ibm.com:8080/slideshow.html
      Then press "start"
      This will run a previously generated script of the spread of
      a flu virus in the United States showing "Infectious" individuals.


   -  To create a new set of STEM/KML file you must run STEM and
      use the GoogleEarth Viewer to enable the logging of KML files
      and then run a simulation.  This will be documented elsewhere.


   -   Use the following URL to run the above slideshow eiter concurrently
       or afterwards.
        http://localhost:8080/slideshow.html
        When prompted: specify the folder that you created above.

     - An alternative is to update the <project>slideshow.kml file with
       the folder that you created above.
        http://localhost:8080/SlideShow/slideshow?folder=e:/tmp/ge

       and then launch the slideshow.kml file by doubleclicking
       on the file in FileExplorer.


   At this point, the slideshow.kml file will be read by GoogleEarth(GE)
   and it will tell GE that it should read KML files from the specified
   URL at the specified interval.
   The URL will invoke the doGet() method of SlideShowServlet which
   will send the KML files from the specified folder one by one
   based on a counter keyed by the id= parameter.

   If the "wait" option is specified as "y" then when the last KML file
   is read, rather than starting over, it will wait for more files to
   appear in the folder and show each new file as it appears.

   The above instruction assume that you are doing everything on your local system.
   Obviously, this could all run on another system by replacing the use of
   localhost with the external system name. However the folder containing
   the KML files must be accessable from the webserver perhaps via network
   sharing.  However there is a restriction.  With XP, a system service cannot
   network attached files so you need to run Tomcat as an application and not
   as a service.

 Please let me know if any of the above instructions are wrong or confusing!

 John

 jthomas@seabrightbeach.com
	org.eclipse.stem.ge.servlet

	Overview:

	This plugin provides a servlet based interface for displaying the
	STEM map as an overlay on GoogleEarth.

	There are 2 parts. Using the STEM GoogleEarth interface View,
	STEM can be instructed on each cycle (or on every Nth
	cycle) to write the map data to a specified directory as a KML file.

	As STEM is producing KML files or as a later step, one starts the
	process to display the STEM results on GoogleEarth.
	The Servlet interface includes a HTML file and StartServlet that will
	send a NetworkLink file to GoogleEarth that tells it to every N seconds
	to issue a request to SlideShowServlet to get the KML file for the next cycle.

	SlideShowServlet.java
	This is a Java Servlet to interface to GoogleEarth
	to display KML files generated by STEM.

	StartServlet.java
	This is a Servlet that based on user input will send a
	NetworkLink.kml file to GoogleEarth.

	ImageServlet.java
	This is a Servlet that based on user input will create an image
	file that can be sent to GoogleEarth. The image will have
	whatever text is specified.
	This is used to display text messages on the GoogleEarth screen.

	VerifyServlet.java
	This is a servlet that is used by VerifyClient to provide
	a way for the client to verify that the web server is active
	and that the servlet interface is deployed correctly.

	VerifyClient
	This utility class holds a verify method that will try to
	access the VerifyServlet to check that it is up and running.
	String url = "http://localhost:8080/SlideShow/verify"
	VerifyClient vc = new VerifyClient();
	boolean ok = vc.verify(url)
	if (! ok) {
	System.out.println(vc.getError());
	return;
	}



	The installation of this interface involves the following:
	- Installing the TomCat web server.
	- Installing the servlets on Tomcat
	- Installing Google Earth
	- Installing and running STEM
	- Invoking the SlideShow.html

	These steps are described in detail below.



	To install this servlet so it will run on your own Windows PC,
	do the following with:
	<path>=your stem workspace folder.
	<project>=<path>.org.eclipse.stem.ge.servlet
	This is for Windows systems only at the current time.
	Linux instatallation will be documented when it is available.

	- Checkout the org.eclipse.stem projects from
	svn.opensource.ibm.com/svn/stem/trunk

	- Install Tomcat (version 5) on your Windows PC.
	http://tomcat.apache.org

	- download current 5.5 executable and invoke it.
	- Take the defaults and assign a user and password for admin.
	- After it starts, click on the Tomcat tray icon and
	specify "start service"
	- From your browser goto http://localhost:8080
	and select "Tomcat Manager" from Administration.
	- Alternative is to use the Tomcat server embedded in Eclipse.

	The preferences for gE have a checkbox that can be set
	to use the embedded server. This works fine for running
	GoogleEarth and STEM together but can not be used for
	offline display of STEM data.

	- Run ant to generate a WAR file.
	cd <project>
	ant war
	This builds the war file in
	<project>/WEB-INF/SlideShow.war

	- Use the Tomcat Manager to deploy SlideShow.war
	URL http://localhost:8080/manager/html/upload
	- click "undeploy" for existing slideshow (if present)
	- Under "WAR file to deploy"
	- browse to <project>/build/war/SlideShow.war
	- click "deploy"

	- To verify the installation, enter the following URL in your browser"
	http://localhost:8080/SlideShow/image
	You should get a small image with text "default" displayed in your browser

	- Copy <project>slideshow.html to <Tomcat>\webapps\ROOT


	To run this servlet you need to do the following:

	- Install GoogleEarth http://earth.google.com/
	Insure that GoogleEarth runs on your system. There may be issues with
	firewalls or 3D video drivers that will prevent GoogleEarth from
	running. The current version of GESlideShow runs with
	GoogleEarth V4 beta.

	- To run the existing STEM demo on HII003.almaden.ibm.com,
	select the following url.
	http://hii003.almaden.ibm.com:8080/slideshow.html
	Then press "start"
	This will run a previously generated script of the spread of
	a flu virus in the United States showing "Infectious" individuals.


	- To create a new set of STEM/KML file you must run STEM and
	use the GoogleEarth Viewer to enable the logging of KML files
	and then run a simulation. This will be documented elsewhere.


	- Use the following URL to run the above slideshow eiter concurrently
	or afterwards.
	http://localhost:8080/slideshow.html
	When prompted: specify the folder that you created above.

	- An alternative is to update the <project>slideshow.kml file with
	the folder that you created above.
	http://localhost:8080/SlideShow/slideshow?folder=e:/tmp/ge

	and then launch the slideshow.kml file by doubleclicking
	on the file in FileExplorer.


	At this point, the slideshow.kml file will be read by GoogleEarth(GE)
	and it will tell GE that it should read KML files from the specified
	URL at the specified interval.
	The URL will invoke the doGet() method of SlideShowServlet which
	will send the KML files from the specified folder one by one
	based on a counter keyed by the id= parameter.

	If the "wait" option is specified as "y" then when the last KML file
	is read, rather than starting over, it will wait for more files to
	appear in the folder and show each new file as it appears.

	The above instruction assume that you are doing everything on your local system.
	Obviously, this could all run on another system by replacing the use of
	localhost with the external system name. However the folder containing
	the KML files must be accessable from the webserver perhaps via network
	sharing. However there is a restriction. With XP, a system service cannot
	network attached files so you need to run Tomcat as an application and not
	as a service.

	Please let me know if any of the above instructions are wrong or confusing!

	John

	jthomas@seabrightbeach.com