File: README

package info (click to toggle)
libflux0 0.3.0-5
  • links: PTS
  • area: main
  • in suites: woody
  • size: 2,244 kB
  • ctags: 2,028
  • sloc: ansic: 15,937; sh: 7,704; java: 470; makefile: 126; lex: 108
file content (80 lines) | stat: -rw-r--r-- 3,818 bytes parent folder | download
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
This is the first release of classes to perform token tree I/O in
Java. The package classes, in the packages/ subdirectory, provide
abstractions for the lower level Java I/O libraries, and implement a
listener model for incoming comm blocks. This is JDK1.2/Java2 code,
although not too many 1.2 features are used at the moment (mainly some
1.2-specific java.util.Vector methods). Later releases will use more,
though, so the decision was made to not support anything earlier.

No installation is required. Optionally, move the contents of the
packages/ subdir to somewhere in your classpath, or add it to your
classpath either by setting the CLASSPATH environment variable, or by
setting it in the -classpath parameter to javac and -cp to java.

In the examples dir of the main distribution is a C program called
ttree-server-java-example, which is made for interfacing with the
TestClient class in this example. Start the server, and then start the
client with:

java -cp .:packages/ TestClient

The comments in the TestClient code should explain most of the basic
use of the package. The TTreeComm object is the most important. It's
constructed using an InetAddress, a port number, and a class which
implements the DefaultListener interface.

The DefaultListener has two methods, one which is called in the event
of incoming blocks that have a transaction ID of 0, and one which is
called in the event of incoming blocks that have a non-null
transaction ID (this method usually registers the transaction by
instantiating a TransactionListener for it, and calling
startTransaction() on the TTreeComm object, as shown).

In addition, you can call addListener() on the TTreeComm object to add
a TokenListener, with the root-level token you want it to listen
for. You can add multiple TokenListeners for one token, and multiple tokens
for one TokenListener, by calling addListener() repeatedly. The
registered TokenListeners' tTreeReceived() method will be called when
a block containing a TTree with a matching root-level token is
received.

Also included in the TestClient is the private method printTTree,
which shows how easy it is to recursively traverse a TTree once it's
received.


TODO's, known bugs, etc.

* There is a method to unregister all listeners for a specified token
  in the TTreeComm object, but it's mainly untested, and expected to
  contain bugs. Don't use it. Then again, all of this is alpha, so,
  what do you expect?

* There's no implemented way to close a socked and otherwise end the
  use of a TTreeComm object. If the server closes the socket while the
  client is trying to read or write, this is handled like all other IO
  errors (IE. not at all, just giving an error message and a stack
  trace, then quitting the entire client).

* There are very few support functions to process TTrees, for
  instance searching them. Splitting and merging TTrees is extremely
  trivial, though, given their homogenous nature.

* The TTreeComm class' read functions are extremely naive, and assume
  valid input. It's fully possible to crash the client by overflowing
  it with trash input, for instance, since there is no sanity
  checking.

* The I/O loop should probably be implemented as two threads instead
  of so it's easier to sleep while waiting for things to happen. As it
  is now, it's semi-busywaiting, which is not optimal (although
  resource usage by the package in general is neligible).

* There's no way to make a server socket, but it should be trivial to
  implement, and should be by the next release.

The maintainer of the Java code is Joakim Ziegler,
joakim@styx.net. Bugs, suggestions, and sucessful usage reports are
extremely welcome. This code, as the rest of libflux, is under the GNU
GPL license. See the COPYING file in the root dir of the distribution
for details.