JBoss.orgCommunity Documentation
The AdminShell tooling provides scripting based programming environments that enable user to access, monitor and control a Teiid Server. Both the command line and graphical console tools are built on functionality provide by the Groovy ( http://groovy.codehaus.org/ ) project. The AdminShell tools can be used in ad-hoc scripting mode or to run pre-defined scripts.
AdminShell features:
fully functional programming environment with resource flow control and exception management. See Groovy docs for the full power of the language.
quick administrative tool. The user can connect to a running Teiid Server and invoke any of the AdminAPI methods, such as "deployVDB" or "stopConnectionFactory", to control the Teiid System. Since this can be script driven, these tasks can be automated and re-run at a later time.
simplified data access tool. The user can connect to a VDB, issue any SQL commands, and view the results of the query via Groovy Sql extensions.
migration tool. This can be used to develop scripts like moving the Virtual Databases (VDB), Connection Factories, and Configuration from one development environment to another. This will enable users to test and automate their migration scripts before production deployments.
testing tool. The JUnit ( http://junit.org ) test framework is built in, see Groovy Unit Tests. User can write regression tests for checking system health, or data integrity that can be used to validate a system functionality automatically instead of manual verification by QA personnel.
AdminShell is distributed along with other Teiid downloads under "teiid-7.2-adminshell-dist.zip" name. Download and unzip this file to any directory. Once you have unzipped the file, in root directory you will find "adminshell" and "adminshell-console" executable scripts to launch the command line and graphical tools respectively.
Windows: Double click or execute "adminshell.cmd"
*nix: Execute the "adminshell.sh" script
To learn the basics of Groovy take a look at their documents and tutorials on their website.
Basic knowledge of the Java programming language and types is required in order to effectively design and develop scripts using the AdminShell. To learn Java language find learning resources at http://java.sun.com.
You can learn about the Teiid AdminAPI either using “adminHelp()” function or by using the JavaDocs.
AdminShell is a specialized version of Groovy which works in several different modes: interactive shell, graphical console, or script run mode. In interactive shell mode (launched via adminshell), the user can invoke connect to a live Teiid system and issue any ad-hoc commands to control the system. The interactive buffer can be used to develop a script and the interactive session input and output can be captured into a log file, more on this later in the document.
In graphical mode (lanched via adminshell-console), the user can develop and run scripts using a text editor that supports syntax highlighting.
In the script run mode, the user can execute/play back previously developed scripts. This mode especially useful to automate any testing or to perform any repeated configurations/migrations changes to a Teiid system.
To use AdminShell successfully, there are some basic syntactical rules to keep in mind.
In interactive shell mode, most commands (as seen by the help command) are used to control shell behavior and are not general Groovy scripting constructs. Admin methods will typically be called using functional notation:
connectAsAdmin()
All commands and functions are case sensitive.
An ending semicolon is optional for Groovy statements.
If a function requires input parameter(s), they should be declared inside "(" and ")". A function may have more than one parameter. String parameters can be wrapped in double or single quotes. Example:
connectAsAdmin("mm://localhost:34413", "user", "password")
Other Java methods and classes can be used from your scripts, if the required Java class libraries are already in class path. You may place additional jars in the lib directory to have be automatically part of the class path. An example showing an import:
import my.package.*; myObject = new MyClass(); myObject.doSomething();
To execute the commands and arbitrary script in interactive mode you enter them first and press enter to execute, then enter the next line, so on.
To exit the tool in the interactive mode, first disconnect if you are connected to the Teiid system by executing “disconnect();” then type "exit". In the script mode, when execution of the script finishes the tool will exit automatically, however you still have to disconnect from Teiid system in the script.
Note: If SSL is turned on the Teiid server, you would need to adjust the connection URL and the client SSL settings as necessary (typically this will only be needed for 2-way SSL).
The adminHelp() methods lists all the available administrative API methods in the AdminShell. Please note that none of the Groovy Shell commands or other available function calls will be shown in this list
adminHelp();
To get a specific definition about a method and it's required input parameters, use adminHelp("method")
adminHelp("deployVDB");
/*
*Deploy a VDB from file
*/
void deployVDB(
String /* file name */)
throws AdminException
throws FileNotFoundExceptionThe sqlHelp() methods lists all Sql extension methods.
sqlHelp();
To get a specific definition about a method and it's required input parameters, use sqlHelp("method")
The list below contains some common commands used in AdminShell.
println "xxx"; // print something to console
adminHelp(); // shows all the available admin commands;
sql = connect(); // get an extended Groovy Sql connection using connection.properties file
sql.execute(<SQL>); // run any SQL command.
connectAsAdmin(); // connect as admin; no need have the vdb name. SQL commands will not work under this connection
println getConnectionName(); // returns the current connection name
useConnection(<connection name>); // switches to using the given connection settings
disconnect(); // disconnects the current connection in the context
To execute a script file "foo.groovy" in a directory "some/directory" in the interactive comamnd line tool, execute as following
. some/directory/foo.groovy
"foo.groovy" is read into current context of the shell as if you typed in the whole document. If your script only contained method calls, you can explicitly invoke the call to execute.
Full execute syntax may also be used, and is required outside of the interactive command line tool:
evaluate("some/directory/foo.groovy" as File) To execute the same file without entering interactive mode, run
./adminshell.sh . some/directory/foo.groovy
Parameters can be passed in as Java System properties. For example
./adminshell.sh -Dparam=value . some/directory/foo.groovy
Inside the script file, you can access these properties using System.getProperty
value = System.getProperty(“param”); // will return "value"
During the interactive mode, input is recorded in a history file. This file can be accessed via the up arrow in the interactive shell.
User can also capture the commands entered during a interactive session to their own script file by using “startRecording” and “stopRecording” commands. For example,
record start directory/filename.txt <commands and script ..> record stop
All input and output between the start and stop are captured in the “directory/filename.txt” file. This gives the user an option to capture only certain portions of the interactive session and to later refine a script out of recorded file.
The file "connection.properties" in the installation directory of the AdminShell defines the default connection properties with which user can connect to Teiid system. The following properties can be defined using this file
admin.url = <server host name or ip address>
admin.name = <user name>
admin.password = <password>
jdbc.url = <server host name or ip address>
jdbc.user = <user name>
jdbc.password = <password>
A call to "connect()" or "connectionAsAdmin()" without any input parameters, will connect to the Teiid system using the properties defined in properties file. However, a user can always pass in parameters in the connect method to connect to a same or different server than one mentioned in the “connection.properties”. Look all the all the different connect methods using the “adminHelp()” method.
Note that it is not secure to leave the passwords in clear text, as defined above. Please take necessary measures to secure the properties file, or do not use this feature and always pass in password interactively or some other secure way.
Note: At any given time user can be actively connected to more than one system or have more than one connection to same system. To manage the connections correctly each connection is created given a unique connection name. To learn more about this look at Handling Multiple Connections.
Using AdminShell, a user can actively manage more than one connection to a single or multiple Teiid systems. For example, two separate connections can be maintained, one to the development server and one to the integration server at the same time. This is possible because AdminShell supports a feature called named connections.
Every time a connection is made, the connection has an explicit or an implicitly assigned name. If another connect command is executed then a new connection is made with a unique name and execution will be switched to use the new connection. The previous connection will be held as it is in its current state, and will not be closed.
You can use the following command to find out the current connection's name
name = getConnectionName();
Knowing the names of the connection that user is working with is important to switch the active connection to a previous connection. To switch the active connection, use the following command and supply the name of the connection to be used
useConnection("name");
If user supplies the same name as the active connection as they are currently participating in, then this operation will simply return with out any modifications. There is no limitation the number of simultaneous connections.
The following shows an example of using and switching between two connections.
// creates a connection
connectAsAdmin();
//capture the connection name
conn1 = getConnectionName();
deployVDB("file.vdb")
// creates a second connection
connectAsAdmin();
conn2 = getConnectionName();
deployVDB("file.vdb")
// switch the connection to "conn1"
useConnection(conn1);
// close the connection in the "conn1"
disconnectAll();The interactive shell uses a special shell interpretter and therefore has different behavior than just writting a script in Groovy. See the Groovy Shell Documentation for more on its usage. Notable differences:
Def statements do not define a variable in the context of the Shell, e.g. do not use def x = 1, use x = 1
Shell commands (as seen through help) using the non-functional shell syntax are only available in the shell.
Groovy classes using annotations cannot be parsed in the Shell.