cubicchunks.regionlib.api.storage

Class SaveSection<S extends SaveSection<S,K>,K extends IKey<K>>

java.lang.Object

cubicchunks.regionlib.api.storage.SaveSection<S,K>

Type Parameters:

S - This type

K - The location key type

All Implemented Interfaces:

java.io.Closeable, java.io.Flushable, java.lang.AutoCloseable

Direct Known Subclasses:

MinecraftSaveSection, SaveSection2D, SaveSection3D

public abstract class SaveSection<S extends SaveSection<S,K>,K extends IKey<K>>
extends java.lang.Object
implements java.io.Flushable, java.io.Closeable

A high level abstraction over the low level region-based storage API. Acts as a simple database for storing data for keys that are close together/clumped. Example: Key could be an integer location in n-dimensional space, like Minecraft chunk locations. Allows to use fallback region providers for reading and writing, allowing for backwards compatibility when data organization gets changed, or allows to use different storage method for entries not supported by the default IRegion implementation (standard Region implementetion has an upper limit for size)

Constructor Summary

Constructors

Constructor and Description
SaveSection(IRegionProvider<K> regionProvider) Creates a SaveSection with a customized IRegionProvider
SaveSection(java.util.List<IRegionProvider<K>> regionProviders) Creates a SaveSection with a customized IRegionProviders, with each next RegionProvider used as a fallback in case reading/writing is unsuccessful

Method Summary

Modifier and Type	Method and Description
java.util.stream.Stream<java.util.Map.Entry<K,java.nio.ByteBuffer>>	allEntries(boolean ensureUnique) Gets a Stream over all the already saved entries.
java.util.stream.Stream<K>	allKeys(boolean ensureUnique) Gets a Stream over all the already saved keys.
void	close()
void	flush()
void	forAllKeys(CheckedConsumer<? super K,java.io.IOException> cons) Deprecated. see allKeys(boolean)
boolean	hasEntry(K key)
java.util.Optional<java.nio.ByteBuffer>	load(K key, boolean createRegion) Loads/gets a value at a key This Method is thread safe.
void	save(K key, java.nio.ByteBuffer value) Saves/puts a value at a key This method is thread safe.
void	save(java.util.Map<K,java.nio.ByteBuffer> entries) Saves/puts multiple values at multiple keys This method is thread safe.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

SaveSection

public SaveSection(IRegionProvider<K> regionProvider)

Creates a SaveSection with a customized IRegionProvider

Parameters:

regionProvider - The region provider

SaveSection

public SaveSection(java.util.List<IRegionProvider<K>> regionProviders)

Creates a SaveSection with a customized IRegionProviders, with each next RegionProvider used as a fallback in case reading/writing is unsuccessful

Parameters:

regionProviders - The region providers

Method Detail

save

public void save(K key,
                 java.nio.ByteBuffer value)
          throws java.io.IOException

Saves/puts a value at a key This method is thread safe.

Parameters:

key - The key

value - The value to save

Throws:

java.io.IOException - when an unexpected IO error occurs

save

public void save(java.util.Map<K,java.nio.ByteBuffer> entries)
          throws java.io.IOException

Saves/puts multiple values at multiple keys This method is thread safe.

Parameters:

entries - the keys and values to save

Throws:

java.io.IOException - when an unexpected IO error occurs

load

public java.util.Optional<java.nio.ByteBuffer> load(K key,
                                                    boolean createRegion)
                                             throws java.io.IOException

Loads/gets a value at a key This Method is thread safe.

Parameters:

key - The key

createRegion - if true, a new region file will be created and cached. This is the preferred option.

Returns:

An Optional containing the value if it exists

Throws:

java.io.IOException - when an unexpected IO error occurs

allKeys

public java.util.stream.Stream<K> allKeys(boolean ensureUnique)
                                   throws java.io.IOException

Gets a Stream over all the already saved keys.

Keys added while the Stream is being evaluated may be skipped. Keys modified or removed while the Stream is being evaluated may be skipped or duplicated.

The returned Stream should be closed (using BaseStream.close()) once no longer needed to avoid potential resource leaks. If not closed, any resources allocated by the Stream may not be freed until the Stream instance is garbage-collected.

Parameters:

ensureUnique - if false and this SaveSection was created with multiple IRegionProviders, some keys may be duplicated even if no keys are saved while the Stream is being evaluated. Setting this parameter to true will prevent duplicate keys as long as no keys are saved while the Stream is being evaluated, but comes at a substantial performance cost. It is therefore strongly recommended to set it to false unless your application cannot deal with duplicate keys.

Returns:

a Stream over all already saved keys

Throws:

java.io.IOException - when an unexpected IO error occurs

allEntries

public java.util.stream.Stream<java.util.Map.Entry<K,java.nio.ByteBuffer>> allEntries(boolean ensureUnique)
                                                                               throws java.io.IOException

Gets a Stream over all the already saved entries.

Keys added while the Stream is being evaluated may be skipped. Keys modified or removed while the Stream is being evaluated may be skipped or duplicated.

The returned Stream should be closed (using BaseStream.close()) once no longer needed to avoid potential resource leaks. If not closed, any resources allocated by the Stream may not be freed until the Stream instance is garbage-collected.

Parameters:

ensureUnique - if false and this SaveSection was created with multiple IRegionProviders, some keys may be duplicated even if no keys are saved while the Stream is being evaluated. Setting this parameter to true will prevent duplicate keys as long as no keys are saved while the Stream is being evaluated, but comes at a substantial performance cost. It is therefore strongly recommended to set it to false unless your application cannot deal with duplicate keys.

Returns:

a Stream over all already saved entries

Throws:

java.io.IOException - when an unexpected IO error occurs

forAllKeys

@Deprecated
public void forAllKeys(CheckedConsumer<? super K,java.io.IOException> cons)
                            throws java.io.IOException

Deprecated. see allKeys(boolean)

Applies the given consumer to all already saved keys. Keys saved while this method is running are not guaranteed to be listed.

Implementation note: this implementation will sacrifice overall performance for O(1) memory usage in case of many fallback region provider

Parameters:

cons - Consumer that will accept all the existing regions

Throws:

java.io.IOException - when an unexpected IO error occurs

hasEntry

public boolean hasEntry(K key)
                 throws java.io.IOException

Throws:

java.io.IOException

flush

public void flush()
           throws java.io.IOException

Specified by:

flush in interface java.io.Flushable

Throws:

java.io.IOException

close

public void close()
           throws java.io.IOException

Specified by:

close in interface java.io.Closeable

Specified by:

close in interface java.lang.AutoCloseable

Throws:

java.io.IOException