[Home] [News] [Contextual Features] [Lightweight Version] [Full Version]
The Contextual Features of eMoose
In this page we introduce the contextual features of eMoose, available both in the lightweight version and in the full product.
For a more detailed description, please consult our publicationss: a short paper in CSCW'08, and a full paper that has been submitted for publication.
Consider the following scenario: A developer (such as you or one of your peers) is busy working on some important functionality. He complete the "sunny day" scenario and test it out, but there are a few things left to be done: some secondary functionality that he hasn't finished writing, making the method robust against a certain combination of inputs, optimizing a few things, and maybe even resolving some bug that occasionally appears. Imagine now that you are writing code that relies on many methods, including the one we have just described. You type the object's name, see the list of methods, and pick it. You may optimistically expect that the method is correct and robust. However, without actually examining the source code for comments and //TODO comments, and perhaps also the task list and external bug repository, you may not be aware that this is not the case. You are therefore invoking something which may cause your program to fail.
Similarly, the developers of many methods associate certain types of knowledge with them that may affect clients, and which we term directives. These include assumptions, preconditions, side effects, performance and threading issues, restrictions, preferred alternatives, etc. When a client is making a call to a method or examining code that includes such a call, there is no immediate indication that any of this knowledge is associated with the target. Even if it is documented in the JavaDocs, it may be hidden among a lot of details, and of course, there are no guarantees that a developer would invest the time in reading that particular call. After all, a client uses many services from many sources. Indeed, our studies show that some calls are avoided or skimmed.
Consider, for example, the following code fragment, which initializes a topic connection in the Java Messaging Service (JMS) API:
Which targets, if any, should we examine more in depth? All of them? Any of them?
It turns out, for example, that the seemingly innocent call to createTopicConnection actually instructs the user to call the start method on the connection before any messages will be delivered, or the program will block once we try to receive messages. Other calls, such as getTopicConnectionFactory, createTopicSession, and createTopic, all present detailed specifications with some information that is not necessarily relevant.
If we now turn to examine the call to setClientId, we face a huge JavaDoc block:
In this case, there is a critical directive hidden within the text (highlighted), which states that we should have set the client identifier before taking any other action on the connection, including the creation of the session; otherwise, the id does not propagate. These lines thus would have to be reversed. Our studies show that many developers may miss this clause even if they examine the JavaDoc for this method. Part of the problem is that without knowing that a directive exists, one may not invest sufficient effort in searching the JavaDocs for one.
Note that another difficult situation occurs due to polymorphism. For example, consider the two statements, Set s1 = new TreeSet() and Set s2 = new HashSet(). After these statements execute, we have two variables whose static type is Set, and whose dynamic type can be HashSet, TreeSet or even other types of sets. The same variable may reference different object types at different times. If we now call s1.add(new TreeMap()) and make a similar call on s2, the first call will fail because the passed object does not implement Comparable. In other words, we had a directive that appeared only in the dynamic type but not in the static type. While this is a violation of conformance principles, it is in fact quite common. In addition, there are many situations where overriding versions have additional requirements or have limitations and remaining action items. With standard IDE support, which simply presents the JavaDocs of the static type, you may not be aware of this problem unless you explicitly investigate all possible subtypes.
The contextual features of eMoose have two important goals: to give the developer cues about which call targets are more likely to have important information and which are less likely to, and to help identify that information once the target's JavaDoc is explored. It is important to note that eMoose does not guarantee that the knowledge is interesting, new, ore relevant to the current context. For instance, there may be a directive discussing return values even if the call does not make use of this value.
eMoose merely uses a knowledge in which certain "observations" are associated with methods. These observatons come from three sources: from the existence of //TODO comments in the code of the target, from corpuses of directives which we have targged in the documentation of certain APIs and libraries, or from user input in the full version of eMoose.
eMoose constantly scans the current viewport in Eclipse and (when in the Java editor) identifies all method calls. It checks the target of each call against the knowledge space, and if there is a match, it decorates the call with a box and with an icon at the beginning of the line, as can be seen below:
If a user wishes to investigate one of the marked target, the standard hover window is augmented with a lower pane that highlights the relevant directives:
eMoose also offers (optional) support for the problem of polymorphism. By changing a configuration parameter, eMoose will start looking for observations not only in the static type of a call target but in potential dynamic types. It can then mark the call if there is a possible dynamic type that has knowledge, and can also present these observations in the lower pane of the hover while the JavaDoc part still reflects only the static type.
All these features are available in the lightweight and full versions of eMoose.