ExCom

ExCom, short for External Communication, allows you to send commands from the command-line to your running application. ExCom is a small Java class (a runnable Jar file, “sender”) that you run whenever you need to send a command to your application. Your application needs to include the ExCom “receiver”. The receiver accepts the commands from the ExCom sender and processes them. Since the receiver runs within you application it can access all of your application’s classes and resources.

ExCom doesn’t know anything specific about your application unless you tell it. You do this by creating “command” classes that perform a specific function that you want to expose to the ExCom command-line sender. You then register each of these command classes with the ExCom receiver. Registering allows you to give the command a name (for the ExCom sender menu).

One of the frequent commands you might ask ExCom sender to do is “help”. This returns a list of the commands that you previously registered with the ExCom receiver.

> xc help
=========================================================
Help Table of Contents  (case does not matter)
=========================================================
Dump                - Stack trace
Echo                - Echo to log
GC                  - Garbage Collection
Kill                - Application Shutdown
=========================================================

The listed commands are some of the provided, standard, commands in ExCom. You can also ask for help on any one of the commands.

> xc help dump
=========================================================
Help for "dump"
=========================================================
Dump

  [-m --matches]

    Java Patterns anded together that compare to the Thread header only.
    none or at least 1
    isCaseSensitive

  [-v --invertMatches]

    Inverts the selection based on -m.  Only valid with -m
=========================================================

And ultimately, you would actually execute the “dump” command by leaving the word “help” off the command-line. In this case we are asking for only the threads that have “system” in the name.

> xc dump --matches system
2 system:Reference Handler WAITING
        java.lang.Object.wait(Native Method)
        java.lang.Object.wait(Object.java:502)
        java.lang.ref.Reference$ReferenceHandler.run(Reference.java:133)
4 system:Signal Dispatcher RUNNABLE
3 system:Finalizer WAITING
        java.lang.Object.wait(Native Method)
        java.lang.ref.ReferenceQueue.remove(ReferenceQueue.java:133)
        java.lang.ref.ReferenceQueue.remove(ReferenceQueue.java:149)
        java.lang.ref.Finalizer$FinalizerThread.run(Finalizer.java:177)
67 system:Java2D Disposer WAITING
        java.lang.Object.wait(Native Method)
        java.lang.ref.ReferenceQueue.remove(ReferenceQueue.java:133)
        java.lang.ref.ReferenceQueue.remove(ReferenceQueue.java:149)
        sun.java2d.Disposer.run(Disposer.java:143)
        java.lang.Thread.run(Thread.java:636)
142 system:Keep-Alive-Timer TIMED_WAITING
        java.lang.Thread.sleep(Native Method)
        sun.net.www.http.KeepAliveCache.run(KeepAliveCache.java:168)
        java.lang.Thread.run(Thread.java:636)

The results of the “dump” command will vary according to your own application.

If you have this question “But why do I need this?” There are other ways to communication with my application. Read this.

Convenience script for running ExCom – xc.
Requirements for adding ExCom Receiver to your application.
Writing an ExCom command for your application.
Registering your Commands in your Application.
Registering your Commands via Spring.