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:
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
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:
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
For example, to set the tenant to
SAMPLE, you would type:
Assuming that a tenant named
SAMPLE exists, the shell prompt will update to indicate the current tenant:
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
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.
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
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
@ symbol in front of the scripting filename (
Getting Help With Commands
You can get a list of all available commands by typing
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:
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>]