=============================================================================
                 ________    _______    ________   ________
                |        |  |       |  |  _____/  |        |
                |____   _|  |__   __|  | |        | _______|
                     | |       | |     | |____    | |____
                     | |       | |     |  ___/     \____ |_
                  ___| |       | |     | |         _____\  |
                 |_____|ava    |_|est  |_|ile     |________|ystem

                         JTFS by Dimitris Michelinakis

=============================================================================


-=[ Introduction ]=-

	JTFS is a Java based file system which emulates the low-level
interaction of a real file system with a block device. It is specificly
made for educational perposes, so many parts of the code may not be
optimal for a real system, but help our understanding of a file system.


-=[ File System structure ]=-

	The file system itself is written in a streamline/serialised
method. There are no set boundaries, and no set possitions. Everything
is resizable. Thus one JTFS partition may differ from another based
on the options that the file system was compiled with. All limits
are resizable, so one file system may have a 30 bytes limit on the
file name, and another may have 255 bytes limit.

	The file system structure is also generic, so that any program
may be able to read the block device and understand the file system.
	
        JTFS splits the block device in three parts. Blocks that hold
the file table information, blocks that hold the 'info blocks' and
blocks that hold the file data. The file table is the file information,
and the info block is a storage to keep the blocks of the file.

	Here is an example of the structure of the file table:
        :1;19.01;readme.txt
        Described as:
	:fd;info block.attributes;file name

	The info block is just a string list of block numbers
separated by commas. Both file table and info block are manipulated
as strings.

	There is a large overhead in this structure, but this is
an educational file system and it helps to understand how the file
system works in a 'visual' way. Its possible to dump the block device
to debug it and read it by hand, since the file structure is written
in a humanly rational way.


-=[ The Code ]=-

	The code is written for optimal performance, many stages are
are re-written in the code again and again. This may seem redundant
but in fact is faster that way. Java doesn't have to call many
secondary methods/classes and thus doesn't have to re-create the scope
of the variables all the time.

	Additionally each of these parts which are repeated, have slight
changes to perform specific tasks, for example a loop may look for a file
based on the file descriptor, or based on the name of the file.

	The code doesn't use ArrayLists, and avoids Vectors as much
as possible. A static array is much faster to manipulate and the overhead
in memory is not that big in our case.

-=[ Limitations ]=-

	JTFS has virtually no limits on the maximum length of any
of its stractures. File names, number of files, blocks per file,
and open files, are all unlimited. The only limits are based on the
block device, if it can store enough or not.

	The only important limit, is that of the info block. There is
only one block which stores the blocks used by the file, so if the
block size is for example 2048, then a single file may use less than
4096 blocks.

	All the limits are set based on the number of blocks and the
size of the blocks in the block device. The file system needs blocks
that are big enough to store atleast a single file entry of the file table.

	To calculate the minimum length of a block:
        5+(digits of max number of files)+(digits of number of total
        blocks)+(max filename length)

	The minimum number of blocks is the max number of files.

-=[ Testing ]=-

	JTFS was written under OS/2 Warp Server v4.51 and FreeBSD v5.0-CURRENT,
running Java(TM) 2 Runtime Environment, Standard Edition (build 1.3.0).

	Testing was done based on a sample of test cases while running a
large amount of debug code. Each test case would target a specific running
feature of the file system.

-=[ Bugs! ]=-

	Small problem after deleting a file and re-creating the same file
again on the same possition. It should reset the EOF pointer.

