You are viewing an older version of the site. Click here to view
the latest version of this page. (This may be a dead link, if so, try the root page of the docs
here.)
The data manager is a tool that is built directly in to CommandHelper that assists you in managing your persisted data.
There are several functions available to help you view, edit, and move your stored data around. Before you jump into using
the data manager, it is important that you understand the lower level details, so you don't mess anything up. The data
manager gives you direct access to the underlying data, so you could possibly screw things up if you aren't careful,
so please read this documentation carefully, and be sure you understand what's happening before you try it.
==Persistence Details==
Currently, several methods of data storage are available. Usage of the actual Persistence Network is described
[[Persistence_Network|here]], and explains how to configure the different backends.
Conversion between the types is also be possible, so if you begin storing values now, these will be portable
later. The data in each row is stored as a partial [http://en.wikipedia.org/wiki/JSON JSON], but otherwise follows
all rules of JSONs. {Objects} and [Arrays] are supported.
The simplest and quickest way to view all the currently stored values is to open up a terminal, and change to the
directory the CommandHelper jar is in, and run the following command:
refactor - Allows you to shuffle data around in the persistence network more granularly than the merge tool.
print - Prints out the information from your persisted data
cleardb - Clears out your database of persisted data
edit - Allows you to edit individual fields
interpreter - Command Line Interpreter mode. Most minecraft related functions don't work.
merge - Merges an entire database from one backend into another, even across formats. (Not individual keys.)
You can also use this tool to an extent to import or export data.
hidden-keys - Lists all hidden keys in known data sources
exit - Quits the Data Manager
Type help <command> for more details about a specific command
===refactor=== This tool allows you to granularly move individual keys from one datasource to another. Unlike the merge tool, this works with individual keys, not necessarily keys that are within a particular data source. There are three required inputs, the transfer key pattern, the input configuration file, and the output configuration file. Data is transferred from one configuration to the other, that is, it is added in the new place, and removed in the old place. This tool is more complicated than the merge tool, so consider using the other tool for simple tasks. ===print=== Prints out the information in your persistence file. Entries may be narrowed down by specifying the namespace (for instance print storage.warp will show only that data.) This is namespace based, so you must provide the entire namespace that your are trying to narrow down.(print storage is valid, but print stor is not) ===cleardb=== Wipes your database clean of CommandHelper's persistence entries, but not other data. This includes any data that CommandHelper would have inserted into the database, or data that CommandHelper otherwise knows how to use. If using Serialized Persistence (ser), this means the entire file. For other data backends, this may vary slightly, for instance, an SQL backend would only have the CH specific tables truncated, but the rest of the database would remain untouched. ===edit=== Allows you to manually edit the values in the database. You have the option to add or edit an existing value, delete a single value, or view the value of an individual key. ===interpreter=== Generally speaking, works the same as the in game interpreter mode, but none of the minecraft related functions will work. You should not run this while the server is operational. ===merge=== The merge tool allows you to shuffle persisted data around as entire databases, not as individual keys, however. You specify the source database, and the output database, and it copies all the database entries. This can be used to an extent to import and export values, but it is not granular at all. Key conflicts are handled by prompting the user for an action, whether to overwrite the destination's value, or to keep it as is. Thusly, this operation is very safe from accidentally deleting your data. Keys that don't exist in the destination already are simply copied, and keys that have the same value are skipped. No changes are made to the source database. ===hidden-keys=== The hidden-keys tool allows you to locate any "hidden keys," that is, keys that exist in a data source, but can't be accessed normally. This can happen if you make changes to your persistence.ini file but don't refactor or otherwise migrate the data when you "hide" the keys. For instance, say you only have "**=sqlite://persistence.db" in your file, and you store some value in "storage.a". Later, you add "storage.a=json://file.json" to your persistence.ini file, but you don't refactor. The value stored at "storage.a" in the sqlite file is now inaccessible, and if you store another value in "storage.a," the new value would be stored in file.json, and the original value in the sqlite file would simply be dead memory. This wouldn't cause any direct issues, but if a significant number of keys are "dead," this would take up hard disk space for no reason. Additionally, refactors could have unexpected results. You will have the option to view or delete the hidden keys. Viewing them will print out a summary of all the keys, and deleting them will allow you to wholesale delete them. ==Namespaces== If you have a script that runs
java -jar CommandHelper.jar print-db
Printing all persisted values: storage.value1: 1 storage.hi: "hi" storage.value2: ["string", null, true, false, []] storage.value3: "\"string\" with special characters \\" Done printing persisted valuesThe
storage. bit simply namespaces the data. This way we can reserve other namespaces for future use.
The part that you typically have control over from your scripts is this:
value1: 1 hi: "hi" value2: ["string", null, true, false, []] value3: "\"string\" with special characters \\"The key for the data is on the left, and the value is on the right. Each piece of data (other than arrays) are stored as ''partial JSONs'', which by themselves aren't any kind of standard thing, but can be combined to form a true JSON. You can determine the datatype of each node by noting the [http://www.json.org/ rules that JSONs follow]. In the future, CommandHelper will allow you to create your own JSONs from internal data structures, which will be usable by all sorts of neat advanced functions. Also, once values are stored in databases, you'll be able to manipulate this data from external or even remote applications, which will allow you to do all sorts of cool things. ==Using the Data Manager== The data manager is an interactive shell program that runs as a standalone program. Before using the data manager to edit your data, you should first ensure that nothing else is using your persistence files (so, shut down your server). The only exception to this is for locking databases, such as SQL based backends, there should be no issues with read/write access, even if the server is running, and read access for all other backends. To access the data manager, open up a terminal (command prompt in Windows) and cd to the plugins folder of your server, and run the following command:
java -jar CommandHelper.jar manager
refactor - Allows you to shuffle data around in the persistence network more granularly than the merge tool.
print - Prints out the information from your persisted data
cleardb - Clears out your database of persisted data
edit - Allows you to edit individual fields
interpreter - Command Line Interpreter mode. Most minecraft related functions don't work.
merge - Merges an entire database from one backend into another, even across formats. (Not individual keys.)
You can also use this tool to an extent to import or export data.
hidden-keys - Lists all hidden keys in known data sources
exit - Quits the Data Manager
Type help <command> for more details about a specific command
===refactor=== This tool allows you to granularly move individual keys from one datasource to another. Unlike the merge tool, this works with individual keys, not necessarily keys that are within a particular data source. There are three required inputs, the transfer key pattern, the input configuration file, and the output configuration file. Data is transferred from one configuration to the other, that is, it is added in the new place, and removed in the old place. This tool is more complicated than the merge tool, so consider using the other tool for simple tasks. ===print=== Prints out the information in your persistence file. Entries may be narrowed down by specifying the namespace (for instance print storage.warp will show only that data.) This is namespace based, so you must provide the entire namespace that your are trying to narrow down.(print storage is valid, but print stor is not) ===cleardb=== Wipes your database clean of CommandHelper's persistence entries, but not other data. This includes any data that CommandHelper would have inserted into the database, or data that CommandHelper otherwise knows how to use. If using Serialized Persistence (ser), this means the entire file. For other data backends, this may vary slightly, for instance, an SQL backend would only have the CH specific tables truncated, but the rest of the database would remain untouched. ===edit=== Allows you to manually edit the values in the database. You have the option to add or edit an existing value, delete a single value, or view the value of an individual key. ===interpreter=== Generally speaking, works the same as the in game interpreter mode, but none of the minecraft related functions will work. You should not run this while the server is operational. ===merge=== The merge tool allows you to shuffle persisted data around as entire databases, not as individual keys, however. You specify the source database, and the output database, and it copies all the database entries. This can be used to an extent to import and export values, but it is not granular at all. Key conflicts are handled by prompting the user for an action, whether to overwrite the destination's value, or to keep it as is. Thusly, this operation is very safe from accidentally deleting your data. Keys that don't exist in the destination already are simply copied, and keys that have the same value are skipped. No changes are made to the source database. ===hidden-keys=== The hidden-keys tool allows you to locate any "hidden keys," that is, keys that exist in a data source, but can't be accessed normally. This can happen if you make changes to your persistence.ini file but don't refactor or otherwise migrate the data when you "hide" the keys. For instance, say you only have "**=sqlite://persistence.db" in your file, and you store some value in "storage.a". Later, you add "storage.a=json://file.json" to your persistence.ini file, but you don't refactor. The value stored at "storage.a" in the sqlite file is now inaccessible, and if you store another value in "storage.a," the new value would be stored in file.json, and the original value in the sqlite file would simply be dead memory. This wouldn't cause any direct issues, but if a significant number of keys are "dead," this would take up hard disk space for no reason. Additionally, refactors could have unexpected results. You will have the option to view or delete the hidden keys. Viewing them will print out a summary of all the keys, and deleting them will allow you to wholesale delete them. ==Namespaces== If you have a script that runs
store_value('MyKey','MyValue'), then the following entry would be created
in the database:
storage.MyKey: "MyValue"The
storage namespace is reserved for values that are created and accessible from our script's store_value
and get_value functions. If you manually edit the data from the data manager, or import other external data, if you
want this data to be accessible from your scripts, you must include the correct namespace in the key name. The
following namespaces are reserved for future use, and should not be used outside of their given scope:
* storage.**: Values accessible from your main script's store_value and get_value functions.
* oauth.**: Refresh and access tokens stored by the OAuth scripts
* site_deploy.**: Information used by site-deploy tool is stored in this namespace.
* federation.**: The Federation system stores values here. The namespace should never be set to read only, and should be in a transient data source.
* extension.<extension name>.**: Extensions may store data in this namespace.
* custom.**: CommandHelper will not ever touch any values stored in here, and you may use this however you wish with external scripts.
* l10n.**: Settings related to the Localization UI Tool.
If you intend on putting in your own values, the only namespace you should use is custom. All other namespaces are not
currently planned to hold data, but are not guaranteed to remain unused in the future.
''Note:'' The store_value() function allows for namespaces to be added, but that, get_value()
and get_values() namespaces are all children of the underlying storage namespace, and should
not be referenced when using the functions from code.
{{LearningTrail}}
Find a bug in this page? Edit this page yourself, then submit a pull request.
