Monday, October 30, 2006
Use the source, Luke!
Ever spend like 15 minutes - or more than an hour, even - trying to figure out how some fairly complex API was supposed to be used - when what you wanted to spend was just 5 minutes of coding?
Well, I have.
Nowadays, if you are programming in Java - you do not have to do that anymore.
You can look up Javadocs describing an API and code samples of it actually being used in seconds.
Here are some very useful resources in that regard:
Note that I also have these in my blogroll in the sidebar of this blog.
I have used these more than a couple of times in the past few months. They save me a lot of time.
Once or twice recently, I worked out how to do something on my own - construct this factory factory, then use it to create this factory, then use it to get one of these objects, then use that to get one of those objects... - then later discovered the same thing spelled out at one of these sites.
I would much rather have something like that spelled out for me and just read it, than work it out by looking things up all over and then pulling it all together myself.
Using these services raises some hackles.
Sure, you can write it yourself - and you should.
That is not what these services are for doing. They are for showing you how the APIs are intended to be used. That is the point of using them.
Sometimes it is just plain simple how to do something. In other cases - it is not. Or, you have to read a lot of documentation just to get to the
So, that is the point.
Read the documentation, sure. That is how you learn the big picture, the caveats, the constraints, and the fundamentals of an API.
But to find intended usage patterns - sometimes the supplied docs are not the best. Sometimes they are the worst. Examples supplied with a Java library and JVM help - do not overlook them. However, these search sites are another tool to include in your toolbox.
Bookmark them and use them whenever the need arises.
Note that Firefox search add-ons are available for most of them. You are probably using Firefox, so grab them. Then you have them at your beck and call with barely a half second delay.
Well, I have.
Nowadays, if you are programming in Java - you do not have to do that anymore.
You can look up Javadocs describing an API and code samples of it actually being used in seconds.
Here are some very useful resources in that regard:
- Google Code Search open source code search
- Koders open source code search
- Codehound Java source code search
- javadoc online public source code search
- docjar open source code search
- Java Almanac APIs and examples
Note that I also have these in my blogroll in the sidebar of this blog.
I have used these more than a couple of times in the past few months. They save me a lot of time.
Once or twice recently, I worked out how to do something on my own - construct this factory factory, then use it to create this factory, then use it to get one of these objects, then use that to get one of those objects... - then later discovered the same thing spelled out at one of these sites.
I would much rather have something like that spelled out for me and just read it, than work it out by looking things up all over and then pulling it all together myself.
Using these services raises some hackles.
Is it for copying?and
You cannot write it yourself?
Sure, you can write it yourself - and you should.
That is not what these services are for doing. They are for showing you how the APIs are intended to be used. That is the point of using them.
Sometimes it is just plain simple how to do something. In other cases - it is not. Or, you have to read a lot of documentation just to get to the
Eurekamoment where you go:
Aha! I have used an API that was almost exactly the same as this before - I see what they are doing!
So, that is the point.
Read the documentation, sure. That is how you learn the big picture, the caveats, the constraints, and the fundamentals of an API.
But to find intended usage patterns - sometimes the supplied docs are not the best. Sometimes they are the worst. Examples supplied with a Java library and JVM help - do not overlook them. However, these search sites are another tool to include in your toolbox.
Bookmark them and use them whenever the need arises.
Note that Firefox search add-ons are available for most of them. You are probably using Firefox, so grab them. Then you have them at your beck and call with barely a half second delay.
Saturday, October 28, 2006
dbdoclet - the DocBook outputting doclet for the javadoc command
There has been this utility out for a few years, a javadoc doclet called
dbdoclet - the DocBook API doc generator for Java programs:
Now that DocBook has caught on, there might be a lot of Java programmers - and Java project managers - who are interested in this utility.
I think at some point, people who buy custom software and get the source code and/or library/framework APIs - will want to get DocBook format documentation with it.
This doclet will probably be something they all find very interesting.
docbook Homepage.
dbdoclet - the DocBook API doc generator for Java programs:
The DocBook Doclet (dbdoclet) creates DocBook code from Java source
documentation. It is helpful, if you want to print reference handbooks of your
API. The program can be used as javadoc doclet or as standalone
application. The standalone application can be used as a converter to transform
HTML documents to DocBook documents. Additionally DocBookDoclet comes with a
Swing application called dbdoclet.TiDBit, which helps you to manage your
documentation projects and to create PDF files.
Now that DocBook has caught on, there might be a lot of Java programmers - and Java project managers - who are interested in this utility.
I think at some point, people who buy custom software and get the source code and/or library/framework APIs - will want to get DocBook format documentation with it.
This doclet will probably be something they all find very interesting.
Thursday, October 05, 2006
Java Tester - What Version of Java Are You Running?
Java Tester is a handy tool I have been using for at least several years to find out what version of Java my browser is running.
It would be nice if every computer I used was using the newest JVM installed on it for running applets in all its browsers, and every computer had the latest JVM installed.
Sadly, that is pretty often not the case. The reason varies from OS to OS, and browser to browser.
The key questions are: do I have any JVM to run applets in this browser I am using, and is it a new enough version for this applet I want to access from a web page?
Browsers are pretty complicated, kind of unstable, oddly configured, and ever changing environments. Lots of things can make you not have the default JVM for running applets be the one you think it should be.
Things that can play with your expectations include:
* JVMs installed out of order. Example: you install latest JDK 1.5 or a beta of the next JVM this week, and then next week you install a new update of JDK 1.4.2 to do some compatibility testing.
* changed setting in Java control panel
* changes to the registry
* OS patch breaks stuff, including Java
* browser patch from its maker breaks Java
* Java OS is behind on your platform
* you installed Java on your other computer
* you installed a plugin in your browser to let you run a newer version of Java in it than your maker provides, then the maker upgrades the browser and your plugin gets deleted or moved aside - or the prerelease plugin does not work with the new version of the browser
Most of these are problems with any browser plugin.
The idea behind the web is: point, click, cool.
The reality is that sometimes the web is more like: point, click, huh?
It would be nice if every computer I used was using the newest JVM installed on it for running applets in all its browsers, and every computer had the latest JVM installed.
Sadly, that is pretty often not the case. The reason varies from OS to OS, and browser to browser.
The key questions are: do I have any JVM to run applets in this browser I am using, and is it a new enough version for this applet I want to access from a web page?
Browsers are pretty complicated, kind of unstable, oddly configured, and ever changing environments. Lots of things can make you not have the default JVM for running applets be the one you think it should be.
Things that can play with your expectations include:
* JVMs installed out of order. Example: you install latest JDK 1.5 or a beta of the next JVM this week, and then next week you install a new update of JDK 1.4.2 to do some compatibility testing.
* changed setting in Java control panel
* changes to the registry
* OS patch breaks stuff, including Java
* browser patch from its maker breaks Java
* Java OS is behind on your platform
* you installed Java on your other computer
* you installed a plugin in your browser to let you run a newer version of Java in it than your maker provides, then the maker upgrades the browser and your plugin gets deleted or moved aside - or the prerelease plugin does not work with the new version of the browser
Most of these are problems with any browser plugin.
The idea behind the web is: point, click, cool.
The reality is that sometimes the web is more like: point, click, huh?
Eclipse Plugin Central - a rich biome of diversity bringing productivity
Eclipse is a very powerful Java IDE - but these days, a programmer has to work in a lot more than one langauge.
Fortunately, Eclipse is fully up to that challenge. It has a very rich environment for creating modular, yet interoperating plug-ins. They let it do a lot more than just Java.
Eclipse Plugin Central lets you see how many there are, and helps you find/get the ones you want.
Eclipse Plugin Central :: Eclipse plugin resource center and marketplace for Eclipse and Plugin Ecosystem:
If you need to do J2EE programming - or web development using Java and possibly JSP - then you should probably try out Eclipse Callisto. It bundles a bunch, so you don't get burned by version torsion stress and the integration blues.
Fortunately, Eclipse is fully up to that challenge. It has a very rich environment for creating modular, yet interoperating plug-ins. They let it do a lot more than just Java.
Eclipse Plugin Central lets you see how many there are, and helps you find/get the ones you want.
Eclipse Plugin Central :: Eclipse plugin resource center and marketplace for Eclipse and Plugin Ecosystem:
Eclipse Plugin Central (EPIC) offers the Eclipse community a convenient, information-rich portal that helps software developers find open source and commercial Eclipse plug-ins, tools, and products that enhance the entire Java software development life-cycle.
If you need to do J2EE programming - or web development using Java and possibly JSP - then you should probably try out Eclipse Callisto. It bundles a bunch, so you don't get burned by version torsion stress and the integration blues.
