Servertec
Persistent Object Store
1.4.1 09/04/2005

stec.pos
Class ObjectStore

java.lang.Object
  extended by stec.pos.ObjectStore

public final class ObjectStore
extends java.lang.Object

Contains static methods used to create, delete, open, rehash, expand and pack persistent object stores.

Persistent object stores are simular to java.util.Hashtables, except they do not reside in memory, but on storage media, are not automaically rehashed and support null values.

Each persistent object store physically exists in two (2) physical random access files, .htstore and .htmapper. The .htstore file contains a header, zero (0) or more data pages containing encoded keys and associated values and zero (0) or more freed data pages. The .htmapper contains a header, a lookup table and zero (0) or more mapper pages pointing to corresponding keys, value pairs stored in .htstore and zero (0) or more freed mapper pages.

.htstore Header

1 byte - type - the file type. Currently 0x01 for .htstore.
2 bytes - version - the version number. Currently 0x0100 (1.0.0).
4 bytes - page_length - the size in bytes of the average page as specified when the persistent object store was created.
4 bytes - page_count - the number of data pages currently in use or free. 0 or more.
4 bytes - maximum_page_count - the maximum number of pages that can be allocated. 1 or more. -1 for unlimited.
4 bytes - free_list - pointer to first free data page. -1 if none.
4 bytes - free_count - the number of free data pages. 0 or more.

Each data page is composed of a header and data area of size page_length as specified in the above header.

.htstore Data Page

1 byte - flags - flags used to specify whether the data page is in use or has been freed. 1 for in use and 0 for free.
4 bytes - next_data_page - pointer to any data page that follows. -1 if none.
n bytes - entry - the encoded key or value mapped to fixed data page of page_length as specified in the header.

The persistant object store stores variable length objects by storing them into one (1) or more fixed length data pages.

Once a key or associated value is changed or removed, data pages no longer used are linked to the beginning of the free_list as defined in the above header.

.htmapper Header

1 byte - type - the file type. Currently 0x02 for .htmapper.
2 bytes - version - the version number. Currently 0x0100 (1.0.0).
4 bytes - page_count - the number of mapper pages currently in use or free. 0 or more.
4 bytes - maximum_page_count - the maximum number of pages that can be allocated. 1 or more. -1 for unlimited.
4 bytes - free_list - pointer to first free mapper page. -1 if none.
4 bytes - free_count - the number of free mapper pages. 0 or more.
4 bytes - lookup_table_page_count - the number of pages in the lookup table as specified when the persistent object store was created. 1 or more.
4 bytes - record_count - the number of existing keys and associated values. 0 or more.

.htmapper Lookup Table

The lookup table is an array of four (4) byte pointers to the first mapper pages of size lookup_table_page_count as defined in the above header.

.htmapper Mapper Page

1 byte - flags - flags used to specify whether the mapper page is in use or has been freed. 1 for in use and 0 for free.
4 bytes - previous_page - pointer to any previous mapper page. -1 if none.
4 bytes - next_page - pointer to any next mapper page. -1 if none.
4 bytes - hash_code - the hash code value of the key object.
4 bytes - key_base_pointer - the base pointer to the data page containing the encoded key.
4 bytes - key_length - the number of bytes used to store the encoded key.
4 bytes - value_base_pointer - the base pointer to the data page containing the encoded value.
4 bytes - value_length - the number of bytes used to store the encoded value.

Once a key and associated value are removed, mapper pages no longer used are linked to the beginning of the free_list as defined in the above header.

Keys and associated values are encoded as following:

null - 1 byte - 0x00
Byte - 2 bytes - 0x01 byte
Character - 3 bytes - 0x02 char
Short - 3 bytes - 0x03 short
Integer - 5 bytes - 0x04 int
Long - 9 bytes - 0x05 long
Float - 5 bytes - 0x06 float
Double - 9 bytes - 0x07 double
String - 1 + bytes - 0x08 utf8_encoded_string
Object - 1 + bytes - 0x09 serialized_object
Boolean - 2 bytes - 0x0A boolean_value
Blob - 1 + bytes - 0x0B byte_array
Date - 9 bytes - 0x0C date
BigInteger - 1 + bytes - 0x0D byte_array
BigDecimal - 1 + bytes - 0x0E byte_array
byte[] - 1 + bytes - 0x0F byte_array

Limits

In general Servertec Persistent Object Stores (POS) are limited by size of signed int (32-1 bits).

Limit Size
Maximum Number of Pages in Lookup Table 232-1
Maximum Number of Pages in Mapper 232-1
Maximum Number of Pages in Store 232-1
Maximum Number of Keys 232-1
Maximum Number of Values 232-1
Maximum Size of Key 232-1
Maximum Size of Value 232-1
Maximum File Size of Mapper File Platform/Java VM Specific
Maximum File Size of Store File Platform/Java VM Specific
Maximum Number of Open Stores Platform/Java VM Specific
Number of File Handles Per Opened Store 2

Locking

Object locking is at a per stec.pos.ObjectStoreReference basis with each store maintaining its own in-memory lock table. When an ObjectStoreReference is closed all its locks are released.

Multi-Threading

Each thread should have its own stec.pos.ObjectStoreReference that is not shared with other threads.

Internally stec.pos.ObjectStoreReference operations block other threads from accessing the single instance to the object store.

Since:
1.0.0 08/12/2001
See Also:
Hashtable, ByteArray

Field Summary
static boolean displayLogo
           
 
Constructor Summary
ObjectStore()
           
 
Method Summary
static void copy(java.lang.String from_filename, java.lang.String to_filename, boolean overwrite)
          Copies the specified persistent object store.
static void create(java.lang.String filename, int page_length, int lookup_table_page_count, int mapper_maximum_page_count, int store_maximum_page_count, boolean overwrite)
          Used to create a new persistent object store or to overwrite an existing persistent object store.
static void delete(java.lang.String filename)
          Deletes the specified persistent object store.
static boolean exists(java.lang.String filename)
          Returns whether the specified persistent object store currently exists.
static void expand(java.lang.String filename, int mapper_maximum_page_count, int store_maximum_page_count)
          Changes the maximum number of pages that the mapper and/or store can grow to.
static boolean inUse(java.lang.String filename)
          Returns whether the specified persistent object store is being used.
static void move(java.lang.String from_filename, java.lang.String to_filename, boolean overwrite)
          Moves the specified persistent object store.
static ObjectStoreReference open(java.lang.String filename, boolean exclusive)
          Opens the specified persistent object store and returns a stec.pos.ObjectStoreReference to it.
static void pack(java.lang.String filename)
          Releases unused space at the end of the specified persistent object store back to the operating system.
static void rehash(java.lang.String filename, int new_lookup_table_page_count, int new_maximum_page_count)
          Used to change the number of lookup table pages in the specified persistent object store.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

displayLogo

public static boolean displayLogo
Constructor Detail

ObjectStore

public ObjectStore()
Method Detail

create

public static final void create(java.lang.String filename,
                                int page_length,
                                int lookup_table_page_count,
                                int mapper_maximum_page_count,
                                int store_maximum_page_count,
                                boolean overwrite)
                         throws java.lang.IllegalArgumentException,
                                java.io.IOException
Used to create a new persistent object store or to overwrite an existing persistent object store.

Parameters:
filename - the path and base file name of the persistent object store to create.
page_length - the size in bytes of the average page.
lookup_table_page_count - the number of pages in the lookup table. 1 or more.
mapper_maximum_page_count - the maximum number of mapper pages. -1 for unlimited.
store_maximum_page_count - the maximum number of store pages. -1 for unlimited.
overwrite - whether to overwrite any existing persistent object store.
Throws:
java.lang.IllegalArgumentException - if any of the parameters specified were not valid.
java.io.IOException - if the store is in use, already exists or cannot be created or if an I/O exception occurred.
See Also:
delete

exists

public static final boolean exists(java.lang.String filename)
                            throws java.io.IOException
Returns whether the specified persistent object store currently exists.

Parameters:
filename - the path and base file name of the persistent object store to test.
Returns:
whether the specified persistent object store currently exists.
Throws:
java.io.IOException - if an I/O exception occurred.

delete

public static final void delete(java.lang.String filename)
                         throws java.io.FileNotFoundException,
                                java.io.IOException
Deletes the specified persistent object store.

Parameters:
filename - the path and base file name of the persistent object store to delete.
Throws:
java.io.FileNotFoundException - if the store does not exist.
java.io.IOException - if the store is in use or cannot be deleted or if an I/O exception occurred.
See Also:
create

open

public static final ObjectStoreReference open(java.lang.String filename,
                                              boolean exclusive)
                                       throws java.io.FileNotFoundException,
                                              java.io.IOException
Opens the specified persistent object store and returns a stec.pos.ObjectStoreReference to it.

Parameters:
filename - the path and base file name of the persistent object store to open.
exclusive - whether to open the persistent object store reference for exclusive use.
Returns:
the stec.pos.ObjectStoreReference to the persistent object store.
Throws:
java.io.FileNotFoundException - if the store does not exist.
java.io.IOException - if the store is exclusively opened or cannot be opened or if an I/O exception occurred.
See Also:
ObjectStoreReference, close

rehash

public static final void rehash(java.lang.String filename,
                                int new_lookup_table_page_count,
                                int new_maximum_page_count)
                         throws java.lang.IllegalArgumentException,
                                java.io.FileNotFoundException,
                                java.io.IOException
Used to change the number of lookup table pages in the specified persistent object store.

Rehashing a large persistent object store may take a long time.

Internally creates a new mapper file, then performs a rehash using the newly created mapper file and after successfully completing renames the original mapper file to a temporary name and then renames the new mapper file to the original mapper file's name and then finally deletes the renamed original mapper file.

Parameters:
filename - the path and base file name of the persistent object store to rehash.
new_lookup_table_page_count - the number pages in the lookup table. 1 or more.
new_maximum_page_count - the maximum number pages in the mapper file. -1 for unlimited.
Throws:
java.lang.IllegalArgumentException - if any invalid parameters were specified.
java.io.FileNotFoundException - if the store does not exist.
java.io.IOException - if the store is in use or cannot be rehashed or if an I/O exception occurred.

pack

public static final void pack(java.lang.String filename)
                       throws java.io.FileNotFoundException,
                              java.io.IOException
Releases unused space at the end of the specified persistent object store back to the operating system.

Packing a large persistent object store may take a long time.

Java 1.2.0 or later is required to change the physical size of store files.

Parameters:
filename - the path and base file name of the persistent object store to pack.
Throws:
java.io.FileNotFoundException - if the store does not exist.
java.io.IOException - if the store is in use or cannot be packed or if an I/O exception occurred.

expand

public static final void expand(java.lang.String filename,
                                int mapper_maximum_page_count,
                                int store_maximum_page_count)
                         throws java.lang.IllegalArgumentException,
                                java.io.FileNotFoundException,
                                java.io.IOException
Changes the maximum number of pages that the mapper and/or store can grow to.

Parameters:
filename - the path and base file name of the persistent object store to expand.
mapper_maximum_page_count - the maximum number of mapper pages. -1 for unlimited.
store_maximum_page_count - the maximum number of store pages. -1 for unlimited.
Throws:
java.lang.IllegalArgumentException - if any of the parameters specified were not valid.
java.io.FileNotFoundException - if the store does not exist.
java.io.IOException - if the store is in use or cannot be expanded or if an I/O exception occurred.

inUse

public static final boolean inUse(java.lang.String filename)
                           throws java.io.IOException
Returns whether the specified persistent object store is being used.

Parameters:
filename - the path and base file name of the persistent object store to test.
Returns:
whether the specified persistent object store is being used.
Throws:
java.io.IOException - if an I/O exception occurred.
Since:
1.1.0 09/01/2002

copy

public static final void copy(java.lang.String from_filename,
                              java.lang.String to_filename,
                              boolean overwrite)
                       throws java.lang.IllegalArgumentException,
                              java.io.FileNotFoundException,
                              java.io.IOException
Copies the specified persistent object store.

Parameters:
from_filename - the path and base file name of the persistent object store to copy.
to_filename - the path and base file name of the persistent object store to copy to.
overwrite - whether to overwrite any existing persistent object store.
Throws:
java.lang.IllegalArgumentException - if any of the parameters specified were not valid.
java.io.FileNotFoundException - if the store does not exist.
java.io.IOException - if the store is in use or cannot be copied or if an I/O exception occurred.
Since:
1.2.2 03/03/2003

move

public static final void move(java.lang.String from_filename,
                              java.lang.String to_filename,
                              boolean overwrite)
                       throws java.lang.IllegalArgumentException,
                              java.io.FileNotFoundException,
                              java.io.IOException
Moves the specified persistent object store.

Parameters:
from_filename - the path and base file name of the persistent object store to move.
to_filename - the path and base file name of the persistent object store to move to.
overwrite - whether to overwrite any existing persistent object store.
Throws:
java.lang.IllegalArgumentException - if any of the parameters specified were not valid.
java.io.FileNotFoundException - if the store does not exist.
java.io.IOException - if the store is in use or cannot be moved or if an I/O exception occurred.
Since:
1.2.2 03/03/2003

Servertec
Persistent Object Store
1.4.1 09/04/2005

Copyright © 2001-2005 Servertec. All rights reserved.