Getting Started

Dodeca Shell (Dshell) is a command-line utility that helps you work with a Dodeca repository. It connects directly to the repository database (without going through the Dodeca server itself). Various actions can be performed on a repository, including viewing, exporting, importing, and searching for data.

Dshell is packaged as a self-contained runnable JAR file. In order to run it, you need to have Java 1.8+ installed on your system. It is much more convenient to run when you have java available on your system path, so that you only need to type java to run it, as opposed to a fully qualified path.

You can quickly test if Java is available on the current path as well as of a new enough version by trying to run the Java version command from a commmand-line:

java -version

If Java is installed and available on the path, you may see output like the following:

java version "1.8.0_25"
Java(TM) SE Runtime Environment (build 1.8.0_25-b17)
Java HotSpot(TM) 64-Bit Server VM (build 25.25-b02, mixed mode)

You can run dshell by executing the following command:

java -Dloader.path=lib/ -jar dodeca-shell.jar

This command defines a variable named loader.path and sets it to the lib subfolder of the current working directory. This setting sets the folder that Dshell should look in for additional JDBC drivers that may be needed to connect to your Dodeca repository. You will likely need additional JAR files for your repository, based on its database technology (such as Oracle, Microsoft SQL Server, DB2, MySQL, and others).

If everything works correctly, you will see Dshell start up similar to the following:

       __     __         ____
  ____/ /____/ /_  ___  / / /
 / __  / ___/ __ \/ _ \/ / /
/ /_/ (__  ) / / /  __/ / /
\__,_/____/_/ /_/\___/_/_/
You are connected to an internal repository. Use the connect command to connect to a Dodeca repository
Type 'help connect' for information on how to use the connect command
dshell/:>

By default, dshell starts up and is connected to an internal repository that does not have any objects in it. You can use this workspace to facilitate certain types of testing, but most likely you will need and want to connect it to your own repository.

Connecting To Your Dodeca Repository

The easiest way to connect to a repository is to create a properties file with the connection settings in it. This can be as simple as a file with the following contents:

dodeca.datasource.url = jdbc:mysql://server/dodeca?noDatetimeStringSync=true
dodeca.datasource.username = dodeca
dodeca.datasource.password = password

The preceding example is for a repository inside a MySQL database, therefore the JDBC URL is formatted specifically for MySQL. The URL format for other database types typically varies. You can use the same setting from your existing hibernate.properties file configured for your Dodeca server or attempt to create the URL yourself. The username and password fields are defined with the plaintext version of the password.

For convenience, you can use the suffix .dodeca.properties on your connection file, for a total file name such as mysql-dev.dodeca.properties. This allows you to use the list-connections command in the shell, which will list all of the files in the current directory that have this suffix. You may then use the connect command to refer to this short version of the file, such as:

connect mysql-dev

You may use the fully-qualified name of the file as well. You can switch between different repository connections during a single shell session, even if those connections are different database technologies (so long as the appropriate JDBC drivers are available, of course).

Most shell commands require having specified a tenant to work with by using the use command. For example, to set the tenant to SAMPLE, you would type:

use SAMPLE

Assuming that a tenant named SAMPLE exists, the shell prompt will update to indicate the current tenant:

dshell/SAMPLE:>

Using Tab-based Auto-completion

Many commands in the shell support tab-based auto-completion. This can make entering artfiact IDs, tenants, commands, and file names much more quick and less error prone.

For example, consider when there are a number of tenants available, such as by using the list-tenants command:

dshell/SAMPLE:>list-tenants
+---------------------------+
|Tenant                     |
+---------------------------+
|DEMOWARE                   |
|SAMPLE                     |
+---------------------------+

You may then wish to switch to the DEMOWARE tenant. You can have the shell provide you a list of items to select from, or a list of items based on what you have already typed in. For example, upon typing use DE followed by pressing the tab key, the shell will finish off the text by using the matching tenant (in this case, DEMOWARE), and you can then press enter to execute the command.

If you have not started typing the text for an item, the shell may prompt your for the parameter name first, which you can select and press tab again in order to get the list of all available options.

Scripting

The shell offers limited scripting/automation capabilities by way of running the shell with an additional parameter that specifies a list of commands to run sequentially. For instance, you may wish to automate a process that connects to your repository and exports all of the comments for a certain Dodeca tenant named SAMPLE. The sequence of commands for accomplishing this would be the following:

connect mysql-dev
use SAMPLE
export-comments --file comment_export.xml

You can then put these lines into a file named export_comments.dshell and then run it with the following command:

java -Dloader.path=lib/ -jar dodeca-shell.jar @export_comments.dshell

Note that @ symbol in front of the scripting filename (@export_comments.dshell).

Getting Help With Commands

You can get a list of all available commands by typing help. You can get help and parameter information by typing help followed by the command name. For instance, to get help on the export-comments command, type:

help export-comments

You will then be presented with help like the following:

NAME
	export-comments - Export comments

SYNOPSYS
	export-comments [--file] file  [[--author] string]  [[--include-key-spec]
	comment-key-spec]  [[--exclude-key-spec] comment-key-spec]

OPTIONS
	--file or -F  file

		[Mandatory]

	--author  string

		[Optional, default = <none>]

	--include-key-spec  comment-key-spec

		[Optional, default = <none>]

	--exclude-key-spec  comment-key-spec

		[Optional, default = <none>]