user/src/com/google/gwt/junit/remote/BrowserManagerServer.java - gwt - Git at Google

 /*
  * Copyright 2008 Google Inc.
  *
  * Licensed under the Apache License, Version 2.0 (the "License"); you may not
  * use this file except in compliance with the License. You may obtain a copy of
  * the License at
  *
  * http://www.apache.org/licenses/LICENSE-2.0
  *
  * Unless required by applicable law or agreed to in writing, software
  * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
  * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
  * License for the specific language governing permissions and limitations under
  * the License.
  */
 package com.google.gwt.junit.remote;

 import com.google.gwt.junit.remote.BrowserManagerProcess.ProcessExitCb;

 import java.io.IOException;
 import java.rmi.RemoteException;
 import java.rmi.server.UnicastRemoteObject;
 import java.util.HashMap;
 import java.util.LinkedList;
 import java.util.Map;
 import java.util.Queue;
 import java.util.StringTokenizer;
 import java.util.Timer;
 import java.util.logging.Level;
 import java.util.logging.Logger;

 /**
  * Manages instances of a web browser as child processes. This class is
  * experimental and unsupported. An instance of this class can create browser
  * windows using one specific shell-level command. It performs process
  * management (baby sitting) on behalf of a remote client. This can be useful
  * for running a GWTTestCase on a browser that cannot be run on the native
  * platform. For example, a GWTTestCase test running on Linux could use a remote
  * call to a Windows machine to test with Internet Explorer.
  *
  * <p>
  * Calling {@link #main(String[])} can instantiate and register multiple
  * instances of this class at given RMI namespace locations.
  * </p>
  *
  * <p>
  * This system has been tested on Internet Explorer 6 & 7. Firefox does not work
  * in the general case; if an existing Firefox process is already running, new
  * processes simply delegate to the existing process and terminate, which breaks
  * the model. A shell script that sets MOZNOREMOTE=1 and cleans up
  * locks/sessions is needed. Safari on MacOS requires very special treatment
  * given Safari's poor command line support, but that is beyond the scope of
  * this documentation.
  * </p>
  *
  * <p>
  * TODO(scottb): We technically need a watchdog thread to slurp up stdout and
  * stderr from the child processes, or they might block. However, most browsers
  * never write to stdout and stderr, so this is low priority. (There is now a
  * thread that is spawned for each task to wait for an exit value - this might
  * be adapted for that purpose one day.)
  * </p>
  *
  * <p>
  * This class is not actually serializable as-is, because timer is not
  * serializable.
  * </p>
  *
  * see http://bugs.sun.com/bugdatabase/view_bug.do;:YfiG?bug_id=4062587
  */
 public class BrowserManagerServer extends UnicastRemoteObject implements
     BrowserManager {

   /**
    * Implementation notes: <code>processByToken</code> must be locked before
    * performing any state-changing operations.
    */

   /**
    * Entry in the launchCommandQueue to use when tasks are serialized.
    */
   private static class LaunchCommand {
     long keepAliveMsecs;
     int token;
     String url;

     LaunchCommand(int tokenIn) {
       this(tokenIn, null, 0);
     }

     LaunchCommand(int tokenIn, String urlIn, long keepAliveMsecsIn) {
       token = tokenIn;
       url = urlIn;
       keepAliveMsecs = keepAliveMsecsIn;
     }

     @Override
     public boolean equals(Object obj) {
       if (obj instanceof LaunchCommand && ((LaunchCommand) obj).token == token) {
         return true;
       }
       return false;
     }

     @Override
     public int hashCode() {
       return token;
     }
   }

   private static final Logger logger = Logger.getLogger(BrowserManagerServer.class.getName());

   /**
    * Starts up and registers one or more browser servers. Command-line entry
    * point.
    */
   public static void main(String[] args) throws Exception {

     // Startup logic has been delegated to BrowserManagerServerLauncher
     // class to facilitate use of the ToolBase class for
     // argument handling.
     BrowserManagerServerLauncher serverMain = new BrowserManagerServerLauncher();
     if (serverMain.doProcessArgs(args)) {
       serverMain.run();
     }
   }

   /**
    * Receives an event when a child process exits.
    */
   private final ProcessExitCb childExitCallback = new ProcessExitCb() {
     /**
      * Called back from BrowserManagerProcess in a DIFFERENT THREAD than the
      * main thread.
      *
      * @param token token value of browser that exited.
      * @param exitValue exit status of the browser.
      */
     public void childExited(int token, int exitValue) {
       synchronized (processByToken) {
         processByToken.remove(token);
         // Start up any commands that were delayed.
         launchDelayedCommand();
       }
     }
   };

   /**
    * The shell command to launch when a new browser is requested.
    */
   private final String launchCmd;

   /**
    * A queue of delayed commands. This is used if the serialized option is
    * turned on.
    */
   private Queue<LaunchCommand> launchCommandQueue = new LinkedList<LaunchCommand>();

   /**
    * The next token that will be returned from
    * {@link #launchNewBrowser(String, long)}.
    */
   private int nextToken = 1;

   /**
    * Master map of tokens onto ProcessManagers managing live processes. Also
    * serves as a lock that must be held before any state-changing operations on
    * this class may be performed.
    */
   private final Map<Integer, BrowserManagerProcess> processByToken = new HashMap<Integer, BrowserManagerProcess>();

   /**
    * Flag that is set if the serialized option is turned on.
    */
   private final boolean serializeFlag;

   /**
    * A single shared Timer used by all instances of
    * {@link BrowserManagerProcess}.
    */
   private final Timer timer = new Timer();

   /**
    * Constructs a manager for a particular shell command. The specified launch
    * command should be a path to a browser's executable, suitable for passing to
    * {@link Runtime#exec(java.lang.String)}. It may also include newline
    * delimited arguments to pass to that executable. The invoked process must
    * accept a URL as the final command line argument.
    *
    * @param launchCmd a command to launch a browser executable
    * @param serializeFlag if <code>true</code>, serialize instance of browser
    *          processes to only run one at a time
    */
   BrowserManagerServer(String launchCmd, boolean serializeFlag)
       throws RemoteException {
     // TODO: It would be nice to test to see if this file exists, but
     // currently this mechanism allows you to pass in command line arguments
     // and it will be a pain to accommodate this.
     this.launchCmd = launchCmd;
     this.serializeFlag = serializeFlag;
   }

   /**
    * @see BrowserManager#keepAlive(int, long)
    */
   public void keepAlive(int token, long keepAliveMs) {

     if (keepAliveMs <= 0) {
       throw new IllegalArgumentException();
     }

     synchronized (processByToken) {
       // Is the token one we've issued?
       if (token < 0 || token >= nextToken) {
         throw new IllegalArgumentException();
       }
       BrowserManagerProcess process = processByToken.get(token);
       if (process != null) {
         if (process.keepAlive(keepAliveMs)) {
           // The process was successfully kept alive.
           return;
         }
       } else if (launchCommandQueue.contains(new LaunchCommand(token))) {
         // Nothing to do, the command hasn't started yet.
         return;
       }

       // The process is already dead. Fall through to failure.
     }

     throw new IllegalStateException("Process " + token + " already dead");
   }

   /**
    * @see BrowserManager#killBrowser(int)
    */
   public void killBrowser(int token) {

     synchronized (processByToken) {
       // Is the token one we've issued?
       if (token < 0 || token >= nextToken) {
         throw new IllegalArgumentException();
       }
       BrowserManagerProcess process = processByToken.get(token);
       if (process != null) {
         logger.info("Client kill for active browser: " + token);
         process.killBrowser();
       } else if (launchCommandQueue.contains(new LaunchCommand(token))) {
         launchCommandQueue.remove(new LaunchCommand(token));
         logger.info("Client kill for waiting browser: " + token);
       } else {
         logger.info("Client kill for inactive browser: " + token);
       }
     }
   }

   /**
    * @see BrowserManager#launchNewBrowser(java.lang.String, long)
    */
   public int launchNewBrowser(String url, long keepAliveMs) {
     logger.info("Launching browser for url: " + url + " keepAliveMs: "
         + keepAliveMs);
     if (url == null || keepAliveMs <= 0) {
       throw new IllegalArgumentException();
     }

     try {
       synchronized (processByToken) {
         int myToken = nextToken++;
         // Adds self to processByToken.

         if (serializeFlag && !processByToken.isEmpty()) {
           // Queue up a launch request if one is already running.
           launchCommandQueue.add(new LaunchCommand(myToken, url, keepAliveMs));
           logger.info("Queuing up request token: " + myToken + " for url: "
               + url + ".  Another launch command is active.");
         } else {
           execChild(myToken, url, keepAliveMs);
         }
         return myToken;
       }
     } catch (IOException e) {
       logger.log(Level.SEVERE, "Error launching browser '" + launchCmd
           + "' for '" + url + "'", e);
       throw new RuntimeException("Error launching browser '" + launchCmd
           + "' for '" + url + "'", e);
     }
   }

   /**
    * This method is mainly in place for writing assertions in the unit test.
    *
    * @return number of tasks waiting to run if serialized option is enabled
    */
   int numQueued() {
     synchronized (processByToken) {
       return launchCommandQueue.size();
     }
   }

   /**
    * This method is mainly in place for writing assertions in the unit test.
    *
    * @return number of launch commands running that have not yet exited.
    */
   int numRunning() {
     synchronized (processByToken) {
       return processByToken.size();
     }
   }

   /**
    * Actually create a process and run a browser.
    *
    * (Assumes that code is already synchronized by processBytoken)
    *
    * @param token token value of browser that exited.
    * @param url command line arguments to pass to the browser
    * @param keepAliveMs inital keep alive interval in milliseconds
    */
   private void execChild(int token, String url, long keepAliveMs)
       throws IOException {
     // Tokenize the launchCmd by carriage returns (used for unit testing).
     StringTokenizer st = new StringTokenizer(launchCmd, "\n");
     int userTokens = st.countTokens();
     String[] cmdarray = new String[userTokens + 1];
     for (int i = 0; st.hasMoreTokens(); i++) {
       cmdarray[i] = st.nextToken();
     }
     // Append the user-specified URL.
     cmdarray[userTokens] = url;

     // Start the task.
     Process child = Runtime.getRuntime().exec(cmdarray);

     BrowserManagerProcess bmp = new BrowserManagerProcess(childExitCallback,
         timer, token, child, keepAliveMs);
     processByToken.put(token, bmp);
   }

   /**
    * If serialization is enabled on the server, kicks off the next queued
    * command on the delayed command queue.
    *
    * (Assumes that code is already synchronized by processBytoken)
    */
   private void launchDelayedCommand() {
     if (!serializeFlag || !processByToken.isEmpty()) {
       // No need to launch if serialization is off or
       // something is already running
       return;
     }

     // Loop through the commands until we can launch one
     // successfully.
     while (!launchCommandQueue.isEmpty()) {
       LaunchCommand lc = launchCommandQueue.remove();
       try {
         execChild(lc.token, lc.url, lc.keepAliveMsecs);
         // No exception? Great!
         logger.info("Started delayed browser: " + lc.token);
         return;

       } catch (IOException e) {
         logger.log(Level.SEVERE, "Error launching browser '" + launchCmd
             + "' for '" + lc.url + "'", e);
         throw new RuntimeException("Error launching browser '" + launchCmd
             + "' for '" + lc.url + "'", e);
       }
       // If an exception occurred, keep pulling cmds off the queue.
     }
   }
 }
	/*
	* Copyright 2008 Google Inc.
	*
	* Licensed under the Apache License, Version 2.0 (the "License"); you may not
	* use this file except in compliance with the License. You may obtain a copy of
	* the License at
	*
	* http://www.apache.org/licenses/LICENSE-2.0
	*
	* Unless required by applicable law or agreed to in writing, software
	* distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
	* WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
	* License for the specific language governing permissions and limitations under
	* the License.
	*/
	package com.google.gwt.junit.remote;

	import com.google.gwt.junit.remote.BrowserManagerProcess.ProcessExitCb;

	import java.io.IOException;
	import java.rmi.RemoteException;
	import java.rmi.server.UnicastRemoteObject;
	import java.util.HashMap;
	import java.util.LinkedList;
	import java.util.Map;
	import java.util.Queue;
	import java.util.StringTokenizer;
	import java.util.Timer;
	import java.util.logging.Level;
	import java.util.logging.Logger;

	/**
	* Manages instances of a web browser as child processes. This class is
	* experimental and unsupported. An instance of this class can create browser
	* windows using one specific shell-level command. It performs process
	* management (baby sitting) on behalf of a remote client. This can be useful
	* for running a GWTTestCase on a browser that cannot be run on the native
	* platform. For example, a GWTTestCase test running on Linux could use a remote
	* call to a Windows machine to test with Internet Explorer.
	*
	* <p>
	* Calling {@link #main(String[])} can instantiate and register multiple
	* instances of this class at given RMI namespace locations.
	* </p>
	*
	* <p>
	* This system has been tested on Internet Explorer 6 & 7. Firefox does not work
	* in the general case; if an existing Firefox process is already running, new
	* processes simply delegate to the existing process and terminate, which breaks
	* the model. A shell script that sets MOZNOREMOTE=1 and cleans up
	* locks/sessions is needed. Safari on MacOS requires very special treatment
	* given Safari's poor command line support, but that is beyond the scope of
	* this documentation.
	* </p>
	*
	* <p>
	* TODO(scottb): We technically need a watchdog thread to slurp up stdout and
	* stderr from the child processes, or they might block. However, most browsers
	* never write to stdout and stderr, so this is low priority. (There is now a
	* thread that is spawned for each task to wait for an exit value - this might
	* be adapted for that purpose one day.)
	* </p>
	*
	* <p>
	* This class is not actually serializable as-is, because timer is not
	* serializable.
	* </p>
	*
	* see http://bugs.sun.com/bugdatabase/view_bug.do;:YfiG?bug_id=4062587
	*/
	public class BrowserManagerServer extends UnicastRemoteObject implements
	BrowserManager {

	/**
	* Implementation notes: <code>processByToken</code> must be locked before
	* performing any state-changing operations.
	*/

	/**
	* Entry in the launchCommandQueue to use when tasks are serialized.
	*/
	private static class LaunchCommand {
	long keepAliveMsecs;
	int token;
	String url;

	LaunchCommand(int tokenIn) {
	this(tokenIn, null, 0);
	}

	LaunchCommand(int tokenIn, String urlIn, long keepAliveMsecsIn) {
	token = tokenIn;
	url = urlIn;
	keepAliveMsecs = keepAliveMsecsIn;
	}

	@Override
	public boolean equals(Object obj) {
	if (obj instanceof LaunchCommand && ((LaunchCommand) obj).token == token) {
	return true;
	}
	return false;
	}

	@Override
	public int hashCode() {
	return token;
	}
	}

	private static final Logger logger = Logger.getLogger(BrowserManagerServer.class.getName());

	/**
	* Starts up and registers one or more browser servers. Command-line entry
	* point.
	*/
	public static void main(String[] args) throws Exception {

	// Startup logic has been delegated to BrowserManagerServerLauncher
	// class to facilitate use of the ToolBase class for
	// argument handling.
	BrowserManagerServerLauncher serverMain = new BrowserManagerServerLauncher();
	if (serverMain.doProcessArgs(args)) {
	serverMain.run();
	}
	}

	/**
	* Receives an event when a child process exits.
	*/
	private final ProcessExitCb childExitCallback = new ProcessExitCb() {
	/**
	* Called back from BrowserManagerProcess in a DIFFERENT THREAD than the
	* main thread.
	*
	* @param token token value of browser that exited.
	* @param exitValue exit status of the browser.
	*/
	public void childExited(int token, int exitValue) {
	synchronized (processByToken) {
	processByToken.remove(token);
	// Start up any commands that were delayed.
	launchDelayedCommand();
	}
	}
	};

	/**
	* The shell command to launch when a new browser is requested.
	*/
	private final String launchCmd;

	/**
	* A queue of delayed commands. This is used if the serialized option is
	* turned on.
	*/
	private Queue<LaunchCommand> launchCommandQueue = new LinkedList<LaunchCommand>();

	/**
	* The next token that will be returned from
	* {@link #launchNewBrowser(String, long)}.
	*/
	private int nextToken = 1;

	/**
	* Master map of tokens onto ProcessManagers managing live processes. Also
	* serves as a lock that must be held before any state-changing operations on
	* this class may be performed.
	*/
	private final Map<Integer, BrowserManagerProcess> processByToken = new HashMap<Integer, BrowserManagerProcess>();

	/**
	* Flag that is set if the serialized option is turned on.
	*/
	private final boolean serializeFlag;

	/**
	* A single shared Timer used by all instances of
	* {@link BrowserManagerProcess}.
	*/
	private final Timer timer = new Timer();

	/**
	* Constructs a manager for a particular shell command. The specified launch
	* command should be a path to a browser's executable, suitable for passing to
	* {@link Runtime#exec(java.lang.String)}. It may also include newline
	* delimited arguments to pass to that executable. The invoked process must
	* accept a URL as the final command line argument.
	*
	* @param launchCmd a command to launch a browser executable
	* @param serializeFlag if <code>true</code>, serialize instance of browser
	* processes to only run one at a time
	*/
	BrowserManagerServer(String launchCmd, boolean serializeFlag)
	throws RemoteException {
	// TODO: It would be nice to test to see if this file exists, but
	// currently this mechanism allows you to pass in command line arguments
	// and it will be a pain to accommodate this.
	this.launchCmd = launchCmd;
	this.serializeFlag = serializeFlag;
	}

	/**
	* @see BrowserManager#keepAlive(int, long)
	*/
	public void keepAlive(int token, long keepAliveMs) {

	if (keepAliveMs <= 0) {
	throw new IllegalArgumentException();
	}

	synchronized (processByToken) {
	// Is the token one we've issued?
	if (token < 0 \|\| token >= nextToken) {
	throw new IllegalArgumentException();
	}
	BrowserManagerProcess process = processByToken.get(token);
	if (process != null) {
	if (process.keepAlive(keepAliveMs)) {
	// The process was successfully kept alive.
	return;
	}
	} else if (launchCommandQueue.contains(new LaunchCommand(token))) {
	// Nothing to do, the command hasn't started yet.
	return;
	}

	// The process is already dead. Fall through to failure.
	}

	throw new IllegalStateException("Process " + token + " already dead");
	}

	/**
	* @see BrowserManager#killBrowser(int)
	*/
	public void killBrowser(int token) {

	synchronized (processByToken) {
	// Is the token one we've issued?
	if (token < 0 \|\| token >= nextToken) {
	throw new IllegalArgumentException();
	}
	BrowserManagerProcess process = processByToken.get(token);
	if (process != null) {
	logger.info("Client kill for active browser: " + token);
	process.killBrowser();
	} else if (launchCommandQueue.contains(new LaunchCommand(token))) {
	launchCommandQueue.remove(new LaunchCommand(token));
	logger.info("Client kill for waiting browser: " + token);
	} else {
	logger.info("Client kill for inactive browser: " + token);
	}
	}
	}

	/**
	* @see BrowserManager#launchNewBrowser(java.lang.String, long)
	*/
	public int launchNewBrowser(String url, long keepAliveMs) {
	logger.info("Launching browser for url: " + url + " keepAliveMs: "
	+ keepAliveMs);
	if (url == null \|\| keepAliveMs <= 0) {
	throw new IllegalArgumentException();
	}

	try {
	synchronized (processByToken) {
	int myToken = nextToken++;
	// Adds self to processByToken.

	if (serializeFlag && !processByToken.isEmpty()) {
	// Queue up a launch request if one is already running.
	launchCommandQueue.add(new LaunchCommand(myToken, url, keepAliveMs));
	logger.info("Queuing up request token: " + myToken + " for url: "
	+ url + ". Another launch command is active.");
	} else {
	execChild(myToken, url, keepAliveMs);
	}
	return myToken;
	}
	} catch (IOException e) {
	logger.log(Level.SEVERE, "Error launching browser '" + launchCmd
	+ "' for '" + url + "'", e);
	throw new RuntimeException("Error launching browser '" + launchCmd
	+ "' for '" + url + "'", e);
	}
	}

	/**
	* This method is mainly in place for writing assertions in the unit test.
	*
	* @return number of tasks waiting to run if serialized option is enabled
	*/
	int numQueued() {
	synchronized (processByToken) {
	return launchCommandQueue.size();
	}
	}

	/**
	* This method is mainly in place for writing assertions in the unit test.
	*
	* @return number of launch commands running that have not yet exited.
	*/
	int numRunning() {
	synchronized (processByToken) {
	return processByToken.size();
	}
	}

	/**
	* Actually create a process and run a browser.
	*
	* (Assumes that code is already synchronized by processBytoken)
	*
	* @param token token value of browser that exited.
	* @param url command line arguments to pass to the browser
	* @param keepAliveMs inital keep alive interval in milliseconds
	*/
	private void execChild(int token, String url, long keepAliveMs)
	throws IOException {
	// Tokenize the launchCmd by carriage returns (used for unit testing).
	StringTokenizer st = new StringTokenizer(launchCmd, "\n");
	int userTokens = st.countTokens();
	String[] cmdarray = new String[userTokens + 1];
	for (int i = 0; st.hasMoreTokens(); i++) {
	cmdarray[i] = st.nextToken();
	}
	// Append the user-specified URL.
	cmdarray[userTokens] = url;

	// Start the task.
	Process child = Runtime.getRuntime().exec(cmdarray);

	BrowserManagerProcess bmp = new BrowserManagerProcess(childExitCallback,
	timer, token, child, keepAliveMs);
	processByToken.put(token, bmp);
	}

	/**
	* If serialization is enabled on the server, kicks off the next queued
	* command on the delayed command queue.
	*
	* (Assumes that code is already synchronized by processBytoken)
	*/
	private void launchDelayedCommand() {
	if (!serializeFlag \|\| !processByToken.isEmpty()) {
	// No need to launch if serialization is off or
	// something is already running
	return;
	}

	// Loop through the commands until we can launch one
	// successfully.
	while (!launchCommandQueue.isEmpty()) {
	LaunchCommand lc = launchCommandQueue.remove();
	try {
	execChild(lc.token, lc.url, lc.keepAliveMsecs);
	// No exception? Great!
	logger.info("Started delayed browser: " + lc.token);
	return;

	} catch (IOException e) {
	logger.log(Level.SEVERE, "Error launching browser '" + launchCmd
	+ "' for '" + lc.url + "'", e);
	throw new RuntimeException("Error launching browser '" + launchCmd
	+ "' for '" + lc.url + "'", e);
	}
	// If an exception occurred, keep pulling cmds off the queue.
	}
	}
	}