|
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.Index
public final class Index
Contains static methods used to create, delete, open, expand and pack indexes.
Servertec Indexes are modified B-*trees, where non primitive key, value objects are for efficiency stored in secondary files.
Each index physically exists in one (1) or more physical random access files, .keys.index, .keys.store, .values.store and .values.index. The .keys.index file contains a header, zero (0) or more index pages containing encoded keys and associated values and zero (0) or more freed index pages. The .keys.store is used when the key objects are non primitive values and contains a header, zero (0) or more pages containing key objects and zero (0) or more freed pages. The .values.store is used when the value objects are non primitive values and contains a header, zero (0) or more pages containing value objects and zero (0) or more freed pages. The .values.index is used for duplicate values and contains a header, zero (0) or more index pages containing encoded values and zero (0) or more freed pages.
.keys.index Header
1 byte - type - the file type. Currently 0x08 for .keys.index.
2 bytes - version - the version number. Currently 0x0100 (1.0.0).
1 byte - flags - 0x01 specifies whether to allow multiple duplicate sorted values and 0x02 specifies whether to sort keys in ascending or descending order.
1 byte - key_type - specifies the data type used when encoding key objects. See Key Data Types
4 bytes - key_length - the number of bytes that a key object requires. See Key Data Types
1 byte - value_type - specifies the data type used when encoding value objects. See Value Data Types
4 bytes - value_length - the number of bytes that a value object requires. See Value Data Types
4 bytes - order - the order. Each index page will contain twice the number of entries.
4 bytes - maximum_page_count - the maximum number of pages that can be allocated. 1 or more. -1 for unlimited.
4 bytes - page_count - the number of index pages currently in use or free. 0 or more.
4 bytes - root_page_number - the page number of the root page. -1 if none.
4 bytes - free_count - the number of free index pages. 0 or more.
4 bytes - free_list - pointer to first free index page. -1 if none.
4 bytes - total_entry_count - the total number of entries in the index. 0 or more.
n bytes - key_class_name - the UTF-8 encoded class name of the key object.
n bytes - value_class_name - the UTF-8 encoded class name of the value object.
n bytes - collator_class_name - the UTF-8 encoded class name of the collator object.
Key Data Types:
Object | Size | Data Type |
---|---|---|
null | 1 | 0x00 |
Byte | 1 | 0x01 |
Character | 2 | 0x02 |
Short | 2 | 0x03 |
Integer | 4 | 0x04 |
Long | 8 | 0x05 |
Float | 4 | 0x06 |
Double | 8 | 0x07 |
String | 8 | 0x08 |
Object | 8 | 0x09 |
Blob | 8 | 0x0B |
Date | 8 | 0x0C |
BigInteger | 8 | 0x0D |
BigDecimal | 8 | 0x0E |
byte[] | 8 | 0x0F |
Value Data Types:
Object | Size | Data Type |
---|---|---|
null | 1 | 0x00 |
Byte | 1 | 0x01 |
Character | 2 | 0x02 |
Short | 2 | 0x03 |
Integer | 4 | 0x04 |
Long | 8 | 0x05 |
Float | 4 | 0x06 |
Double | 8 | 0x07 |
String | 8 | 0x08 |
Object | 8 | 0x09 |
Boolean | 1 | 0x0A |
Blob | 8 | 0x0B |
Date | 8 | 0x0C |
BigInteger | 8 | 0x0D |
BigDecimal | 8 | 0x0E |
byte[] | 8 | 0x0F |
Duplicates | 8 | -1 |
Primitives
java.lang.Byte
java.lang.Character
java.lang.Short
java.lang.Integer
java.lang.Long
java.lang.Float
java.lang.Double
java.lang.Boolean
java.util.Date
Each index page is composed of a header and entry area of size 9 + ((4 + key_length + value_length) * (order * 2)) as specified above.
.keys.index Page
1 byte - flags - flags used to specify whether the index page is in use or has been freed. 1 for in use and 0 for free.
4 bytes - next_index_page - pointer to any index page that follows. -1 if none.
4 bytes - entry_count - the number of entries in use. 1 if none.
n bytes - entries - the encoded key, value pairs.
.keys.index Entry
4 bytes - previous_index_page - pointer to any previous index page. -1 if none.
n bytes - key - the encoded key. 4 bytes for the object length and 4 bytes for the base record number in the keys store for non primitive keys. See Key Data Types.
n bytes - value - the encoded value. 4 bytes for the object length and 4 bytes for the base record number in the values store for non primitive values. 4 bytes for the value count and 4 bytes for the base record number in the values index for duplicate values. See Value Data Types.
Non primitive values are stored seperately into one (1) or more fixed length data pages.
Once a key or associated value is changed or removed, pages no longer used are linked to the beginning of the free_list as defined in the above header.
keys.store and values.store Header
1 byte - type - the file type. Currently 0x09 for keys.store and values.store.
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 index was created.
4 bytes - maximum_page_count - the maximum number of pages that can be allocated. 1 or more. -1 for unlimited.
4 bytes - free_count - the number of free data pages. 0 or more.
4 bytes - free_list - pointer to first free data page. -1 if none.
4 bytes - page_count - the number of data pages currently in use or free. 0 or more.
4 bytes - record_count - the number of objects. 0 or more.
Each data page is composed of a header and data area of size page_length as specified in the above header.
.keys.store and .values.store 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 object mapped to fixed data page of page_length as specified in the header.
Non primitive objects are stored in one (1) or more fixed length data pages.
Once a an object is changed or removed, data pages no longer used are linked to the beginning of the free_list as defined in the above header.
.values.index Header
1 byte - type - the file type. Currently 0x0a for .values.index.
2 bytes - version - the version number. Currently 0x0100 (1.0.0).
1 byte - flags - 0x02 specifies whether to sort duplicate values in ascending or descending order.
1 byte - value_type - specifies the data type used when encoding value objects. See Value Data Types
4 bytes - value_length - the number of bytes that a value object requires. See Value Data Types
4 bytes - order - the order. Each index page will contain twice the number of entries.
4 bytes - maximum_page_count - the maximum number of pages that can be allocated. 1 or more. -1 for unlimited.
4 bytes - page_count - the number of index pages currently in use or free. 0 or more.
4 bytes - free_count - the number of free index pages. 0 or more.
4 bytes - free_list - pointer to first free index page. -1 if none.
Value Data Types:
Object | Size | Data Type |
---|---|---|
null | 1 | 0x00 |
Byte | 1 | 0x01 |
Character | 2 | 0x02 |
Short | 2 | 0x03 |
Integer | 4 | 0x04 |
Long | 8 | 0x05 |
Float | 4 | 0x06 |
Double | 8 | 0x07 |
String | 8 | 0x08 |
Object | 8 | 0x09 |
Boolean | 1 | 0x0A |
Blob | 8 | 0x0B |
Date | 8 | 0x0C |
BigInteger | 8 | 0x0D |
BigDecimal | 8 | 0x0E |
byte[] | 8 | 0x0F |
Primitives
java.lang.Byte
java.lang.Character
java.lang.Short
java.lang.Integer
java.lang.Long
java.lang.Float
java.lang.Double
java.lang.Boolean
java.util.Date
Each values index page is composed of a header and entry area of size 9 + ((4 + value_length) * (order * 2)) as specified above.
.values.index Page
1 byte - flags - flags used to specify whether the index page is in use or has been freed. 1 for in use and 0 for free.
4 bytes - next_index_page - pointer to any index page that follows. -1 if none.
4 bytes - entry_count - the number of entries in use. 1 if none.
n bytes - entries - the encoded values.
.values.index Entry
4 bytes - previous_index_page - pointer to any previous index page. -1 if none.
n bytes - value - the encoded value. 4 bytes for the object length and 4 bytes for the base record number in the values store for non primitive values. See Value Data Types.
Non primitive values are stored seperately into one (1) or more fixed length data pages.
Once a value is changed or removed, pages no longer used are linked to the beginning of the free_list as defined in the above header.
Limits
In general Servertec Indexes are limited by size of signed int (32-1 bits).
Limit | Size |
---|---|
Maximum Number of Pages in Index | 232-1 |
Maximum Number of Pages in Keys Store | 232-1 |
Maximum Number of Pages in Values Store | 232-1 |
Maximum Number of Pages in Duplicate Values Index | 232-1 |
Maximum Number of Pages in Duplicate Values Index Values Store | 232-1 |
Maximum Number of Keys | 232-1 |
Maximum Number of Values | 232-1 |
Maximum Number of Duplicate Values | 232-1 |
Maximum Size of Key | 232-1 |
Maximum Size of Value | 232-1 |
Maximum File Size of Index File | Platform/Java VM Specific |
Maximum File Size of Keys Store File | Platform/Java VM Specific |
Maximum File Size of Values Store File | Platform/Java VM Specific |
Maximum Number of Open Indexes | Platform/Java VM Specific |
Number of File Handles Per Opened Index | At least 1 and upto 4 |
Locking
Object locking is at a per stec.pos.IndexReference basis with each index maintaining its own in-memory lock table. When an IndexReference is closed all its locks are released.
Multi-Threading
Each thread should have its own stec.pos.IndexReference that is not shared with other threads.
Internally stec.pos.IndexReference operations block other threads from accessing the single instance to the index.
ByteArray
Field Summary | |
---|---|
static boolean |
displayLogo
|
Constructor Summary | |
---|---|
Index()
|
Method Summary | |
---|---|
static void |
copy(java.lang.String from_filename,
java.lang.String to_filename,
boolean overwrite)
Copies the specified Index. |
static void |
create(java.lang.String filename,
int order,
int index_maximum_page_count,
java.lang.String key_class_name,
int key_length,
int keys_store_maximum_page_count,
java.lang.String value_class_name,
int value_length,
int values_store_maximum_page_count,
java.lang.String collator_class_name,
boolean overwrite,
boolean ascending,
boolean duplicates,
int values_order,
int values_index_maximum_page_count,
java.lang.String values_collator_class_name,
boolean values_ascending)
Used to create a new index or to overwrite an existing index. |
static void |
create(java.lang.String filename,
java.lang.String key_class_name,
int key_length,
java.lang.String value_class_name,
int value_length,
boolean overwrite)
Used to create a new index or to overwrite an existing index. |
static void |
delete(java.lang.String filename)
Deletes the specified index. |
static boolean |
exists(java.lang.String filename)
Returns whether the specified index currently exists. |
static void |
expand(java.lang.String filename,
int index_maximum_page_count,
int keys_store_maximum_page_count,
int values_store_maximum_page_count,
int values_index_maximum_page_count)
Changes the maximum number of pages that the support files and/or index can grow to. |
static boolean |
inUse(java.lang.String filename)
Returns whether the specified Index is being used. |
static void |
move(java.lang.String from_filename,
java.lang.String to_filename,
boolean overwrite)
Moves the specified Index. |
static IndexReference |
open(java.lang.String filename,
boolean exclusive)
Opens the specified index and returns a stec.pos.IndexReference to it. |
static void |
pack(java.lang.String filename)
Releases unused space at the end of the specified index back to the operating system. |
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 Index()
Method Detail |
---|
public static final void create(java.lang.String filename, java.lang.String key_class_name, int key_length, java.lang.String value_class_name, int value_length, boolean overwrite) throws java.lang.IllegalArgumentException, java.io.IOException, java.lang.ClassNotFoundException, java.lang.IllegalAccessException, java.lang.InstantiationException
filename
- the path and base file name of the index to create.key_class_name
- the class name for key objects. For example java.lang.Integerkey_length
- the average length of key objects. Used when the key is a not a primitive object.value_class_name
- the class name for value objects. For example java.lang.Integervalue_length
- the average length of value objects. Used when the value is a not a primitive object.overwrite
- whether to overwrite any existing indexes.
java.lang.IllegalArgumentException
- if any of the parameters specified were not valid.
java.io.IOException
- if the index is in use, already exists or cannot be created or if an I/O exception occurred.
java.lang.ClassNotFoundException
- if the key_class_name or the value_class_name cannot be found.
java.lang.IllegalAccessException
- if the key_class_name or the value_class_name cannot be loaded because the class is not public or is in another package.
java.lang.InstantiationException
- if the key_class_name or the value_class_name cannot be instantiated because it is an interface or an abstract class.delete
public static final void create(java.lang.String filename, int order, int index_maximum_page_count, java.lang.String key_class_name, int key_length, int keys_store_maximum_page_count, java.lang.String value_class_name, int value_length, int values_store_maximum_page_count, java.lang.String collator_class_name, boolean overwrite, boolean ascending, boolean duplicates, int values_order, int values_index_maximum_page_count, java.lang.String values_collator_class_name, boolean values_ascending) throws java.lang.IllegalArgumentException, java.io.IOException, java.lang.ClassNotFoundException, java.lang.IllegalAccessException, java.lang.InstantiationException
filename
- the path and base file name of the index to create.order
- the order. Each index page will contain twice the number of entries. -1 to have POS calculate the value.index_maximum_page_count
- the maximum number of index pages. -1 for unlimited.key_class_name
- the class name for key objects. For example java.lang.Integerkey_length
- the average length of key objects. Used when the key is a not a primitive object.keys_store_maximum_page_count
- the maximum number of keys store pages. -1 for unlimited. Used when the key is a not a primitive object.value_class_name
- the class name for value objects. For example java.lang.Integervalue_length
- the average length of value objects. Used when the value is a not a primitive object.values_store_maximum_page_count
- the maximum number of values store pages. -1 for unlimited. Used when the value is a not a primitive object.collator_class_name
- the class name of the key collator. null for the default collator.overwrite
- whether to overwrite any existing indexes.ascending
- whether to sort keys in ascending or descending order.duplicates
- whether to allow multiple duplicate sorted values.values_order
- the order used for duplicate values. Each duplicate values index page will contain twice the number of entries. -1 to have POS calculate the value. Used when storing duplicate values.values_index_maximum_page_count
- the maximum number of duplicate values index pages. -1 for unlimited. Used when storing duplicate values.values_collator_class_name
- the class name of the duplicate values collator. Used when storing duplicate values. null for the default collator.values_ascending
- whether to sort duplicate values in ascending or descending order. Used when storing duplicate values.
java.lang.IllegalArgumentException
- if any of the parameters specified were not valid.
java.io.IOException
- if the index is in use, already exists or cannot be created or if an I/O exception occurred.
java.lang.ClassNotFoundException
- if the key_class_name, the value_class_name, the collator_class_name or the values_collator_class_name cannot be found.
java.lang.IllegalAccessException
- if the key_class_name, the value_class_name, the collator_class_name or the values_collator_class_name cannot be loaded because the class is not public or is in another package.
java.lang.InstantiationException
- if the key_class_name, the value_class_name, the collator_class_name or the values_collator_class_name cannot be instantiated because it is an interface or an abstract class.delete
public static final boolean exists(java.lang.String filename) throws java.io.IOException
filename
- the path and base file name of the index 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 index to delete.
java.io.FileNotFoundException
- if the index does not exist.
java.io.IOException
- if the index is in use or cannot be deleted or if an I/O exception occurred.create
,
create
public static final IndexReference open(java.lang.String filename, boolean exclusive) throws java.io.FileNotFoundException, java.lang.ClassNotFoundException, java.lang.IllegalAccessException, java.lang.InstantiationException, java.io.IOException
filename
- the path and base file name of the index to open.exclusive
- whether to open the index reference for exclusive use.
java.io.FileNotFoundException
- if the index does not exist.
java.io.IOException
- if the index is exclusively opened or cannot be opened or if an I/O exception occurred.
java.lang.ClassNotFoundException
- if the key_class_name, the value_class_name, the collator_class_name or the values_collator_class_name cannot be found.
java.lang.IllegalAccessException
- if the key_class_name, the value_class_name, the collator_class_name or the values_collator_class_name cannot be loaded because the class is not public or is in another package.
java.lang.InstantiationException
- if the key_class_name, the value_class_name, the collator_class_name or the values_collator_class_name cannot be instantiated because it is an interface or an abstract class.IndexReference
,
close
public static final void pack(java.lang.String filename) throws java.io.FileNotFoundException, java.lang.ClassNotFoundException, java.lang.IllegalAccessException, java.lang.InstantiationException, java.io.IOException
Packing a large index may take a long time.
Java 1.2.0 or later is required to change the physical size of the index and support files.
filename
- the path and base file name of the index to pack.
java.io.FileNotFoundException
- if the index does not exist.
java.io.IOException
- if the index is in use or cannot be packed or if an I/O exception occurred.
java.lang.ClassNotFoundException
- if the key_class_name, the value_class_name, the collator_class_name or the values_collator_class_name cannot be found.
java.lang.IllegalAccessException
- if the key_class_name, the value_class_name, the collator_class_name or the values_collator_class_name cannot be loaded because the class is not public or is in another package.
java.lang.InstantiationException
- if the key_class_name, the value_class_name, the collator_class_name or the values_collator_class_name cannot be instantiated because it is an interface or an abstract class.public static final void expand(java.lang.String filename, int index_maximum_page_count, int keys_store_maximum_page_count, int values_store_maximum_page_count, int values_index_maximum_page_count) throws java.lang.IllegalArgumentException, java.lang.ClassNotFoundException, java.lang.IllegalAccessException, java.lang.InstantiationException, java.io.FileNotFoundException, java.io.IOException
filename
- the path and base file name of the index to expand.index_maximum_page_count
- the maximum number of index pages. -1 for unlimited.keys_store_maximum_page_count
- the maximum number of keys store pages. -1 for unlimited. Used when the key is a not a primitive object.values_store_maximum_page_count
- the maximum number of values store pages. -1 for unlimited. Used when the value is a not a primitive object.values_index_maximum_page_count
- the maximum number of duplicate values index pages. -1 for unlimited. Used when storing duplicate values.
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.
java.lang.ClassNotFoundException
- if the key_class_name, the value_class_name, the collator_class_name or the values_collator_class_name cannot be found.
java.lang.IllegalAccessException
- if the key_class_name, the value_class_name, the collator_class_name or the values_collator_class_name cannot be loaded because the class is not public or is in another package.
java.lang.InstantiationException
- if the key_class_name, the value_class_name, the collator_class_name or the values_collator_class_name cannot be instantiated because it is an interface or an abstract class.public static final boolean inUse(java.lang.String filename) throws java.io.IOException
filename
- the path and base file name of the Index 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, java.lang.ClassNotFoundException, java.lang.IllegalAccessException, java.lang.InstantiationException
from_filename
- the path and base file name of the Index to copy.to_filename
- the path and base file name of the Index to copy to.overwrite
- whether to overwrite any existing Index.
java.lang.IllegalArgumentException
- if any of the parameters specified were not valid.
java.io.FileNotFoundException
- if the Index does not exist.
java.lang.ClassNotFoundException
- if the key_class_name, the value_class_name, the collator_class_name or the values_collator_class_name cannot be found.
java.lang.IllegalAccessException
- if the key_class_name, the value_class_name, the collator_class_name or the values_collator_class_name cannot be loaded because the class is not public or is in another package.
java.lang.InstantiationException
- if the key_class_name, the value_class_name, the collator_class_name or the values_collator_class_name cannot be instantiated because it is an interface or an abstract class.
java.io.IOException
- if the Index 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, java.lang.ClassNotFoundException, java.lang.IllegalAccessException, java.lang.InstantiationException
from_filename
- the path and base file name of the Index to move.to_filename
- the path and base file name of the Index to move to.overwrite
- whether to overwrite any existing Index.
java.lang.IllegalArgumentException
- if any of the parameters specified were not valid.
java.io.FileNotFoundException
- if the Index does not exist.
java.lang.ClassNotFoundException
- if the key_class_name, the value_class_name, the collator_class_name or the values_collator_class_name cannot be found.
java.lang.IllegalAccessException
- if the key_class_name, the value_class_name, the collator_class_name or the values_collator_class_name cannot be loaded because the class is not public or is in another package.
java.lang.InstantiationException
- if the key_class_name, the value_class_name, the collator_class_name or the values_collator_class_name cannot be instantiated because it is an interface or an abstract class.
java.io.IOException
- if the Index 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.