Package squidpony
Class SquidStorage
java.lang.Object
squidpony.store.json.JsonStorage
squidpony.SquidStorage
public class SquidStorage extends JsonStorage
Helps games store information in libGDX's Preferences class as Strings, then get it back out.
Created by Tommy Ettinger on 9/16/2016.
-
Field Summary
Fields inherited from class squidpony.store.json.JsonStorage
compress, contents, garbleKey, json, preferences, storageName
-
Constructor Summary
Constructors Constructor Description SquidStorage()
Please don't use this constructor if possible; it simply callsSquidStorage(String)
with the constant String "nameless".SquidStorage(String fileName)
Creates a SquidStorage with the given fileName to save using Preferences from libGDX.SquidStorage(String fileName, long[] garble)
Creates a SquidStorage with the given fileName to save using Preferences from libGDX.SquidStorage(String fileName, String garble)
Creates a SquidStorage with the given fileName to save using Preferences from libGDX. -
Method Summary
Modifier and Type Method Description SquidStorage
clear()
Clears the current group of objects; recommended if you intend to store under multiple outerName keys.<T> T
get(String outerName, String innerName, Class<T> type)
Gets an object from the storage by the givenouterName
key fromstore(String)
andinnerName
key fromput(String, Object)
, and uses the class given bytype
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.SquidStorage
put(String innerName, Object o)
Prepares to store the Objecto
to be retrieved withinnerName
in the current group of objects.SquidStorage
remove(String innerName)
Removes one object from the current group by theinnerName
it was prepared with usingput(String, Object)
.String
show()
Gets a String representation of the data that would be saved whenstore(String)
is called.SquidStorage
store(String outerName)
Actually stores all objects that had previously been prepared withput(String, Object)
, withouterName
used as a key to retrieve any object in the current group.
-
Constructor Details
-
SquidStorage
public SquidStorage()Please don't use this constructor if possible; it simply callsSquidStorage(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
-
SquidStorage
Creates a SquidStorage 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 callstore(String)
, and can further distinguish data under the outerName when you callput(String, Object)
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.
-
SquidStorage
Creates a SquidStorage 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 callstore(String)
, and can further distinguish data under the outerName when you callput(String, Object)
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
- a String that will be used as a key to obfuscate the saved output if non-null
-
SquidStorage
Creates a SquidStorage 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 callstore(String)
, and can further distinguish data under the outerName when you callput(String, Object)
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
- a long array that will be used as a key to obfuscate the saved output if non-null
-
-
Method Details
-
put
Prepares to store the Objecto
to be retrieved withinnerName
in the current group of objects. Does not write to a permanent location untilstore(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).- Overrides:
put
in classJsonStorage
- Parameters:
innerName
- one of the two Strings needed to retrieve this latero
- the Object to prepare to store- Returns:
- this for chaining
-
store
Actually stores all objects that had previously been prepared withput(String, Object)
, withouterName
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, useclear()
. If you want to remove just one object from the current group, useremove(String)
.- Overrides:
store
in classJsonStorage
- Parameters:
outerName
- one of the two Strings needed to retrieve any of the objects in the current group- Returns:
- this for chaining
-
show
Gets a String representation of the data that would be saved whenstore(String)
is called. This can be useful for finding particularly problematic objects that require unnecessary space when serialized.- Overrides:
show
in classJsonStorage
- Returns:
- a String that previews what would be stored permanently when
store(String)
is called
-
clear
Clears the current group of objects; recommended if you intend to store under multiple outerName keys.- Overrides:
clear
in classJsonStorage
- Returns:
- this for chaining
-
remove
Removes one object from the current group by theinnerName
it was prepared with usingput(String, Object)
. This does not affect already-stored objects unlessstore(String)
is called after this, in which case the new version of the current group, without the object this removed, is stored.- Overrides:
remove
in classJsonStorage
- Parameters:
innerName
- the String key used to put an object in the current group withput(String, Object)
- Returns:
- this for chaining
-
get
Gets an object from the storage by the givenouterName
key fromstore(String)
andinnerName
key fromput(String, Object)
, and uses the class given bytype
for the returned value, assuming it matches the object that was originally put with those keys. If no such object is present, returns null. Results are undefined iftype
doesn't match the actual class of the stored object.- Overrides:
get
in classJsonStorage
- Type Parameters:
T
- the type of the value to retrieve; if type wasRNG.class
, this would beRNG
- Parameters:
outerName
- the key used to store the group of objects withstore(String)
innerName
- the key used to store the specific object withput(String, Object)
type
- the class of the value; for a class like RNG, useRNG.class
, but changed to fit- Returns:
- the retrieved value if successful, or null otherwise
-
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.- Overrides:
preferencesSize
in classJsonStorage
- Returns:
- the size, in bytes, of the already-stored preferences
-