|
Servertec Persistent Object Store 1.4.1 09/04/2005 |
||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectstec.pos.ObjectStore
public final class ObjectStore
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.
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 |
---|
public static boolean displayLogo
Constructor Detail |
---|
public ObjectStore()
Method Detail |
---|
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
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.
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.delete
public static final boolean exists(java.lang.String filename) throws java.io.IOException
filename
- the path and base file name of the persistent object store to test.
java.io.IOException
- if an I/O exception occurred.public static final void delete(java.lang.String filename) throws java.io.FileNotFoundException, java.io.IOException
filename
- the path and base file name of the persistent object store to delete.
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.create
public static final ObjectStoreReference open(java.lang.String filename, boolean exclusive) throws java.io.FileNotFoundException, java.io.IOException
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.
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.ObjectStoreReference
,
close
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
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.
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.
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.public static final void pack(java.lang.String filename) throws java.io.FileNotFoundException, java.io.IOException
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.
filename
- the path and base file name of the persistent object store to pack.
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.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
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.
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.public static final boolean inUse(java.lang.String filename) throws java.io.IOException
filename
- the path and base file name of the persistent object store to test.
java.io.IOException
- if an I/O exception occurred.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
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.
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.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
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.
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.
|
Servertec Persistent Object Store 1.4.1 09/04/2005 |
||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
Copyright © 2001-2005 Servertec. All rights reserved.