Admin Tool Developer 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

This developer guide covers how to configure and extend the admin tool. For information on how to run the admin tool, see the admin tool user guide.

Additional Command-Line Parameters

The following parameters that are not documented in the admin tool user guide are recognised when starting the admin tool:

[-debug]

Where:

-debug
Enables outputting of additional messages that are helpful when debugging the admin tool.

Classes Implementing the AdminShell Interface

The AdminTool object that you run when you execute the jar file calls an object that implements the AdminShell interface to do the work. You must specify which class to use either as the value of the omar.client.adminTool.AdminShellFactory.adminShellClass property in your jaxr-ebxml.properties file or on the command line using the -class parameter.

There is currently only one class provided for your use: org.freebxml.omar.client.adminTool.SimpleAdminShell.

Implementing a new AdminFunction

The easiest way it to copy and modify one of the existing classes in org.freebxml.omar.client.adminTool.function.

Once you've written the class, add it to the org.freebxml.omar.client.adminTool.AdminShellFunctions properties file.

Built-in Commands

The help and quit commands are built into SimpleAdminShell because they require extra knowledge of the workings of the admin tool.

Implementing the AdminFunction Interface

Exceptions

The methods in AdminFunction throw Exception rather than, say, AdminFunctionException because any exception is caught by the AdminShell implementation and, potentially, shown to the user. If AdminFunction methods caught and rethrew exceptions as AdminFunctionException it would just add unnecessary complexity to the stack trace seen by the user.

Property Files

The admin tool uses multiple property files. At the time of this writing, they are:

org.freebxml.omar.client.adminTool.AddFunctions
Mapping of subcommands of the add command to class names.
org.freebxml.omar.client.adminTool.AdminFunctionResources
Localizable strings used by any admin function.
org.freebxml.omar.client.adminTool.AdminShellFunctions
Mapping of command names to class names; for example:
ls=org.freebxml.omar.client.admin.function.Ls
org.freebxml.omar.client.adminTool.AdminShellResources
Localizable strings used by AdminTool, AdminShellFactory and any AdminShell implementation.
org.freebxml.omar.client.adminTool.InfoFunctions
Unused at present.

Debugging

Batch mode

Use the debug.adminTool target and attach your debugger to the port number stated in the output from the Ant task, typically 1044.

Interactive

You have to specify the additional debugging parameters in the Java command line yourself, e.g:

java -Xdebug -Xrunjdwp:transport=dt_socket,address=<port>,server=y,suspend=y \
-jar build/lib/admin-tool.jar  -alias <alias> -keypass <keypass>

You must attach your debugger to the port number that you specified in the address component of the runjdwp argument.