me.ryandw11.ods

Class ObjectDataStructure

java.lang.Object

me.ryandw11.ods.ObjectDataStructure

public class ObjectDataStructure
extends java.lang.Object

The primary class of the ObjectDataStructure library.

ObjectDataStructure has two storage types: File and Memory. File reads from a file while memory deals with an array (or buffer) of bytes. This class deals with both types. The type is dependent on the constructor.

Most methods in ODS use what is called a key to reference objects within the file/buffer. A key allows you to grab specific information within the file/buffer. For example: If you wanted a specific string inside of an object with lots of information, you can get that specific string without any other data. If you have an object named Car and you wanted to get a string tag named owner from the inside the object, then the key for that would be:

Car.owner

Let's say that the owner is an object called 'Owner' and you want to get the age of the owner, you could do:

Car.Owner.age

You can obtain any tag using the key system, including ObjectTags. So the key `Car.Owner` would be valid.

ODSException is thrown when an IOException is encountered or the file/buffer is not in the ODS format / is corrupted.

For exact information on the methods depending on storage type (viz. File or Memory) please visit the respective internal classes.

Version:

1.0.5

Constructor Summary

Constructors

Constructor and Description
ObjectDataStructure() Create ODS using the memory storage type.
ObjectDataStructure(byte[] data, Compressor compressor) Create ODS using the memory storage type.
ObjectDataStructure(java.nio.ByteBuffer data, Compressor compressor) Create ODS using the memory storage type.
ObjectDataStructure(java.io.File file) Create ODS using the file storage type.
ObjectDataStructure(java.io.File file, Compressor compression) Create ODS using the file storage type.

Method Summary

Modifier and Type	Method and Description
void	append(Tag<?> tag) Append tags to the end of the data.
void	appendAll(java.util.List<Tag<?>> tags) Append a list of tags to the end of the data.
void	clear() Clear all data from the file / memory.
boolean	delete(java.lang.String key) Remove a tag from the list.
byte[]	export(Compressor compressor) Get the array of bytes in any compression format.
boolean	find(java.lang.String key) Find if a key exists within the data.
<T extends Tag<?>> T	get(java.lang.String key) Grab a tag based upon an object key.
java.util.List<Tag<?>>	getAll() Get all of the tags in the file/buffer.
void	importFile(java.io.File file, Compressor compressor) Import the data from an ODS file.
boolean	replaceData(java.lang.String key, Tag<?> replacement) Replace a key with another tag.
void	save(java.util.List<? extends Tag<?>> tags) Save tags to the file/buffer.
void	saveToFile(java.io.File file, Compressor compressor) Save the data to a file.
void	set(java.lang.String key, Tag<?> value) This method can append, delete, and set tags.

Methods inherited from class java.lang.Object

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

Constructor Detail

ObjectDataStructure

public ObjectDataStructure(java.io.File file)

Create ODS using the file storage type. Data will be written to and read from a file.

This uses the GZIP compression format by default.

Parameters:

file - The file.

ObjectDataStructure

public ObjectDataStructure(java.io.File file,
                           Compressor compression)

Create ODS using the file storage type. Data will be written to and read from a file.

Parameters:

file - The file.

compression - What compression the file should use.

ObjectDataStructure

public ObjectDataStructure(byte[] data,
                           Compressor compressor)

Create ODS using the memory storage type. Data will be written to and read from a buffer.

Parameters:

data - Pre-existing data that should be inserted into the buffer.

compressor - The compression format the data uses.

ObjectDataStructure

public ObjectDataStructure(java.nio.ByteBuffer data,
                           Compressor compressor)

Create ODS using the memory storage type. Data will be written to and read from a buffer.

Parameters:

data - Pre-existing data should be inserted into the buffer.

compressor - The compression format the data uses.

ObjectDataStructure

public ObjectDataStructure()

Create ODS using the memory storage type. Data will be written to and read from a buffer.

An empty buffer is created.

Method Detail

get

public <T extends Tag<?>> T get(java.lang.String key)

Grab a tag based upon an object key.

This method allows you to directly get sub-objects with little overhead.

get("Object1.Object2.valuetag");

Type Parameters:

T - The tag type.

Parameters:

key - The key to use.

Returns:

The object Tag.

This will return null if the requested sub-object does not exist, or if the file does not exist.

getAll

public java.util.List<Tag<?>> getAll()

Get all of the tags in the file/buffer.

Returns:

All of the tags.

This will return null if there are no tags, or if the file does not exist.

save

public void save(java.util.List<? extends Tag<?>> tags)

Save tags to the file/buffer.

This will overwrite the existing data. To append tags see append(Tag) and appendAll(List)

Parameters:

tags - The list of tags to save.

append

public void append(Tag<?> tag)

Append tags to the end of the data.

Parameters:

tag - The tag to be appended.

appendAll

public void appendAll(java.util.List<Tag<?>> tags)

Append a list of tags to the end of the data.

Parameters:

tags - The list of tags.

find

public boolean find(java.lang.String key)

Find if a key exists within the data.

This will not throw ODSException if an IOException occurs.

Parameters:

key - They key to find

Returns:

If the key exists.

delete

public boolean delete(java.lang.String key)

Remove a tag from the list.

Parameters:

key - The key to remove.

Returns:

If the deletion was successfully done.

replaceData

public boolean replaceData(java.lang.String key,
                           Tag<?> replacement)

Replace a key with another tag.

Parameters:

key - The key

replacement - The data to replace

Returns:

If the replacement was successful. ODSException is not thrown.

set

public void set(java.lang.String key,
                Tag<?> value)

This method can append, delete, and set tags.

A note on keys when appending:
ObjectOne.ObjectTwo.tagName
When appending data tagName will not be the actual tag name. The tag name written to the file is the name of the specified tag in the value parameter. Any parent objects that do not exist will be created. For example:
ObjectOne.ObjectTwo.NewObject.tagName
If in the example above NewObject does not exist, than the object will be created with the value tag inside of it. Please see the wiki for a more detailed explanation on this.

When value is null, the specified key is deleted. The key MUST exist or an ODSException will be thrown.

Parameters:

key - The key of the tag to append, delete, or set.

When appending the key does not need to exist. ObjectTags that don't exist will be created automatically.

When the key is set to "" (An empty string) than it is assumed you want to append to the parent file/buffer.

Valid Tags:

ObjectOne.tagToDelete
ObjectOne.NewObject.tagToAppend
ObjectOne.tagToSet


value - The tag to append or replace the key with.

If this parameter is null than the key is deleted.

export

public byte[] export(Compressor compressor)

Get the array of bytes in any compression format.

Parameters:

compressor - The compression format.

Returns:

The array of bytes.

importFile

public void importFile(java.io.File file,
                       Compressor compressor)

Import the data from an ODS file.

See ODSMem.importFile(File, Compressor) and ODSFile.importFile(File, Compressor) for the specifics.

Parameters:

file - The file to import from.

compressor - The compressor.

saveToFile

public void saveToFile(java.io.File file,
                       Compressor compressor)

Save the data to a file.

See ODSMem.saveToFile(File, Compressor) and ODSFile.saveToFile(File, Compressor) for the specifics.

Parameters:

file - The file.

compressor - The Compressor.

clear

public void clear()

Clear all data from the file / memory.