Usage

Remote Machine (Raspberry Pi or Headless Remote Server)

On remote machine start the agent with:

java -jar remotevmlauncher-agent.jar

from any directory you would like cache directory to be created in. Home directory is ideal place. If no "--listen" option is specified it will listen on default 0.0.0.0 address on port 8999. For more details you can always used --help:

$ java -jar remotevmlauncher-agent.jar --help
Remote VM Launch Agent usage:

java -jar remotevmlauncher-agent.jar {options}

Options:

  -l|--listen [address:]port  listen on defined address and port. Default: 0.0.0.0:8999
  -e|--executable path        path to java executable. Default: java (it must be in path)
  -d|--debug level            debug level from 0 to 4. Default: 1
  -h|--help                   this help.

The latest version of the agent can be downloaded from here or check downloads agent section.

Development Machine (The Client)

New, remote JVMs can be started from the development machine (the client) by adding client jar to launcher's classpath and invoking org.ah.java.remotevmlauncher.client.LaunchRemote main class, passing remote machine's address and port (8999), application's main class name and application's arguments.

First argument of org.ah.java.remotevmlauncher.client.LaunchRemote is remote machine's address and port. The agent must be already running on that machine. Default port value is 8999.

Second argument is your application's main class.

Following is "--" and then all are passed and your application's arguments.

Classpath of JVM running org.ah.java.remotevmlauncher.client.LaunchRemote is going to be pushed to the remote machine (through the agent) - so if your application's classpath is needed to be defined as you would normally as org.ah.java.remotevmlauncher.client.LaunchRemote will read it of parent URLClassLoader.

If there is anything specially to be added to the classpath on the remote machine, that portion of the classpath can be set through "--remote-classpath" (or "-rcp") options of org.ah.java.remotevmlauncher.client.LaunchRemote. Those options are to be specified before any arguments. Each "--remote-classpath" (or "-rcp") option represents only one classpath segment, so if you need more then use that option as many times you need it.

Development Machine (The Client)

If you need to debug your remote application, you can use "--remote-debug-port" (or "-rdp") argument. WHen port is specified, remote JVM is going to be started with

-Xdebug -Xrunjdwp:transport=dt_socket,server=y,suspend=(y|n),address=<port>

where "suspend" is set to "y" if you specify "--remote-debug-suspend" (or "-rds") option (alternatively it will stay "n"). So, for example, your set of arguments passed to org.ah.java.remotevmlauncher.client.LaunchRemote, if you want remote JVM to be started in suspended debug mode, on port 5001 could look like:

<remote-machine-ip-or-hostname>:8999
<your-main-class-name>
--remote-debug-port 5001
--remote-debug-suspend
--
arg1
arg2
arg3

Development (Eclipse) Launcher Example

For example in Eclipse, create new launcher for main class org.ah.pi.test.Clock which is going to display temperature using "/sys/bus/w1/devices/28-000004d41cd5/w1_slave" (argument passed to the main class), on machine with hostname "pi2" of default port of 8999:

Set arguments:

And add remote launcher jar:

Note: Project clock, in this case, has all needed dependencies in the classpath (pi4j for instance) and they are, in this case, passed from development machine to the Raspberry Pi. That included all the native jars and .so libraries (included in pi4j project). To achieve that I needed to copy portion of pi4j .m2/repository dir to my development machine's .m2/repository.

Development (Remote Launcher's Help)

For more details you can always used --help:

$ java -jar remotevmlauncher-client/target/remotevmlauncher-client.jar --help
Remote VM Launcher usage:

java -jar remotevmlauncher-client.jar {options} [address:]port mainClass

Options:

  -rcp|--remote-classpath classpath-entry
                      classpath entry as seen from remote machine
                      where agent is running.
  -ecp|--exclude-classpath classpath-entry");
                      classpath entry not to be send to the remote
                      machine where agent is running.
  -d|--debug level    debug level from 0 to 4. Default: 0
  -rdp|--remote-debug-port port
                      If port is specified remote VM will be launched
                      in debug mode at the specified port.
  -rds|--remote-debug-suspend
                      If port is specified and if this flag as well
                      remote VM will be suspended.
  -h|--help           this help.

If launcher is used from an IDE, and
   org.ah.java.remotevmlauncher.client.LaunchRemote class is directly used as
main class, then supplied classpath will automatically used (provided that it
is defined as URLClassLoader or descendant class) on the remote side.

Note: if remote debug port is specified launcher's VM is started with:
-Xdebug -Xrunjdwp:transport=dt_socket,server=y,suspend=(y|n),address=<port>
depending on port and if suspend is specified or not.

The lastest version of the client or remote launcher can be downloaded from here or remote launcher section of downloads.