Interface Store
-
- All Known Implementing Classes:
AbstractStore
,HeapStore
,JournalledFileStore
public interface Store
A store is a resource where areas can be allocated and freed to store objects. A store can be backed by a file or main memory, or a combination of the two.Some characteristics of implementations of Store may be separately specified. For example, a file based store that is intended to persistently store objects may have robustness as a primary requirement. A main memory based store, or other type of volatile store, may not require robustness.
- Author:
- Tobias Downer
-
-
Method Summary
All Methods Instance Methods Abstract Methods Modifier and Type Method Description AreaWriter
createArea(long size)
Allocates a block of memory in the store of the specified size and returns an AreaWriter object that can be used to initialize the contents of the area.void
deleteArea(long id)
Deletes an area that was previously allocated by the 'createArea' method by the area id.java.util.List
getAllAreas()
Returns a complete list of pointers to all areas in the Store as Long objects sorted from lowest pointer to highest.Area
getArea(long id)
Returns an object that allows for the contents of an area (represented by the 'id' parameter) to be read.java.io.InputStream
getAreaInputStream(long id)
Returns an InputStream implementation that allows for the area with the given identifier to be read sequentially.MutableArea
getMutableArea(long id)
Returns an object that allows for the contents of an area (represented by the 'id' parameter) to be read and written.boolean
lastCloseClean()
Returns true if the store was closed cleanly.void
lockForWrite()
It is often useful to guarentee that a certain sequence of updates to a store is completed and not broken in the middle.void
unlockForWrite()
See the 'lockForWrite' method description.
-
-
-
Method Detail
-
createArea
AreaWriter createArea(long size) throws java.io.IOException
Allocates a block of memory in the store of the specified size and returns an AreaWriter object that can be used to initialize the contents of the area. Note that an area in the store is undefined until the 'finish' method is called in AreaWriter.- Parameters:
size
- the amount of memory to allocate.- Returns:
- an AreaWriter object that allows the area to be setup.
- Throws:
java.io.IOException
- if not enough space available to create the area or the store is read-only.
-
deleteArea
void deleteArea(long id) throws java.io.IOException
Deletes an area that was previously allocated by the 'createArea' method by the area id. Once an area is deleted the resources may be reclaimed. The behaviour of this method is undefined if the id doesn't represent a valid area.- Parameters:
id
- the identifier of the area to delete.- Throws:
java.io.IOException
- (optional) if the id is invalid or the area can not otherwise by deleted.
-
getAreaInputStream
java.io.InputStream getAreaInputStream(long id) throws java.io.IOException
Returns an InputStream implementation that allows for the area with the given identifier to be read sequentially. The behaviour of this method, and InputStream object, is undefined if the id doesn't represent a valid area.When 'id' is -1 then a fixed area (64 bytes in size) in the store is returned. The fixed area can be used to store important static static information.
- Parameters:
id
- the identifier of the area to read, or id = -1 is a 64 byte fixed area in the store.- Returns:
- an InputStream that allows the area to be read from the start.
- Throws:
java.io.IOException
- (optional) if the id is invalid or the area can not otherwise be accessed.
-
getArea
Area getArea(long id) throws java.io.IOException
Returns an object that allows for the contents of an area (represented by the 'id' parameter) to be read. The behaviour of this method, and Area object, is undefined if the id doesn't represent a valid area.When 'id' is -1 then a fixed area (64 bytes in size) in the store is returned. The fixed area can be used to store important static static information.
- Parameters:
id
- the identifier of the area to read, or id = -1 is a 64 byte fixed area in the store.- Returns:
- an Area object that allows access to the part of the store.
- Throws:
java.io.IOException
- (optional) if the id is invalid or the area can not otherwise be accessed.
-
getMutableArea
MutableArea getMutableArea(long id) throws java.io.IOException
Returns an object that allows for the contents of an area (represented by the 'id' parameter) to be read and written. The behaviour of this method, and MutableArea object, is undefined if the id doesn't represent a valid area.When 'id' is -1 then a fixed area (64 bytes in size) in the store is returned. The fixed area can be used to store important static static information.
- Parameters:
id
- the identifier of the area to access, or id = -1 is a 64 byte fixed area in the store.- Returns:
- a MutableArea object that allows access to the part of the store.
- Throws:
java.io.IOException
- (optional) if the id is invalid or the area can not otherwise be accessed.
-
lockForWrite
void lockForWrite()
It is often useful to guarentee that a certain sequence of updates to a store is completed and not broken in the middle. For example, when inserting data into a table you don't want a record to be partially written when a check point is made. You want the entire sequence of modifications to be completed before the check point can run. This means that if a crash occurs, a check point will not recover to a possible corrupt file.To achieve this, the 'lockForWrite' and 'unlockForWrite' methods are available. When 'lockForWrite' has been called, a check point can not created until there are no write locks obtained on the table.
-
unlockForWrite
void unlockForWrite()
See the 'lockForWrite' method description.
-
lastCloseClean
boolean lastCloseClean()
Returns true if the store was closed cleanly. This is important information that may need to be considered when reading information from the store. This is typically used to issue a scan on the data in the store when it is not closed cleanly.
-
getAllAreas
java.util.List getAllAreas() throws java.io.IOException
Returns a complete list of pointers to all areas in the Store as Long objects sorted from lowest pointer to highest. This should be used for diagnostics only because it may be difficult for this to be generated with some implementations. It is useful in a repair tool to determine if a pointer is valid or not.- Throws:
java.io.IOException
-
-