2012-02-22

Java Module Systems The EDT and ClassLoader Issues

As mentioned in Java Module Systems SwingWorker, Runnable, Thread and ClassLoader Issues, where invokeLater and invokeAndWait are discussed, the EDT is a separate thread with its own context classloader, and this is most likely the system classloader. It is important to understand this.

If you create a user interface in a modular system, such as the NetBeans RCP, upon a user action logic will run on the EDT, and if in that logic you access classes by name, create new instances of them, or perform casts and those classes could possibly be in more than one module, you will run into classloader collision issues. I will restate here that this also affects EventQueue.invokeLater and invokeAndWait.

Along with collision issues, you need to also understand that certain class access may be blocked depending on the classloader being used once you set the thread context classloader. Imagine you have some classes your current UI components classloader can see; they are part of its dependencies. Those dependencies classloaders may not have access to each other. If you use a classloader which does not have access to some classes to set the thread context classloader, then access will be blocked to those classes, and your logic will not work.

Suppose there is a button and it has an action listener attached to it. It could be written as:
public class MyActionListener implements ActionListener {
public void actionPerformed(ActionEvent evt){
ClassLoader oldCl = Thread.currentThread().getContextClassLoader();
try {
//here we are actually taking the current instances classloader
//which could be slightly better than
//MyActionListener.class.getClassLoader()
Thread.currentThread()
.setContextClassLoader(getClass().getClassLoader());
//create instances, cast, load classes by name
}finally{
Thread.currentThread().setContextClassLoader(oldCl);
}
}
}


The above could make an assumption it is the only possible some.specificpackage.MyActionListener to be within any module in the system at one time were it to use MyActionListener.class.getClassLoader(), and if that were not to be the case, you would need to get creative in the manner in which you get a classloader into this object.

The code does slightly guard against that since it uses getClass().getClassLoader() versus the static MyActionListener.class.getClassLoader() which would unequivocally infer it is expected to be the only one in the system per the way the class and classloader are being accessed. This means the instances classloader will be used, and if the instance was created using a specific classloader, and it is correct, then the code will simply work. If the classloader is not correct, then the logic which created the instance will need to be fixed.

This is another subtle way in which classloader issues can creep into the domain of concurrency and Java modular systems. You can use this information to ensure you have protected your modules logic from being broken by other modules at runtime which you probably will not have tested against.

Remember, if you use 3rd party libraries in a module, or you are writing one, it is highly probable and definitely possible others will too, and you may use the same ones. Whether the library is the same version or not, unless it is accessed in the context of a shared module classloader, i.e. the library is itself in a module versus a simple JAR dependency and all other modules use it this way, it can cause collision and access issues.

2012-02-21

Agile MVC User Interface Design - Not Soley For The Web

Introduction

When I wrote this I mainly had Java Swing developers in mind, particularly members of my current development team working on a NetBeans RCP based application, and I was initially going to title it Java Swing User Interface Design, but it certainly applies to any user interface work I have done in C, C++, C#, and JavaScript.

There are a few things to keep in mind when starting to design and develop a user interface. First, and most importantly, has anyone from the user community contributed to the interface you are working on; ideas, use cases/user stories, business rules? Next, has the user community reviewed any ideas and UI mock ups before starting any heavy coding? Have you taken time to design the user interface before adding complex business rules or worrying about concurrency and threading? These things affect time and resources which impacts how quickly they can be done correctly.

User Community Initial Input - User Stories or Use Cases

The essential question to basically everything we do may be: Why am I doing this? The user community, which a developer could possibly be a member, knows their domain or business. In many cases, they don't know how to get that result out of a user interface or possible ways the experience can be better until they are shown, but they know what data goes in and what data should come out; roughly at a minimum.

This is where requirements gathering comes into play. These have to start some where. The initial user stories (interchange with use cases) will be broad statements of what the users want to do. Users need to be coached into breaking those broad statements down into some very discreet ones which collectively would allow them to achive the one which is more broad. In project management terms, this starts to form what is known as a work breakdown structure.

The above is the top tier of the work breakdown structure or the work to be performed which allows the application and project to fulfill its purpose. A developer should be able to take this information and create those portions of the application. If the user stories are refined enough, developers should be able to understand them, and in turn, create tasks which will guide the development of their source code.

The tasks the developers create will become the lower tiers of the WBS. If the developers have a hard time deriving tasks from the refined user stories, they need to push back on the users until the stories are refined enough to allow this to happen. To the point. This represents why you are doing the thing you are doing. In this case, and more specifically, why the user interface will work the way it does.

User Contributions to The User Interface - User Interface Mock Ups

The advantage to iterative development, or in construction speak - design build, is direction can change more easily as development progresses. As the system gradually grows, replacing the whole becomes a more and more expensive proposition. If additions are built incrementally or in baby steps, they can be corrected within an iteration or two. Getting feedback from users ahead of time through UI mock ups helps with this as it relates to user interface design.

A UI mock up should be as simple as possible while expressing and displaying enough of the UI layout along with functionality to the assumed user community, or at least a narrowed test group of the user community. Various tools can be used to perform this work.

In some cases, a simple graphics application with annotated screen shots can be extremely useful. This is good when minor improvements or tweaks are added to existing functionality. This can be useful less the screen shots as well; imagine a simple form is thought to be all that is needed. Image applications can be useful for creating general layout examples along with rudimentary form objects. There are tools designed specifically for creating these type UI mock ups too, but many of the image manipulation programs one uses often work well.

In other cases, more developer oriented tools are better suited. With developer oriented tools, such as the NetBeans IDE and its UI designer, a partially functional representation can be created complete with real UI form components and windows and dialogs. Executable JAR files can be given to users which when run allow the user to play with an actual UI and get a feel for the ideas being presented.

Along with the above, branch development provides yet another option. In a branch of the source code, parts of the UI changes can be worked into an existing and running application. Though the parts will not be complete, remember this is a mock up, they give the user a glimpse of exactly how those pieces will fit into the current system. The whole thing need not be working or a large amount of work done to achieve the desired result. If the UI is acceptable, then the rest of the UI work can take place inside the branch taking advantage of the work which went into the mock up; some refactoring will certainly be required, but at least much of the UI components will be in place even if simply copied and pasted.

In some other cases, it may be best to create some kind of a functional prototype as mentioned above along with taking screen shots and then annotating them. It is often going to be much easier to create certain graphical effects in an image manipulation program than to write logic or source code from scratch to work those effects into an application; even if it is a prototype. The user can then take the functionality you can give them quickly, examine it, take the screen shots into consideration, and then make a determination as to whether such a feature adds value.

All features should be evaluated as to which of the above will work best. Remember: mock ups should show the user the intent and give them a glimpse of possibilities as quickly as possible to allow the team to change course if needed. If too much code and time goes into the mock up, then it may not provide as many advantages. But, there are times where a more in depth prototype will be required. It simply depends on whether users really understand what they are being shown or not, so always remember that communication is the best tool.

Incrementally Add Complexity

Possibly the best designed user interface will have as little business logic in the UI components as possible. The UI components should merely be a vessel for retrieving information from the user and displaying it to them. Initially this will be to get and set information intentionally not adding progress updates and background threading possibly long processes.

Progress updates and background operations will be determined by the data being set and retrieved per user operations and the processes required to get it. If taken into consideration in the user interface from the start, the user interface components are more likely to require changes often and in multiple places as use cases and operations evolve per user feedback. Minimise this until absolutely necessary. If the interface, along with data models - which probably differ from the data, capture the business rules correctly, then adding progress updates and threading at the end should require less work than reworking them.

MVC

In general an MVC pattern should be used. Data models, general utilities, controller logic, and the UI classes should be built into separate classes and files allowing them to be tested independently. This will also reduce the size of the individual files of the project. It will probably help produce a better design, and definitely with better separation.

UI components should know how to take a data model and display it or convert it from a model into something the user sees through the lens of the component. Data models should be able to take a set of data and expose it through a particular programming interface which various logic can access. Often models will have selected values, data, and fire events upon certain changes or at least allow a domain to tell it when to fire such an event through something like a fireXEvent() method call.

UI components should expose setters and getters or mechanisms to set and retrieve data the users actions have modified. These can expose data or models. These components should also allow various listeners to be added, removed, and retrieved. User actions, even if pressing a single button in some complex UI component, should generally be exposed through listeners and cause nothing to necessarily change in the UI unless it is purely related to the UI state.

The controller should attach listeners and act upon such actions, and the logic which enables, disables, or changes various features of the user interface, such as setting a new model or updating an existing one which was a result of the action, should be built into the controller. The controller should contain the business logic. Other extraneous logic which seems fairly generic in the process should go into some possibly shareable utility class and not pollute the controller.

A simple example of an MVC would be a file search utility. Suppose the UI of this utility has a single text field called searchTerm. Next, there is a button to the right of searchTerm called searchButton with a magnifying glass on it. The UI contains a tree table below called searchResults. The searchResults displays a model called searchModel of the type SearchModel (which is just an interface). The component has a property inSearch which when true searchButton has a magnifying glass which moves slowing in a circle, and searchTerm is disabled. When false, searchButton has its default still graphic, and searchTerm is enabled.

Let's simply state that searchModel has a method called getFile which accepts an integer as the row in the model as well as one called getSize. It doesn't provide any filtering or anything. This is done by the controller by way of the searchTerm. The UI component knows how to take a model and show its files represented in a tree structure by way of getFile(ndx).getParent(), and that is all this component knows of this model.

The UI component allows add/remove/getSearchButtonActionListener(s), get/setSearchTerm which sets and gets searchTerms text, set/getSearchModel, and set/isInSearch. The controller uses these exposed attributes of the UI component to do all the work and tell the UI how to look. It hooks in a searchButton listener, when searchButton is clicked, it sets inSearch to true, performs its background work, retrieves data, creates a model, which may be empty, sets the model, and finally sets inSearch to false. All the UI component did was fire an event, handle the button animation, and get and display information from and to the user.

As it relates to incrementally adding complexity, there are a couple things which would have been done last in the above example. They are probably obvious, but they are 1) animating the searchButton, and 2) background work of the search. The actual functionality is the most important part. Once that works correctly, then backgrounding some logic and animating a button can be done. Those are not very high risk items on an agenda. It is safe to say that once one has done such a thing a couple times they will be able to do it in various situations over and over; static from a pure human memory perspective. The domain/business logic is the higher priority and most difficult and dynamic piece.

2012-02-10

Java Module Systems, SwingWorker, Runnable, Thread and Class Loader Issues

People often have a hard time getting used to a Java module systems constraints on class loaders and dealing with compile time versus runtime dependencies. There are a lot of issues just around getting the dependencies organized.

Often overlooked is how threading impacts class loaders. NetBeans modules, when "they" create a thread for you, will generally set the context class loader to the current class loader. However, in your own code you need to handle this.

Note Runnable is mentioned above. This does not necessarily consider the cases of EventQueue.invokeLater and invokeAndWait as those things are generally cases where the object instances have been realized, and class loading is no longer in the picture, or at least they should be, as those things should be short and to the point as they happen on the EDT, but it focuses on Runnable when given to the Thread constructor.

However, this could become a source of issues, and if creating new object instances in the Runnable, and it is ever a possibility those classes could be included in more than one module in the targeted system, then you should probably go ahead and deal with a class loader change out as your code will be running on the EDT.

Either way, the reason this becomes important is class access and class collision.

Access deals with the visibility or permissions a given class loader gives the calling code. Calling code may not have access to a certain class, and thus the current class loader should not be the one to load classes, but should instead delegate that to another module which has access to not only the public API but the private API of the module itself. That would be the one loading the classes the caller can access or the public API of the called module.

Collision is a more subtle thing to deal with. Imagine one module has class mine.Foo and another module does as well. Even though these modules may not call or touch each other and thus not collide with each other under normal calling conditions, they may very well do that in a thread without setting the context class loader as those classes will have to be loaded some how, and here the system class loader will be used which will access all the class loaders, and that means either an arbitrary class must be chosen or the first one found, and in nearly all conditions this is not what you want.

In the NetBeans module system this will cause an error as the NetBeans developers do not want this to be a surprise and thus hide crashes. Others may load them; I'm not sure, so if anyone knows how various module systems handle this please comment. Either way, unless you give Java and the module system more guidance, you will run into strange and unusual problems.

Given a class, the following should really be used:

public class MyClass {

Runnable r = new Runnable(){
public void run(){
ClassLoader oldCl = Thread.currentThread().getContextClassLoader();
try {
Thread.currentThread().setContextClassLoader(MyClass.class.getClassLoader());
}finally{
Thread.currentThread().setContextClassLoader(oldCl);
}
}
};

Thread t = new Thread(){
public void run(){
ClassLoader oldCl = Thread.currentThread().getContextClassLoader();
try {
Thread.currentThread().setContextClassLoader(MyClass.class.getClassLoader());
}finally{
Thread.currentThread().setContextClassLoader(oldCl);
}
}
};

SwingWorker<Void, Void> = new SwingWorker<Void, Void>{
public Void doInBackGround(){
ClassLoader oldCl = Thread.currentThread().getContextClassLoader();
try {
Thread.currentThread().setContextClassLoader(MyClass.class.getClassLoader());
}finally{
Thread.currentThread().setContextClassLoader(oldCl);
}
return null;
}
};

}


This does a couple things at various runtimes. When the code runs in a regular Java application with no module system, the system class loader will always be used. Next, when run in a modular application, the current caller, or current module will use its class loader in the threaded logic. Finally, in both cases, the loader is reset to whatever it was before; for throw away threads, that is probably not a big deal, but what if your code is using a thread pool?

This is a basic convention to follow for safety and refactorability. Safety as noted in access and collision. If your code is used in a modular system, and does not follow the above, it will crash as soon as you add the same classes to other modules. Refactorability per the fact that if more than one module later adds a different version of a class, or the same version different class loader, then the application will start to crash until fixed, and if the person tracking down the issue has to spend time finding and/or fixing it, they can't focus on refactoring code to work with the same classes in different ways.

Another thing to keep in mind is there are times when you may need to pass a specific class other than your own for some block of code to pin-point an exact class loader. Imagine some code you are calling will need classes which your class loader does not have access as the module being called does not expose them as part of its public API.

So, there are times when you have to think beyond the current class loader, but the good thing is no matter which class works in the modular system, the code will continue to work if used outside of one in a standard Java application.

The one major time this differs are libraries written to load and use classes dynamically. MyBatis is a good example. In such cases, the current thread context class loader should be passed along. The idea being the caller is telling you which class loaders to use. This only applies to threads however as the module wrapping the called code will have configured the context class loader as needed for the current thread.

The MyBatis folks were working to address this issue the last time I was on the lists. Someone using it in such a context now should comment if able.

I hope this will help projects (open source and not) write Java code which is compatible in both modular and non-modular applications.

2012-02-09

Java Community Process (JCP) 2.8 Seems Encouraging But What's Missing

I'm looking at the JCP 2.8 and I am encouraged by what I'm reading. For instance, in "Changes for Specification and Maintenance Leads" it states "You are responsible to provide a public communication channel for posting and archiving all Expert Group nominations and your deliberations on them (1.2.1), all Expert Group communications (1.1.1), and all Expert Group documents (1.1.1)." and too "You are responsible to provide and maintain an Issue Tracker visible to the public and a mechanism for the public to log issues in that tracker (1.1.2). ". My favorite is "The Specification license you provide at JSR Proposal may not change (1.1.3). ".

That stated, I am let down that I see no reference to compatibility kits and any requirements upon their openness. Does anyone have more information on this? To me, this is one big thing which caused rifts in the Java community. Too, I feel there should be something in the JCP about JSRs openness as well. How open and freely usable the specifications are determines how they will be used for innovation to move the Java ecosystem forward.

In my opinion, there should at a minimum be a statement that the Java Community Process favors more open and free JSRs. That doesn't mean implementations, except for the reference implementation, need to be free. The reference implementation should always be free, and if not in the JCP, that needs to be added. The reason for such a requirement should be obvious, but how does one create a specification known to work without an actual proof of concept? Experience tells me if one does it will be mostly flawed, and to have the right to create a specification and market it through the JCP process, one should have to prove it.

It may be the concerns I raise have already been addressed, and I just do not see them. If so, that's awesome, and thank you to anyone who points them out. If not, then I believe there is still more to do before the JCP can live up to its potential. Here's to hoping it does!