First, you HAVE to manually download the Korean font I’m using (because I don’t think I can legally include it in the executable file :( )

http://www.i18nl10n.com/fonts/UnBatang.ttf

NOTE: you MUST (windows is rubbish) do “Save to” and select C:\Windows\Fonts (this causes windows to automagically “install” the font) – I can’t remember how to install new fonts on Linux or OS-X, but it should work fine with both of those OS’s too.

Then just stick the two attached files in a directory somewhere, and double-click on the one called korean-numbercounter-all.jar

Essential library (download this)
Main file (download this to same directory as the library file, and run this file)

NB: this is mainly just a proof of concept to test my rendering code, I’ve got a couple of other simple “games” like this I’ve knocked up as tests.

Quick test program using Java (NB: java one of the easier languages for this because it was invented late enough that Unicode had settled down, and so it has extremely good Unicode support built-in to the core libraries, unlike C++ et al. By default, Java uses unicode almost everywhere, so I don’t need to debug unicode support, yay!):

NB: …but then when I tried it I quickly discovered a problem. I quickly gave up on the obvious route, so might have missed a workaround, but… I could have done this using Java’s built-in GUI toolkit (Swing), which supports using any font as a text label. However, it seems there’s a design flaw in Swing that’s been around since 1997 (yes, folks, 11 years and counting): the only component that can have the font changed – JLabel – which is a “general-purpose” label for any GUI component (good idea!) … is incompatible with the only component capable of being a button – JButton – which is a “general-purpose” button. Crap. If I’m not missing something here, with one small piece of poor API design, Sun have made their *almost* international-friendly GUI system almost completely useless for multi-language GUIs. Just to be clear: it’s not specifically internationalization they’ve broken here: its a general issue – any forms of customized rendering cannot use the JButton / JLabel combo. Why? Why, why, why would you do such a stupid thing, after going to the effort of making these generic widgets? Oh, well. Custom rendering it is…

/**
 * Simple test program that renders Unicode characters from a particular font of
 * your choice, a couple of thousand at a time, automatically wrapping them based on
 * render width on screen.
 *
 * You need to manually change the font name and the start/end co-ordinates of where
 * in the unicode constellation to render.
 */

import java.awt.*;
import javax.swing.*;

public class PaintSomeUnicodeChars extends JFrame
{
	void setup()
	{
		getContentPane().add( new charPane() );
	}

	public static void main( String[] args )
	{
		PaintSomeUnicodeChars window = new PaintSomeUnicodeChars();
		window.setDefaultCloseOperation( JFrame.EXIT_ON_CLOSE );
		window.setup();
		window.pack();
		window.setSize( 600, 500 );

		window.setVisible( true );
	}
}

class charPane extends JPanel
{
	public void paint( Graphics g )
	{
		int si = 44032;
		int ei = 46000;
		g.setColor( Color.red );
		g.setFont( new Font( "Verdana", 10, 40 ) );
		g.drawString( "Chars from " + si + " to " + ei, 30, 30 );

		g.setColor( Color.black );
		g.setFont( new Font( "Lucida Sans Unicode", 10, 20 ) );

		int accumulator = 0;
		int height = 20;
		int xwidth = getWidth();
		for( int i = si; i < ei; i++ )
		{
			char[] chars = Character.toChars( i );
			String drawString = String.copyValueOf( chars );
			int advance = g.getFontMetrics().charsWidth( chars, 0, chars.length );

			if( accumulator + advance > xwidth )
			{
				accumulator = 0;
				height += g.getFontMetrics().getHeight();
			}

			g.drawString( drawString, accumulator, height );

			accumulator += advance;
		}
	}
}

Why choose Lucida Sans Unicode?

Apart from the fact that it’s present on all modern Windows machines automatically, I cheated a bit and used Character Map (Start > Programs > Accessories > System Tools > Character Map) to quickly inspect each of the fonts already installed and find out which ones had lots of unicode in them. Character Map has a neat feature where it completely ignores missing characters, automatically skipping over them, so you can very quickly see if a font has lots of unicode, some, or very little.

Stepping through in the java app, I fairly quickly found lots of Unicode characters. success – I can correctly render arbitrary Unicode characters in java.

NB: important because it took a lot more lines of source than I expected; java’s built-in “char” datatype is incapable of being used to render Unicode, because it’s too small a range of values. That also means you can’t use ANY methods that take a char as argument (this is documented in the Java API docs for Character). I’d never really used the methods that take int’s as argument before…

Fonts…

Not really happy with the font, though, and it’s clearly missing a whole bunch of characters. Some googling for free CJK fonts found me that allegedly Arial Unicode MS would work – which comes free with Microsoft Office (which I have on one of my machines).

NB: the way font licensing works, it’s probably illegal to copy a font you have on one machine to another machine you own. Unless you can obtain the font from the original source (e.g. in this case by buying a second copy of MS Office).

Arial Unicode MS has lots of characters, but … they’re wrong. At least, one third of the ranges of Korean characters are completely useless, as far as I can tell, because whoever made this font (whoever Microsoft licensed it from?) didn’t read the spec carefully and stuck the wrong characters in from U+1100-U+11FF. More on this later…

Giving up on that font, I went looking for others. The first four or five I tried that didn’t look ugly were all from download sites in Japan or Korea and kept crashing on the download. I found a couple of places hosting UnBatang (”UnBatangOdal.ttf”) and claiming it was free, but the first I found where the download didn’t crash was on http://www.i18nl10n.com/fonts

UnBatang (the name you have to use in Windows / Java from inside an application in order to load it) seems to work very well. It has nicely painted ideographs for the main range of Hangul characters/syllables, and it has *correct* glyphs for the other two ranges (although they’re a bit ugly).

Unicode Hangul

Specifications for official standards tend to be big. Really big.

Specifications for anything to do with internationalization tend to be huge.

Add in localization and data-transfer between different cultures, and you can expect something gargantuan.

So, I was really really happy to find a downloadable copy of only the CJK Chapter of the Unicode 5.0 specification (it’s still a big document!). This contains a full explanation of what Hangul is in Unicode, where to find it (yay!), and why there are not one but three separate sets of Hangul glyphs.

Here’s the preface to the Chapter 12 PDF I downloaded, in case you want to find the spec / electronic version yourself:

Electronic Edition

This file is part of the electronic edition of The Unicode Standard, Version 5.0, provided for online
access, content searching, and accessibility. It may not be printed. Bookmarks linking to specific
chapters or sections of the whole Unicode Standard are available at

http://www.unicode.org/versions/Unicode5.0.0/bookmarks.html

Purchasing the Book

For convenient access to the full text of the standard as a useful reference book, we recommend purchasing
the printed version. The book is available from the Unicode Consortium, the publisher, and
booksellers. Purchase of the standard in book format contributes to the ongoing work of the Unicode
Consortium. Details about the book publication and ordering information may be found at

http://www.unicode.org/book/aboutbook.html

Unicode 5, Hangul, and Arial Unicode MS

So, armed with the offical spec, I read up on Hangul. What did I find?

The Unicode Standard contains both the complete set of precomposed modern Hangul syllable
blocks and the set of conjoining Hangul jamo. This set of conjoining Hangul jamo can
be used to encode all modern and ancient syllable blocks.

(this is the glyphs at U+1100–U+11FF)

“conjoining Hangul jamo” means “these glyphs have been positioned inside their spaces in the font so that if you need to make one ideograph out of, say, four Korean letters, you just pick the top-left version of the first letter, the top-right version of the second, etc, and OVERLAY all the glyphs, and what comes out will autamatically be correctly spaced out etc”.

What did the author of Arial Unicode MS do?

Made all those glyphs take up the full available space, and centre them horizontally and vertically.

Why? Seriously, why? Because any application that tries to render those characters is going to render them on top of each other (according to the specification, this is the ONLY point of having those characters), and you won’t be able to read at all what the letters say.

If you want to render just individual letters from the Korean alphabet, there’s a different range of Unicode where you can find them all centred etc (which Arial Unicode MS also has … so it seems to be just copy/pasting internally).

I guess the font author just didn’t read the spec. Or I’m completely misunderstanding the spec. But the fact that UnBatang spaces the conjoining jamos out in such a way that this works as I expected it to suggests to me that it’s the Arial Unicode that’s broken…

The joy of Conjoining

I couldn’t get hold of the Unicode spec section on how to conjoin, because of some mimetype problems between their server and my PDA’s web browser. I figured I could probably work it out by trial and error fairly quickly.

I can’t remember how to spell my name in Korean yet – I know the letters, I’m just a bit flaky on what the placement of them is. So, a quick experiment, to see how easy it is to position characters using the Conjoining Jamo from UnBatang:

	... constants used later - the Unicode values for the letters of my name: ...

	int a = 0x1161; // jungseong vowel
	int d = 0x1103; // choseong consonant
	int d2 = 0x11ae; // jongseong consonant
	int m = 0x1106; // choseong consonant
	int m2 = 0x11b7; // jongseong consonant
	int blank = 0x110b; // silent char you place at front if first letter is a vowel

	... the body of the paint method: ...

	g.setColor( Color.black );
	g.setFont( new Font( "UnBatang", 10, 30 ) );

	int w = 0;
	int lead = 0;
	w += renderIdeograph( g, blank, lead, 40  );
	w += renderIdeograph( g, a, lead+w, 40  );
	w += renderIdeograph( g, d2, lead+w, 40  );

	lead+=30; w = 0;
	w += renderIdeograph( g, blank, lead+w, 40  );
	w += renderIdeograph( g, a, lead+w, 40  );
	w += renderIdeograph( g, m2, lead+w, 40  );

	lead=0; w = 0;
	w += renderIdeograph( g, blank, lead+w, 80  );
	w += renderIdeograph( g, a, lead+w, 80  );

	lead+=30; w = 0;
	w += renderIdeograph( g, d, lead+w, 80  );
	w += renderIdeograph( g, a, lead+w, 80  );
	w += renderIdeograph( g, m2, lead+w, 80  );

	... and then this method to do the paint of each part of an ideograph: ...

	/** Doesn't really render an ideograph, renders a single glyph from the Font */
	public int renderIdeograph( Graphics g, int i, int x, int y )
	{
		char[] chars = Character.toChars( i );
		String drawString = String.copyValueOf( chars );
		int advance = g.getFontMetrics().charsWidth( chars, 0, chars.length );

		g.drawString( drawString, x, y );

		return advance;
	}

Which renders exactly like this:

Which makes me want to point out the nice thing about properly specified fonts: in the source code, I simply did “the natural thing”, as if I were outputting characters in an arbitrary conjoined language:

1. Render the first part of the first ideograph at (x,y)
2. Ask the font to tell you how many pixels wide (w) it just rendered that part
3. Render the next part of the first ideograph at (x+w,y)
4. …repeat until first ideograph is complete, increasing w more and more each time…
5. Choose a value for how much you want the ideographs separated from start to start (ideograph_width)
6. Render the first part of the second ideograph at (x + ideograph_width, y)
7. …repeat as for first ideograph

And it worked. First time. I didn’t expect it to – I expected to have to do something strange like manually “reset” the (w) value each time I went from the first line of the ideograph to the second (Korean orders letters top-left, top-right, bottom-left, bottom-right, (repeat) … as opposed to Latin which is just left, right, more right, even more right, etc).

For this to have worked, it means the font is deliberately rendering the lower letters (e.g. d2 and m2 in my constants) a long way to the left of the origin that you tell it to render them at. This would be very, very confusing if you just tried to render these letters individually (well, duh).

Of course, if you try to run that code using Microsoft’s Arial Unicode MS font, you get a complete mess instead, because that font is FUBAR, as mentioned before. You get this:

…which is completely incomprehensible.

Specifically if you want to be a Computer Scientist, I’d say that the initial claim that “java is bad as a first language” is true, just as “C++ is bad as a first language” is true. What disappoints me is that they go on to suggest that C++ is good as a first language (disclaimer: my uni course taught ML as first language, ARM assembler as second).

Do you want to be a Computer Scientist? Why would you want that? Well, the article makes some good points in that regard – essentially, if you want to be an OK-to-good programmer, then it will help to be a CS, but not required, but if you want to be a *great* programmer, you absolutely need to be a CS. So, if you’re not interested, stop here :). But if you hope to be a really good programmer one day – or to understand those who are – read on.

Objections

- I could defend using a very pure, low-level assembler as first language (preferably a very modern one, with very logical syntax – ARM is the best example I know)

- I could defend using a very pure, low-level functional as first language (preferably one with a really good IDE and debugger, I haven’t used any recently enough to know of any with particularly good IDE’s that beginners would find easy :( )

- I could probably even defend using a very pure, low-level data driven language as first language (I have too little experience with data languages to make a good suggestion here), although I don’t think that would be as useful as either of the first two options.

But anything C-derived seems to be an excuse for avoiding teaching the fundamentals of computer science: you should either be teaching the theory (as the article laments we are not currently doing), or you should be teaching the hardware (as it also laments, but less forcefully, and seems to mention only as an excuse for why C is good). Or…you should be accepting that you’re not [even attempting to] teaching either. C/C++/Java force you to learn neither of those things, so make for poor first languages IMHO.

Assembler

Teaches you to be REALLY good at the meat of programming: the individual lines of code that follow one after another within any chunk of a program, such as the body of a function or method.

Functional

The closest form of programming to the theoretical mathematics of programming, and hence the easiest in which to achieve a lot of solutions (for instance, parallel programming such as needed to take advantage of multiple CPU’s or multiple servers in a cluster is orders of magnitude easier to do in a functional language).

Data-driven

Much of the programming problems in the world come down to manipulating, generating, or managing data. Data languages don’t get much attention because they aren’t general-purpose languages, but they’re the best choice for a big chunk of the systems that most programmers will spend most of their lives working with. Amongst the non-general languages, they’re probably the most useful to a modern programmer (sheer speculation on my part there – feel free to smack me down for my foolishness :)).

Flamebait articles

In passing, I wanted to comment on the article itself. Mainly because on the whole it’s a GOOD article, making some good points and bringing attention to some problems that have been allowed to get out of hand – but I can’t recommend it without reservations, because in some respects it’s deeply flawed. To people under-experienced in this stuff (e.g. undergraduate programmers, and high-schoolers choosing CS degrees) I think it would be easy to be misled by some stuff in the article that really isn’t fair.

The way the article has been written makes it easy to speed-read it and recycle it as food for a “java is bad” argument :(. As noted at the start, I think the arguments for this aspect ALL hold equally true for declaring that “C++ is bad”, but the author not only glosses over this but instead even has a half-hearted attempt to argue the opposite. To see this as justification for either argument would be foolish, of course, but it’s easy to see how pre-prejudiced (i.e. flamers and trolls ;)) people will do that. I’m sure it will happen, although I don’t think the authors meant it that way (if anything, I think it’s an extended attempt to elevate Ada in people’s estimation). In the modern internet world, on certain topics (such as anything that compares and contrasts programming language) you have a duty to be extra careful about how you present your arguments.

Given the way the article starts (by poking java), I’m particularly disappointed that the “Why Java matters” section misses out any of the stronger benefits of java in particular, mainly I think because they wanted to mention them in the Ada section (where several of them appear), and didn’t want the fact that they’d mentioned them in the java section to weaken the argument (I note that C#/.NET/CLR isn’t mentioned at all either – if you’re even going to try to defend java as a choice, I think you should mention other managed languages).

I also think it’s odd that they would choose LISP as the only functional language represented. Not just because I’m an ML fanboy :), but because IME, functional languages fit much more closely to standard human approaches to problem solving than imperative languages.. If you’re going to pick the ideal language to teach students first, it would be a functional language, so there ought if anything to be MORE fn langs than imperative ones in the list – but it’s the other way around. I think if they fairly compared both fn and imperative, the fn langs would probably win the majority of reader mindshare. I think the main reason they didn’t include them is probably their desire to make Ada seem good, as mentioned above.

That’s purely my personal opinion, of course; take it or leave it…

Download, documentation, license details, tutorial etc after the jump…

EDIT: I’ve now created a SourceForge project for this project – http://javanioserver.sourceforge.net/

EDIT2: Because Wordpress is utterly, utterly crap at allowing you to have category pages, the old “main news page” for the project no longer exists. Blame Wordpress, and hope that *one day* they will bother to fix their code so that it supports this standard blogging feature :).

Download

The most important thing is the full source code (DOWNLOAD FROM SOURCEFORGE LINK ABOVE), but if you decide just to use it as-is, you’ll probably want the much smaller binary-only jar (DOWNLOAD FROM SOURCEFORGE LINK ABOVE). NOTE: both jars have an auto-run that runs a very simple Hello,World! server so you can check they are working OK.

You’ll also need log4j (the fast, powerful, and extremely widely used open-source logging-library) – if you want the application to auto-run, you’ll need to name your log4j file “log4j-1.2.8.jar” (there’s a copy of the latest version here (DOWNLOAD FROM SOURCEFORGE LINK ABOVE), already renamed for you, that you can download directly; sorry, that was my mistake when building the JAR).

Finally, there are fully-documented javadocs here that should answer all your questions and explain how to use this library.

Why did I make this?

Mainly because Sun’s NIO libraries are good, but very low-level, with a few major flaws and a few unfixed bugs,
so that it takes a lot of time and effort to make even the simplest of working
client/server applications with them. This small, simplistic library (fewer than 1000 lines of code)
is designed so that you can:

• easily implement a new single-threaded, non-blocking NIO server in minutes
• edit the fully-documented source to customize it any way you need
• read all the source code and understand how it was done so you can make your own servers from scratch

In case you weren’t aware, MOST resources on the internet providing source code
for Java NIO servers are WRONG and FULL OF BUGS that mean they WILL NOT WORK -
including BOTH of the O’Reilly books I’ve read (”Java NIO” and “Learning Java”).
That’s pretty shameful considering those are both extremely widely-used books :(.
In both cases, the authors clearly A) never read the API properly, and B) never
actually tried writing any NIO server code in their life. Or, at least, they
wrote it but never ran it on the internet – a glance at their source code shows
it won’t work except on a local switched LAN, and even then only for VERY simple
programs.

So, although this library is NOT particularly optimized (mostly in that it is
wasteful with how it creates ByteBuffers), it DOES ACTUALLY WORK and is pretty
simple and well-documented, so hopefully you can use it to make your own servers.

Why string-based, and TCP only?

TCP only: because I created this for “incubation” projects – i.e. small game
experiments I wanted to try out. The code supplied will actually work reasonably
well for most realtime games with current internet performance (I’ve made various
simple multiplayer games with it) – but if you find your game is particularly good
and want to make a proper multiplayer version over the internet, you’ll want to
replace the TCP with UDP. That will be very, very easy to do – but not necessary
for the majority of people who are just making simple games.

String-based: because A) you ALWAYS need strings! (what, your game has no in-game
chat? Shame on you!), and B) it’s much, much easier to debug, and C) when you’re
developing code very fast (I’m using Scrum) strings allow you to use “fuzzy”
message protocols, such as XML + XPath, which means that when you switch around
features, or change the message format, most of your code carries on working fine.
Binary protocols tend to break every time you make even one tiny change.

When you get to the point where strings aren’t good enough performance for your
game, you’ve already got a pretty damned advanced game, and you’ll find the only
thing you need to do to make this server work purely in bytes is to REMOVE lines
of code (all the Charset encoding and decoding) and to change one or two method
signatures to accept bytearrays or bytebuffers instead of strings as argument.

(I assume you’ve already had a look at part 1 and part 2? They’re more beginner-oriented)

Bugs, Misconceptions, and Subtle Features

Interfacing with Facebook’s servers is pretty hard, considering how seemingly trivial the interface is. Obviously the almost total lack of documentation is mostly to blame for this, but some of it is just common bugs that have yet to be fixed.

So, here’s ten things I’ve found whilst fiddling with the API, and some of the nicer features that may not be immediately obvious even if you do read the docs provided by FB (you should go read all of them, but … there’s some bad organization and layout, so it can be a chore reading the mega-long HTML pages, with many of the API features having just blanks for description fields :( ).

#1 – FacebookRestClient.java is broken (bug)

I’ve had a couple of problems with this class, provided by FB themselves, although most of them turned out to be just inconveniences / bad design. This one, however, is clearly a bug, since it’s impossible to use some of the methods in the class until you fix their source code.

NOTE: I’ve done this for you, at the bottom of this page is a link to download a “fixed” version of the source, along with some other useful files. What follows is FYI in case you want to make the change yourself…

In line 103, you need to change:

protected class Pair<N, V> {

to:

public class Pair<N, V> {

Note: without this, you cannot legally create instances of that class from within your own code.

If you cannot create instances of that class, you cannot provide the arguments to the handful of methods that REQUIRE a Pair<N,v> (or a list of them) as one of their arugments.

I’m not sure why the author of the class made this class protected – seems to just be a silly mistake. I imagine they thought that perhaps “it’s an internal hidden class – therefore I must hide it” … but it seems to exist mainly to be one of the REQUIRED arguments to the public methods, so this is obviously wrong. Oh well.

#2 – Callback URL is not a page, it’s a directory

This one is annoyingly subtle – everywhere you use the callback URL, and create canvas pages, this isn’t explained. When you are REQUIRED to invent a URL for this, you’re not told what it really is. Instead you have to dig into the docs to find the following nugget:

If you want to create Facebook Canvas pages, you must specify a directory name for your pages. Directory names are unique so you cannot have a name another app has claimed. Once you specify a directory name, going to http://apps.facebook.com/YOUR_DIRECTORY_NAME/pagex.abc will render pagex.abc from pagex.abc in the Facebook Canvas.

Note: that is CORRECT even though it appears to have a typo – Facebook really does render the page pagex.abc with no slash inserted between the two parts – if you don’t put a slash on the end of your Callback URL when you type it into the Create Application form, you’ll find there’s no slash between the Callback URL and the “pagex.abc”.

Note2: You can, in fact, deliberately request “http://apps.facebook.com/YOUR_DIRECTORY_NAME//pagex.abc” (note the double-slash) to cause FB to insert a slash in the request it sends to your webserver. But I woudl advise against this – it’s the kind of behaviour that’s likely to be removed in the future, since double-slashes are not legal in URL’s IIRC (c.f. the URL/URI RFC’s if you’re interested…), and are usually a sign of attempts to hack a server (so are strongly discouraged).

I’d actually given up on creating canvas pages, and had just moved to doing everything with relative iframe links. This is, apparently, WRONG (and probably explains some of the other inconveniences I’ve had to date).

So, to be entirely clear, here’s the way you should make your Canvas pages (I think!)

1. When you choose a Callback URL, make sure you type it in with a slash on the end
2. Each page you want as part of your app you should link to as “[callback URL]/[page name]“
3. In J2EE, map a servlet (in the simplest case; get more fancy if you prefer using struts etc) onto the directory path
4. Configure that servlet to handle authentication (see my previous post on how to do facebook authentication)
5. …and to chain the request to a different servlet by reading the “[page name]” part of the incoming URL

NB: there are various ways of doing that more elegantly in J2EE. I don’t want to start writing a tutorial on J2EE, so I’m not going to go into them – there’s tonnes and tonnes of info and docs on this stuff if you don’t know it yet … google is your friend!

#3 – Facebook apps can ONLY change things when one of their users is in the middle of using Facebook

You CANNOT perform actions with the FB API unless at least one of your app’s users is actively logged in to Facebook AND is using your application.

This is by design, but it has some nasty knock-on effects. Essentially, it seriously limits your ability to interface FB with other applications and networks, because although FB users can have arbitrary effects on external data, external data is forcibly prevented from having any effect on FB.

Example? Well, you can only post to the newsfeed of user X if user X themself is currently using FB *right now* at the moment you want to do the post. That means that you cannot, say, post to someone’s newsfeed (and by extension to all their Friends’ feeds for free) each time “someone visits my MySpace page” or each time “someone rates me a 10 on HotOrNot”.

There are workarounds:

Workaround 1: many of the API actions can legally be peformed for ANY of the “users of your application” if “any” of the other users are actively logged-in. For instance, you can query the friends of one of your users so long as at least one user is logged-in. Assuming your app is popular, there will always be SOMEONE logged-in, and you can piggyback of that logged-in user to refresh other data inside your app that depends upon reading info from facebook.

Workaround 2: In particular, anywhere that you use FBML, you can insert an tag, and for a given fb:ref it is possible – with a single method call – to simultaneously update ALL Facebook pages (every user profile, for instance) that has the fb:ref tag in it.

The way the tag works is that you include something like this:

<fb:ref url="http://yoursite/facebook/profile-FBML" />

inside the FBML you “set” as each user’s profile-FBML for your app.

Sometime later, perhaps once every hour – and only when you have a logged-in user who’s Facebook authToken you’re using! – you call:

// See item #10 on this page for more info!
iFacebookClient.fbml_refreshRefUrl( "http://yoursite/facebook/profile-FBML" )

…and ALL the user profiles will update simultaneously. Allegedly – I haven’t tried this yet myself, I’m only using FBML a very small amount at the moment. I’ll update this as and when I have problems / find solutions / etc :).

NB: this ONLY allows you to update the “common” or shared parts of people’s profiles (or whatever FBML you’re setting) – it doesn’t allow you to update customized FBML for each person.

i.e. you could use it to have a “top 10 leaderboard of all users” that appers in everyone’s profile and updates frequently seemingly automatically, but you could NOT use it to have a “your position on the leaderboard” that updates automatically (you would only be able to update that part for each user when that particular user simultaneously logged-in to your app and to facebook).

However … you can still use workaround #1 to update EVERYONE’s profiles manually, one-by-one, whenever ANYONE is logged-in, because the method call to update an individual profile has an optional argument that lets you specify exactly which profile to update – it doesn’t HAVE to update only the profile of the logged-in user.

#4 – Javascript is not allowed in FBML

Currently, Javascript is not allowed. If you include attributes like onClick, onMouseOver, onKeyUp, etc. we will strip them out.

So, in case you were wondering, *that’s* why your javascript ain’t working…

#5 – CSS is not allowed in FBML (with exceptions)

Referencing external CSS stylesheets is not allowed, but you can use style tags and put your CSS definitions there.

I *think* that’s another typo (argh!) – I think they meant “but you can use style ATTRIBUTES” (i.e. the person writing it didn’t realise that style=”" is an HTML attribute, whereas HTML tags look like this: <span></span>).

i.e. you are NOT allowed to do this:

<head>
< ... stylesheet href="...">

(you’re pointing to the stylesheet on some other website (even your own website) on the internet, using the URL of the stylesheet to tell HTML to pull it in)

…but you ARE allowed to do this:

<span style="border-top: 30px; margin-right: 0; text: #ff0000;">
some formatted text
</span>

So, you’re allowed to “use” CSS within the HTML, but you just aren’t allowed to make your HTML clean, readable, easy to edit, or easy to debug. That sucks. Most people who use CSS will avoid doing “CSS in style attributes” like the plague – it’s messy and horrible and really hard to maintain.

But at least you can actually use CSS, instead of being forced to write 10-years-old HTML from the pre-CSS days.

#6 – The Create-App HTML form (bug)

The create-app page on FB is broken – it periodically saves its data to the live servers, but the data it displays that it THINKS it has saved is not the same as what has ACTUALLY been saved. If you change e.g. your Callback URL, it will APPEAR to change on the settings, but it won’t have changed in real life, but then if you refresh the settings it will APPEAR to have reverted to the old value, but if you “edit” it using the link provided, the value in the textbox will be the NEW value (that it has just claimed it is NOT using).
This is very confusing, and a silly bug, but what it means is: when you change your callback URL, just keep trying refresh on your canvas page URL (apps.fb.com/yourapp) until it finally “works”. Some people have had to wait hours for this to happen, others waited minutes. I found it took around an hour to update.

Also … that whole page is a nightmare. It’s badly explained, it has far too much text, and critically important concepts (like your Callback URL, which is almost the only thing on the whole page you have to fill out, but which – contrary to the instructions! – you HAVE to fill out) are buried deep within it. c.f. Item number 2 above for more info just on the Callback URL alone, info which SHOULD have been embedded in this form.

#7 – Fancy GUI hide/show effects for free

Adding the attributes clicktohide and clicktoshow, you can dynamically hide and show content rendered with FBML

FB even give an example (how nice of them):

<span id="cdc03" style="background: yellow">this can appear and disappear</span>
<input type="submit" clicktohide="cdc03" value="hide"/>
<input type="submit" clicktoshow="cdc03" value="show"/>

#8, #9, and #10 – FacebookRestClient.java is very bad java (bug)

Actually, I got fed up with this crappy class. Problems include:

1. It’s not an interface
2. It’s got bugs (c.f. the Pair inner class bug above)
3. Many methods are 100% undocumented
4. The class itself is 100% undocumented
5. Some of the undocumented methods have undocumented REQUIRED ways to call them

So … I took their source code and refactored it.

1. Get the new interface here (compile all your code against the interface – anything less is just Bad Java Coding)
2. Get the new “main implementation” here (this is almost 100% the original official FB source code, just refactored a little to fix some nasty design flaws in their use of conflicting method signatures)
3. Get the new “Pair” class here (used to be contained within the old class with incorrect signature (see the bug above about this), now refactored into separate source file)

Epilogue…

I hope these prove useful to you. If you have any problems, or want more tips on using Facebook, feel free to leave a comment. This is the third post I’ve done on how to write facebook apps, and I’ve got at least one more I want to do yet. If you want to keep up to date with these, add the “facebook” category on this blog to your RSS reader (see also part 1 and part 2)…

NB: if the quoted source code is unreadable because it disappears off the edge of the screen, select it and copy/paste (or view source of the page to see it). The most useful stuff is put together into one class you can download here – source code for FacebookLoginServlet.java.

iFrames vs FBML

Facebook apps can be implemented one of two ways, iframes, or FBML.

*** – NB: actually, the way Facebook have designed their system, you need your own webserver anyway, they won’t let you make a Facebook App without one. So, although in theory FBML would be a faster and simpler way to get a basic app up and running, in practice, it doesn’t save you any time or effort at all.

Mostly, I’ll be assuming you want to write your app using iframes instead of FBML. FBML is great, and for some parts of your app you will want to use it, but the fact you can’t debug it makes life extremely difficult. If you can get all your code working with iframes first, then it will be relatively easy to switch some bits to FBML when the time comes. It’s much harder to try things the other way around.

Facebook Apps: Detailed explanation

What happens when a Facebook user tries to use your Facebook App?

1. User opens their web browser
2. Finds a link to your app – usually your Canvas Page URL (http://apps.facebook.com/[your app name])
3. Clicks on the link
4. Web browser goes to that site (part of FB) and asks for the webpage
5. Facebook sends back the Facebook navbar, with an empty iframe in the centre
6. Facebook redirects the browser to your site to get the contents of the iframe – AND adds extra information to the request from the user
7. Web browser automatically goes to YOUR site, sending the extra information FB provided it
8. Your site creates a webpage, and sends it to the user’s browser
9. User’s browser renders your webpage inside the iframe embedded inside the page it got from FB

…but what does this look like to the user?

1. User opens browser
2. Clicks on the name of your app
3. Your app appears on the screen inside the navbars etc for Facebook

So, the first thing to understand, especially if you’ve used FB a lot yourself, is that there’s a lot more going on behind the scenes than appears to the user. This will become especially clear when you make a mistake and start trying to debug your app.

Authentication

There are two “modes” in which you can create a webpage to display as part of your app:

• Default
• Authenticated

In the default mode, i.e. if you do nothing special, you have NO ACCESS to any of Facebook’s data. You cannot find out ANYTHING about the Facebook user – you can’t find their name, you can’t find their friends, you can’t post items on their Wall, nothing.

In the authenticated mode, you have full access to:

• read all the data of the currently logged-in user
• most of the data of all OTHER users of your app (people who have “added” your app to their Facebook account)
• send messages, post newsitems, etc, from the logged-in user (but they have to OK this manually)

Authenticating in java

FB provides you with a java class, FacebookRestClient.java, which you can use to authenticate with the FB servers. Once you have authenticated an instance of this class, that class will then ALSO provide you with access to all the features of Facebook (reading data about users, sending messages to other users, etc).

FB has partially documented the way that authentication works, but there are lots of missing details. In particular, there is no documentation on how to use the FacebookRestClient class to do authentication, and several of the methods that appear to work together are actually mutually exclusive. This is because that one class is responsible both for doing Web-based apps (the only kind of app that most people have ever seen or used on Facebook) and Desktop apps (which do exist but are much less common right now).

In brief, you need to:

1. Generate a URL for a custom login page for your app (http://www.facebook.com/login.php?api_key=[your api key goes here] )
2. Send a redirect to the user’s web browser to force them to go to that page
3. …Facebook will then redirect them back to your “Callback URL” page…
4. Read the “auth_token” parameter from the HTTP Query String
5. Instantiate an instance of FacebookRestClient using your API key and your API secret
6. Invoke .auth_getSession( auth_token ) using the value of auth_token you received

Authenticating your servlets

Now, you may notice a problem with the above sequence of events. Traditionally, when writing a J2EE app, you have multiple servlets, one for each “page” of your website – but in order to authenticate, the servlet MUST redirect the user back to Facebook, which will then ALWAYS send the user back to your Callback URL page, which means they will be sent to the “wrong” page.

Note: just because you redirect the user to Facebook’s login page doesn’t actually mean the user SEES a login page – if they are already logged-in to Facebook, FB just automatically sends them straight back to your site (but this time, it gives your site the login information, which doesn’t otherwise do!)

So, effectively, Facebook ONLY ALLOWS ONE SERVLET to authenticate with Facebook – whichever servlet you gave the address of when you filled in the “Callback URL” field when creating your app on Facebook’s Developer page.

That’s not a big problem, though. J2EE servlets have the Session object, automatically maintained by your J2EE container, that will take care of this: if you ever want the user to be authenticated when using your app, just make the Callback URL page force the user to login once (as noted above, if already logged in to FB, the user won’t be asked to login again, but you still have to force FB to make the check), and then store the authenticated instance of FacebookRestClient.java in the J2EE Session object, like this:

protected void doGet(HttpServletRequest request, HttpServletResponse response)
{
   ...
   FacebookRestClient authenticatedClient = new FacebookRestClient( apiKey, secret );
   authenticatedClient.setIsDesktop(false);
   request.getSession().setAttribute( "auth", authenticatedClient );
}

Then, whenever you need to interrogate Facebook about any data in ANY of your servlets, fetch the authenticated FacebookRestClient instance from the J2EE session, and use it directly:

protected void doGet(HttpServletRequest request, HttpServletResponse response)
{
   FacebookRestClient authenticatedClient = (FacebookRestClient) request.getSession().getAttribute( "auth" );
   ...
}

In fact, I’d advise you to dedicate one servlet purely to logging-in to Facebook, and make that servlet your Callback URL one. For instance, here’s source code for FacebookLoginServlet.java you could use directly for that servlet. Note that the provided source code assumes you are using Apache Log4j to do your logging – you may want to change that to use Sun’s java.util.logging API. I advise you at least use some form of logging (it helps a lot when debugging!)

Old sessions

You also have to handle the situation where a player leaves their web browser open for a long time, long enough that the J2EE Session timesout and/or the Facebook authentication timesout, and then they hit “refresh”. If you’re merely starting every doGet / doPost method in your servlets with the request.getSession() call above, you’ll find that either the Session is empty and you get a null client, or you get a client but that when you attempt to invoke methods on it they all fail with FacebookException’s. Exactly what will go wrong depends upon the implementation of your J2EE container, and how long it keeps Sessions alive for before expiring them (and whether the connected web browser kept all the Cookie’s it was given).

For this, I currently just surround all my doGet’s with a big try/catch:

protected void doGet(HttpServletRequest request, HttpServletResponse response)
{
   try
   {
      ...
   }
   catch( FacebookException e )
   {
      logger.error( "Facebook exception, probably due to timeout on authentication; sending error page to user", e );
      String loginPage = "http://www.facebook.com/login.php?api_key="+apiKey+"&v=1.0";
      response.getWriter().println( "<h1>Error: Couldn't talk to Facebook</h1>" );
      response.getWriter().println( "Your Facebook session has probably timed out" );
      response.getWriter().println( "Please <a ref=\""+loginPage+"\">click here</a> to login again");
   }
}

Testing…

And, again, time to finish off with some basic tests, so you can be sure all this stuff above is working. For my basic testing, I created a servlet that would fetch the user-id of the currently-logged-in Facebook user, and ask Facebook for a list of all their friends’ names. This is the same basic test that Facebook uses in their one and only piece of sample java code in their API.

public class TestFaceBookServlet extends HttpServlet
{
   protected void doGet( HttpServletRequest request, HttpServletResponse response ) throws IOException, FacebookException
   {
      FacebookRestClient client = (FacebookRestClient) request.getSession().getAttribute("facebookClient");
      client.setDebug(true);

      logger.info( "Fetching friends for user to prove that our auth to FB's server worked OK ... should see a list of \"uid\"s now, with NO java-exceptions!");
      Document d = client.friends_get();

      FacebookRestClient.printDom(d, "  ");
   }
}

Conclusion

By now you should have:

• A facebook app that you can connect to via Facebook itself that displays the content from your basic servlets
• A login-servlet as your Callback URL that automatically logs in the current user to Facebook
• A simple test servlet that your login-servlet redirects to after a successful login, and which prints in your server log-files a list of all the uid’s of your friends

In the next part, I’ll probably stop to cover likely problems and gotchas you’ll run into, since there’s quite a few you’re likely to hit by this point.

If there’s anything else you’d like to see covered, add a comment at the bottom and I’ll try to fit it in as well.

UPDATE 21st Sept 2007: Third part now posted

Google kept giving me zero hits for any of the problems, or even any java-focussed docs (just one link to a FAQ on an issue that seems to be a bug that was fixed a while ago. That’s all). So, as I solve the various problems that come up, I’m writing about them.

Platform

First thing to be clear about: if you want to write FB apps using java, you’ll be using Enterprise Edition (J2EE). The way FB works *requires* you to provide a webserver for your app. Whilst its true that java can run in the web browser, that’s a completely different way of using java – for this, you’re going to have to find a server, and install J2EE (it’s the same as standard java, just has lots of extra libraries, only a few of which you’ll need to use).

Facebook Apps: how they work

This diagram shows a very simplistic summary of the different URL’s you are asked for when registering a Facebook application, or are used when serving an App. Note that FBML is served entirely internally in the FB server, it does NOT make a request to your web server.

NB: this image got deleted in the server crash last month; WordPress is rather badly designed with images, and doesnt save them. But it’s been stolen and copied widely all over the web, so you can probably find it relatively easily

First step: Registering your Facebook Application

Assuming you can find yourself a webserver/J2EE server to run your app on, and have a domain name for it (or the hosting provider gives you a default domain-name – you don’t HAVE to buy one just for your app), the first thing to do is register the app with Facebook. This just reserves the name of your app, and gets you the login details you’ll need before you can do ANY testing or development.

This process is actually nicely documented (and is also very simple – although the huge scary forms they ask you to fill in are very poorly explained, there’s a only a few fields you actually *need* to fill in). Don’t follow the list of things on that page literally, see the differences below that you want to make.

For the URL’s you need to fill-in, you’ll be making a servlet for each. So, work out the URL for each of the servlets (depends on how you setup your J2EE server), and have them ready to give to FB.

So, to summarise:

1. Create a Facebook account if you don’t have one, and login
2. Add the “Developer” app to your account (link is here)
3. Go to your Home page on FB
4. Click on the Developer app in the sidebar to go to the main centre for all your Developer activity
5. Make a new application, and fill in the form it presents you with (make sure you do at least:
   1. App name
   2. Callback URL (see the example app)
   3. Canvas page (see the example app)
   4. iFrame (not FBML)
   5. Post-add URL (see the example app)
6. Save the api-key and the session-key that it now displays for the newly-created app – you’ll need them to do any coding

First test: Can Facebook display your Application?

Create the various servlets on your server (callback, postadd, and canvas) and make each of them return basic HTML that just says “callback servlet”, “postadd servlet”, or “canvas servlet”).

Open a new browser window, and type in the canvas page URL from FB, something like: http://apps.facebook.com/yourApplicationName

You might be asked some security stuff by FB, but once you’ve got past that you should then see a Facebook page with the navbars etc, but just a big empty space in the middle with the test “callback servlet”. If so, congratulations, you’ve got your app basically working. Now comes all the hard stuff…

If not, first check that your servlet is even working, by copy/pasting the callback URL from your FB application setttings (click Edit Settings to re-load the form you submitted) into a browser window, and seeing if you can get the page. You’ve probably got a typo in the URL you gave FB. If the “callback servlet” text doesn’t come up on its own, without all the FB stuff, then your J2EE server is misconfigured or broken. Time for you to go find some Tomcat / jBoss / etc tutorials and get your J2EE working…

Part two…

Now you can move on to part 2 of this series, covering the details of how to authenticate with Facebook and start doing interesting work, including sample source code.