Sunday, October 19, 2008

Managing Source and Class Files

This lesson obliquely answers a question not answered in the earlier lesson on creating packages. Quoting from the lesson: "Many implementations of the Java platform rely on hierarchical file systems to manage source and class files, although The Java Language Specification does not require this".

So in theory, it seems, you can put package members anywhere you like, but in practice it seems advisable to file them in an orderly way. If you use NetBeans, it will do the filing for you, with each project in a directory or folder and class files and source files in subdirectories or subfolders.

If you program by hand, this lesson recommends that you put package members in a folder which corresponds to the package name. It also suggests that (like NetBeans) you put your source files and compiled files into separate subfolders. This all seems very reasonable and sensible, but I still can't fathom why the information was not put up front in the lesson on creating packages.

And that concludes the Learning the Java Language trail.

But the lesson ends with a paragraph about setting the class path. And as my first Java Blog included a beef about the path instructions, before I start another trail, I shall revisit the path issue.

Friday, October 10, 2008

Using Package Members

This is an important lesson. Notwithstanding my comments on the linguistic style of the previous few lessons, java packages are central to the java model for sharing code.

Microsoft uses what they call dynamic link libraries (dll's) to store code shared by many applications. When you, the ordinary programmer, create an application which uses an object defined in a dll, VB, or whatever other programming application is being used, makes a note of it, and when you distribute the application, that, and any other dll you have used, gets included in the cab files. In contrast with the Java model, your own code is stored (after compiling) in an executable, and is not readily usable by other programmers or applications.

In the java model, it seems that even the most humble programmer, has the option of making the classes, which they create, usable by others. And because they have the option of doing so, they are encouraged to organise their work in the same manner which is required of paid programmers working in large organizations. Indeed they are more than encouraged. If they don't follow the rules, even for a very simple application, they are likely to come unstuck, as I discovered to my cost.

In a later blog, I shall describe in detail the fun I had with NetBeans, but for now all I need to say is that to make my code work, I had to create a custom class, and because I did not read this lesson properly, I attached my class to the wrong package, failed to import it properly, and nothing did work.

So the first rule of thumb is that if you are writing an application comprising objects from more than one class, attach all the class files to the same package. Now obviously if you want a graphic interface, you will apply code written by others, and which will belong to other packages. But if you are using a tool like NetBeans, a lot of the thinking on that side of it will be done for you. Where you have to be careful, is when you start creating custom objects from custom classes, because you have to assign everything you create to a package, and it pays to have done some thinking in advance as to how you are going to do this.

The "Hello World!" application sidesteps all these issues, because it doesn't call on any external code. It is entirely self contained. So it doesn't need to be assigned to a package. It therefore represents a very bad template from which to learn Java.

The BicycleDemo is more misleading still, because it does create objects from a class, and neither it nor the class from which the objects are created appear to have been assigned to a package.

In practice, it seems, you need to use packages, and if you create an object from a class, if the class does not reside in the package in which you are writing, you need to refer to the class by its qualified name (as defined in the lesson), or you need to import either the class or the whole package (again as described in the lesson).

Monday, October 6, 2008

How to Make a Java Package

After a singularly unconvincing lesson on the theory behind packages, there follows one on how to make them. And the opening is not auspicious: "To create a package, you choose a name for the package ... ". Gosh I'd never have guessed that. Never having created a file before, or a folder, or zip file, I'd never have guessed that you have to "choose a name" for java packages.

The level of these tutorials is not consistent. One minute they use undefined terms, and just assume you can work out what they mean. And the next go down to a level which can only be described as inane.

Is it Sun, is it Java, or is it Americans who just can't express themselves in writing. It can't be Americans. I had my doctoral thesis proof read by an American whose English was impeccable. It must be mainstream programmers, who just aren't used to writing in English. The bottom line is that it makes the learning process long, slow and hard.

After reading the opening paragraph fifteen times, the message seems to be that creating a java package involves not so much grouping a bunch of source files into a folder or zipping them into an archive, but rather a "belongs to" statement has to be included in each file. That's OK. It's not something I've had to do manually before, but now I've been told, I'll try to remember it. But why can't it be explained simply, and explicitly?

The second paragraph in the lesson is shorter, clearer, but still amazingly trivial. The "belongs to" statement must be in the first line of the source file, and check this out, each source file can only belong to one package - as if one is used to files having membership of multiple folders or archives!

There follows an insert containing more tangential gibberish, and then we see excerpts from six source files, each with an identical "belongs to" statement in the first line. Two contradictory thoughts arise from this. First do we really need six illustrations of such a simple construct? Second, is that it? Is that all you do to create a package? The location of the files in the local file system is apparently irrelevant? There is no compression or archiving of the source files into a single (dare I say) package? Apparently not. A java package is apparently just a collection of files which share a common opening statement.

Sunday, October 5, 2008

Package Theory

Here is a trail which should apply to everyone. Let us hope it is useful and easy to understand. Let us hope it is written in English.

Let us hope in vain.

Even the opening sentence of the opening lesson includes an undefined term. "To make types easier to find and use ... programmers bundle groups of related types into packages." From all the preceding lessons I hardly recollect the term type being used, let alone defined. A quick search through the lessons revealed one the more esoteric lessons: "Enum Types", using the term in the same context, but again with no definition. It is just assumed that you can read the authors mind, or can work it out for yourself. This is a bad assumption in a tutorial.

But then, as if as an afterthought, there has been inserted into the text a definition. Is it a definition of "type"? No; it is a definition of package, which is fair enough since that is the title of the thread. But the "type" is central to the definition of package: "A package is a grouping of related types ... ". And as an afterthought to the afterthought, a sort of apology for a definition is appended: "Note that types refers to classes, interfaces, enumerations, and annotation types." It's a pity the author doesn't know how to conjugate verbs, and its odd that the definition seems to be recursive, but it's better than nothing, and the author could, with grace, have stopped there. But perhaps a sixth sense told him (or her) that what had been written so far was grammatical and logical gibberish, so he (or she) fumbled on, still in the insert intended for a short crunchy definition, but now on the tangential path of a long and rambling essay: "Enumerations and annotation types are special kinds of classes and interfaces, respectively, so types are often referred to in this lesson simply as classes and interfaces".

Why not say that in the first place? Why not open the lesson with a simple definition, such as: a package is a group of related classes and interfaces? That would be too simple I suppose; not highfalutin enough.

The gibberish continues: "The types that are part of the Java platform are members of various packages that bundle classes by function: fundamental classes are in java.lang, classes for reading and writing (input and output) are in, and so on. You can put your types in packages too." Well thank you very much. But besides making our code files look pretty, why should we want to?

The text continues with the silliest example imaginable. The world is awash with graphics software, and has been for twenty years or more. This may be new and exciting for the boffins at Sun, who never properly weaned themselves from the command line, but why would anyone in the real world want to write code for creating plane geometrical graphics. And none of the reasons for bundling these files into a package struck me as particularly compelling.

Wednesday, October 1, 2008


When I read the trail on Generics the first time I fogged out. And when I read it a second time I fogged out again.

For me, key phrases include:

        // Imagine this is one part of a large application
// modified by one programmer.
        // ... and this is another, perhaps written
// by a different programmer

These phrases are a let out for me because I am a sole programmer working from home on a non-collaborative project. So the situation described with not apply.

Another key phrase is: "In any nontrivial software project, bugs are simply a fact of life". This tells me the trail has something to do with error trapping. This in turn raises two questions in my mind.

First, why is there nothing about error trapping or bug avoidance in the trail heading? Second, why is the first lesson which even mentions errors and bugs so incredibly esoteric? Why not have a basic lesson on bugs first, and then put the weird one in an appendix somewhere.

All in all I rank this trail below reference. For beginners I'd rate this a skip altogether trail.