aterm is a Mediaflux terminal client application, distributed in the Java jar package aterm.jar. In addition to the aterm graphical user interface (GUI), aterm.jar provides classes for issuing commands directly to the Mediaflux server from the command line allowing execution of services and transfer of data to/from the Mediaflux server. In this way it can be used for scripting.
You can either call the classes directly or use one of the wrappers available.
See the Software Downloads page. You can also download aterm.jar using the unimelb aterm wrapper script.
Main classes
In aterm.jar file, there are two main classes can be used to communicate with a Mediaflux server:
These are the entry points used by the wrapper scripts, and can also be called directly on the command line.
The configuration file specifies the connection parameters that aterm will use. If you're running aterm.jar directly, a configuration file can be passed to aterm with the -Dmf.cfg=path_to_config_file java argument. The wrapper scripts generally take care of this for you; refer to each script for the method used.
When running aterm directly, the values specified in the configuration file can also be passed as Java command line arguments.
| argument | meaning |
|---|
| -Dmf.host=$MFLUX_HOST | mediaflux server host address |
| -Dmf.port=$MFLUX_PORT | mediaflux server port number |
| -Dmf.transport=$MFLUX_TRANSPORT | mediaflux server transport: http https or tcp/ip |
-Dmf.cfg=$MFLUX_CFG | configuration for mediaflux server details. Either this or combination of mf.host, mf.port and mf.transport must be supplied |
| -Dmf.sid=$MFLUX_SID | mediaflux session id. It is generated by the logon process. then it is used for any subsequent service calls |
-Dmf.result=$MFLUX_OUTPUT | mediaflux service output format. can be: shell or xml |
This is the default entry point (main class) for aterm.jar. Each invocation will create a new user session on the Mediaflux server which is not destroyed when it exits (the session will be eventually disappear after expiry). For this reason it is recommended to use arc.mf.command.Execute or source a TCL script if you are running many commands (e.g. in a loop).
java -cp /path/to/aterm.jar arc.mf.aterm.AppSelector
This is equivalent to:
java -jar /path/to/aterm.jar
To work with the aterm script wrapper in this way you first need to setup a configuration file to tell aterm which server and which Mediaflux account to use.
A shell script based on main class: arc.mf.aterm.AppSelector which makes issuing commands more convenient can be found at Mediaflux installation directory $MFLUX_HOME/bin/unix/aterm and is included here:
#!/bin/sh
#
# Aterm shell commands - enables the aterm command line terminal.
#
# Usage:
#
# ./aterm
# ./aterm <service>
# ./aterm <script>
#
# See if the location of aterm has been set.
if [ -z $MFLUX_ATERM ]
then {
# If not, then assume relative to the location of this shell script
# which is distributed one level below the aterm.jar
MFLUX_ATERM=`dirname "$0"`/../aterm.jar
}
fi
# Have we been supplied with the location of a configuration file
# that specifies the host, etc. If so, use that.
#
# This file has the form:
#
# host=<host>
# port=<port>
# transport=[http|https]
# #
# domain=<domain>
# user=<user>
# password=<password>
# # Authentication can be via a token
# # aterm> secure.identity.token.create :role -type role read-only
# # :token -actor-type "identity" -actor-name "172" "IykJZOEx89kdT331Yq5mgUHrpvF98v6ykNxvZCKpMydWhMLtZSt33ZuoqgANThis-is-A-Fake-Tokenc8F8waEzCyOjhLXw2ADhCCyaa566V249SlWg4pPJcyuHzTv801707"
# #
# token=IykJZOEx89kdT331Yq5mgUHrpvF98v6ykNxvZCKpMydWhMLtZSt33ZuoqgANThis-is-A-Fake-Tokenc8F8waEzCyOjhLXw2ADhCCyaa566V249SlWg4pPJcyuHzTv801707
#
# All are optional - if not specified, then aterm.jar will ask for them.
#
if [ -z $MFLUX_CFG ]
then {
# Execute without configuration. Will be prompted for connection and
# credential details
java -jar $MFLUX_ATERM nogui $*
} else {
# Use the supplied configuration
java -jar -Dmf.cfg=$MFLUX_CFG $MFLUX_ATERM nogui $*
}
fi
java -cp /path/to/aterm.jar arc.mf.aterm.AppSelector nogui server.uuid
java -jar /path/to/aterm.jar nogui server.uuid
java -jar /path/to/aterm.jar nogui asset.create :name test.txt :namespace /test :in file:/tmp/test.txt
arc.mf.command.Execute is is another entry point (main class) in aterm.jar.
java -cp /path/to/aterm.jar arc.mf.command.Execute <mediaflux-command>
This main class can be used to start a system session, and use the session for subsequent service calls.
The script below authenticates with user password, and returns the server uuid. The domain, user and password can be specified in the configuration file or on the command line as in the script below.
#!/bin/bash
MFLUX_SID=`java -cp /path/to/aterm.jar -Dmf.cfg=$MFLUX_CFG arc.mf.command.Execute logon YourDomain YourUsername YourPassword`
MFLUX_UUID=`java -cp /path/to/aterm.jar -Dmf.cfg=$MFLUX_CFG -Dmf.sid=$MFLUX_SID -Dmf.result=shell arc.mf.command.Execute server.uuid`
echo $MFLUX_UUID
java -cp /path/to/aterm.jar -Dmf.cfg=$MFLUX_CFG -Dmf.sid=$MFLUX_SID arc.mf.command.Execute logoff
By passing command line arguments we can log on and store the MFLUX_SID. We pass this to subsequent executions to avoid logging on again for each command that we execute.
MFLUX_SID=`java -cp /path/to/aterm.jar -Dmf.cfg=$MFLUX_CFG -cp $MFLUX_ATERM arc.mf.command.Execute logon $MFLUX_DOMAIN $MFLUX_USER $MFLUX_PASSWORD`
Note that arc.mf.command.Execute cannot pull the token and token.app values from the config file. To authenticate with a token, -token and -app arguments should be used.
MFLUX_SID=`java -cp /path/to/aterm.jar -Dmf.cfg=$MFLUX_CFG -cp $MFLUX_ATERM arc.mf.command.Execute logon -token $MFLUX_TOKEN -app $MFLUX_TOKEN_APP`
A shell script based on main class arc.mf.command.Execute which makes issuing mediaflux commands more convenient can be found at Mediaflux installation directory $MFLUX_HOME/bin/unix/mfcommand and is included here:
#!/bin/sh
# file name mfcommand
# MFLUX_HOME is the location of the mediaflux installation to be
# controlled by this script.
#MFLUX_HOME=/home/mediaflux/mflux
# PATH is the location of the directory containing the Java
# executable. Edit the path to point to the correct Java version.
#PATH=$PATH:/usr/java/j2re1.4.2_01/bin
check_env() {
if [ -z "$MFLUX_ATERM" ]
then {
if [ -z "$MFLUX_HOME" ]
then {
echo "The environment variable MFLUX_HOME has not been defined.";
echo "This environment variable must be set to the root of the Mediaflux";
echo "installation."
exit 1;
}
fi
MFLUX_ATERM=$MFLUX_HOME/bin/aterm.jar
}
fi
# If there is an external configuration, then we'll use that, otherwise ask for the
# host, port etc.
if [ -z "$MFLUX_CFG" ]
then {
if [ -z "$MFLUX_HOST" ]
then {
echo "The environment variable MFLUX_HOST has not been defined.";
echo "This environment variable must be set to the DNS or IP address of"
echo "the server.";
exit 1;
}
fi
if [ -z "$MFLUX_PORT" ]
then {
echo "The environment variable MFLUX_PORT has not been defined.";
echo "This environment variable must be set to the port number used"
echo "for the network connection.";
echo "";
echo "The transport will be assumed as follows:";
echo "";
echo " Port Transport";
echo " ----------------------";
echo " 80 HTTP";
echo " 443 HTTPS";
echo " * TCP/IP";
echo "";
echo "That is, any other port will be assumed to be TCP/IP unless";
echo "the environment variable MFLUX_TRANSPORT is set.";
exit 1;
}
fi
if [ -z "$MFLUX_TRANSPORT" ]
then {
case "$MFLUX_PORT" in
80)
MFLUX_TRANSPORT=HTTP
;;
443)
MFLUX_TRANSPORT=HTTPS
;;
*)
MFLUX_TRANSPORT=TCPIP
;;
esac
}
fi
}
fi
if [ -z "$MFLUX_OUTPUT" ]
then {
MFLUX_OUTPUT=shell
}
fi
case "$MFLUX_OUTPUT" in
xml)
;;
shell)
;;
*)
echo "If provided, the environment variable MFLUX_OUTPUT must be";
echo "set to either 'shell' or 'xml'. Defaults to 'shell'";
exit -1;
;;
esac
}
# We use the hostname to qualify the location of the SID file
# Since a SID is only valid for a given host.
# MFLUX_SID_FILE is a file in which we will store the current
# session id for this user. The session will then be valid for
# any session for that user on this host.
MFLUX_SID_FILE=~/.MFLUX_SID_$MFLUX_HOST
# Function: logon
#
logon() {
check_env;
if test -f "$MFLUX_SID_FILE"
then {
logoff
}
fi
if [ -z $MFLUX_CFG ]
then {
MFLUX_SID=`java -Djava.net.preferIPv4Stack=true -Dmf.host=$MFLUX_HOST -Dmf.port=$MFLUX_PORT -Dmf.transport=$MFLUX_TRANSPORT -cp $MFLUX_ATERM arc.mf.command.Execute logon $1 $2 $3 $4`
} else {
MFLUX_SID=`java -Djava.net.preferIPv4Stack=true -Dmf.cfg=$MFLUX_CFG -cp $MFLUX_ATERM arc.mf.command.Execute logon`
}
fi
RETVAL=$?
case $RETVAL in
0) echo $MFLUX_SID >> "$MFLUX_SID_FILE"
;;
2) echo "Authentication failure"
;;
esac
}
# Function: help
#
# This executes displays command help
#
help() {
check_env;
if test -f "$MFLUX_SID_FILE"
then {
MFLUX_SID=`cat "$MFLUX_SID_FILE"`
if [ -z $MFLUX_CFG ]
then {
java -Djava.net.preferIPv4Stack=true -Dmf.host=$MFLUX_HOST -Dmf.port=$MFLUX_PORT -Dmf.transport=$MFLUX_TRANSPORT -Dmf.sid=$MFLUX_SID -Dmf.result=$MFLUX_OUTPUT -cp $MFLUX_ATERM arc.mf.command.Execute $*
} else {
java -Djava.net.preferIPv4Stack=true -Dmf.cfg=$MFLUX_CFG -Dmf.sid=$MFLUX_SID -Dmf.result=$MFLUX_OUTPUT -cp $MFLUX_ATERM arc.mf.command.Execute $*
}
fi
RETVAL=$?
case $RETVAL in
3) echo "Session has timed out - need to logon again.";
rm -f "$MFLUX_SID_FILE"
;;
esac
} else {
echo "Not logged on"
RETVAL=1
}
fi
}
# Function: execute
#
# This executes an arbitrary command.
#
execute() {
check_env;
#
# Account for secure token being passed through..
#
if [ "$1" == "-token" ]
then {
java -Djava.net.preferIPv4Stack=true -Dmf.host=$MFLUX_HOST -Dmf.port=$MFLUX_PORT -Dmf.transport=$MFLUX_TRANSPORT -Dmf.sid=$MFLUX_SID -Dmf.result=$MFLUX_OUTPUT -cp $MFLUX_ATERM arc.mf.command.Execute $*
RETVAL=$?
case $RETVAL in
3) echo "Session has timed out - need to logon again.";
rm -f "$MFLUX_SID_FILE"
;;
esac
} else {
#
# No token, so expect SID file
#
if test -f "$MFLUX_SID_FILE"
then {
MFLUX_SID=`cat "$MFLUX_SID_FILE"`
if [ -z $MFLUX_CFG ]
then {
java -Djava.net.preferIPv4Stack=true -Dmf.host=$MFLUX_HOST -Dmf.port=$MFLUX_PORT -Dmf.transport=$MFLUX_TRANSPORT -Dmf.sid=$MFLUX_SID -Dmf.result=$MFLUX_OUTPUT -cp $MFLUX_ATERM arc.mf.command.Execute $*
} else {
java -Djava.net.preferIPv4Stack=true -Dmf.cfg=$MFLUX_CFG -Dmf.sid=$MFLUX_SID -Dmf.result=$MFLUX_OUTPUT -cp $MFLUX_ATERM arc.mf.command.Execute $*
}
fi
RETVAL=$?
case $RETVAL in
3) echo "Session has timed out - need to logon again.";
rm -f "$MFLUX_SID_FILE"
;;
esac
} else {
echo "Not logged on"
RETVAL=1
}
fi
}
fi
}
# Function: import
#
# This executes an arbitrary command.
#
import() {
check_env;
if test -f "$MFLUX_SID_FILE"
then {
MFLUX_SID=`cat "$MFLUX_SID_FILE"`
if [ -z $MFLUX_CFG ]
then {
java -Djava.net.preferIPv4Stack=true -Dmf.host=$MFLUX_HOST -Dmf.port=$MFLUX_PORT -Dmf.transport=$MFLUX_TRANSPORT -Dmf.sid=$MFLUX_SID -Dmf.result=$MFLUX_OUTPUT -cp $MFLUX_ATERM arc.mf.command.Execute import $*
} else {
java -Djava.net.preferIPv4Stack=true -Dmf.cfg=$MFLUX_CFG -Dmf.sid=$MFLUX_SID -Dmf.result=$MFLUX_OUTPUT -cp $MFLUX_ATERM arc.mf.command.Execute import $*
}
fi
RETVAL=$?
case $RETVAL in
3) echo "Session has timed out - need to logon again.";
rm -f "$MFLUX_SID_FILE"
;;
esac
} else {
echo "Not logged on"
RETVAL=1
}
fi
}
# Function: logoff
#
logoff() {
check_env;
if test -f "$MFLUX_SID_FILE"
then {
MFLUX_SID=`cat "$MFLUX_SID_FILE"`
# Remove the file now..
rm -f "$MFLUX_SID_FILE"
java -Djava.net.preferIPv4Stack=true -Dmf.host=$MFLUX_HOST -Dmf.port=$MFLUX_PORT -Dmf.transport=$MFLUX_TRANSPORT -Dmf.sid=$MFLUX_SID -cp $MFLUX_ATERM arc.mf.command.Execute logoff
RETVAL=$?
} else {
echo "Not logged on"
RETVAL=1
}
fi
}
# Function: status
#
status() {
if test -f "$MFLUX_SID_FILE"
then {
MFLUX_SID=`cat "$MFLUX_SID_FILE"`
echo "Logged on in session $MFLUX_SID"
} else {
echo "Not logged on"
}
fi
RETVAL=1
}
# Options:
#
case "$1" in
logon)
logon $2 $3 $4 $5
;;
logoff)
logoff
;;
import)
import $2 $3 $4 $5 $6 $7 $8
;;
status)
status
;;
help)
help $*
;;
--help)
echo $"Usage: $0 {logon|logoff|status|help|<mediaflux service>}"
RETVAL=1
;;
*)
execute $*
;;
esac
exit $RETVAL
- Log on
- Execute the mediaflux command server.uuid
- Print the result
- Log off
#!/bin/bash
MFLUX_SID=`java -cp /path/to/aterm.jar -Dmf.cfg=$MFLUX_CFG arc.mf.command.Execute logon YourDomain YourUsername YourPassword`
MFLUX_UUID=`java -cp /path/to/aterm.jar -Dmf.cfg=$MFLUX_CFG -Dmf.sid=$MFLUX_SID -Dmf.result=shell arc.mf.command.Execute server.uuid`
echo $MFLUX_UUID
java -cp /path/to/aterm.jar -Dmf.cfg=$MFLUX_CFG -Dmf.sid=$MFLUX_SID arc.mf.command.Execute logoff
- Log on
- Execute the mediaflux command server.uuid
- Print the result
- Log off
#!/bin/bash
MFLUX_SID=`java -cp /path/to/aterm.jar -Dmf.cfg=$MFLUX_CFG arc.mf.command.Execute logon -token $TOKEN -app $APP`
MFLUX_UUID=`java -cp /path/to/aterm.jar -Dmf.cfg=$MFLUX_CFG -Dmf.sid=$MFLUX_SID -Dmf.result=shell arc.mf.command.Execute server.uuid`
echo $MFLUX_UUID
java -cp /path/to/aterm.jar -Dmf.cfg=$MFLUX_CFG -Dmf.sid=$MFLUX_SID arc.mf.command.Execute logoff