Java NIO docummentation

General Discussions
#1

here the rant >:(

I’m working since a few moment with NIO sockets and I ammazed how poor is Sun doc about it (the best is prolly the JDK source and blah³ article). I think the main advantage of java for gaming is the fancy deployement/network/portability (at least in my view). and I found it pittyfull the way NIO is documented (try to find a working example/tutorial). It’s not that new now, it’s there since first release of 1.4 . I propose my help, for write tutorials (but be carefull of my non-native-techie-english) but I whould like to see a real effort from Sun about documenting his own API… ::slight_smile:

#2

I suppose you have already looked over:
http://java.sun.com/j2se/1.4.2/docs/guide/nio/

it does have a few simple examples.

d

#3

[quote]I suppose you have already looked over:
http://java.sun.com/j2se/1.4.2/docs/guide/nio/

it does have a few simple examples.

d
[/quote]
The examples are **** (self-censored :O), they even go against some of what the API docs suggest, without explaining why (although eventually I tracked down explanations to the diversions, but not from official channels, just consensus opinion amongst users).

I think I’d actually recommend avoiding those examples - they have done some people (read sun’s forums, and other forums via google) more harm than good.

Every way you look at it, the NIO doc situation is unacceptable.

#4

[quote]Every way you look at it, the NIO doc situation is unacceptable.
[/quote]
Have you filed a bug report against the docs?

#5

IIRC I’ve filed about 5 of them ;D. Just against the docs. Mainly against things like “you say X and yet Y happens” or “you don’t say whether X is X-1 or X-2, and it’s not possible to write an app defensively if the API neither mandates one NOR lets you detect it at runtime”.

IIRC in one I even suggested looking at the OpenGL extension mechanisms for inspiration on providing runtime information on what behaviour and/or guarantees the actual implementation was offering

…but I’ve been using NIO for so long now that I really can’t remember :(. And there’s no feature that I’ve found (so far; but… I haven’t checked in a long time, so perhaps you can now?) that lets you search for “my filed bugs” - you have to retain the email with the URL / bug number or else lose it :(. I think I filed an RFE on that a couple of years ago ;D

#6

[quote]remember :(. And there’s no feature that I’ve found (so far; but… I haven’t checked in a long time, so perhaps you can now?) that lets you search for “my filed bugs” - you have to retain the email with the URL / bug number or else lose it :(. I think I filed an RFE on that a couple of years ago ;D
[/quote]
Searching on my nickname (mthornton) gets most of mine. Of course it also include bugs where I have commented rather than being the author.

#7

Hmmm, that’s what I get for not actually looking at the docs before recommending them…

d

#8

Ah. I don’t have a JDC id (I don’t want yet another pointless password and someone knowing enough details about me to steal from my bank account), which may be the problem!

#9

JavaNIO by Ron Hitchens is a great book on NIO.
http://www.javanio.info/

I got my NIO server working by using the book. I’m on another mail list with Ron and he was even helpfull when I had some further questions.

His little tool (BufferDemo) on that website was very helpful in understanding buffers. I think the method names on the Buffer class are terribly named and not intuitive at all. Ron’s tool helps.

My only complaint was his design using worker threads needed more detail, but I did manage to get my version working.

Wood

#10

[quote]JavaNIO by Ron Hitchens is a great book on NIO.
http://www.javanio.info/
Wood
[/quote]
Disclaimer: I’ve only read about half the book so far.

Ron’s book doesn’t have anything meaty in it. It basically teaches you how to use the API in the abscence of having to do any real programming with it.

When I contacted him, he wasn’t even aware of basic fundamental bugs in gathering writes that made them unusable.

The book is expressly not a book from a battle-hardened expert on how to use a tool, and it doesn’t give you much help in using the API “in anger”.

OTOH, as an aid to learning and understanding the sparsely documented API, it’s great.

#11

it’s a bit expensive too ;D

#12

[quote]here the rant >:(

I’m working since a few moment with NIO sockets and I ammazed how poor is Sun doc about it (the best is prolly the JDK source and blah³ article).
[/quote]
Now (finally) on the JGF site: http://grexengine.com/sections/externalgames/

and if you can produce a good article on any other aspect of NIO, send me a message and we’ll see about getting yours up there too.