icejar

This is software for extending a Mumble server using ZeroC Ice and Java. For each connection to a Mumble server, a configuration file is provided which defines the details of the connection, the modules to enable, and an optional configuration for each enabled module.

Usage

There are 4 accepted command line arguments.

• -s path/to/server/config/directory (defaults to ./servers)
• -m path/to/module/directory (defaults to ./modules)
• -d path/to/data/directory (defaults to ./data)
• -v enable verbose output

Configuration

Server configuration files use the TOML format. Their file names must end in .toml. Parsing is done with toml4j.

The following keys are used and should be placed in a table called [server]:

• server_id: Attempt to connect to a virtual server with this ID.

  If server_name is defined, the connection will only succeed if the virtual server with the given ID also has a registerName equal to the value of server_name.

  If server_id is undefined, server_name will be used to determine the virtual server to which the connection will be made.

  By default, the Mumble server creates a single virtual server with an ID equal to 1.

• server_name: Attempt to connect to a virtual server with this name. If server_id is defined, the connection will be established according to the description of server_id.

  If server_id and server_name are undefined, the connection to the Mumble server will not connect to a specific virtual server as well.

• ice_args: Arguments with which the Ice Communicator will be initialized. The available arguments are documented by ZeroC. The value should be a list of strings.

• ice_host: The hostname or IP address of the Mumble server. Use "127.0.0.1" for a local Mumble server.

• ice_port: The port on which Ice is listening. Mumble uses port 6502 by default

• ice_secret: Plaintext secret which must match the value configured on the server in order to connect. If the server does not set an Ice secret, ice_secret can be left undefined. See the Mumble wiki for more information.

• callback_host: The hostname or IP address at which Icejar can be reached over TCP. This should only be set if icejar is running on a different computer than the Mumble server.

• callback_port: The port at which Icejar can be reached over TCP. This should only be set if icejar is running on a different computer than the Mumble server.

• default_invocation_timeout: The time in seconds after which an Ice invocation will be cancelled and throw an exception. If left unspecified, the timeout will be set to 5 seconds. See the ZeroC Ice docs for more information.

• enabled_modules: List of module names to enable for this connection. The names should be the file names of modules without their extension, i.e. to enable the module found at ./modules/foo.jar, you would add "foo" to the value of enabled_modules.

• enabled: Control whether or not the config will be used to establish a connection. Set to true or false. Leaving enabled undefined is the same as setting it to true.

Additionally, each enabled module may also be configured. To do so, create a table in the server configuration file with the same name as the module you want to configure. The key-value pairs defined will be passed to the appropriate module whenever a connection is established.

Example configuration:

# Configuration for connection
[server]
server_id = 1

ice_args = []
ice_host = "127.0.0.1"
ice_port = 6502
ice_secret = "secret"

enabled_modules = [ "test_module", "another_module" ]

# Configuration for `test_module`
[test_module]
foo = "bar"
arbitrary_key = "arbitrary_value"

Modules

Modules are JAR files which contain a class implementing the Module interface defined in icejar-module-api/src/main/java/Module.java.

The Module interface defines two methods which can be overridden:

• setup: This method is called whenever a connection is established and must be overridden by sub-classes. This method is called with the configuration for the module, the interface to the Mumble server, the interface to register callbacks and optionally the interface to the virtual server if one was configured. This method may be called multiple times for any given module.

• cleanup: This method is called only once, when a module is unloaded. It does not have to be overridden, but is provided to support modules which require some additional clean-up procedure. Callbacks registered using Ice are cleaned up automatically and do not require an implementation of this method.

• setLogger: This method is only called once, immediately after a module is instantiated and before any calls to setup. It does not have to be overridden. setLogger is called with a single argment: an instance of java.util.logging.Logger Using the Logger is preferable to using print statements because logged messages will automatically be timestamped and display both the module and mumble server connection from which the messages originate.

Implementors of Module must provide a constructor which accepts no arguments, either by keeping the default constructor or explicitly defining its equivalent.

More information is available in the generated documentation for the icejar-module-api and ice-generated sub-projects. You can generate this documentation by running gradle javadoc from the project root.

The generated documentation will be produced at icejar-module-api/build/docs/javadoc/ and ice-generated/build/docs/javadoc/.

Compling Modules

To compile modules, add the JAR file located at icejar-module-api/build/MumbleIceModuleAPI.jar to the class path.