Friday September 30, 2005

A subject that comes up regularly is how to mix HTML with JSF. There are several gotchas and limitations you need to be aware of.

1. The "content inter-weaving problem". The issue here is that if you mix and match JSF components and normal "plaintext", these are processed separately, and it's possible for the text to appear out-of-sync with the component. See this article for more information. However, the good news is that this issue is fixed in JSF 1.2! (Creator however is still using JSF 1.1; JSF 1.2 is not out yet.) You need to be aware of this issue, and obviously test your application thoroughly. The problem does not show up at designtime in Creator because we don't process the page using the normal JSP engine.
   • You can use a <f:verbatim> tag around your markup to make it "JSF friendly". This will force the embedded text to be processed by JSF rather than the JSP handler, so the right thing will happen.
   • In Creator 2 you can also use the <ui:markup> component. It's easier to use than <f:verbatim> for some use cases. It's in the Advanced palette.


2. Components that render their own children frequently don't handle HTML child content. (Examples of these are the Data Table, and the Panel Grid components.) These are the UIComponents that return true from getRendersChildren. These components specifically state that they want to handle rendering of their children themselves, and unless they are really careful, they won't pick up the HTML markup children nodes (whereas the standard child iteration used for most components does get this right.) Thus, for these components you need to resort to the <f:verbatim> technique again.


3. By now you may wonder why you wouldn't ALWAYS just put <f:verbatim> around your HTML tags - and all your problems would be solved. The problem is that what verbatim does what its name suggests - it renders its child content verbatim. That means you don't get to put other JSF components inside of it! You'll see your JSF tags emitted as text. In other words, you can't freely insert <div> tags around your JSF content to do normal HTML page layouts.


4. Your HTML needs to be well formed XHTML. This isn't necessarily a JSF requirement, although it should be noted JSF emits XHTML, not HTML. However, Creator requires this. Specifically this means that you need to remember to close your tags - I've often seen people write <br> which is invalid XHTML. It needs to be <br/>. As another example, remember that your tags need to be lowercase - don't insert <STYLE>color:blue</STYLE>.


5. The way you actually add HTML to your web pages is to switch to the JSP view and edit away. However, note that you don't get to write plain HTML there, because you're actually editing an XML-formatted JSP file. Tags work the same way as in HTML - you can for example add <hr> to add a horizontal ruler. But entities are different. They need to be "XML escaped". If you want to write the HTML entity for the Spanish n for example, ñ, you cannot simply write ñ. You have to replace the & with &. Thus, if you want the page to render in the browser as Piña Colada, in HTML you would have had to type, Piñna Colada, but in the JSP file you need to escape the & such that you end up with Piña Colada.

With all those potential problems, you may wonder why you should bother with HTML at all? It would be ideal if you didn't have to. However, if you restrict yourself to standard JSF components there is simply too much markup you cannot get to. For example, you cannot add a horizontal ruler since there's no component for that. In Creator 2 we have a new component library which adds a wide array of new components.

However, there are two remaining areas where you might find yourself resorting to HTML.

• Flexible layouts. If you want to achieve a really advanced layout that offers good resize behavior etc. you may need to resort to old-school HTML tables with rowspans and colspans. However, I urge you to consider using CSS for your layouts instead. It may be a bit harder at first, but it will pay off. True, CSS is not supported well in older browsers, but many of these older browsers aren't supported for similar reasons in the existing markup rendered for many components already.


• Pre-existing content. You may have existing HTML that you want to reuse directly - perhaps it was crafted by a web designer and you want the same look in your JSF app with no rewrite effort. You can import these into Creator using File | Add Existing Item. The screenshot on the right for example shows the java.net page imported into Creator. The import mechanism will not catch all the gotchas above however so you need to Test, Test, Test.

As should be evident from the gotchas list however, you need to consider this carefully.

Thursday September 29, 2005

A new episode of the Java Posse podcast is available. Episode #1 was an interview recorded a while back by Dick, so this episode is actually our first joint recording. It was a fun start.

Let me apologize in advance for using the phrase "you know" way too much. It's, you know, totally subconscious. Next time I'll try to slow down and reduce the you-knows. And Carl is getting a new microphone :-)

iTunes link

Wednesday September 28, 2005

NetBeans 5.0 Beta is now out. In my blog entry yesterday I wrote how easy the new plugin support made it to add my own favorite debugging function to the debugger. There's a long list of big improvements over 4.1. Click on the image to go to the "What's New" page and see descriptions with screenshots of the new goodies!

Tuesday September 27, 2005

Until now in this "column" I've written about source code itself: Don't use vanity tokens, don't capitalize acronyms, don't use tabs, and don't (over)use logging. Today I'd like to talk process instead: debugging.

The process of debugging usually involves mental verification: you step through the code, and compare what you think should be happening with what is actually happening. As you do this, you frequently have to decide if you should Step Into or Step Over method calls. On the one hand, you don't want to step over a method in case the bug is occurring within the method call. On the other hand, if you don't know where the bug is yet, you can waste a lot of time stepping through methods before the bug is triggered.

With the following technique however you get the best of both worlds. The approach is as follows: Always step over. If you detect that the bug has happened (e.g. some return value from a method is wrong, or a class field is changed into the bad value you're looking for, etc. etc.) then simply Retry the method. By retry, I mean pop the current stack frame and step back into the method! This gives you a primitive "Undo" function. Without restarting your program, you get to step through the method again.

Many debuggers offer actions to pop the stack, so you can use this technique today. What I really want however is a convenient action which does both of these operations (pop followed by step into), and have it located in a convenient place such as the debugging toolbar.

So I decided to try out the new NetBeans 5.0 module plugin development support. Holy cow! - It was unbelievably easy! In 25 minutes, I wrote a plugin (which adds a debugger toolbar action which pops the stack and steps into in one step), I generated a plugin bundle, installed it in the IDE and tested that it works on a simple test program. And this was as a first time user of the plugin support! I especially liked the "New | Action" wizard which automatically handled everything from icon and displayname to positioning the action in the menus and toolbars.

I'm not exaggerating - it took just 25 minutes. And I'm not bragging either; doing all this in 25 minutes says something about the productivity of the tool, not about my programming skills. There's a quick-start document available with more information on how to build plugins in 5.0. But I wrote the plugin while on the train commuting to work, and without a network connection I figured it out anyway on my own.

You can download and install the plugin yourself in NetBeans 5.0. As you can see, the main source file is very trivial.

The screenshot on the right (click for full size) shows the IDE in action; notice the new action in the toolbar (easily spottable by the ugly icon I supplied) as well as the plugin project in the navigator.

Anyway, you can use this retry technique as long as your IDE supports Pop Topmost Stackframe. It sometimes requires a little work on your part. If you're stepping through a method that has side effects (such as initializing fields), you may have to account for these. By "account for" I mean undo the side effect. Usually I handle it by clearing out the fields in the watch window after popping the stack. You did realize you can change values in the Value column and cause assignment in the debugged process, right?

Monday September 26, 2005

The iTunes directory has been updated to include the Java Posse podcast now. If you search for "Java" in the music store it's also the first match!

Click on the image on the left to subscribe. If you've already subscribed manually consider resubscribing so you're counted in the iTunes statistics.

Thursday September 22, 2005

The Improved JavaCast is here: Java Posse. A wild band of Java mercenaries riding through the frontier of .... ah never mind. You get the idea: A group of people talking about Java. The charter is the same: weekly programs covering the Java world. But the format will change. Less ranting. Shorter programs. Separate interviews. And the show will evolve based on feedback.

The set of anchors has changed too. The show will now be hosted by Dick Wall of New Energy, Carl Quinn of Google, and yours truly. I'm hoping Carl will use his insider status to get some of Google's A-list Java personalities on the air, and I will do the same at Sun... and by then the ball should be rolling!

There is already a first episode available. This one was recorded by Dick a while back under the JavaCast banner, but never got broadcast (JavaCast story here.) It's an interview with one of the people behind the IntelliJ IDE. I thought it was very interesting - and several of his metaphors work for me.

Unfortunately there's no subscription link up in the iTunes music store yet. I'll post it as soon as it's available. Please tune in, and if you have feedback on the format do share it. We'll record our first "new" show next week. For more details, subscribe to the javaposse blog at http://javaposse.com.

P.S. If you want, you can subscribe to the podcast manually now; in iTunes, go to the Advanced menu, select "Subscribe to Podcast" and paste in http://feeds.feedburner.com/javaposse

The morning commute. The San Francisco bay area has lots of radio stations to help you through it - provided of course you enjoy listening to commercials or "flipping stations". And despite the large number of software people in the area, the morning show topics are invariably the safe staple of morning shows anywhere: celebrity trash, traffic, and endless banter. Oh, and if there's ever a good segment, you can be sure it's right when you're about to lose reception as you're heading into a tunnel or the train is going underground.

One of my coworkers today asked me what the deal was with "podcasting". It is not named podcasting because people walk around recording their diaries on their iPods. Podcasts are basically radio programs. iTunes and your iPods have special support for podcasts, and treat them quite differently from regular music files. In particular, in any given program, it remembers where you left off. Therefore, if you come back to play the same program later (having played other music other podcasts in the meantime), it continues right where you left off. Podcasts are organized separately from other music, and is listed chronologically automatically. And today I discovered that if you hit pause, and later resume, it will back up a couple of seconds in the soundfile such that you don't miss a single word.

So, podcasting is really the ability to broadcast radio programs to pods - playing devices. This has some advantages. For example, since they don't rely on the airwaves for distribution, they don't have the same restrictions that radioprograms do, where the range is so limited they have to focus on topics of broad population interest. Instead, you can have highly specialized podcasts with listeners spread throughout the world. I've found it a great way to replace my constant radio frustration. Reception is perfect since you're not relying on an antenna. The topics are interesting since I picked them myself. And in addition to the special interest topics, I can get good radio programs like NPR's Nova and Jim Lehrer's Newshour.

Wednesday September 21, 2005

(See intro for a background and caveats on these coding advice blog entries.)

Remember how your ${NATIVE_LANGUAGE} teacher taught you to capitalize your acronyms? Please unlearn it. Thanks.

Seriously though... when you're writing code, you're not writing English. It makes perfect sense to choose symbol names that read well in your preferred human language. But CamelCase, the preferred capitalization scheme in Java code, is not proper English capitalization either. So don't carry over the acronym habit from English.

For example, use HtmlDocument instead of HTMLDocument. Use CssParser, not CSSParser. Unfortunately, many existing APIs violate this rule. Even the JDK has many violations - acronyms like IO, UTF, EOF, XML, SQL, HTTP, URL and URI abound. However, I think the trend is towards uncapitalized acronyms in newer classes going through the JSR process.

So why precisely should acronyms not be capitalized? For readability reasons. The acronyms are treated as words, not as individual letters, so when you're scanning a CamelCase word you can quickly see that HtmlDocument contains the words "Html" and "Document". So it's easier to visually scan, and I think it just looks better.

Unfortunately, it may be tricky to rename existing classes in your code. If you use CVS, changing class names that vary only in capitalization will confuse CVS on some platforms. On Windows two filenames are considered identical if they only vary in case.

Eof.

Tuesday September 20, 2005

Switch to your JSP, and inside the body tag, type

Now try the same thing, but edit the text inside a page fragment. If you deploy, you'll see this in the browser:

Uh oh! What happened?

Turns out the app server doesn't realize that the page fragment file, the jspf file, should be interpreted as an XML-formatted JSP, just like the main document. As a result, the source fragment file (which is just a static JSP include behind the scenes) gets, well, mistreated. You can see a very similar thing with entities. If you go and insert JSPX entities in your fragment, these will not be correctly expanded and instead of spaces you'll see things like " ".

Here's how you can fix this. You basically need to tell the deployment container that it needs to treat .jspf files as XML formatted JSPs. Unfortunately, you can only do that using JSP 2.0. That means this won't work on deployment containers that don't support JSP 2.0. The bundled one, Sun Application Server 8.1, does (as does 8.0 which we shipped with Creator 1.0, so this solution works for Creator 1.0 as well.)

Switch to the Files view (it's in the same window container as the project navigator), drill into your project, then open web/WEB-INF/web.xml. Switch to the XML view. Replace the root <webapp> element with the following:

<web-app version="2.4" xmlns="http://java.sun.com/xml/ns/j2ee"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd">

  <jsp-config>
    <jsp-property-group>
      <url-pattern>*.jspf</url-pattern>
      <is-xml>true</is-xml>
    </jsp-property-group>
  </jsp-config>

This is how this should look:

Now when you deploy, the page fragment text should be treated the way it's supposed to - and your Piña Colada will be on the way.

So why don't we just add this configuration info to the default web.xml we ship with Creator? Well, then you would no longer be able to use Creator with any older app servers. We're trying to hard to be compatible. However, we might be able to do something better here. I'll talk to Mr. Deployment to see what we can do.

Say hi to Winston Prakash - another Creator developer who now has a blog. Winston wrote the new CSS editor in Creator 2 that I described a while back. I sometimes call the CSS Editor the Winston Editor...

Saturday September 17, 2005

Creator 2 EA2 now supports JSF refactoring. Take a look at this screenshot of the Refactoring window:

You might think supporting Refactoring is a slamdunk since we're built on top of NetBeans 4.1 which supports refactoring. However, notice that we're doing a lot of JSF specific stuff here.

• We update value binding expression references
• We update navigation rules
• We update managed beans definitions
• We update web.xml if the start page has been renamed

Eric had to do a lot of work to get our Creator source modeller to play nice with the NetBeans one. Yes, we're working to resolve this architectural redundancy - that was partly the agenda for the August trip to Prague. Here are some of the suspects at our favorite breakfast bistro in Prague: Robert Brewin, Tom Ball, and Eric Arseneau. Yes, the Eric who did the Creator refactoring work. This particular cafe serves the largest lattés I've ever seen; not quite "Big Gulp" size but certainly a healthy morning dose to combat jet lag!

Wednesday September 14, 2005

An update to the early access version of Creator 2 is now available.

The high level changes in the update are described here.

Here's my own list of stuff to look for in the update - heavily skewed towards the changes in the designer and related areas!

• It now runs on (and in fact, ships with) JDK 5.0.
• Various memory leaks have been fixed so it doesn't deteriorate over extended use. However, performance work is still ongoing.
• We now have inline editing of buttons, textfields and textareas as well. Note that when you drop a button you immediately edit its name. This is to strongly encourage you to provide a specific label rather than relying on defaults (which vary from browser to browser, and can interfere with your layout.) To enter inline editing mode (which is done by default for buttons, but not for text fields), click twice, or hit F2, or use the Edit <Property> context menu item.
  
  (Tip: When you're editing text in a multi-line text field, enter inserts a newline. To commit the text edits, hit Shift+Enter, or as with any other inline editing operation, click outside the inline editing component. Press Escape to cancel editing.)
• Some new designtime behavior has been added for components. Check out the Tab Set for example. They now come pre-configured with an associated grid panel for each tab. The components placed in this grid panel will show up only when the associated tab is selected. Finally, easy tab panels without needing to create multiple pages! And in the designer you can click on the Tabs at designtime to automatically switch the rendered view so you can easily design each tab.
• The property sheet shows values that are different from the defaults in bold! See screenshot; style and text properties have been changed, whereas the columns property, 20, is just an inherited default:
  
• Page fragments work better now. I'll probably blog on that separately.
• Component metadata can now specify the default text for event handlers. These are now more helpful, hopefully giving you some specific hints as to what you need to do. For example, if you add a validate event handler for a text field, the default method inserted in your page bean is this:
  
  Note also that the parameter names in the event handlers are much better (they used to be composed by simply taking the capital letters from the type name; e.g. a FacesContext parameter would be named fc.) As you can see, it's now named context, just like in the interface definition for Validator.
• Creator now supports JSF refactoring. I'll wait a couple of days and see if Eric blogs on it (he did the work); if not I'll talk more about it.

Please take it for a spin and give us feedback.

Monday September 12, 2005

We have an update to Creator 2 Early Access which should go out any day now. One of the big things we fixed in the update is closing various memory leaks which caused Creator to slowly run out of juice. There are lots of other important improvements too - for example, Creator will finally run on JDK 5.0. But one big thing is still missing before we can ship it: Speed tuning.

I finally got done with my other 2.0 tasks last week, and have now started the performance tuning work in earnest.

It's really fun! I perform various tasks, look for hotspots, study the code and decide if (a) the code is doing something stupid, and (b) if the code is getting called too often. I've found several easy things to fix, so I've integrated a couple of things, sent e-mail to some other people when the bottlenecks are in their code. And in one case filed a NetBeans issue with my analysis.

The right way to performance tune is to measure the code looking for hotspots, rather than using your intuition about code you've written which is probably slow. So that's what I did - and I measured an enormous bottleneck in the CSS handling code.

This bottleneck has been there since 1.0. However, the bottleneck is proportional to the number of rules in your stylesheets as well as the number of elements in your document, so it doesn't show up for most pages created with Creator 1.0. However, in Creator 2, with our new nice themes, we have really large stylesheets which trigger the slowdown. And if your document has a lot of elements, which is pretty easy now with some of our new complex components, the slowdown is significant. As pointed out by the profiler.

This performance bug was really fun to analyze and fix, so I'll explain the gory details to you.

The problem is this: For each element in the document, we need to figure out which rules apply to that element. This was done by iterating over the rules, checking the selectors in each rule to see if they apply to the current element, and if so, "apply" the rule to the element.

The problem is that in Creator, the new Theme stylesheet contains nearly 800 rules! And of course, most of those rules contain multiple selectors, each of which must be checked! Then there's the possibility of additional stylesheets. There's the builtin user-agent stylesheet (which assigns HTML semantics for the element) as well as the project default stylesheet, and any stylesheets you've added yourself. Finally, some of the selector checks involved iterating up node hiearchies (for example, the :link pseudo tag means we need to see if the element is enclosed within an <a> tag.) To cut to the chase: some of the node iteration and selector check code would get called over a million times for a page render!

Clearly, this needs to be optimized. There is a straightforward technique to handle this which apparently is used by Mozilla's layout engine. I learned about it from reading David Hyatt's blog. That's right boys and girls - spending time reading blogs CAN benefit your daytime job! Give yourself a pat on the shoulder and resolve to return to my blog regularly :)

The technique is as follows: preprocess the stylesheet when it's first loaded, by setting up some extra datastructures which will make the later (frequently called) "find-rules-for-element" perform faster.

Consider the following sample rules:

 .Tab1Div table {border-collapse:collapse}
 .WizMst {background:#C6D6DF}

Therefore, when I preprocess the stylesheet I split up the set of rules into four categories. First, for any rules where I can identify a "tag name requirement", I add the rule to a hashmap indexed by the tag name. Then, for any rules that have a "class attribute requirement", I place these in a hashmap indexed by the class attribute. Similarly for the element id condition. Then I have a list of all the "remaining" rules, which don't have obvious tag/class/id requirements. These will need to be checked the old way against all elements. But amazingly, out of the 800 rules in the theme stylesheet, only 5 fit into this last category!

Now, whenever I need to compute matching styles for an element, I first look up its tagname, check for applicable rules in the hashmap, then do a full selector check on each one of these rules. Then I check the styleclasses in the class attribute with the class hashmap, and so on. Finally, I do the old-style iteration of the "remaining" rules. This effectively partitions the rules up into small buckets, one for each of the tag names, and one for each of the attribute names, so for each element I get to do a lot less work.

This does however add one complication: cascade order. I cannot simply process all tag-related rules followed by all class-attribute rules. Later rules in the stylesheet should "overwrite" earlier rules (modulo various cascade rules etc.). So after matching rules from my hashmaps and the remainder-list, I need to sort the rules into the right cascade order again.

The first thing to do was to verify that the optimization works - that pages still render correctly. They appear to. Check. Then I measured the performance differences to make sure I actually get an improvement and remove the bottleneck. To make it easy to check, I put the new code path under a global flag I could turn on and off. Then I ran style attribution with the optimization on, then with the optimization off, and compared the results. And the effort definitely paid off. For smallish pages, style attribution got a speedup of 12x. For large pages, I got a speedup of 8x!

Note that these speed improvements are not in EA Update - which has been out of our hands for a while now.

Check out these ads eventually rejected by "top business publications". clientjava.com claims it was Wall Street Journal - I have no inside information.

(There are more ads at the marketing site)

Sunday September 11, 2005

(See intro for a background and caveats on these coding advice blog entries.)

Should you use spaces or tab characters when indenting your code? This question has been debated at length in the past, with a fervor similar to the "emacs versus vi" editor debate. But unlike "emacs versus vi", we cannot just agree to disagree. We can each choose to use a different IDE. But the source code is often shared, and if there's one thing that's worse than a source file indented with tabs, it's a source file partially indented with tabs and spaces. This is typically the result of a file edited by multiple users.

My advice is simple: Always use spaces to indent. That doesn't mean you can't use the Tab key in your keyboard to indent - most tools will automatically do the right thing with spaces instead. In other words, the Tab key is the Indent key, not the Tab character key.

So why is it bad to use tabs instead of spaces?

There are several reasons. Obviously, there's the reason I started out with: that we really need to pick one convention. Spaces for indentation is the most common scheme used to today, so it's a reasonable choice on that basis alone.

One of the problems with tabs is that a tab character needs to be converted into whitespace by the editor when displaying the file. How much whitespace should each tab character be replaced with? In an ideal world, the old typewriter functionality could be used, where each tabstop had a certain pixel position. That way people could even use proportional width fonts in their editors (instead of the blocky monospace fonts used by practically all code editors today), and the code would still indent nicely. However, no editor that I'm aware of supports this, so that's not a practical venue. Instead, editors typically make an assumption that a tab is either 8 characters (common in ye old days) or 4 characters (common in Java editors today). Some editors will stick with the 8 character assumption, but support 4-character indents in Java (which is common), so when indenting to level 3, they will insert a tab, followed by 4 characters, to get a 12 character indent using an 8-character tab.

Why is this bad? Because code is viewed in more than one tool. In the presence of tabs, code often gets misaligned. Code integration e-mail diffs, code viewed in other editors, code edited by other tools which treats tabs in a different way will easily get "mangled" (e.g. start getting mixed spaces and tabs).

(Sidenote: In the old days, source files sometimes included a comment at the top of the file, with special "tokens" (-*-) intended for Emacs. These tokens would identify the language mode as well as the intended tab size for the file. When loading the file, emacs would use the specified tab size. Thus, the source files actually carried the tab information needed to edit the file as intended. However, this solution doesn't really solve the problem since all other tools which process and display the file would also need to be aware of this metadata.)

I've heard people put forward two arguments in favor of using the tab character:

1. If a file uses ONLY tab characters for indentation, it is easy for users to read code at their own favorite indentation level. In other words, I can read your source file with tabs=4, you can read it with tabs=2
2. It's easier to move back and forth indentation levels, since a single left/right keystroke will jump across tab characters, e.g. whole indentation levels.

Regarding argument 1: There are lots of other things I want to customize when I read other people's code too. You see, people don't all agree with my code rules that I'm putting forth in these blog entries :-) So if I read code that is indented poorly, or worse yet put spaces between function calls and the parenthesis, or other horrible coding sins, I hit Shift-F10 to reformat the source properly first anyway. This solution is more comprehensive than simply adjusting the indentation depth.

Regarding argument 2: I don't see a big usecase for being able to move the caret up and down indentation levels. These only apply at the beginning of the code line, and the Home key should alternate between jumping to the beginning of the line and the first nonspace character on the line. Why would you ever need to go somewhere else? Perhaps you want to move some code up an indentation level. That's what the Reformat feature is for. Just reformat the buffer instead.

(Minor sidenote: In Emacs, and I believe in JBuilder, the Tab key was bound to a reindent action, NOT inserting indentation. This is a much better use of the Tab key. When you're on a new line, pressing Tab should move the tab to the correct indentation level (reindent), NOT inserting say 4 characters. If you're on a line with existing code, hitting Tab should NOT insert 4 characters where the caret is located, it should adjust the line indentation such that it's correctly indented. Thus, if I put an if block around a piece of code, I can just hit Tab, Arrow Down a couple of times to indent the block correctly. I submitted a patch for NetBeans to do this a while ago but this behavior is apparently a bit controversial. For a previous XEmacs user like myself it's indispensable.)

All IDEs let you do this. (I even believe most IDEs default to using spaces. Please double check in your own.) Here's the option in the new NetBeans 5.0 options dialog:

The people who seem to rely the most on Tabs today are people using old-style editors where Tab characters are still the default. If you're using Emacs, add the following to your .emacs file:

(custom-set-variables
 '(indent-tabs-mode nil)
 '(tab-width 4))