Sunday, January 11, 2009

Extending the Java Console

The lack of a good way to be able to interact with the console in Java is extremely annoying. I have been working on a small project (hopefully the content of another blog eventually) which would work best if it had good access to the console. It is frustrating that even after all these years, Java has no good way of writing a decent console based application. I can only guess that the reason for this is perhaps WORA goals are compromised? I have created an extension to the Console API which allows for better access and additional features. This blog entry is about that project.

The limitations
Java has no equivalent of the C getch() API which allows you to read a single character from the input buffer. The only way to get to return is to hit enter after typing in your input which makes it an extremely clunky way to read characters and every character is then on a new line – like a newbie Java program. Java is just not meant for console input unless you are doing simple things like “Enter Name : “.

If you did somehow get past the lim
itations (and if you know a way how to do this with plain ol’ Java 6.0, please educate me) you get stuck with the lack of ability to be able to control your output. The introduction of Console.printf does add some significant output formatting capabilities, however there is no ability to move the cursor around to position your text right. Say you wanted to overwrite the current word under the cursor when Tab is pressed (like the command prompt does when you want to complete paths) – you can’t do that.
There have been a couple of solutions to these problems - there is a hack which partially works. Maven does this neat thing when downloading anything significant from a repository where it shows the download progress.

Maven does this by using \r at the end of the System.out.print() which allows it to overwrite the previous line. Another hack - If you wanted to do the Tab-should-overwrite-current-word-under-the-cursor thing you could do System.out.print(“\b”) as many times are required to overwrite the letters under the cursor. This would work BUT both these techniques are limited by the start of the current line – i.e. they are unable to go to the previous line which limits their usage.

What is really required is an addition to the Console API in Java. The Console API was introduced in Java 6.0 and provides some much needed additions to Java’s capabilities to deal with character based applications. Console introduces methods to read passwords (without echo) and adds the printf method I talked about earlier. However, it still lacks the ability to read individual characters and to position the cursor and therefore was still insufficient for me.

The solutions

Like every lazy developer, I did Google away for a Java curses or Console implementation. The most promising one I found was JCurses – a Java Curses implementation for Windows and Unix (using JNI).

This is a nice little project that provides the curses API in Java. It provides a bunch of widgets and layouts and containers for creating UI in character mode. It’s nice but that’s not what I wanted. However, it did have a lower level API (that was not recommended for use but that’s just an invitation, isn’t it?) that allowed character input and character output. The input could be retrieved one character at a time just like I wanted but the output forced me to provide an x, y location. That in it self would be fine if I had an idea of where I was on the screen. The API lacked the ability to get and set the cursor location – basically I think the idea was to create character UIs (probably full-screen) so it wasn’t that important in the context of the JCurses project. Also, the output methods did not move the cursor which made the whole thing look and feel rather weird. I wanted something that will make the user retain his feel of the command line – not a character mode UI.

There has been a similar project in the past which seems to have moved or died - at least I couldn't find it - here's the link.
Sun has been introducing features bit by bit as mentioned above. Here's the link to the discussion on the password entry. This is nothing close to what I want and continues to have the clunky enter-for-input behaviour.

Then I figured what I only wanted was really a small Console API with supporting classes. I got the Windows SDK and looked up the Console support and Windows has Console API that did exactly what I wanted that would work just fine. Writing the JNI library to get the basic console API wasn’t that hard.

The next step was to have the Java API that provided basic extensions to the Console. It has very few methods –

  • to read characters with or without echo
  • to output characters at the cursor location or at a specified location
  • to retrieve the current cursor location
  • to set the cursor location
  • to retrieve the screen size.
The Console library has all capabilities to let me do console input and output. What I have is lean and does exactly what I want – a useful Console extension that provides basic capabilities that were missing.

Project - help wanted!
The project is available on Google Code here. I will try contributing back to the JCurses project when I am done. If you are interested look at console.Console. console.ConsoleBuffer provides a higher level abstraction allowing the console to be treated as a text field with an index into the text instead of dealing with the row-column nature of the cursor.

I would like some help with a few things though –
  1. I used to be a good C programmer but am significantly rusty so my C code could use a good code review to look for leaks and such or any suggestions on doing thing better.
  2. I am basically on Windows so I didn’t write anything for Linux – so someone to provide a Linux port and build would be great.
  3. I need to get the Maven build working completely. It builds the Java part but I had trouble with the native-maven-plugin to get it compile the native parts. So that is done as a bunch of batch files right now :-(
If someone would like to help me with these please drop me a line. The project is using Apache License 2.0 so is available for re-use in other projects.

If you do use the library and have any feedback, I would love to hear it.

I really think functionality should be added to the Console class in Java. There are a couple of RFE’s in the Java Bug Database that request for more capabilities in the Console API – 6672641, 6552816, 4050435.


Yuri Schimke said...

Did you look at jline

Khalil said...

You may want to take a look at Jline, which does not seem to be that actively maintained. There was a discussion on the JVM languages mailing list as several REPL tools are currently using it. Nevertheless I do think that your request for a better Console API is spot on.

Sachin said...

No, I hadn't seen JLine. Thanks for the pointer. It does seem like a nice library. It seems to do a lot of stuff including providing completion handlers for tab completion on the command line - nice. It doesn't have any ability to position the cursor though.

Anonymous said...

BeanShell. Been around for years. Quit your bitching and do a damn Google search once in a while.

Anonymous said...

BeanShell is NO shell or curses lib but a scripting language. BeanShell uses either JLine (see above) or a Swing-Console as output.

Anonymous said...

Take a look at this simple implementation that uses JNI/PDcurses: