Neuroning

Practical API Design

Sun, 31 Aug 2008 18:14:00 -0400

I wrote about API design guidelines before, collecting links, resources, papers and hoping someone would write a book on the subject.

The wait is over! Jaroslav Toulash published a book on Practical API Design!

Take a look at the book’s accompanying website for more details.

I’m waiting for my copy.

Oracle eats BEA

Wed, 16 Jan 2008 09:37:00 -0500

To me, BEA was the big fish not long ago.

Today, BEA is the small one in the mouth of Oracle.

We are in a steep ride, jumping quickly from a start-up to becoming part of BEA and now of Oracle. I hope we can keep the “small-company” atmosphere here in our division.

Content-aware image resizing

Thu, 06 Sep 2007 10:16:00 -0400

Watch this video demonstrating some cool algorithms for resizing and cropping images. They analyse the content of the image and try to remove/add/stretch/shrink only those areas of the image that are less relevant.

http://www.youtube.com/v/qadw0BRKeM

Online Mind Mapping

Wed, 05 Sep 2007 22:06:00 -0400

A couple of smart friends of mine are strong advocates of mind maps, so much in fact that they had nothing better to do than develop http://wisemapping.com. It’s a pretty impressive online mind-mapping tool with everything you’d expect these days from a web two-oh application: rich UI, collaboration, tagging, sharing.

Here’s my first try, presenting the basic ideas behind DITA:

It’s still a private beta, with many more features coming.

Moving back to Argentina

Sun, 13 May 2007 23:13:00 -0400

In March, I accepted a new position within BEA, to work for BEA Argentina.

After more than six years in the U.S., my wife and I were thinking about moving back to Argentina. We were talking about doing so in 2008. Then, this opportunity within BEA came across. It was sooner than what we planned, but it was interesting for me professionally, and BEA was helping with all the relocation needs. So I accepted.

It all happened (is happening I’d say) pretty quickly. Me and my family arrived at Argentina a couple of weeks ago, and I started on this new role immediately.

April was a good exercise on getting things done, both in and out of work. Here’s just a summary:

I played the negotiating game before signing the final offer to move to BEA Argentina.
We did a “virtual” garage-sale on craiglist (sold a grill, furniture, garden tools and more).
A strong storm (Texas style) blew several shingles off our roof. We had to get it fixed quickly before putting the house in the market!. Some of those asphalt shingles landed on top of my car!, scratching it really bad. I had to take it to the body shop ASAP before selling it.
I flew to Boulder, Colorado to get a one day training for “new managers”
The water heater went nuts. Long story short, I managed to replace the thermostat and that fixed the problem.
Worked a lot on reconditioning the house for selling (painting, cleaning, fixing…).
Had to get a “certificate of residency” from the Argentine consulate in the US (to avoid paying fees when clearing customs). Sounds simple, but the Argentine consulate in Houston is the worst and most inefficient public office I’ve ever seen in the U.S. or Argentina.
Sold our house (in less than 2 days!, I cannot imagine how we would have dealt with it otherwise). If you need a Realtor in Dallas/Plano, I strongly recommend Alan Bertucci (an ex-Fuego guy who got tired of working with computers).
I worked at a customer site for two weeks, which is always more stressful than working in your office, specially when you are dealing with so much stuff out of work.
Packed and shipped all our goods. Big help from the relocation company, but we had to spent two days watching over them, labeling boxes, separating things for air or sea shipment, writing a detailed inventory. Not to mention that they made two big holes in a wall (1 day before we had to turn the house over to the new owners!).
Closed all accounts (phone, mobiles, electric, water, gas, toll tags, credit cards, banks, directv, tivo, … ). This included fighting a few battles, like the one to prevent Cingular from charging us a hefty early-termination fee.
Worked on finishing and handing over a couple of internal software projects I was working on.
I flew to California (for a day) to meet my new boss.
I gave a full day training for customer and internal BEA employees.
We went on a shopping spree: books, electronics, apparel, and things we knew was cheaper or easier to get in the U.S.
Tried to meet and say “bye” to all the good friends I made in the U.S.
Sold our cars (CarMax doesn’t pay very well, but it was convenient).
Rented a car and lived in a hotel for a few days.
We picked up our daughter from school and drove straight to the airport. We took our final flight back to Argentina. A 10-hour trip is never easy with 2 kids; Pilar (our 1-year-old) made it specially hard this time.

That’s just the first half. Now in Argentina, we are re-building our lives.

We are looking for a home, mortgage, school for the kids, car, doctors, we are doing paperwork to make our kids permanent residents in Argentina, I’m adapting to my new job, and we are living as guests until we find a home and the shipment with all our goods arrives.

Luckily, here we get a lot of help from our bigger family. After all, they are pretty much the only reason why we decided to come back to our home country!

The dust should settle the next month or so, and we’ll feel “at home” again.

Violating Java's privacy

Mon, 19 Feb 2007 22:49:00 -0500

I found myself in the need to invoke a private method of a Java class that was out of my control. I really needed it.

So, I went ahead and violated the method’s privacy declaration via reflection. You can (under certain circumstances) invoke methods which are declared as private using the Reflection APIs (java.lang.reflect).

But before using reflection, I created two classes:

class A {
  public String method1() {
    return "Hello World!";
  }
}

class B {
  public static void main(String[] args) {
    A a = new A();
    System.out.println(a.method1());
  }
}

They compiled, and java B said “Hello World!” as expected.

Then, I made A’s method private and recompiled A. And I run java B again. Nothing changed. It just worked again.

That cannot be right. This would mean you can handcraft a class with the same name and methods as the original one but making everything public. Then you could use this class only at compilation time, allowing your code to call any method. (Or, one could modify the Java compiler to ignore access declarations altogether).

Returning to the reflection APIs for a sec., here’s how I called private method ProcessService.getSession(String):

Class clazz = ProcessService.class;
Class[] params = new Class[] { String.class };
Method m = clazz.getDeclaredMethod("getSession", params);

m.setAccessible(true); // allow access, as if it were public

Object session = m.invoke(this, new Object[] {sessionId});

The Java compiler enforces access restrictions at compilation time. But it’s the Security Manager (an object of type java.lang.SecurityManager) the man on duty at runtime. The above code works because, by default, the JVM does not use a SecurityManager.

For the curious, the implementation for method “setAccessible(boolean)” (part of the JDK) looks like:

public void setAccessible(boolean flag) throws SecurityException {
  SecurityManager sm = System.getSecurityManager();
  if (sm != null) sm.checkPermission(ACCESS_PERMISSION);
  setAccessible0(this, flag);
}

It simply asks the current SecurityManager for permission before actually changing the “accessible” property. In general, before any “sensitive” operation, the code in the JDK asks the SecurityManager for permission.

You enable the default SecurityManager passing -Djava.security.manager to the java command. This would make the first code snipet above to throw an AccessControlException. Both methods Class.getDeclaredMethod() and Method.setAccessible() are guarded by the SecurityManager.

To allow the above use of reflection with the SecurityManager enabled, one must define a security policy for explicitly permitting those operations.

Anyway, back to my original concern of class B being able to invoke class A’s private method directly. I could try to run it with the SecurityManager enabled:

$ java -Djava.security.manager B
Hello World!

It still works. So, I run the same test but from an applet (a more restricted container):

import java.awt.Label;
import java.applet.Applet;
public class BApplet extends Applet
{
  public void start() {
    A a = new A();
    add(new Label(a.method1()));
  }
}

<html>
  <body>
    <applet width="300" height="300" code="BApplet.class">
    </applet>
  </body>
</html>

And now it did fail, finally:

$ appletviewer BApplet.html
java.lang.IllegalAccessError: tried to access method
                  A.method1()Ljava/lang/String; from class BApplet
  at BApplet.start(BApplet.java:7)
  at sun.applet.AppletPanel.run(AppletPanel.java:414)
  at java.lang.Thread.run(Thread.java:595)

For this particular type of runtime checks, the Security Manager is clearly not involved. Nothing shows up in the StackTrace. It happens at a lower level, in the JVM itself. Makes sense now: it would be really inefficient to invoke the SecurityManager for every non-public method call… (and who’d check the calls to the SecurityManager itself!?).

But still, Why does it work with the java command, but fails within an applet?

To help with performace, the JVM only enforces these checks on classes loaded by custom classloaders. Classes loaded by the standard class loaders (bootstrap, extensions and System) are considered trusted. There are “levels” of trust actually, (bootstrap being the most trusted), but for this particular case, even the System (classpath) class loader trusted my class.

Inside the JVM covers the JVM internals extensively, including security and class loaders.

I'm sold to Beryl

Wed, 31 Jan 2007 19:27:00 -0500

I’ve been trying Beryl (a 3D Window Manager for X) and I’m pretty impressed.

True, it’s full of useless graphical effects and pure eye-candy. But it also provides practical features and is very configurable.

Among the actually useful things: fast and practical ways to change windows, desktops, to expose the desktop area, scale and pick a window (ala Mac OS X’s “exposé”), visual notifications, desktop zoom, screen annotations.

Unfortunately, most demo videos concentrate on the graphical effects instead of the useful features, but they still give you an idea of what it can do.

I really like the idea of using a “water-ripple” effect as an unobtrusive -but impossible to miss- way of receiving notifications.

It integrates nicely with KDE, Gnome and pretty much any desktop environment. And you can easily switch back to your previous window manager at any time on-the-fly.

I have it running on my work laptop, with Fedora 6, KDE and AIGLX.

Very nice.

History and auto-completion with rlwrap

Thu, 18 Jan 2007 23:06:00 -0500

If you ever used Oracle’s sqlplus you’d agree that it provides an arcane command-line interface.

Being a textmode command-line tool is not what makes it arcane though. It’s that it doesn’t offer auto-completion or a command history. If you made a small mistake when typing a long statement, you would have to re-enter it all over again.

Most modern command-line tools (including MySQL and PostgreSQL’s equivalent to Oracle’s sqlplus) provide much more powerful interfaces, just like the bash shell does. They include auto-completion of the text you are typing (by pressing TAB), access to a history of commands (up/down arrows, or C-p/C-n), incremental search on the history (C-r), they remember the history in between invocations and more. Virtually all these tools use the GNU readline library to provide these capabilities.

Unfortunately, not all command-line tools use GNU readline (splplus being one). Fortunately, there’s rlwrap. I just came to know this nice little tool.

rlwrap “wraps” any other command-line tool and gives you a readline interface to it. So, you can invoke rlwrap sqlplus and you get sqlplus with the history capabilities of the readline library.

You may also pass to rlwrap a list of potential words to use for completion. For example, I also use rlwrap with groovysh (the Groovy language shell), so I created a file “~/.groovysh_completions” containing the list of commands groovysh accepts. Now, when I launch groovysh I get command history and specialized auto-completion.

Now, rlwrap cannot do magic. Being so generic, it cannot do intelligent context-dependent auto-completion. For instance, PostgreSQL’s command-line interface automatically pulls the list of potential table names after doing SELECT * FROM <TAB>. rlwrap cannot give this intelligence to sqlplus, but it’s still much better than nothing.

On API Design Guidelines

Sun, 19 Nov 2006 22:31:00 -0500

Update: Good news! Jaroslav Toulash emailed me that he published a book on Practical API Design !!!

Looks like Brian McAllister may be preparing a talk on Designing Elegant APIs.

I've been very interested in good API design for a long time. But I could never find a single book on the subject. Many design and programming books provide good advice and guidelines that are essential for designing good APIs, but none of them tackles the matter directly.

I reviewed "Interface Oriented Programming" a few months back with disappointment. It may not be a bad book, but I felt it was quite basic and superficial. May be my expectations were too high, and too focused on API design.

Over time, I collected some links on the subject and shared some with Brian:

Best Practices in Javascript Library Design (via John Resig on JavaScript API Design) - A good presentation given by the author of JQuery.
API: Design Matters - Article by Michi Henning, ZeroC, for ACM Queue magazine.
How to Design a Good API and Why it Matters - Excellent deck from Joshua Bloch. There's also a video of his presentation at JavaPolis 2005.
Interface Design, Best Practices in Object-Oriented API Design in Java, by Bill Venners - This one is a Book in progress!. Unfortunately, the last updates seem to be from 2002 or so. I'm not sure if the project is still alive. Anyway, it contains many good articles.
How To Design a (module) API - A great page on good design practices for writing APIs. It's tailored for NetBeans module writers, but is still pretty general and gives very valuable guidelines.
How to Write APIs That Will Stand the Test of Time - A session I attended at JavaOne 2006. Presented by Tim Boudreau and Jaroslav Tulach, members of the NetBeans team. It focuses on API evolution and compatibility, but also covers usability and other guidelines. I guess they are the main guys behind NetBeans' How To Design a (module) API page linked above.

I had the chance to speak with Jaroslav after his session and suggested he should write a book on this topic. I emailed him the references I had, and he said he would try to draft something by the end of year.
API Usability - Focused on making APIs easy to use. The article applies general usability principles (commonly used in GUI design) to the design of APIs.
Measuring API Usability - An interesting article by a usability engineer at Microsoft, published on Dr. Dobb's. It favors the use of scenario-based design to achieve usable APIs, and explains the use of their "cognitive dimensions" framework for measuring API usability. He also blogs about API usability.
Krzysztof's Laws of API Design - From another Microsoft blogger on API design.
Java API Design Guidelines - A good article from a developer who was also surprised by the lack of a book about API design. He collected some advice and additional links.
XOM Design Principles - Some design "principles" followed by XOM (an XML parsing library).
The Most Important Design Guideline? - A short article by C++ guru Scott Meyers.
Humane Interface, Minimal Interface, Designed Inheritance, DSL Boundary, Duck Interface, Fluent Interface, Public vs. Published Interfaces - Some of the many great writings from Martin Fowler. These selection is on specific topics that are relevant to API design. Most of them are quite recent.
Programmers are People, Too - An article by Ken Arnold for ACM Queue magazine: "Programming language and API designers can learn a lot from the field of human-factors design."

So, let's hope Brian gives his talk at a big conference, signs a contract with a big publisher and fills the void.

Variable Severity Logging

Sun, 24 Sep 2006 19:21:00 -0400

Most software products and logging frameworks produce entries in their log files with different severity levels (say, from Debug to Severe). Then, you can configure which level of messages you want the application to log.

At development time, you may want all messages to be logged. But once in production, you normally configure things so that only Warning and higher messages get logged (for performance, space and other reasons).

The problem is that when a Severe message arises you may need more detailed (Debug level) information in order to understand the actual cause of the problem. So, a common practice is to increase the logging level at that point, and wait for the problem to happen again –not very effective.

This is one of the problems that motivated the guys behind LogBag. The idea they propose is nice and simple:

Make the system write only Warning (and higher) messages to the log, but when such a message is logged, it should also include some lower-severity messages that occurred right before and after this one.

It’s one of those good ideas that might seem obvious, but for some reason nobody thought (or did anything) about before.

To implement this, the logging system could keep a buffer of the last N messages generated by the application, and when a Warning (or above) message comes in, the whole buffer is flushed to disk. This should not be too hard to implement, since most logging frameworks already use some kind of buffering, in a producer-consumer pattern, to improve concurrency and performance.

From the LogBag site:

You keep on putting things in a Log bag. Then whether the entire log bag gets written or not depends on the highest severity level in the entire bag. So either you write everything or you write nothing.

I think it’s a nice idea. I bet the technical support guys would like it too :-).