Remote Console, what is?

Remote Console team:   Artur Hefczyc
API documentation:   Here
WTTools site:   More WTTools

Java library for getting remote access to application during run-time. This remote access can be performed with any simple telnet application.

This library is very useful for special kind of applications. Application which runs very long and it is difficult to diagnose them. The good example may be daemon in operating system. There is no console to this application, no standard I/O. Of course it is not good practice to create system daemons in Java but there are many kinds of applications which works similary and there are similar difficulties.

Remote Console was created to get access to these applications. If you load remotecons library and inittialize socket listener your can simply run any 'telnet' like programm and connect to your software and see what is going on.
With command handler implementation you can define as many new commands as you need to perform all necessary actions.

How to use?

Simply run it: 'java -jar remotecons.jar'. ;-) No, no. Although it can be run from command line it is not designed to use it as stand alone application. Possibility for running from command line was added only for education purpose.
You should use it as library. Look below for small user/developer guide how to use it in your own application.

The simplest console initialization

RemoteServer.java is the main interface between your application and remotecons package. You can create and initialize new console server with instance of this class.

Look below for sample code. The simple code for initializing remote console server is given in main() method. If you want to start console server first without your own command handler and on default server port your code may looks like:

// Don't forget to 'import remotecons.RemoteServer;'
RemoteServer rs = new RemoteServer();
// rs.setAs_daemon(false);   // Uncomment this line if it is only code in your app.
// rs.setServer_port(2702);  // Uncomment this line to set different port number
try {
  rs.initialize(null);
} catch (IOException e) {
  e.printStackTrace();
  System.exit(1);
} // end of try-catch

Now if you run your application it will be listening on default port: 1612 and waiting for incoming connection requests. If you just created simple java class containing only above code in main() method your application will exit immediately. To prevent this uncomment line setting daemon mode to false.

Connect to console

You can run telnet and try to connect to it with command:

 $ telnet localhost 1612

Be aware of putting correct port number! Output should looks like following:

Trying 10.1.0.153...
Connected to ahe.nutech.com.pl.
Escape character is '^]'.
10.1.0.153 <<

It means that remote console is ready for receiving your commands. Don't waste your time searching how finish connection. :-) Use 'quit' command to disconnect from remote console. And note that there is another similar command 'exit' which causes killing JVM where our remote console works.

Your first command

Your first command should be 'help'. You will get information about all available commands for user which are supported by all loaded command handlers.
Output of 'help' command looks like following:

remotecons.wttools.ConnectionServer$InternalCommands >>
  echo           - switch 'echo' mode (for windows telnet is really needed)
  quit           - close connection to server
  who            - list all active connections
  close n        - close active connection number 'n'
  help [command] - display this message info
  ls [dir]*      - list content of given directory
  show filename  - display content of given file
remotecons.wttools.CommandHandlerImpl >>
  time - display current time on server
  gc   - run System.gc() command on remote system
  mem [total|free] - display amount of total/free memory on remote system
  exit [n] - call System.exit(n) on remote system
  get [params]+ - complex command require additional parameters,
                  call 'help get' for more info. (Not implemented yet.)
  set [params]+ - complex command require additional parameters,
                  call 'help set' for more info. (Not implemented yet.)
  exec [params]+ - run Runtime.exec(String[] params) command on remote system
10.1.0.153 <<

You can see two command handlers loaded 'remotecons.wttools.ConnectionServer$InternalCommands' and 'remotecons.wttools.CommandHandlerImpl' each with its own set of commands.

Creating own command handler

Although there are several commands available in buildin handlers, remote console can be really useful only if you can use your own command handlers for accessing your own objects at running time.
To do this look in sample code below. The simplest possible command handler must look like following:

  // Don't forget to 'import remotecons.ifc.CommandHandlerIfc;'
  public class SampleCommandHandler implements CommandHandlerIfc {
    public String handleCommand(String comm) {
      if (comm.trim().equals("hello")) {
        return "Hello world!\r\n";
      } // end of if (comm.trim().equals("hello"))
      return null;
    }
    public String help() {
      return"\r\n  hello    - Returns 'Hello world!' string as a result.\r\n";
    }
    public String help(String comm) {
      return "";
    }
    public CommandHandlerIfc getInstance() {
      return new SampleCommandHandler();
    }
  }

Using own command handler

To add your new created command handler your above code initializing remote console must be changed to following:

// Don't forget to 'import remotecons.RemoteServer;'
// Don't forget to 'import your new SampleCommandHandler;'       // NEW LINE !!!
// Don't forget to 'import java.util.LinkedList;'                // NEW LINE !!!
RemoteServer rs = new RemoteServer();
// rs.setAs_daemon(false);   // Uncomment this line if it is only code in your app.
// rs.setServer_port(2702);  // Uncomment this line to set different port number
LinkedList ll = new LinkedList();                                // NEW LINE !!!
ll.add(new SampleCommandHandler());                              // NEW LINE !!!
try {
  rs.initialize(ll);                                             // CHANGED LINE !!!
} catch (IOException e) {
  e.printStackTrace();
  System.exit(1);
} // end of try-catch

Try your code

Try now to run your application and telnet to it. After running help command you should now get following output:

remotecons.wttools.ConnectionServer$InternalCommands >>
  echo           - switch 'echo' mode (for windows telnet is realy needed)
  quit           - close connection to server
  who            - list all active connections
  close n        - close active connection number 'n'
  help [command] - display this message info
  ls [dir]*      - list content of given directory
  show filename  - display content of given file
remotecons.wttools.CommandHandlerImpl >>
  time - display current time on server
  gc   - run System.gc() command on remote system
  mem [total|free] - display amount of total/free memory on remote system
  exit [n] - call System.exit(n) on remote system
  get [params]+ - complex command require additional parameters,
                  call 'help get' for more info. (Not implemented yet.)
  set [params]+ - complex command require additional parameters,
                  call 'help set' for more info. (Not implemented yet.)
  exec [params]+ - run Runtime.exec(String[] params) command on remote system
SampleCommandHandler >>
  hello    - Returns 'Hello world!' string as a result.
10.1.0.153 <<

As you can see your command handler was added to all command handler lists and your supported command is now visible. Try to run your command.
You should get result string:

10.1.0.153 << hello
Hello world!
10.1.0.153 << quit
Bye
Connection closed by foreign host.

I hope this is all you should know to use this library. I hope it will be useful.

Need more info?

If you have any problems with this application or you found any bugs or you have any ideas about extending this package, want to join to project or you simply need to contact me please send e-mail to addres: Artur Hefczyc kobit@users.sf.net

This is part of Web Test Tools project.