Admin Tool Guide

The admin tool utility provides a simple, command-line interface for common administration tasks such as adding Associations to the registry and removing objects from the registry

The admin tool is still actively being developed. This means that there may be differences between the current version and what has been documented here. It also means that it is still possible for you to lobby for any features that you want to see added to the admin tool. Lastly, it means that the admin tool needs you to test it out to make sure that it works as expected.

The tool operates either in batch mode, where it executes the commands specified on the command line, or in interactive mode, where you enter your sequence of commands in the tool's interactive shell.

In keeping with the "files and folders" metaphor used for RegistryObjects in RegistryPackages, several commands - such as ls and rm - mimic both the name and the behavior of well-known Unix commands that operate on files and folders. There are also other, registry-specific commands that have no corresponding Unix equivalent.

For information on configuring and extending the admin tool, see the admin tool developer guide.

Running the Admin Tool

You run the admin tool by executing the admin-tool.jar jar file:

java -jar path/to/admin-tool.jar <parameters>

Batch mode

For example, to execute a command on the command line:

java -jar build/lib/admin-tool.jar -command "ls *.html"

The admin tool will echo your commands and the tool's responses to the screen and then exit once your commands have been executed.

It's up to you to make sure that you properly escape any characters that are significant to your shell.

Ant target

This is batch mode under another name, since the Ant target just runs the admin tool with arguments that you specified in the -DadminTool.args argument to Ant, e.g.:

ant -DadminTool.args="-command \"ls *.html\"" run.adminTool

It is up to you to adequately escape any characters that are significant either to your shell or to Ant. For example, any '\' characters may need to be escaped one or more times.

Interactive mode

To start the admin tool shell where the same command can be entered interactively:

java -jar build/lib/admin-tool.jar

The admin tool will emit an admin> prompt and wait for your input.

Parameters

The following parameters are recognised when starting the admin tool:

[-alias <alias>]
[-class <adminShellClass>]
[-command <commands>]
[-debug]
[-help]
[-keypass <keypass>]
[-localdir <localdir>]
[-locale <locale>]
[-property <name> <value>]*
[-registry <url>]
[-root <locator> [-create]]
[-sqlselect <SQL statement>]
[-v | -verbose]

Where:

-alias <alias>
Alias to use when accessing user's certificate in keystore. Default alias defined in jaxr-ebxml.properties is used if this is not specified.
-basedir <basedir>
Base directory in local file system for commands that relate to files in the local file system.
-class <adminShellClass>
Class to use for instance of AdminShell. The default class generated by org.freebxml.omar.client.adminTool.AdminShellFactory is used if omitted.
-command <commands>
Admin tool command sequence to run instead of getting commands from System.in. Separate commands should be separated by a semicolon (;). It is not necessary to include a 'quit' command in <commands>. If you need a ';' that is not a command separator, include it as '\;'. (Note that the shell in which you run the Admin tool may require the '\' in '\;' to be quoted by a second '\'). If any command contains spaces, the entire command sequence must be enclosed in single or double quotes so the sequence is treated as one command-line parameter instead of several. If your shell also interprets ';' as separating shell commands, you will always have to quote sequences of multiple admin shell commands.
-create
If necessary, create the RegistryPackage specified by the -root parameter as well as any parent RegistyPackage objects as needed.
-debug
Output extra information that is useful when debugging.
-keypass <keypass>
Keypass to use when accessing user's certificate in keystore. Default keypass defined in jaxr-ebxml.properties is used if this is not specified.
-locale <locale>
Locale (e.g., "EN" or "FR_ca") to use for selecting the resource bundle to use for error and status messages. The default is determined by the Java VM.
-property <name> <value>
Name and value of an additional property that may be used by a particular implementation of org.freebxml.omar.client.adminTool.AdminShell or by a particular implementation of org.freebxml.omar.client.adminTool.AdminShellFunction. Implementations will ignore any additional properties that they do not support.
-registry <url>
URL of ebXML registry to which to connect. The value of the jaxr-ebxml.soap.url property, if specified in jaxr-ebxml.properties, is used if omitted, otherwise a built-in default is used.
-root <locator>
Locator (e.g., "/registry/userData") of the RegistryPackage to use as the base for those commands that treat the repository as a tree of RegistryPackage objects that each contain other RegistryObject and RegistryPackage objects. The default is the RegistryPackage that is defined for user's data: /registry/userData.
-sqlselect <SQL statement>
Execute <SQL statement> to select registry objects. This should be a complete SQL statement, i.e., it should start with 'select'. The SQL statement does not have to be terminated by a semicolon (;).
-v or -verbose
Specifies verbose output of status messages.

Using the Admin Tool

Exception Reporting

The admin tool tries to save you from having to view long stack traces whenever a command fails.

When a command fails, the admin shell prints the first line of the stack trace and the following:

An error occurred when executing the function.  Use 'show exception' to view messages.

Note that if the classes used by the command are ill-behaved and also write error messages to the screen, you'll see those as well.

If you need more information, you can execute show exception as the next command to see the full stack trace.

Since show exception always shows you the stack trace of the immediately previous command, if you execute a different command before you execute show exception, you'll get the stack trace (or absence of stack trace) from that command.

Identifying Registry Objects

The primary way to identify objects is by name. This extends to identifying RegistryPackage objects by the "path" from the registry root to the RegistryPackage. For example, /registry/userData is the path to the userData RegistryPackage.

Some matches for names support the wildcards '?' for matching a single character and '*' for matching zero or more characters.

Some commands - for example, cd and chown - support identifying objects by their UUID, which must include the leading "urn:uuid"; for example, urn:uuid:2702f889-3ced-4d49-82d1-e4cd846cb9e4.

The chown command also supports using %number to refer to a User object's UUID as listed by a preceding users command.

In some commands, you can enter names containing spaces either by enclosing the whole name in double quotes (") or by preceding each space in the name by a backslash (\).

If you find all this confusing and inconsistent then, firstly, come up with the unified theory for how to refer to objects and, secondly, implement it or lobby to have it implemented.

Effect of Locale

A RegistryObject (or a RegistryPackage) may have multiple names that are each associated with a different locale.

The paths and object names that you specify are evaluated with respect to the current locale only. When you attempt to select by name a registry object that has multiple names, the registry server attempts to match the name that you provide against only one alternative for the registry object's name - the choice whose locale most closely matches the current locale - not against all the multiple names for the registry object.

For example, consider the case when the current RegistryPackage has a member object that has two names, each associated with a different locale: "red" in the en (English) locale and "rouge" in the fr (French) locale. When the current locale is en, the command ls rouge will not display that member object, but when the locale is fr (or one of its variants), the same command will display that member object.

Case Sensitivity

Command names and literal parameters that are recognised by the admin tool shell are not case sensitive. For example, ls, Ls, and LS are equivalent.

Parameters where you provide the value are passed verbatim to the code that uses the parameter.

Commands

The following sections explain the available commands. Each section begins with the command's usage pattern. Within the usage patterns:

  • < and > indicate a parameter that should be replaced by a real value when you run the command
  • ( and ) delimit a choice of parameters (with parameters separated by |) where you must include one of the parameters
  • [ and ] delimit a parameter or choice of parameters that may be omitted
  • + after a parameter indicates that you may repeat the parameter
  • Anything else is literal text that you must include when running the command

The following "datatypes" are used as parameter values:

<string>
A sequence of characters.
<file>
A filename.
<uuid>
A UUID starting with urn:uuid:, for example, urn:uuid:4a6741e7-4be1-4cfb-960a-e5520356c4fd.
<%uuid>
A '% followed by decimal digits, e.g. %1 or %12.
<locator>
The "path" of names of RegistryObject from the "root" of the repository to an object in the repository, with each name preceded by '/'. For example, the locator for the userData RegistryPackage that is a member of the registry RegistryPackage (which is not itself a member of any RegistryPackage) is /registry/userData, and the locator of the folder1 RegistryPackage that is a member of the userData package is /registry/userData/folder1.
<command>
An admin tool command name, for example, echo or chown.
<pattern>
A pattern comprising literal characters and the special characters '*' (representing zero or more characters) and '?' (representing one and only one character).
<property>
Name of a property whose value can be set with the set command or shown with the show command.
<value>
An allowed value for the property being set.
<SQL>
An SQL select statement (without the leading select since that is already present as the name of the command).
<objectType>
Name of an object type, for example, association or user.
<properties>
One or more properties of an object type.

add association

add association -type <type> <sourceUUID> <targetUUID>

Adds an Association object of the specified type, e.g., HasMember, between the source and target objects.

add user

add user [-edit] [-load <file>]
         [(-firstName | -fn) <string>] 
         [(-lastName | -ln) <string>] 
         [(-middleName | -mn) <string>] 
         [-alias <string>] 
         [-keypass <string>] 
         [(-userType | -type) <string>] 
         [(-post1.type | -postalType) <string>] 
         [(-post1.city | -city) <string>] 
         [(-post1.country | -country) <string>] 
         [(-post1.postalcode | -postalcode | -postcode | -zip) <string>] 
         [(-post1.stateOrProvince | -stateOrProvince | -state | -province) <string>] 
         [(-post1.street | -street) <string>] 
         [(-post1.streetNumber | -streetNumber | -number) <string>] 
         [-post2.type <string>] 
         [-post2.city <string>] 
         [-post2.country <string>] 
         [-post2.postalcode <string>] 
         [-post2.stateOrProvince <string>] 
         [-post2.street <string>] 
         [-post2.streetNumber <string>] 
         [-post3.type <string>] 
         [-post3.city <string>] 
         [-post3.country <string>] 
         [-post3.postalcode <string>] 
         [-post3.stateOrProvince <string>] 
         [-post3.street <string>] 
         [-post3.streetNumber <string>] 
         [(-telephone1.type | -phoneType) <string>] 
         [(-telephone1.areaCode | -areaCode) <string>] 
         [(-telephone1.countryCode | -countryCode) <string>] 
         [(-telephone1.extension | -extension) <string>] 
         [(-telephone1.number | -number) <string>] 
         [(-telephone1.URL | -URL) <string>] 
         [-telephone2.type <string>] 
         [-telephone2.areaCode <string>] 
         [-telephone2.countryCode <string>] 
         [-telephone2.extension <string>] 
         [-telephone2.number <string>] 
         [-telephone2.URL <string>] 
         [-telephone3.type <string>] 
         [-telephone3.areaCode <string>] 
         [-telephone3.countryCode <string>] 
         [-telephone3.extension <string>] 
         [-telephone3.number <string>] 
         [-telephone3.URL <string>] 
         [(-email1.type | -emailType) <string>] 
         [(-email1.address | -emailAddress | -email) <string>] 
         [-email2.type <string>] 
         [-email2.address <string>] 
         [-email3.type <string>] 
         [-email3.address <string>]

Adds a User object. The information that you provide is checked for validity using the same criteria as used when adding a new user using the Swing client.

You can specify the information about the user either on the command line itself or by using the -load parameter to specify a Java properties file with the information. The information parameters and the -load parameter are evaluated in the order they appear on the command line; so, for example, you can specify some properties on the command line, load others from a properties file, and then override information in the properties file with later command-line parameters.

You must specify at least one address, telephone number, and email address for the new user, and you can specify up to three of each type. If you need more, then you can add them later using one of the GUI clients.

When you specify a address, telephone number, or email address, you must provide a value for its type, e.g., -emailType work.

You can use shorthand parameters on the command line for some of the common information that is required for every user, but you must use the longer form when providing the information in a properties file. For example, you can specify the user's first email address on the command line using one of -email1.address, -emailAddress, or -email, but when you specify it in a properties file, you must use email1.address=. Since there is only one choice for the user's second email address, you must use -email2.address on the command line and email2.address= in a properties file.

When you use -edit, the admin tool launches an editor so you can edit the new user's information. The tool launches the editor after evaluating the other command-line parameters, so editing starts with the result of evaluating any information specified on the command line or with a -load properties file. The editing program must terminate without error before the command can continue. (At the time of this writing, -edit currently works with emacsclient and /path/to/NetBeans/bin/runide.sh --open (but not very well), has not been shown to work with vi, and has not been tested on Windows.)

The properties files that you load with -load or edit with -edit use the IS0-8859-1 charset, as do all Java properties files. See the documentation for java.util.Properties.load(InputStream) for details on how to represent other characters not in ISO-8859-1 in properties files.

cd

cd <locator> | <uuid>

Change "directory" to the RegistryPackage at the specified path or with the specified UUID.

Changing to a specified UUID is useful when there are multiple RegistryPackage objects with the same path (for the current locale).

chown

chown (<uuid> | <%index>)

Change the ownership of the objects selected with a preceding select command to the user specified by either the UUID or the reference to the user's UUID when listed by a preceding users command.

cp

cp [-owner (<uuid> | <%index>)] [-exclude <pattern>]* <pattern>*

Copy files and folders into the registry as RegistryPackage and ExtrinsicObject objects, respectively.

The "local directory" on the local filesystems from which to copy files and folders defaults to the current directory from which you started the admin tool. You can change the "local directory" at startup using the -localdir parameter, or you can change it after the admin tool has started using the lcd command. You can get the absolute path of the current "local directory" using the show localdir command.

echo

echo <string>

Echoes the string to the output.

help

help [<command>]

Display information about the available commands or a particular command.

help by itself displays the usage information for all commands.

help followed by a command name, e.g., help add, displays information about that command. For commands with subcommands, e.g., add, it displays information about the subcommands.

info

Not implemented.

lcd

lcd [<filename>]

Change the current "local directory" on the local filesystems.

Examples

Change the "local directory" to the /usr/share directory:

lcd /usr/share

Change the "local directory" to your default directory on the local filesystems:

lcd

ls

ls [(<pattern> | <uuid>)+]

List the objects in the current RegistryPackage or, when pattern or uuid is provided, list the objects in the current RegistryPackage whose name (in the current locale) match pattern or uuid.

pwd

pwd

Display the path (or paths) to the current RegistryPackage using the best-matching names for the current locale. Also displays the current locale.

Example

admin> pwd
(en_US) /registry/userData

quit

quit

Exit the admin shell tool.

rm

rm [-d] [-r] (<pattern> | <uuid>)+

Remove the member objects of the current RegistryPackage whose name (in the current locale) match the patterns specified by a pattern or uuid.

When a matching registry object is a member of multiple RegistryPackages, this command just removes the Association between the current RegistryPackage and the object. The object is removed from the registry only when removing the Association leaves it with no other Association with any other registry object.

When a matching member object is itself a RegistryPackage that contains other objects, neither the object nor the Association between the current RegistryPackage and the member RegistryPackage are removed unless either the -r or -d argument is provided.

When the -r argument is provided, the specified RegistryPackage object and all its descendant objects are removed (except when an object has other associations).

When the -d argument is provided, the Association between the current RegistryPackage and the specified RegistryPackage is removed; the RegistryPackage is removed only if its only remaining associations are to its member objects. Member objects of the now-removed RegistryPackage that are not anchored by being the target of other HasMember associations are now accessible as members of the root of the registry.

When both both -d and -r are provided, the -d is applied recursively, so all objects that would be selected by -r (and their associations) are removed whether or not they have other associations.

select

select [<SQL>]

Selects and lists the objects specified by evaluating the entire command as an SQL query. When the command is only select, lists the objects, if any, selected by a preceding select command.

set

set <property> <value>

Sets the value of a property of the admin tool shell.

The properties supported by set are:

set debug (true | on | yes | false | off | no)
Enables or disables output of debugging messages.
set editor <string>
Sets the command to use when the admin tool launches an interactive editor. The default value on Unix and Linux is /bin/vi, and on Windows is notepad.exe.
set verbose (true | on | yes | false | off | no)
Enables or disables output of more verbose messages when executing commands.

show

show [<property>]

Shows the value of a property of the admin tool shell. When no property is specified, shows the value of all properties.

The properties supported by show are:

debug
Whether or not debugging output is enabled.
editor
The command to use when the admin tool launches an interactive editor.
exception
The exception stack trace, if any, from the immediately previously executed command.
locale
The current locale.
verbose
Whether or not verbose output is enabled.

users

users

List the User objects currently in the registry.

The output is in the form index UUID name, for example:

%0:  urn:uuid:2702f889-3ced-4d49-82d1-e4cd846cb9e4  user, test 
%1:  urn:uuid:85428d8e-1bd5-473b-a8c8-b9d595f82728  Stojanovic, Nikola 
%2:  urn:uuid:921284f0-bbed-4a4c-9342-ecaf0625f9d7  Operator, Registry 
%3:  urn:uuid:977d9380-00e2-4ce8-9cdc-d8bf6a4157be  Najmi, Farrukh Salahudin
%4:  urn:uuid:abfa78d5-605e-4dbc-b9ee-a42e99d5f7cf  Guest, Registry

You can use the index, including the %, to refer to a user when running the chown command.