Skip to content

Getting Started

Jump to bottom
Ryandw11 edited this page Dec 9, 2020 · 8 revisions

Navigation

Using ODS

There are many ways to use ODS in your project.

1) Apache Maven

You can use Apache Maven to include ODS in your project. There are two version of ODS you can use: Releases, and Snapshots.

Releases are stable, production ready, builds of ODS.
Snapshots are development builds of ODS.
It is highly recommended that you use the latest release version of ODS.

Releases

To use the latest release version put the following in your pom.xml:

<repository>
    <id>Ryandw11</id>
    <url>https://repo.ryandw11.com/repository/maven-releases/</url>
</repository>

<dependency>
  <groupId>me.ryandw11</groupId>
  <artifactId>ods</artifactId>
  <version>{version}</version>
</dependency>

{version} is the latest version of ods. The latest version can be found here.

Snapshots

To use snapshot builds of ods put the following in your pom.xml:

<repository>
    <id>Ryandw11-SNAPSHOT</id>
    <url>https://repo.ryandw11.com/repository/maven-snapshots/</url>
</repository>

<dependency>
  <groupId>me.ryandw11</groupId>
  <artifactId>ods</artifactId>
  <version>{version}</version>
</dependency>

{version} is the snapshot version you want to use. A list of versions can be found here..

2) Gradle

Using Gradle is very similar to Maven. The versioning of Maven applies to Gradle

Releases

repositories {
    maven { url 'https://repo.ryandw11.com/repository/maven-releases/' }
}
    
dependencies {
    implementation 'com.ryandw11:ods:{version}'
}

Snapshots

repositories {
    maven { url 'https://repo.ryandw11.com/repository/maven-snapshots/' }
}
    
dependencies {
    implementation 'com.ryandw11:ods:{version}'
}

3) Fat Jar

You can also just included the pre-compiled ODS jar into your project.
Pre-compiled jars are only available for releases of ODS. You can find the download for the jar here

Creating an ODS file.

Creating an ods file is very simple, you just simply construct the ObjectDataStructure class with the file and compression option.

ObjectDataStructure ods = new ObjectDataStructure(new File("example.ods"), new GZIPCompression());

Compression Options

Compression just reduces the size of the file. There is zero difference between compression types for the most part.
Note: This has changed as of version 1.0.3. The compression now requires a class that implements Compressor instead of an Enum.
Please see the page on internal notes for possible differences in memory usage.

Built in Compressors:
NoCompression - There is zero compression.
GZIPCompression - Compression using GZIP.
ZLIBCompression - Compression using ZLIB.

You can also add your own compression algorithms or use addons (such as ODSCompressionPlus).

The Tag System

ODS uses tags to store data within files. Each primitive data type has its own tag. For a complete list of tags see the Java Documentation.

Each tag has two things: A name and value. Note: Tag names do not need to be unique.
Here is an example of a string tag with a name of sentance and a value of ODS is Cool!:

StringTag myString = new StringTag("sentance", "ODS is Cool!");

Note: It is preferred to use a camel case naming convention for primitive tags while ObjectTags are uppercase.

To retrieve the value of a tag you can simply use:

String value = myString.getValue();

List, Map, and Object tags have additional methods to improve their usability. Check the Java Documentation for more information.

Object Tags

Object Tags allow you to group multiple tags together. (This is where Object Data Structure gets its name)
You can add an unlimited amount of tags to an Object (including other object tags). This system allows you to make a hierarchy of objects.

ObjectTags do not need to be initialized with a value (although they can be).

ObjectTag carTag = new ObjectTag("Car");

You can add tags to the object via the addTag() method.

carTag.addTag(new StringTag("type", "Jeep"));
carTag.addTag(new IntTag("gas", 20));

You can grab a tag from an object by its name.

String carType = carTag.getTag("type");
// It might be a good idea to check if the object has the desired tag:
carTag.hasTag("type");

Objects can be automatically serialized into an object tag. See this page for more information on object serialization.

Saving Tags to a File

There are multiple way tags can be saved to a file.

1) Saving a list of tags.

This method takes in a list of tags saves it to the specified file. (This overrides existing data in the file)
If the file does not exist than it is automatically created. Note: It does not create directories.

List<Tag<?>> tags = new ArrayList<>();
tags.add(carTag);
ods.save(tags);

2) Appending a tag(s) to the root file.

You can append a tag by using the append(), appendAll(), and set() methods.

Append

You can append a single tag by using the append() method.

ods.append(new StringTag("Test", "TestTag"));

Append All

You can append multiple tags by using the appendAll() method.

ods.appendAll(listOfTags);

3) Replacing a tag.

You can replace tags by using the replaceData() and set() methods.

ods.replaceData("Example.Key", new StringTag("Key", "Example Key String"));

4) Using the Set method.

The set method is very powerful and can accomplish a ton of tasks.
Please see this page for how to use the set method

Clone this wiki locally