Rediscovering the NetBeans Lookup Library (I)
NetBeans is 10 now and so is the NetBeans Lookup Library. What? You don't know what the NetBeans Lookup Library is? Then you're missing something good!! Let me try to explain it to you.
Where do I get a copy from?
The NetBeans Lookup Library is bundled (with many other interesting stuff) inside a single jar file: "org-openide-util.jar" which comes bundled with the NetBeans IDE.
The best way to get a copy is to download NetBeans (any version would do and to seek for the jar file under the "platform?/lib" directory.
The NetBeans Team publishes also the API of the library
How can I use it?
Using it is quite simple: just add the jar file to your classpath.
Of course you can use it in whatever IDE you want, and both in commercial or open source applications (because latest NetBeans versions are released both under the CDDL and the GPL, and you can use either one or the other license).
And what is it good for?
Lots of things. Indeed. Trust me. So many (cool) things that I'll need different blog entries to briefly explain what it can do. Let's get started.
Looking up stuff - Travel bags
The very first thing you want to know in order to use the NetBeans Lookup Library is the Lookup class.
A "Lookup" object is something similar to a travel bag, where you put stuff in (your laptop, your train tickets, your pencils, your condoms, etc.).
At the moment we won't worry about creating those "Lookup" objects, we just want to know how to peek stuff from those travel bags. We'll see how to create those in a next blog entry.
Looking up single instances
So how do we take a peek at those travel bag? Well, using the "lookup" method, of course! Like this:
Lookup myBag = ...
Lipstick c = myBag.lookup( Lipstick.class );
That's easy, isn't it? Now don't you wish women had such a feature in her handbags?
Looking up several instances
If your travel bag is like mine you probably have lots of pencils in there. You may get them all very easily:
Lookup myBag = ...
Collection myPencils =
myBag.lookupAll( Pencil.class );
Advanced lookup: Templates and Results
If you have ever worked with JDBC you know that you have PreparedStatements and ResultSets, right? PreparedStatements represent an SQL query, and ResultSets contain the results of such a query.
The NetBeans Lookup Library has some similar concepts (but for the SQL part, which I don't like).
You can query a travel bag (a Lookup object) using a Lookup.Template object.
And you can get the results of such a query using a Lookup.Result object.
Creating those objects is very simple (and no, you don't need to know SQL at all):
Lookup myBag = ...
Lookup.Template query =
new Lookup.Template( Pencil.class );
Lookup.Result result =
myBag.lookup( query );
That's simple: you just create a query (a template) using the class you want to search, and then you invoke the "lookup" method in your bag, to get a result.
Now comes the interesting part: the Lookup.Result object. In our example above the Lookup.Result object contains all the pencils in our travel bag. But, how can we use the "Lookup.Result" object?
Lookup.Result - avoiding instantiation
The "Lookup.Result" has two main methods to retrieve the results of the lookup, you can invoke "allInstances()" method, to fetch all instances, like this:
Collection myPencils = result.allInstances();
Or you can invoke the "allItems()" method, that retrieves a collection of Lookup.Item, an object used to defer instantiation of objects until such an instantiation is required:
Collection<? extends Lookup.Item> items =
result.allItems();
for( Lookup.Item item : items )
System.out.println( item.getInstance() );
This is important because not all objects in a travel bag are always instantiated, and you may not want to instantiate them all when looking them up (yeah, I have to admit that the NetBeans Development Team has been smart in this!!).
Lookup.Result - watching things change
Another interesting feature of the Lookup.Result object is that you can attach listeners to it. So you can be informed whenever the stuff in your travel bag changes.
So if you add a pencil, a condom or if you remove stuff from it all the listeners will be informed of that.
Adding a listener (a LookupListener) to a Lookup.Result object is, of course, simple again:
final Lookup.Result result = ...
result.addLookupListener(
new LookupListener()
{
public void resultChanged( LookupEvent anEvent )
{
System.out.println("Mmm... you added or removed a pencil!);
}
} );
As we'll see in a future entry, listening to changes in the content of our travel bags will be an important feature. And listening to changes in the content of other people's bags will be even a more important one.
Keep tuned
So keep tuned for the next blog entries about the NetBeans Lookup Library, where we'll learn how to create our own travel bags and what the NetBeans Lookup Library has to do with... rabbits!!
Happy looking-up, Antonio
blog comments powered by Disqus