squidpony.store.text

Class TextStorage

java.lang.Object

squidpony.store.text.TextStorage

public class TextStorage
extends java.lang.Object

Helps games store information in libGDX's Preferences class as Strings, then get it back out. Does not use JSON, instead using a customized and customizable manual serialization style based around StringConvert. Created by Tommy Ettinger on 9/16/2016.

Field Summary

Fields

Modifier and Type	Field and Description
boolean	compress
protected squidpony.squidmath.OrderedMap<java.lang.String,java.lang.String>	contents
long[]	garbleKey
squidpony.StringConvert<squidpony.squidmath.OrderedMap<java.lang.String,java.lang.String>>	mapConverter
com.badlogic.gdx.Preferences	preferences
java.lang.String	storageName

Constructor Summary

Constructors

Constructor and Description
TextStorage() Please don't use this constructor if possible; it simply calls TextStorage(String) with the constant String "nameless".
TextStorage(java.lang.String fileName) Creates a JsonStorage with the given fileName to save using Preferences from libGDX.
TextStorage(java.lang.String fileName, long[] garble) Creates a JsonStorage with the given fileName to save using Preferences from libGDX.
TextStorage(java.lang.String fileName, java.lang.String garble) Creates a JsonStorage with the given fileName to save using Preferences from libGDX.

Method Summary

Modifier and Type	Method and Description
TextStorage	clear() Clears the current group of objects; recommended if you intend to store under multiple outerName keys.
<T> T	get(java.lang.String outerName, java.lang.String innerName, java.lang.CharSequence typeName, java.lang.Class<T> type) Gets an object from the storage by the given outerName key from store(String) and innerName key from put(String, Object, StringConvert), and uses the class given by type for the returned value, assuming it matches the object that was originally put with those keys.
<T> T	get(java.lang.String outerName, java.lang.String innerName, squidpony.StringConvert<?> converter, java.lang.Class<T> type) Gets an object from the storage by the given outerName key from store(String) and innerName key from put(String, Object, StringConvert), and uses the class given by type for the returned value, assuming it matches the object that was originally put with those keys.
int	preferencesSize() Gets the approximate size of the currently-stored preferences.
<T> TextStorage	put(java.lang.String innerName, T o, squidpony.StringConvert converter) Prepares to store the Object o to be retrieved with innerName in the current group of objects.
TextStorage	remove(java.lang.String innerName) Removes one object from the current group by the innerName it was prepared with using put(String, Object, StringConvert).
java.lang.String	show() Gets a String representation of the data that would be saved when store(String) is called.
TextStorage	store(java.lang.String outerName) Actually stores all objects that had previously been prepared with put(String, Object, StringConvert), with outerName used as a key to retrieve any object in the current group.

Methods inherited from class java.lang.Object

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

Field Detail

preferences

public final com.badlogic.gdx.Preferences preferences

storageName

public final java.lang.String storageName

contents

protected squidpony.squidmath.OrderedMap<java.lang.String,java.lang.String> contents

mapConverter

public final squidpony.StringConvert<squidpony.squidmath.OrderedMap<java.lang.String,java.lang.String>> mapConverter

compress

public boolean compress

garbleKey

public long[] garbleKey

Constructor Detail

TextStorage

public TextStorage()

Please don't use this constructor if possible; it simply calls TextStorage(String) with the constant String "nameless". This could easily overlap with other files/sections in Preferences, so you should always prefer giving a String argument to the constructor, typically the name of the game.

See Also:

the recommended constructor to use

TextStorage

public TextStorage(java.lang.String fileName)

Creates a JsonStorage with the given fileName to save using Preferences from libGDX. The name should generally be the name of this game or application, and must be a valid name for a file (so no slashes, backslashes, colons, semicolons, or commas for certain, and other non-alphanumeric characters are also probably invalid). You should not assume anything is present in the Preferences storage unless you have put it there, and this applies doubly to games or applications other than your own; you should avoid values for fileName that might overlap with another game's Preferences values.
To organize saved data into sub-sections, you specify logical units (like different players' saved games) with a String outerName when you call store(String), and can further distinguish data under the outerName when you call put(String, Object, StringConvert) to put each individual item into the saved storage with its own innerName.
Calling this also sets up custom serializers for several important types in SquidLib; char[][], OrderedMap, IntDoubleOrderedMap, FakeLanguageGen, GreasedRegion, and notably Pattern from RegExodus all have smaller serialized representations than the default. OrderedMap allows non-String keys, which gets around a limitation in JSON maps normally, and both FakeLanguageGen and Pattern are amazingly smaller with the custom representation. The custom char[][] representation is about half the normal size by omitting commas after each char.

Parameters:

fileName - the valid file name to create or open from Preferences; typically the name of the game/app.

TextStorage

public TextStorage(java.lang.String fileName,
                   java.lang.String garble)

Creates a JsonStorage with the given fileName to save using Preferences from libGDX. The name should generally be the name of this game or application, and must be a valid name for a file (so no slashes, backslashes, colons, semicolons, or commas for certain, and other non-alphanumeric characters are also probably invalid). You should not assume anything is present in the Preferences storage unless you have put it there, and this applies doubly to games or applications other than your own; you should avoid values for fileName that might overlap with another game's Preferences values. This constructor also allows you to specify a "garble" String; if this is non-null, it will be used as a key to obfuscate the output and de-obfuscate the loaded input using fairly basic methods. If garble is null, it is ignored.
To organize saved data into sub-sections, you specify logical units (like different players' saved games) with a String outerName when you call store(String), and can further distinguish data under the outerName when you call put(String, Object, StringConvert) to put each individual item into the saved storage with its own innerName.
Calling this also sets up custom serializers for several important types in SquidLib; char[][], OrderedMap, IntDoubleOrderedMap, FakeLanguageGen, GreasedRegion, and notably Pattern from RegExodus all have smaller serialized representations than the default. OrderedMap allows non-String keys, which gets around a limitation in JSON maps normally, and both FakeLanguageGen and Pattern are amazingly smaller with the custom representation. The custom char[][] representation is about half the normal size by omitting commas after each char.

Parameters:

fileName - the valid file name to create or open from Preferences; typically the name of the game/app.

garble - the key that must be used exactly to decrypt any data saved by this TextStorage

TextStorage

public TextStorage(java.lang.String fileName,
                   long[] garble)

Creates a JsonStorage with the given fileName to save using Preferences from libGDX. The name should generally be the name of this game or application, and must be a valid name for a file (so no slashes, backslashes, colons, semicolons, or commas for certain, and other non-alphanumeric characters are also probably invalid). You should not assume anything is present in the Preferences storage unless you have put it there, and this applies doubly to games or applications other than your own; you should avoid values for fileName that might overlap with another game's Preferences values. This constructor also allows you to specify a "garble" long array; if this is non-empty, it will be used as a key to obfuscate the output and de-obfuscate the loaded input using fairly basic methods. If garble is null or empty, it is ignored.
To organize saved data into sub-sections, you specify logical units (like different players' saved games) with a String outerName when you call store(String), and can further distinguish data under the outerName when you call put(String, Object, StringConvert) to put each individual item into the saved storage with its own innerName.
Calling this also sets up custom serializers for several important types in SquidLib; char[][], OrderedMap, IntDoubleOrderedMap, FakeLanguageGen, GreasedRegion, and notably Pattern from RegExodus all have smaller serialized representations than the default. OrderedMap allows non-String keys, which gets around a limitation in JSON maps normally, and both FakeLanguageGen and Pattern are amazingly smaller with the custom representation. The custom char[][] representation is about half the normal size by omitting commas after each char.

Parameters:

fileName - the valid file name to create or open from Preferences; typically the name of the game/app.

garble - the key that must be used exactly to decrypt any data saved by this TextStorage; will be copied

Method Detail

put

public <T> TextStorage put(java.lang.String innerName,
                           T o,
                           squidpony.StringConvert converter)

Prepares to store the Object o to be retrieved with innerName in the current group of objects. Does not write to a permanent location until store(String) is called. The innerName used to store an object is required to get it back again, and can also be used to remove it before storing (or storing again).

Parameters:

innerName - one of the two Strings needed to retrieve this later

o - the Object to prepare to store

converter - a StringConvert that supports the type of o

Returns:

this for chaining

store

public TextStorage store(java.lang.String outerName)

Actually stores all objects that had previously been prepared with put(String, Object, StringConvert), with outerName used as a key to retrieve any object in the current group. Flushes the preferences, making the changes permanent (until overwritten), but does not change the current group (you may want to call this method again with additional items in the current group, and that would simply involve calling put() again). If you want to clear the current group, use clear(). If you want to remove just one object from the current group, use remove(String).

Parameters:

outerName - one of the two Strings needed to retrieve any of the objects in the current group

Returns:

this for chaining

show

public java.lang.String show()

Gets a String representation of the data that would be saved when store(String) is called. This can be useful for finding particularly problematic objects that require unnecessary space when serialized.

Returns:

a String that previews what would be stored permanently when store(String) is called

clear

public TextStorage clear()

Clears the current group of objects; recommended if you intend to store under multiple outerName keys.

Returns:

this for chaining

remove

public TextStorage remove(java.lang.String innerName)

Removes one object from the current group by the innerName it was prepared with using put(String, Object, StringConvert). This does not affect already-stored objects unless store(String) is called after this, in which case the new version of the current group, without the object this removed, is stored.

Parameters:

innerName - the String key used to put an object in the current group with put(String, Object, StringConvert)

Returns:

this for chaining

get

public <T> T get(java.lang.String outerName,
                 java.lang.String innerName,
                 squidpony.StringConvert<?> converter,
                 java.lang.Class<T> type)

Gets an object from the storage by the given outerName key from store(String) and innerName key from put(String, Object, StringConvert), and uses the class given by type for the returned value, assuming it matches the object that was originally put with those keys. If no such object exists, returns null. Results are undefined if type doesn't match the actual class of the stored object.

Type Parameters:

T - the type of the value to retrieve; if type was RNG.class, this would be RNG

Parameters:

outerName - the key used to store the group of objects with store(String)

innerName - the key used to store the specific object with put(String, Object, StringConvert)

converter - a StringConvert, such as one from Converters or found with StringConvert.get(CharSequence), to deserialize the data

type - the class of the value; for a class like RNG, use RNG.class, but changed to fit

Returns:

the retrieved value if successful, or null otherwise

get

public <T> T get(java.lang.String outerName,
                 java.lang.String innerName,
                 java.lang.CharSequence typeName,
                 java.lang.Class<T> type)

Gets an object from the storage by the given outerName key from store(String) and innerName key from put(String, Object, StringConvert), and uses the class given by type for the returned value, assuming it matches the object that was originally put with those keys. Uses typeName to find an appropriate StringConvert that has already been created (and thus registered), and because typeName is a CharSequence instead of a Class, it doesn't suffer from generic type erasure at runtime, It can and should have the generic type arguments as if it were the type for a variable, e.g. OrderedSet<ArrayList<String>>. If no such object exists, returns null. Results are undefined if type doesn't match the actual class of the stored object, and this will return null if there is no known StringConvert for the given typeName.

Type Parameters:

T - the type of the value to retrieve; if type was RNG.class, this would be RNG

Parameters:

outerName - the key used to store the group of objects with store(String)

innerName - the key used to store the specific object with put(String, Object, StringConvert)

typeName - the name of the type to produce, with generic type parameters intact; used to find an appropriate StringConvert

type - the class of the value; for a class like RNG, use RNG.class, but changed to fit

Returns:

the retrieved value if successful, or null otherwise

preferencesSize

public int preferencesSize()

Gets the approximate size of the currently-stored preferences. This assumes UTF-16 storage, which is the case for GWT's LocalStorage. Since GWT is restricted to the size the browser permits for LocalStorage, and this limit can be rather small (about 5 MB, sometimes more but not reliably), this method is especially useful there, but it may yield inaccurate sizes on other platforms that save Preferences data differently.

Returns:

the size, in bytes, of the already-stored preferences