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.
You run the admin tool by executing the admin-tool.jar jar file:
java -jar path/to/admin-tool.jar <parameters>
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.
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.
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.
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:
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.
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.
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.
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.
The following sections explain the available commands. Each section begins with the command's usage pattern. Within the usage patterns:
The following "datatypes" are used as parameter values:
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 [-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 <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 (<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 [-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 <string>
Echoes the string to the output.
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.
Not implemented.
lcd [<filename>]
Change the current "local directory" on the local filesystems.
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 [(<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
Display the path (or paths) to the current RegistryPackage using the best-matching names for the current locale. Also displays the current locale.
admin> pwd (en_US) /registry/userData
quit
Exit the admin shell tool.
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 [<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 <property> <value>
Sets the value of a property of the admin tool shell.
The properties supported by set are:
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:
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.