Got a question that the wiki doesn't answer? Ask on the forum (preferred), or join us on IRC.

BeastNode

CommandHelper/Staged/Data Manager

From EngineHub.org Wiki
Jump to: navigation, search


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 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 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:

java -jar CommandHelper.jar print-db

This will print all the stored values to the console. Using pipes and redirects, you can further manipulate this output if desired. Let's take a look at the output and explain it further:

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 values

The 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 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 persistance 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

The manager should then load up. Type "help" at the prompt to view the possible functions.


Currently, your options are:
   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 user.username will only show that particular users's aliases.) 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.
  • 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.

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.



Navigation menu