org.safs.android.auto.lib

Class StartEmulator

java.lang.Object

org.safs.android.auto.lib.StartEmulator

public class StartEmulator
extends java.lang.Object

Default usage:

 new StartEmulator().run(args);
 
 The above starts a new emulator and waits up to the default  seconds detecting boot completion.
 
 Common Alternatives:

 
 StartEmulator.setBootCompletionTimeout(150);
 StartEmulator emu = new StartEmulator();
 emu.setOnlyIfRunning(true);
 emu.setDoReaperThread(false);
 emu.setDoSocketThread(false);
 emu.setDoOpenSocket(false);
 emu.setDoCloseSocket(false);
 emu.run(emulatorArgs);
 

Author:

Carl Nagle

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	EMULATOR_DESTROY_PROPERTY Set this System property "org.safs.android.start-emulator.destroy" to "true" to destroy any emulator we launched.
static java.lang.String	EMULATOR_DESTROYED_PROPERTY System property "org.safs.android.start-emulator.destroyed" is set to "true" when we have detected and attempted an emulator destroy request.
static java.lang.String	EMULATOR_WIN_EXT
static java.lang.String[]	EMULATORS

Constructor Summary

Constructors

Constructor and Description
StartEmulator()

Method Summary

Modifier and Type	Method and Description
Process2	getEmulatorProcess() Retrieve the Process2 object owning/wrapping the emulator process.
static void	main(java.lang.String[] args) This main entry point simply creates a new StartEmulator instance and passes repackaged arguments to the run(onlyIfNotRunning, args) method.
void	run(boolean onlyIfNotRunning, java.lang.String... args) The primary routine used to start an emulator.
void	run(java.lang.String... args) Simply calls run(boolean, String...) using the preset value for onlyIfNotRunning.
static void	setBootCompletionDetectedDelay(long seconds) Set the number of seconds we delay issuing boot completion detected to allow it to settle.
static void	setBootCompletionTimeout(long seconds) Set the number of seconds we watch for boot completion before timing out the watch loop.
void	setChainedStdOut(java.lang.Appendable newOut) Setan Appendable sink to receive stdOut after we are finished using the stdOut Reader to monitor the emulator for bootstrap completion.
void	setDoCloseSocket(boolean doSocket) Set/Clear the flag to Close the Socket Server connection after the Socket Thread has completed with the attempts to report the emulator serial number to some remote receiver.
void	setDoOpenSocket(boolean doSocket) Set/Clear the flag to even attempt a Socket Server connection and temporarily bind to a TCP port to report the emulator serial number.
void	setDoReaperThread(boolean doReaper) Set/Clear the flag to run a monitor "reaper" thread to kill the emulator on command.
void	setDoSocketThread(boolean doSocket) Set/Clear the flag to run a Sockets.accept() timeout thread which attempts to connect with and report the TCP Port the emulator is starting on.
void	setOnlyIfNotRunning(boolean ifNotRunning) Set/Clear the flag to only launch an emulator on run() IF there is not one already running.
void	SysOut(java.lang.String out)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

EMULATOR_DESTROY_PROPERTY

public static final java.lang.String EMULATOR_DESTROY_PROPERTY

Set this System property "org.safs.android.start-emulator.destroy" to "true" to destroy any emulator we launched.

See Also:

Constant Field Values

EMULATOR_DESTROYED_PROPERTY

public static final java.lang.String EMULATOR_DESTROYED_PROPERTY

System property "org.safs.android.start-emulator.destroyed" is set to "true" when we have detected and attempted an emulator destroy request.

See Also:

Constant Field Values

EMULATOR_WIN_EXT

public static final java.lang.String EMULATOR_WIN_EXT

See Also:

Constant Field Values

EMULATORS

public static final java.lang.String[] EMULATORS

Constructor Detail

StartEmulator

public StartEmulator()

Method Detail

main

public static void main(java.lang.String[] args)
                 throws java.io.IOException,
                        java.lang.InterruptedException

This main entry point simply creates a new StartEmulator instance and passes repackaged arguments to the run(onlyIfNotRunning, args) method.

Parameters:

args
- "--only-if-not-running" -- self explanatory.
"noreaper" -- do not run reaper thread to force emulator termination.
"nosocket" -- do not run socket thread to accept socket connections.
"noopensocket" -- do not the socket at all.
"noclosesocket" -- do not close the socket if opened.
"noboottimeout" -- do not set a timeout for boot completion.
"boottimeout <seconds> -- set boot completion timeout in seconds. Default is
all other args will be passed to the emulator instance.

Throws:

java.io.IOException

java.lang.InterruptedException

See Also:

run(boolean, String...)

setBootCompletionTimeout

public static void setBootCompletionTimeout(long seconds)

Set the number of seconds we watch for boot completion before timing out the watch loop. Default: seconds. Set 0 seconds for no timeout--wait indefinitely.

See Also:

watchLogUntilBooted()

setBootCompletionDetectedDelay

public static void setBootCompletionDetectedDelay(long seconds)

Set the number of seconds we delay issuing boot completion detected to allow it to settle. Default: seconds. Set 0 seconds for no delay.

See Also:

watchLogUntilBooted()

setOnlyIfNotRunning

public void setOnlyIfNotRunning(boolean ifNotRunning)

Set/Clear the flag to only launch an emulator on run() IF there is not one already running. This is set FALSE by default.

setDoReaperThread

public void setDoReaperThread(boolean doReaper)

Set/Clear the flag to run a monitor "reaper" thread to kill the emulator on command. This is set TRUE by default.

The reaper thread monitors Java System.getProperty("org.safs.android.start-emulator.destroy"). If this gets set to "true" then the emulator Process created/maintained here will be destroyed.

setDoSocketThread

public void setDoSocketThread(boolean doSocket)

Set/Clear the flag to run a Sockets.accept() timeout thread which attempts to connect with and report the TCP Port the emulator is starting on. This is set TRUE by default.
(I have not seen a scenario where this actually works--connecting and reporting the emulator serial number to a receiver.)

setDoOpenSocket

public void setDoOpenSocket(boolean doSocket)

Set/Clear the flag to even attempt a Socket Server connection and temporarily bind to a TCP port to report the emulator serial number. This is set TRUE by default.
(I have not seen a scenario where binding to the Socket has successfully connected to anything and it may sometimes prevent abd from "seeing" the emulator--but this is just a guess.)

setDoCloseSocket

public void setDoCloseSocket(boolean doSocket)

Set/Clear the flag to Close the Socket Server connection after the Socket Thread has completed with the attempts to report the emulator serial number to some remote receiver. This is set TRUE by default.
(I have not seen a scenario where binding to the Socket has successfully connected to anything and it may sometimes prevent abd from "seeing" the emulator--but this is just a guess.)

setChainedStdOut

public void setChainedStdOut(java.lang.Appendable newOut)

Setan Appendable sink to receive stdOut after we are finished using the stdOut Reader to monitor the emulator for bootstrap completion. If no (optional) Appendable sink is provided, the stdOut is routed to the dev/NULL sink once we are finished with it.

getEmulatorProcess

public Process2 getEmulatorProcess()

Retrieve the Process2 object owning/wrapping the emulator process. Note, at least on Windows, the emulator process spawns multiple other processes and the emulator that ultimately becomes visible is running in an entirely different process.

Thus, doing things like process.destroy() does NOT necessarily mean the emulator will actually be affected. Although, it may free up resources no longer needed (and possibly interfering with) the actual emulator and abd.

Returns:

Process2 wrapper

SysOut

public void SysOut(java.lang.String out)

run

public void run(java.lang.String... args)
         throws java.io.IOException,
                java.lang.InterruptedException

Simply calls run(boolean, String...) using the preset value for onlyIfNotRunning.

Parameters:

args - emulator program args, not StartEmulator args.

Throws:

java.io.IOException

java.lang.InterruptedException

run

public void run(boolean onlyIfNotRunning,
                java.lang.String... args)
         throws java.io.IOException,
                java.lang.InterruptedException

The primary routine used to start an emulator. The routine will exit without starting an emulator if onlyIfNotRunning=true and it detects a running emulator via adb "devices".

if doOpenSocket is true(default) it will also launch and wait for up to 30 seconds for a remote receiver to connect to the emulator remote console and receive the emulator serial number. When that time is up, the connection is closed and the port is released (in theory).

Whatever emulator args are provided this routine also adds the following args:

-logcat *:v -report-console tcp:<SocketServer port>

This routine also will block until it has detected the emulator has completed the boot process.

if doReaperThread is true(default) the routine will also spawn a separate thread to monitor the System property EMULATOR_DESTROY_PROPERTY for emulator destroy requests. However, because the actual running emulator is one or more processes removed from this process this request usually does not result in the emulator being shutdown.

Parameters:

onlyIfNotRunning -

args -

Throws:

java.io.IOException

java.lang.InterruptedException