Version 1.1.0 Released on December 16, 2024

Nailgun Quick Start

Source Background Quick Start Protocol Changelog License JavaDocs

1. Make sure your classpath includes nailgun-server-0.9.1.jar and any class(es) you want Nailgun to run. All your classes need is a standard main(String[]) method. You can also use the examples provided in the nailgun-examples-0.9.1.jar file.
2. Launch the Nailgun server with java com.martiansoftware.nailgun.NGServer. If you just want to run the examples, go into the nailgun-examples directory and type mvn exec:java -Dexec.mainClass=com.martiansoftware.nailgun.NGServer.
3. From another command line session, run your class from the nailgun client with ng com.yourdomain.yourpackage.YourClass. If your class expects command line arguments, go ahead and include them after the classname.

That's it.

To shut down the server, use the ng client again. The command is ng ng-stop. Some statistics will be displayed when Nailgun shuts down.

Aliases

You can avoid a lot of typing by defining aliases for your classnames. Make sure the Nailgun server is still running, and set an alias via ng ng-alias (aliasName) (aliasClass). Replace (aliasName) with a short name of your choosing, and (aliasClass) with the fully qualified classname of your class. You can have multiple aliases for the same class. See the Stack example to see why this can be useful.

To see what aliases are currently defined, use ng ng-alias with no arguments.

Symbolic Links

If you find that aliases still require too much typing, you can create a symbolic link for the ng client. The name you give the link will be interpreted as the command or classname. You can use either an alias or a fully qualified classname for your symlink.

Nails

For MUCH greater functionality, you can provide an additional method in your class:

public static void nailMain(NGContext context) {
    // ...
}

If you provide such a method, congratulations. You've written a Nail. The context provides a great deal of information about the connection, including the client's environment variables, working directory, IP address, and lots more - including the command that was issued by the client (remember what I said above about multiple aliases pointing to the same class? Look at the Stack example to see how you can take advantage of this). For more details, see the JavaDocs.

If your class happens to provide both nailMain and main, nailMain will be called by the Nailgun server.

Overriding Defaults

By default, the Nailgun server listens on port 2113, and the client connects to localhost on that same port.

To run the server on a different port, include the port as an argument when you launch the server. That is, to run the server on port 8765, launch Nailgun with java -server com.martiansoftware.nailgun.NGServer 8765.

To bind the server to a specific address, specify the address as an argument when you launch the server. That is, to run the server only on the loopback address, launch Nailgun with java -server com.martiansoftware.nailgun.NGServer 127.0.0.1.

To combine the above options, specify both separated by a colon. That is, to run the server only on the loopback address on port 8765, launch Nailgun with java -server com.martiansoftware.nailgun.NGServer 127.0.0.1:8765.

Specify port 0 to have NGServer select a port automatically. The selected port number will be displayed on System.out.

The client presents a couple more options. First, the server and port can be individually set via the NAILGUN_SERVER and NAILGUN_PORT environment variables.

Both the defaults and the environment variables can be overridden via command line arguments to the ng client. The arguments are --nailgun-server and --nailgun-port, and they can be placed anywhere on the ng command line. They will not be passed as command line arguments to your Nails. So to shutdown the server you just started on port 8765, issue the command ng --nailgun-port 8765 ng-stop or ng ng-stop --nailgun-port 8765.

Embedding Nailgun

You don't have to run Nailgun as a standalone server; it's very easy to create an NGServer object and start it within your own application in order to provide command-line interaction with your running app. See the JavaDocs for more details.

Built-in Nails

Nailgun comes with a few basic nails that help run the server. These nails are not robust if you specify invalid arguments, and their usage, or even existence, may change in the future. These nails have aliases by default.

• ng-alias (com.martiansoftware.nailgun.builtins.NGAlias) — When called with no arguments, displays Nailgun's current aliases. When called with two arguments, the first argument becomes an alias for the fully-qualified classname specified in the second argument.
• ng-cp (com.martiansoftware.nailgun.builtins.NGClasspath) — When called with no arguments, displays the system classpath. When called with one or more arguments, each argument is resolved by the server to a local file or directory and added to the server's classpath.
• ng-stats (com.martiansoftware.nailgun.builtins.NGServerStats) — Displays nail statistics, including the fully-qualified classname, the number of times that class has run in the current server, and the number of instances currently running in the server.
• ng-stop (com.martiansoftware.nailgun.builtins.NGStop) — Shuts down the server, displaying ng-stats-style server statistics to the server's System.out.
• ng-version (com.martiansoftware.nailgun.builtins.NGVersion) — Displays the server version number.

Example Nails

No aliases are created for these nails by default, and they are not included in the regular nailgun .jar file. To use these examples, be sure to include the nailgun-examples-VERSION.jar file in your server's classpath.

• com.martiansoftware.nailgun.examples.Exit — If you provide any command line arguments, the first argument is converted to an exit code and passed to System.exit() by the nail. The server traps this and instructs the client to exit with the specified code. If no (or non-numeric) arguments are supplied, a nonzero exit code is chosen at random.
• com.martiansoftware.nailgun.examples.DumpAll (was: DumpArgs) — displays all information available from the NGContext (command line arguments, client environment, etc.) and exits.
• com.martiansoftware.nailgun.examples.Echo — copies stdin to stdout. Basically a no-op. Running cat file1 | ng com.martiansoftware.nailgun.examples.Echo > file2 should create a new file, file2, that is identical to file1.
• com.martiansoftware.nailgun.examples.Hash — when called with no arguments, displays a list of available hash functions. When called with a single argument specifying one of those hash functions, this nail hashes stdin using the specified function, and displays the result as a hexadecimal string to stdout.
• com.martiansoftware.nailgun.examples.HelloWorld — displays a friendly greeting.
• com.martiansoftware.nailgun.examples.Prompt — presents the user with a JOptionPane requesting user input. If the user clicks "Cancel", the client exits with exit code 1. Otherwise, the user's input is printed to stdout. Try calling this nail more than once in a running server and observe the speed difference between the first and second calls - the JVM had to start the AWT/Swing subsystems the first time, but not the second.
• com.martiansoftware.nailgun.examples.Stack — in order to work properly, this class must have the aliases "push" and "pop" associated with it. With these aliases set, "ng push arg1 [arg2 ...]" will push the specified arguments onto a stack. "ng pop" will pop a single item from the stack and write it to stdout. If nothing is on the stack, this will block until something is pushed or the server is shut down (in which case it will exit with exit code 1). Note that this is thread-safe; you can have multiple processes blocking on a "pop" and only one (determined by the JVM) will receive the next item pushed.
• com.martiansoftware.nailgun.examples.ThreadTest — this is just a silly program to make sure that any child threads spawned by a nail properly inherit stdin/stdout/stderr from their parent.