Research Platform Services Wiki

If you're a researcher, we'll help you do stuff.

User Tools

Site Tools


Sidebar

data_management:mediaflux:aterm:aterm_scripts

This is an old revision of the document!


Scripts based on Mediaflux aterm.jar

1. About aterm.jar

Aterm is a Mediaflux terminal client application. It's in the Java jar package: aterm.jar. In additional to the graphical user interface, the aterm.jar also provides classes to communicate with Mediaflux server: executing services, transferring data to/from the Mediaflux server.

1.1. Get aterm.jar

To get aterm.jar, you can:

1.2. Run Aterm GUI

To start Aterm graphical user interface:

  • make sure Java runtime is installed
  • double click to aterm.jar file to start
  • or execute the command below in terminal window (or Windows Command Prompt):
    • java -jar /path/to/aterm.jar

1.3. Run Aterm CLI

The Aterm also supports command line interface mode.

To start Aterm CLI:

  • Again, make sure Java runtime is installed.
  • java -jar /path/to/aterm.jar nogui

1.4. Main classes

In aterm.jar file, there are to main classes can be used to communicate with Mediaflux server.They are the entry points for wrapper scripts.

1.4.1 arc.mf.aterm.AppSelector

This is the default entry point (main class) for aterm.jar.

To execute it:

  • java -cp /path/to/aterm.jar arc.mf.aterm.AppSelector

It is equivalent to:

  • java -jar /path/to/aterm.jar

1.4.2. arc.mf.command.Execute

This is another entry point (main class) in aterm.jar.

To execute it:

  • java -cp /path/to/aterm.jar arc.mf.command.Execute $*

2. Scripting based on main class: arc.mf.aterm.AppSelector

2.1. Command options

  • -Dmf.cfg=$MFLUX_CFG
    • specifies the location of the configuration file.

2.2. Configuration file

2.2.1. Option 1: authenticate with user credentials

  • host=mediaflux.yourdomain.org
  • port=443
  • transport=https
  • domain=YourDomain
  • user=YourUsername
  • password=YourPassword

Note: domain, user and password are optional, if any of them is not specified, it will prompt to ask for it.

2.2.2. Option 2: authenticate with secure identity token

  • host=mediaflux.yourdomain.org
  • port=443
  • transport=https
  • token=XXX_TOKEN_XXX
  • token.app=APP_NAME

Note: token.app specifies the app name that should be consistent with the app specification for the token.

2.3. Official script

A shell script based on main class: arc.mf.aterm.AppSelector can be found at Mediaflux installation directory: $MFLUX_HOME/bin/unix/aterm

2.4. Examples

  • 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

2.5. Issues

We've found that every call to this main class creates a system session and the session is not destroyed when exits. The session will be eventually disappear after expiry. Therefore, if you are calling this main the class frequently ( for example in a loop ), it will create large number of sessions.

So you are scripting to do complex operations that involve multiple service calls. I suggest you use the other main class: arc.mf.command.Execute or source a TCL script.

3. Scripting based on main class: arc.mf.command.Execute

This main class can be used to start a system session, and use the session for subsequent service calls.

The script authenticates with user password, and returns the server uuid.

#!/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

3.1. Command options

3.1.1. Java Properties

  • -Dmf.host=$MFLUX_HOST
    • mediaflux server host address.
  • -Dmf.port=$MFLUX_PORT
    • mediaflux server port number.
  • -Dmf.transport=$MFLUX_TRANSPORT
    • meidaflux 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 servic calls.
  • -Dmf.result=$MFLUX_OUTPUT
    • mediaflux service output format. can be: shell or xml.

3.1.2. Logon arguments

  • Option 1: Password authentication
    • 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`
  • Option 2: Token authentication
    • 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`

3.2. Configuration file

  • host=mediaflux.yourdomain.org
  • port=443
  • transport=https
  • domain=YourDomain
  • user=YourUsername
  • password=YourPassword

Note: the configuration file supports only user credentials for authentication. Token specified this configuration file will be ignored. To authenticate with token, -token and -app argument should be used.

3.3. Official script

A shell script based on main class: arc.mf.command.Execute can be found at Mediaflux installation directory: $MFLUX_HOME/bin/unix/mfcommand

3.4. Examples

  1. Logon using user password
    #!/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
  2. Logon using token with app restrication
    #!/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
data_management/mediaflux/aterm/aterm_scripts.1574210808.txt.gz · Last modified: 2019/11/20 11:46 by Wilson Liu