[teiid-commits] teiid SVN: r2247 - in trunk: documentation/admin-guide/src/main/docbook/en-US and 2 other directories.

Author: shawkins Date: 2010-06-18 11:46:33 -0400 (Fri, 18 Jun 2010) New Revision: 2247 Added: trunk/build/kits/adminshell/adminshell-console.bat trunk/build/kits/adminshell/adminshell-console.sh trunk/documentation/admin-guide/src/main/docbook/en-US/content/adminshell.xml Removed: trunk/build/kits/adminshell/adminconsole.bat trunk/build/kits/adminshell/adminconsole.sh trunk/documentation/admin-guide/src/main/docbook/en-US/content/adminshell-introduction.xml trunk/documentation/admin-guide/src/main/docbook/en-US/content/connection-management.xml trunk/documentation/admin-guide/src/main/docbook/en-US/content/getting-started.xml trunk/documentation/admin-guide/src/main/docbook/en-US/content/working-with-scripts.xml Modified: trunk/documentation/admin-guide/src/main/docbook/en-US/admin_guide.xml trunk/documentation/admin-guide/src/main/docbook/en-US/content/admin-console.xml trunk/documentation/admin-guide/src/main/docbook/en-US/content/appendix-a.xml trunk/documentation/admin-guide/src/main/docbook/en-US/content/appendix-b.xml trunk/documentation/admin-guide/src/main/docbook/en-US/content/installation.xml trunk/documentation/admin-guide/src/main/docbook/en-US/content/logging.xml trunk/documentation/admin-guide/src/main/docbook/en-US/content/vdb-deployment.xml trunk/documentation/quick-start-example/src/main/docbook/en-US/content/connect-vdb.xml trunk/documentation/quick-start-example/src/main/docbook/en-US/content/download.xml Log: TEIID-315 editing the admin guide and clarifying the name of the adminshell console tool to not conflict with the admin-console web application. Deleted: trunk/build/kits/adminshell/adminconsole.bat =================================================================== --- trunk/build/kits/adminshell/adminconsole.bat 2010-06-18 15:44:49 UTC (rev 2246) +++ trunk/build/kits/adminshell/adminconsole.bat 2010-06-18 15:46:33 UTC (rev 2247) @@ -1,79 +0,0 @@ -@ECHO OFF -@setlocal - -@REM JBoss, Home of Professional Open Source. -@REM Copyright (C) 2008 Red Hat, Inc. -@REM Licensed to Red Hat, Inc. under one or more contributor -@REM license agreements. See the copyright.txt file in the -@REM distribution for a full listing of individual contributors. -@REM -@REM This library is free software; you can redistribute it and/or -@REM modify it under the terms of the GNU Lesser General Public -@REM License as published by the Free Software Foundation; either -@REM version 2.1 of the License, or (at your option) any later version. -@REM -@REM This library is distributed in the hope that it will be useful, -@REM but WITHOUT ANY WARRANTY; without even the implied warranty of -@REM MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU -@REM Lesser General Public License for more details. -@REM -@REM You should have received a copy of the GNU Lesser General Public -@REM License along with this library; if not, write to the Free Software -@REM Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA -@REM 02110-1301 USA. - -@REM This assumes it's run from its installation directory. It is also assumed there is a java -@REM executable defined along the PATH - -@if not "%ECHO%" == "" echo %ECHO% -@if "%OS%" == "Windows_NT" setlocal - -if "%OS%" == "Windows_NT" ( - set "DIRNAME=%~dp0%" -) else ( - set DIRNAME=.\ -) - -pushd %DIRNAME% -if "x%TEIID_HOME%" == "x" ( - set "TEIID_HOME=%CD%" -) -popd - -set DIRNAME= - -if "x%JAVA_HOME%" == "x" ( - set JAVA=java - echo JAVA_HOME is not set. Unexpected results may occur. - echo Set JAVA_HOME to the directory of your local JDK to avoid this message. -) else ( - set "JAVA=%JAVA_HOME%\bin\java" - if exist "%JAVA_HOME%\lib\tools.jar" ( - set "JAVAC_JAR=%JAVA_HOME%\lib\tools.jar" - ) -) - -set TEIID_CLASSPATH=%TEIID_HOME%\lib\patches\*;%TEIID_HOME%\lib\teiid-adminshell-${pom.version}.jar;%TEIID_HOME%\lib\*; - -rem JVM memory allocation pool parameters. Modify as appropriate. -set JAVA_OPTS=%JAVA_OPTS% -Xms128m -Xmx256m -XX:MaxPermSize=256m -set JAVA_OPTS=%JAVA_OPTS% -Djava.util.logging.config.file=log.properties - -echo =============================================================================== -echo. -echo Teiid AdminShell Bootstrap Environment -echo. -echo TEIID_HOME: %TEIID_HOME% -echo. -echo JAVA: %JAVA% -echo. -echo JAVA_OPTS: %JAVA_OPTS% -echo. -echo CLASSPATH: %TEIID_CLASSPATH% -echo. -echo =============================================================================== -echo. - -"%JAVA%" %JAVA_OPTS% ^ - -classpath "%TEIID_CLASSPATH%" ^ - org.teiid.adminshell.GroovyAdminConsole %* Deleted: trunk/build/kits/adminshell/adminconsole.sh =================================================================== --- trunk/build/kits/adminshell/adminconsole.sh 2010-06-18 15:44:49 UTC (rev 2246) +++ trunk/build/kits/adminshell/adminconsole.sh 2010-06-18 15:46:33 UTC (rev 2247) @@ -1,82 +0,0 @@ -#!/bin/sh -# -# JBoss, Home of Professional Open Source. -# Copyright (C) 2008 Red Hat, Inc. -# Licensed to Red Hat, Inc. under one or more contributor -# license agreements. See the copyright.txt file in the -# distribution for a full listing of individual contributors. -# -# This library is free software; you can redistribute it and/or -# modify it under the terms of the GNU Lesser General Public -# License as published by the Free Software Foundation; either -# version 2.1 of the License, or (at your option) any later version. -# -# This library is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU -# Lesser General Public License for more details. -# -# You should have received a copy of the GNU Lesser General Public -# License along with this library; if not, write to the Free Software -# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA -# 02110-1301 USA. - -DIRNAME=`dirname $0` - -# OS specific support (must be 'true' or 'false'). -cygwin=false; -linux=false; -case "`uname`" in - CYGWIN*) - cygwin=true - ;; - - Linux) - linux=true - ;; -esac - -# For Cygwin, ensure paths are in UNIX format before anything is touched -if $cygwin ; then - [ -n "$TEIID_HOME" ] && - TEIID_HOME=`cygpath --unix "$TEIID_HOME"` - [ -n "$JAVA_HOME" ] && - JAVA_HOME=`cygpath --unix "$JAVA_HOME"` -fi - -# Setup TEIID_HOME -if [ "x$TEIID_HOME" = "x" ]; then - # get the full path (without any relative bits) - TEIID_HOME=`cd $DIRNAME; pwd` -fi -export TEIID_HOME - -# Setup the JVM -if [ "x$JAVA" = "x" ]; then - if [ "x$JAVA_HOME" != "x" ]; then - JAVA="$JAVA_HOME/bin/java" - else - JAVA="java" - fi -fi - -# JPDA options. Uncomment and modify as appropriate to enable remote debugging. -# JAVA_OPTS="$JAVA_OPTS -Xdebug -Xrunjdwp:transport=dt_socket,address=8787,server=y,suspend=n" - -TEIID_CLASSPATH="$TEIID_HOME/lib/patches/*:$TEIID_HOME/lib/teiid-adminshell-${pom.version}.jar:$TEIID_HOME/lib/*" -JAVA_OPTS="$JAVA_OPTS -Xms128m -Xmx256m -XX:MaxPermSize=256m" -JAVA_OPTS="$JAVA_OPTS -Djava.util.logging.config.file=log.properties" - -# Print the env settings -echo "======================================================================" -echo "" -echo " Teiid AdminShell Bootstrap Environment" -echo "" -echo " TEIID_HOME = $TEIID_HOME" -echo " CLASSPATH = $TEIID_CLASSPATH" -echo " JAVA = $JAVA" -echo "" -echo "======================================================================" -echo "" - -$JAVA $JAVA_OPTS -cp $TEIID_CLASSPATH -Xmx256m org.teiid.adminshell.GroovyAdminConsole $* \ No newline at end of file Copied: trunk/build/kits/adminshell/adminshell-console.bat (from rev 2242, trunk/build/kits/adminshell/adminconsole.bat) =================================================================== --- trunk/build/kits/adminshell/adminshell-console.bat (rev 0) +++ trunk/build/kits/adminshell/adminshell-console.bat 2010-06-18 15:46:33 UTC (rev 2247) @@ -0,0 +1,79 @@ +@ECHO OFF +@setlocal + +@REM JBoss, Home of Professional Open Source. +@REM Copyright (C) 2008 Red Hat, Inc. +@REM Licensed to Red Hat, Inc. under one or more contributor +@REM license agreements. See the copyright.txt file in the +@REM distribution for a full listing of individual contributors. +@REM +@REM This library is free software; you can redistribute it and/or +@REM modify it under the terms of the GNU Lesser General Public +@REM License as published by the Free Software Foundation; either +@REM version 2.1 of the License, or (at your option) any later version. +@REM +@REM This library is distributed in the hope that it will be useful, +@REM but WITHOUT ANY WARRANTY; without even the implied warranty of +@REM MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +@REM Lesser General Public License for more details. +@REM +@REM You should have received a copy of the GNU Lesser General Public +@REM License along with this library; if not, write to the Free Software +@REM Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA +@REM 02110-1301 USA. + +@REM This assumes it's run from its installation directory. It is also assumed there is a java +@REM executable defined along the PATH + +@if not "%ECHO%" == "" echo %ECHO% +@if "%OS%" == "Windows_NT" setlocal + +if "%OS%" == "Windows_NT" ( + set "DIRNAME=%~dp0%" +) else ( + set DIRNAME=.\ +) + +pushd %DIRNAME% +if "x%TEIID_HOME%" == "x" ( + set "TEIID_HOME=%CD%" +) +popd + +set DIRNAME= + +if "x%JAVA_HOME%" == "x" ( + set JAVA=java + echo JAVA_HOME is not set. Unexpected results may occur. + echo Set JAVA_HOME to the directory of your local JDK to avoid this message. +) else ( + set "JAVA=%JAVA_HOME%\bin\java" + if exist "%JAVA_HOME%\lib\tools.jar" ( + set "JAVAC_JAR=%JAVA_HOME%\lib\tools.jar" + ) +) + +set TEIID_CLASSPATH=%TEIID_HOME%\lib\patches\*;%TEIID_HOME%\lib\teiid-adminshell-${pom.version}.jar;%TEIID_HOME%\lib\*; + +rem JVM memory allocation pool parameters. Modify as appropriate. +set JAVA_OPTS=%JAVA_OPTS% -Xms128m -Xmx256m -XX:MaxPermSize=256m +set JAVA_OPTS=%JAVA_OPTS% -Djava.util.logging.config.file=log.properties + +echo =============================================================================== +echo. +echo Teiid AdminShell Bootstrap Environment +echo. +echo TEIID_HOME: %TEIID_HOME% +echo. +echo JAVA: %JAVA% +echo. +echo JAVA_OPTS: %JAVA_OPTS% +echo. +echo CLASSPATH: %TEIID_CLASSPATH% +echo. +echo =============================================================================== +echo. + +"%JAVA%" %JAVA_OPTS% ^ + -classpath "%TEIID_CLASSPATH%" ^ + org.teiid.adminshell.GroovyAdminConsole %* Property changes on: trunk/build/kits/adminshell/adminshell-console.bat ___________________________________________________________________ Name: svn:executable + * Copied: trunk/build/kits/adminshell/adminshell-console.sh (from rev 2242, trunk/build/kits/adminshell/adminconsole.sh) =================================================================== --- trunk/build/kits/adminshell/adminshell-console.sh (rev 0) +++ trunk/build/kits/adminshell/adminshell-console.sh 2010-06-18 15:46:33 UTC (rev 2247) @@ -0,0 +1,82 @@ +#!/bin/sh +# +# JBoss, Home of Professional Open Source. +# Copyright (C) 2008 Red Hat, Inc. +# Licensed to Red Hat, Inc. under one or more contributor +# license agreements. See the copyright.txt file in the +# distribution for a full listing of individual contributors. +# +# This library is free software; you can redistribute it and/or +# modify it under the terms of the GNU Lesser General Public +# License as published by the Free Software Foundation; either +# version 2.1 of the License, or (at your option) any later version. +# +# This library is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +# Lesser General Public License for more details. +# +# You should have received a copy of the GNU Lesser General Public +# License along with this library; if not, write to the Free Software +# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA +# 02110-1301 USA. + +DIRNAME=`dirname $0` + +# OS specific support (must be 'true' or 'false'). +cygwin=false; +linux=false; +case "`uname`" in + CYGWIN*) + cygwin=true + ;; + + Linux) + linux=true + ;; +esac + +# For Cygwin, ensure paths are in UNIX format before anything is touched +if $cygwin ; then + [ -n "$TEIID_HOME" ] && + TEIID_HOME=`cygpath --unix "$TEIID_HOME"` + [ -n "$JAVA_HOME" ] && + JAVA_HOME=`cygpath --unix "$JAVA_HOME"` +fi + +# Setup TEIID_HOME +if [ "x$TEIID_HOME" = "x" ]; then + # get the full path (without any relative bits) + TEIID_HOME=`cd $DIRNAME; pwd` +fi +export TEIID_HOME + +# Setup the JVM +if [ "x$JAVA" = "x" ]; then + if [ "x$JAVA_HOME" != "x" ]; then + JAVA="$JAVA_HOME/bin/java" + else + JAVA="java" + fi +fi + +# JPDA options. Uncomment and modify as appropriate to enable remote debugging. +# JAVA_OPTS="$JAVA_OPTS -Xdebug -Xrunjdwp:transport=dt_socket,address=8787,server=y,suspend=n" + +TEIID_CLASSPATH="$TEIID_HOME/lib/patches/*:$TEIID_HOME/lib/teiid-adminshell-${pom.version}.jar:$TEIID_HOME/lib/*" +JAVA_OPTS="$JAVA_OPTS -Xms128m -Xmx256m -XX:MaxPermSize=256m" +JAVA_OPTS="$JAVA_OPTS -Djava.util.logging.config.file=log.properties" + +# Print the env settings +echo "======================================================================" +echo "" +echo " Teiid AdminShell Bootstrap Environment" +echo "" +echo " TEIID_HOME = $TEIID_HOME" +echo " CLASSPATH = $TEIID_CLASSPATH" +echo " JAVA = $JAVA" +echo "" +echo "======================================================================" +echo "" + +$JAVA $JAVA_OPTS -cp $TEIID_CLASSPATH -Xmx256m org.teiid.adminshell.GroovyAdminConsole $* \ No newline at end of file Property changes on: trunk/build/kits/adminshell/adminshell-console.sh ___________________________________________________________________ Name: svn:executable + * Modified: trunk/documentation/admin-guide/src/main/docbook/en-US/admin_guide.xml =================================================================== --- trunk/documentation/admin-guide/src/main/docbook/en-US/admin_guide.xml 2010-06-18 15:44:49 UTC (rev 2246) +++ trunk/documentation/admin-guide/src/main/docbook/en-US/admin_guide.xml 2010-06-18 15:46:33 UTC (rev 2247) @@ -50,10 +50,7 @@ <xi:include href="content/security.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> <xi:include href="content/logging.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> <xi:include href="content/admin-console.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="content/adminshell-introduction.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="content/getting-started.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="content/working-with-scripts.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="content/connection-management.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="content/adminshell.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> <xi:include href="content/appendix-a.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> <xi:include href="content/appendix-b.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> Modified: trunk/documentation/admin-guide/src/main/docbook/en-US/content/admin-console.xml =================================================================== --- trunk/documentation/admin-guide/src/main/docbook/en-US/content/admin-console.xml 2010-06-18 15:44:49 UTC (rev 2246) +++ trunk/documentation/admin-guide/src/main/docbook/en-US/content/admin-console.xml 2010-06-18 15:46:33 UTC (rev 2247) @@ -2,10 +2,9 @@ <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> <chapter id="admin-console"> <title>Teiid Admin Console</title> - <para>Teiid admin console is a web based administrative and monitoring tool for Teiid. - This is built using the <ulink url="http://www.jboss.org/embjopr">Embedded JOPR</ulink> library that is built to manage the - JBoss AS instances. Teiid adds a additional plugin into the Embeeded JOPR program already available in the - <ulink url="http://www.jboss.org/jbossas">JBoss AS</ulink>, to provide the Teiid specific functionality.</para> + <para>The Teiid Admin Console is a web based administrative and monitoring tool for Teiid. + Teiid's Admin Console is built using the <ulink url="http://www.jboss.org/embjopr">Embedded JOPR</ulink> library and adds a additional plugin into the Embeeded JOPR program already available in the + <ulink url="http://www.jboss.org/jbossas">JBoss AS</ulink>.</para> <sect1> <title>What can be monitored and/or configured?</title> @@ -73,7 +72,7 @@ <sect2 id="vdb_deploy"> <title>Deploying the VDB</title> <para>VDB archive files created it the Designer Tool or Dynamic VDBs can be deployed into Teiid server using - this "admin-console" tool.</para> + the Admin Console.</para> <orderedlist> <listitem> <para>Select the Virtual Database node in the Admin Console tree and click the Add New Resource button.</para> </listitem> Deleted: trunk/documentation/admin-guide/src/main/docbook/en-US/content/adminshell-introduction.xml =================================================================== --- trunk/documentation/admin-guide/src/main/docbook/en-US/content/adminshell-introduction.xml 2010-06-18 15:44:49 UTC (rev 2246) +++ trunk/documentation/admin-guide/src/main/docbook/en-US/content/adminshell-introduction.xml 2010-06-18 15:46:33 UTC (rev 2247) @@ -1,48 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> -<chapter id="adminshell_introduction"> - <title>Introduction to Admin Tools</title> - <para> - AdminShell provides scripting based programming environments that enable user to access, monitor and control a Teiid - Server. The Shell and Console tools are built on ones provide by the Groovy ( - <ulink url="http://groovy.codehaus.org/">http://groovy.codehaus.org... - ) project. The AdminShell tools be used in ad-hoc scripting or to run pre-defined scripts. - </para> - <orderedlist> - <title>AdminShell features:</title> - <listitem> - <para>fully functional programming environment with resource flow control and exception - management. See <ulink url="http://groovy.codehaus.org/">Groovy</ulink> docs for the full power of the language.</para> - </listitem> - <listitem> - <para>quick administrative tool. The user can connect to a running Teiid Server and invoke any of - the Admin API methods, such as "deployVDB" or "stopConnectionFactory", to control Teiid System. - Since this can be script driven, these tasks can be automated and re-run at a later time.</para> - </listitem> - <listitem> - <para>simplified data access tool. The user can connect to a VDB, issue any SQL commands, and view the - results of the query via <ulink url="http://groovy.codehaus.org/Database+features">Groovy Sql</ulink> extensions.</para> - </listitem> - <listitem> - <para>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.</para> - </listitem> - <listitem> - <para>testing tool. The JUnit ( - <ulink url="http://junit.org/">http://junit.org</ulink> - ) test framework is built in, see <ulink url="http://groovy.codehaus.org/Unit+Testing">Groovy Unit Tests</ulink>. 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. - </para> - </listitem> - </orderedlist> - <sect1> - <title>Where can you find AdminShell?</title> - <para>AdminShell is distributed along with other Teiid downloads under "teiid-{version}-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 "adminconsole" executable scripts.</para> - <para>Windows: Double click or execute "adminshell.cmd"</para> - <para>*nix: Execute the "adminshell.sh" script</para> - </sect1> -</chapter> \ No newline at end of file Copied: trunk/documentation/admin-guide/src/main/docbook/en-US/content/adminshell.xml (from rev 2242, trunk/documentation/admin-guide/src/main/docbook/en-US/content/adminshell-introduction.xml) =================================================================== --- trunk/documentation/admin-guide/src/main/docbook/en-US/content/adminshell.xml (rev 0) +++ trunk/documentation/admin-guide/src/main/docbook/en-US/content/adminshell.xml 2010-06-18 15:46:33 UTC (rev 2247) @@ -0,0 +1,278 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +<!ENTITY % CustomDTD SYSTEM "../../../../../../docbook/custom.dtd"> +%CustomDTD; +]> +<chapter> + <title>AdminShell</title> +<sect1 id="adminshell_introduction"> + <title>Introduction</title> + <para> + 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 ( + <ulink url="http://groovy.codehaus.org/">http://groovy.codehaus.org... + ) project. The AdminShell tools can be used in ad-hoc scripting mode or to run pre-defined scripts. + </para> + <orderedlist> + <title>AdminShell features:</title> + <listitem> + <para>fully functional programming environment with resource flow control and exception + management. See <ulink url="http://groovy.codehaus.org/">Groovy</ulink> docs for the full power of the language.</para> + </listitem> + <listitem> + <para>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.</para> + </listitem> + <listitem> + <para>simplified data access tool. The user can connect to a VDB, issue any SQL commands, and view the + results of the query via <ulink url="http://groovy.codehaus.org/Database+features">Groovy Sql</ulink> extensions.</para> + </listitem> + <listitem> + <para>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.</para> + </listitem> + <listitem> + <para>testing tool. The JUnit ( + <ulink url="http://junit.org/">http://junit.org</ulink> + ) test framework is built in, see <ulink url="http://groovy.codehaus.org/Unit+Testing">Groovy Unit Tests</ulink>. 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. + </para> + </listitem> + </orderedlist> + <sect2> + <title>Download</title> + <para>AdminShell is distributed along with other Teiid downloads under "teiid-&versionNumber;-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.</para> + <para>Windows: Double click or execute "adminshell.cmd"</para> + <para>*nix: Execute the "adminshell.sh" script</para> + </sect2> +</sect1> + +<sect1 id="getting_started"> + <title>Getting Started</title> + <para> + To learn the basics of + <ulink url="http://groovy.codehaus.org/">Groovy</ulink> + take a look at their documents and tutorials on their website. + </para> + <para> + 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 <ulink url="http://java.sun.com/">http://java.sun.com</ulink>;. + </para> + <para>You can learn about the Teiid AdminAPI either using + “adminHelp()” function or by using the JavaDocs.</para> + <para>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.</para> + <para>In graphical mode (lanched via adminshell-console), the user can develop and run scripts using a text editor that supports syntax highlighting.</para> + <para>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.</para> + <sect2> + <title>Essential Rules</title> + <para>To use AdminShell successfully, there are some basic syntactical rules to keep in mind.</para> + <orderedlist> + <listitem> + <para>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:</para> + <programlisting><![CDATA[connectAsAdmin()]]></programlisting> + </listitem> + <listitem> + <para>All commands and functions are case sensitive.</para> + </listitem> + <listitem> + <para>An ending semicolon is optional for Groovy statements.</para> + </listitem> + <listitem> + <para>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:</para> + <programlisting><![CDATA[ + connectAsAdmin("mm://localhost:34413", "user", "password") + ]]></programlisting> + </listitem> + <listitem> + <para>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: + </para> + <programlisting><![CDATA[import my.package.*; +myObject = new MyClass(); +myObject.doSomething();]]></programlisting> + </listitem> + </orderedlist> + <para>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.</para> + <para>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.</para> + <para>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). + </para> + </sect2> + <sect2> + <title>Help</title> + <para>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</para> + <programlisting><![CDATA[adminHelp();]]></programlisting> + <para>To get a specific definition about a method and it's required + input parameters, use adminHelp("method")</para> + <programlisting><![CDATA[adminHelp("deployVDB"); + +/* + *Deploy a VDB from file + */ +void deployVDB( + String /* file name */) + throws AdminException + throws FileNotFoundException]]></programlisting> + <para /> + <para>The sqlHelp() methods lists all Sql extension + methods.</para> + <programlisting><![CDATA[sqlHelp();]]></programlisting> + <para>To get a specific definition about a method and it's required + input parameters, use sqlHelp("method")</para> + <para /> + </sect2> + <sect2> + <title>Basic Commands</title> + <para>The list below contains some common commands used in AdminShell.</para> + <programlisting><![CDATA[ +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 + ]]></programlisting> + </sect2> +</sect1> + <sect1> + <title>Executing a script file</title> + <para>To execute a script file "foo.groovy" in a directory "some/directory" in the interactive comamnd line tool, execute as + following</para> + <programlisting><![CDATA[. some/directory/foo.groovy]]></programlisting> + <para>"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.</para> + <para>Full execute syntax may also be used, and is required outside of the interactive command line tool:</para> + <programlisting><![CDATA[evaluate("some/directory/foo.groovy" as File) ]]></programlisting> + <para>To execute the same file without entering interactive mode, run</para> + <programlisting><![CDATA[./adminshell.sh . some/directory/foo.groovy]]></programlisting> + <para>Parameters can be passed in as Java System properties. For example</para> + <programlisting><![CDATA[./adminshell.sh -Dparam=value . some/directory/foo.groovy]]></programlisting> + <para>Inside the script file, you can access these properties using System.getProperty</para> + <programlisting><![CDATA[value = System.getProperty(“param”); // will return "value"]]></programlisting> + </sect1> + + <sect1> + <title>Log File and Recorded Script file</title> + <para>During the interactive mode, input is recorded in a history file. This file can be accessed via the up arrow in the interactive shell. + </para> + <para>User can also capture the commands entered during a interactive session to their own script file by + using “startRecording” and “stopRecording” commands. For example,</para> + <para /> + <programlisting><![CDATA[record start directory/filename.txt +<commands and script ..> +record stop]]></programlisting> + <para>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.</para> + <para /> + </sect1> + <sect1> + <title>Default Connection Properties</title> + <para>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</para> + <programlisting><![CDATA[ +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> + ]]></programlisting> + <para>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.  </para> + <para>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.</para> + <para>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 <link linkend="mutiple_connections">Handling Multiple Connections</link>.</para> + <para /> + </sect1> + <sect1 id="mutiple_connections"> + <title>Handling Multiple Connections</title> + <para>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.</para> + <para>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.</para> + <para /> + <para>You can use the following command to find out the current connection's name</para> + <programlisting><![CDATA[ +name = getConnectionName(); + ]]></programlisting> + <para>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</para> + <para /> + <programlisting><![CDATA[ +useConnection("name"); + ]]></programlisting> + <para>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.</para> + <para /> + <para>The following shows an example of using and switching between two connections.</para> + <programlisting><![CDATA[// 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();]]></programlisting> + </sect1> + +</chapter> \ No newline at end of file Modified: trunk/documentation/admin-guide/src/main/docbook/en-US/content/appendix-a.xml =================================================================== --- trunk/documentation/admin-guide/src/main/docbook/en-US/content/appendix-a.xml 2010-06-18 15:44:49 UTC (rev 2246) +++ trunk/documentation/admin-guide/src/main/docbook/en-US/content/appendix-a.xml 2010-06-18 15:46:33 UTC (rev 2247) @@ -1,5 +1,5 @@ <appendix id="faq"> - <title>Frequently Asked Questions</title> + <title>AdminShell Frequently Asked Questions</title> <qandaset> <qandaentry> Modified: trunk/documentation/admin-guide/src/main/docbook/en-US/content/appendix-b.xml =================================================================== --- trunk/documentation/admin-guide/src/main/docbook/en-US/content/appendix-b.xml 2010-06-18 15:44:49 UTC (rev 2246) +++ trunk/documentation/admin-guide/src/main/docbook/en-US/content/appendix-b.xml 2010-06-18 15:46:33 UTC (rev 2247) @@ -1,20 +1,22 @@ +<!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +<!ENTITY % CustomDTD SYSTEM "../../../../../../docbook/custom.dtd"> +%CustomDTD; +]> <appendix id="other_environments"> - <title>Other Environments</title> + <title>Other Scripting Environments</title> <para>The AdminShell methods (named contextual connections, AdminAPI - wrapper, and help system) have no direct dependencies on Groovy and be + wrapper, and help system) have no direct dependencies on Groovy and can be used in other scripting languages.</para> <para>To use the AdminShell methods in another language, simply import the static methods and Admin classes into your script. You will also - need to ensure that the &lt;admin shell - dist&gt;/lib/teiid-{version}-client.jar and &lt;admin shell - dist&gt;/lib/teiid-adminshell-{version}.jar are in your class path. The + need to ensure that the &lt;adminshell + dist&gt;/lib/teiid-&versionNumber;-client.jar and &lt;adminshell + dist&gt;/lib/teiid-adminshell-&versionNumber;.jar are in your class path. The snippet below show import statements that would work in Java, BeanShell, Groovy, etc.</para> - <programlisting><![CDATA[ -import static org.teiid.adminshell.AdminShell.*; -import org.teiid.adminapi.*; - ]]></programlisting> + <programlisting><![CDATA[import static org.teiid.adminshell.AdminShell.*; +import org.teiid.adminapi.*;]]></programlisting> <para>Note that the provided shell and console executables automatically have the proper class path set and inject the proper imports into running scripts. If you wish to use scripts in a Deleted: trunk/documentation/admin-guide/src/main/docbook/en-US/content/connection-management.xml =================================================================== --- trunk/documentation/admin-guide/src/main/docbook/en-US/content/connection-management.xml 2010-06-18 15:44:49 UTC (rev 2246) +++ trunk/documentation/admin-guide/src/main/docbook/en-US/content/connection-management.xml 2010-06-18 15:46:33 UTC (rev 2247) @@ -1,81 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> -<chapter id="connection_management"> - <title>Connection Management</title> - <sect1> - <title>Default Connection Properties</title> - <para>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</para> - <programlisting><![CDATA[ -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> - ]]></programlisting> - <para>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.  </para> - <para>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.</para> - <para>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 <link linkend="mutiple_connections">Handling Multiple Connections</link>.</para> - <para /> - </sect1> - <sect1 id="mutiple_connections"> - <title>Handling Multiple Connections</title> - <para>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.</para> - <para>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.</para> - <para /> - <para>In the interactive mode the name of the connection can found in the command prompt.  Also, you could - use the following command in the interactive and script mode to find out the current connection's name</para> - <programlisting><![CDATA[ -name = getConnectionName(); - ]]></programlisting> - <para>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</para> - <para /> - <programlisting><![CDATA[ -useConnection("name"); - ]]></programlisting> - <para>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.</para> - <para /> - <para>The following shows an example of using and switching between two connections.</para> - <programlisting><![CDATA[ -// 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(); - ]]></programlisting> - </sect1> -</chapter> \ No newline at end of file Deleted: trunk/documentation/admin-guide/src/main/docbook/en-US/content/getting-started.xml =================================================================== --- trunk/documentation/admin-guide/src/main/docbook/en-US/content/getting-started.xml 2010-06-18 15:44:49 UTC (rev 2246) +++ trunk/documentation/admin-guide/src/main/docbook/en-US/content/getting-started.xml 2010-06-18 15:46:33 UTC (rev 2247) @@ -1,138 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> -<chapter id="getting_started"> - <title>Getting Started with AdminShell</title> - <para> - To learn the basics of - <ulink url="http://groovy.codehaus.org/">Groovy</ulink> - take a look at their documents and tutorials on their website. - </para> - <para> - 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 <ulink url="http://java.sun.com/">http://java.sun.com</ulink>;. - </para> - <para>You can learn about the Teiid administrative API either using - “adminHelp()” function or find JavaDoc - for in the installation directory.</para> - <para>AdminShell is a specialized version of Groovy which works in - several different modes: interactive shell, console, or script - run mode.</para> - <para>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 scipt and the interactive session input and output can be - captured into a log file, more - on this later in the document.</para> - <para>In console mode (lanched via adminconsole), the user can develop and run scripts using a graphical text editor that supports syntax highlighting.</para> - <para>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</para> - <sect1> - <title>Essential rules to follow in using AdminShell</title> - <para>To use AdminShell successfully, there are some basic syntactical rules - you should keep in mind.</para> - <orderedlist> - <listitem> - <para>In interactive 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:</para> - <programlisting><![CDATA[ - connectAsAdmin() - ]]></programlisting> - </listitem> - <listitem> - <para>All commands and functions are case sensitive.</para> - </listitem> - <listitem> - <para>An ending semicolon is optional for Groovy statements.</para> - </listitem> - <listitem> - <para>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:</para> - <programlisting><![CDATA[ - connectAsAdmin("mm://localhost:34413", "user", "password") - ]]></programlisting> - </listitem> - <listitem> - <para>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: - </para> - <programlisting><![CDATA[ - import my.package.*; - myObject = new MyClass(); - myObject.doSomething(); - ]]></programlisting> - </listitem> - </orderedlist> - <para>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.</para> - <para>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.</para> - <para>Note: If SSL is turned on the Teiid server, you would need to - supply the correct certificates for the connection. - </para> - </sect1> - <sect1> - <title>Basic commands to get started</title> - <para>The list below contains some common commands used in AdminShell.</para> - <programlisting><![CDATA[ -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 - ]]></programlisting> - </sect1> - <sect1> - <title>Help</title> - <para>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</para> - <programlisting><![CDATA[ -adminHelp(); - ]]></programlisting> - <para>To get a specific definition about a method and it's required - input parameters, use adminHelp("method")</para> - <programlisting><![CDATA[ -adminHelp("deployVDB"); - -/* - *Deploy a VDB from file - */ -void deployVDB( - String /* file name */) - throws AdminException - throws FileNotFoundException - ]]></programlisting> - <para /> - <para>The sqlHelp() methods lists all Sql extension - methods.</para> - <programlisting><![CDATA[ -sqlHelp(); - ]]></programlisting> - <para>To get a specific definition about a method and it's required - input parameters, use sqlHelp("method")</para> - <para /> - </sect1> -</chapter> \ No newline at end of file Modified: trunk/documentation/admin-guide/src/main/docbook/en-US/content/installation.xml =================================================================== --- trunk/documentation/admin-guide/src/main/docbook/en-US/content/installation.xml 2010-06-18 15:44:49 UTC (rev 2246) +++ trunk/documentation/admin-guide/src/main/docbook/en-US/content/installation.xml 2010-06-18 15:46:33 UTC (rev 2247) @@ -1,32 +1,35 @@ <?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +<!ENTITY % CustomDTD SYSTEM "../../../../../../docbook/custom.dtd"> +%CustomDTD; +]> <chapter id="installation"> <title>Installation Guide</title> <para>Teiid 7.0 installation is entirely different from previous versions. Previously Teiid could be installed - as a standalone or embedded server. Starting with this release Teiid needs to be installed into an - existing JBoss AS installation. Teiid does not support the "embedded" mode in 7.0 version. ("embedded" version - will be coming in a future release soon). + as a standalone or embedded server. Starting with 7.0 Teiid needs to be installed into an + existing JBoss AS installation. Teiid does not support the "embedded" mode in &versionNumber; version. ("embedded" will be coming in a future release). </para> <sect1> - <title>Installation:</title> - <para>Here are the steps to follow to install Teiid</para> + <title>Installation</title> <orderedlist numeration="arabic"> + <para>Steps to install Teiid</para> <listitem> <para>Download the <ulink url="http://www.jboss.org/jbossas/downloads.html">JBoss AS 5.1.0</ulink> application server. Install the server by unzipping into a known location. Ex: /apps/jboss-5.1.0</para> </listitem> <listitem> - <para>Download <ulink url="http://www.jboss.org/teiid/downloads.html">Teiid 7.0</ulink>. Unzip the downloaded artifact inside any "profiles" - inside the JBoss AS installation. We suggest using either "default" or "all". - Teiid 7.0 for the administrative purposes uses a service called "profile service" that - is only installed in "default" and "all" profiles, so installing into one of these - profiles is required. Ex: /apps/jboss-5.10/server/default</para> + <para>Download <ulink url="http://www.jboss.org/teiid/downloads.html">Teiid &versionNumber;</ulink>. Unzip the downloaded artifact inside any "profile" + in the JBoss AS installation. Teiid 7.0 uses a JBoss AS service called the "profile service" that + is only installed in "default" and "all" profiles, so installing into one of these + profiles is required. The default profile is the typical installation location, for example "&lt;jboss-install&gt;/server/default". + The Teiid runtime directory structure matches JBoss profiles directly - it is just an overlay. + </para> </listitem> <listitem> - <para>Start the JBoss AS server by executing "/apps/jboss-5.1.0/bin/run.sh" if you installed in the - "default" profile. Other wise use "/apps/jboss-5.1.0/bin/run.sh -c &lt;profilename&gt;" + <para>Start the JBoss AS server by executing "&lt;jboss-install&gt;/bin/run.sh" if you installed in the + "default" profile. Otherwise use "&lt;jboss-install&gt;/bin/run.sh -c &lt;profilename&gt;" </para> </listitem> @@ -35,7 +38,7 @@ </listitem> <listitem> - <para>Users can now connect their JDBC applications to Teiid. If you need help on connecting your application to the + <para>Once VDBs have been deployed, users can now connect their JDBC applications to Teiid. If you need help on connecting your application to the Teiid using JDBC check out the "Client Developer's Guide". </para> </listitem> @@ -43,28 +46,27 @@ </sect1> <sect1> <title>Directory Structure Explained</title> - <para>The below file structure shows the contents of the Teiid 7.0 deployment. This directory - structure is "exactly" same as what is under any JBoss profile directory structure like "default"</para> - - <programlisting><![CDATA[ - teiid - /conf - /props - teiid-security-roles.properties - teiid-security-users.properties - jboss-teiid-log4j.xml - /deploy - /teiid - /connectors - teiid-jboss-beans.xml - teiid-connector-templates-jboss-beans.xml - admin-console.war - /deployers - /teiid.deployer - /lib - /teiid-examples - ]]></programlisting> - + <example> + <title>Directory Structure</title> + <para>This shows the contents of the Teiid 7.0 deployment. The directory + structure is exactly the same under any JBoss profile.</para> + <programlisting><![CDATA[teiid + /conf + /props + teiid-security-roles.properties + teiid-security-users.properties + jboss-teiid-log4j.xml + /deploy + /teiid + /connectors + teiid-jboss-beans.xml + teiid-connector-templates-jboss-beans.xml + admin-console.war + /deployers + /teiid.deployer + /lib + /teiid-examples]]></programlisting> + </example> <sect2> <title>/deploy/teiid/teiid-jboss-beans.xml</title> <para>Master configuration file for Teiid system. This file contains its own documentation, @@ -73,13 +75,20 @@ <sect2> <title>/deploy/teiid/connectors</title> - <para>This directory contains all the connector RAR files that are supplied as part of the Teiid installation.</para> + <para>This directory contains all the translator JAR and connector RAR files that are supplied as part of the Teiid installation.</para> </sect2> <sect2> <title>/conf/props</title> - <para> /teiid-security-users.properties</para> - <para> /teiid-security-roles.properties</para> + <itemizedlist> + <para>Relevant Files</para> + <listitem> + <para>/teiid-security-users.properties</para> + </listitem> + <listitem> + <para>/teiid-security-roles.properties</para> + </listitem> + </itemizedlist> <para>These files define the allowed users and their defined roles in Teiid using the default security domain. Edit these files to add uses. If you want to use a different security domain look for details in main configuration file.</para> </sect2> @@ -89,7 +98,7 @@ <para>This file contains the Teiid specific logging contexts to be included in the "jboss-log4j.xml" file. If you need to turn ON or OFF specific logging in Teiid, then copy the contents of this file into "jboss-log4j.xml" in the - installation directory. See the Server Extension Guide for more on logging.</para> + installation directory. See the Developers Guide for more on customizing logging.</para> </sect2> <sect2> @@ -98,13 +107,8 @@ Teiid's "admin-console", go to http://&lt;host&gt;:&lt;port&gt;/admin-console</para> </sect2> - <sect2> - <title>/deployers/teiid.deployer</title> - <para>This directory contains all the connector RAR files that are supplied as part of the Teiid installation.</para> - </sect2> - - <sect2> - <title>/deploy/teiid/connectors</title> + <sect2> + <title>/deployers/teiid.deployer</title> <para>This directory contains Teiid runtime specific configuration files and its libraries. These configuration files define VDB deployers, connector binding deployers etc. Typically user never need to edit any files in this directory.</para> @@ -112,8 +116,8 @@ <sect2> <title>lib</title> - <para>This directory contains Teiid client libraries. It has the Teiid JDBC driver jar, "teiid-{version}-client.jar", - and also contains "teiid-hibernate-dialect-{version}.jar" that contains Teiid's Hibernate dialect.</para> + <para>This directory contains Teiid client libraries. It has the Teiid JDBC driver jar, "teiid-&versionNumber;-client.jar", + and also contains "teiid-hibernate-dialect-&versionNumber;.jar" that contains Teiid's Hibernate dialect.</para> </sect2> <sect2> Modified: trunk/documentation/admin-guide/src/main/docbook/en-US/content/logging.xml =================================================================== --- trunk/documentation/admin-guide/src/main/docbook/en-US/content/logging.xml 2010-06-18 15:44:49 UTC (rev 2246) +++ trunk/documentation/admin-guide/src/main/docbook/en-US/content/logging.xml 2010-06-18 15:46:33 UTC (rev 2247) @@ -178,8 +178,7 @@ configure a separate file appender for the DETAIL logging of the org.teiid.COMMAND_LOG context. An example of this is shown below and can also be found in the jboss-log4j.xml distributed with Teiid. - <programlisting><![CDATA[ - <appender name="COMMAND" class="org.apache.log4j.RollingFileAppender"> + <programlisting><![CDATA[<appender name="COMMAND" class="org.apache.log4j.RollingFileAppender"> <param name="File" value="log/command.log"/> <param name="MaxFileSize" value="1000KB"/> <param name="MaxBackupIndex" value="25"/> @@ -191,11 +190,9 @@ <category name="org.teiid.COMMAND_LOG"> <priority value="INFO"/> <appender-ref ref="COMMAND"/> - </category> - ]]> - </programlisting> + </category>]]></programlisting> - See Developer's Guide if the file based logging is not sufficient and would need a custom logging solution. + See the Developer's Guide to develop a custom logging solution if file based, or any other built-in Log4j, logging is not sufficient. </para> </sect1> <sect1 id="audit_logging"> @@ -209,7 +206,6 @@ <para>To enable audit logging to an alternative file location, configure a separate file appender for the DETAIL logging of the org.teiid.AUDIT_LOG context. An example of this is already in - the log4j.xml distributed with Teiid. See Developer's Guide if the - file based logging is not sufficient and would need a custom logging solution.</para> + the log4j.xml distributed with Teiid. See the Developer's Guide to develop a custom logging solution if file based, or any other built-in Log4j, logging is not sufficient.</para> </sect1> </chapter> \ No newline at end of file Modified: trunk/documentation/admin-guide/src/main/docbook/en-US/content/vdb-deployment.xml =================================================================== --- trunk/documentation/admin-guide/src/main/docbook/en-US/content/vdb-deployment.xml 2010-06-18 15:44:49 UTC (rev 2246) +++ trunk/documentation/admin-guide/src/main/docbook/en-US/content/vdb-deployment.xml 2010-06-18 15:46:33 UTC (rev 2247) @@ -5,9 +5,8 @@ <para> A <ulink url="http://www.jboss.org/teiid/basics/virtualdatabases.html"&g... the primary means to define a Virtual Database in Teiid. A user can create a VDB using - <ulink url="http://www.jboss.org/teiiddesigner.html">Teiid Designer</ulink> or follow the instructions in the "reference" guide - create a "Dynamic VDB" without Designer for data integration purposes. If you do not know what a VDB is, - then please start with these <ulink url="http://www.jboss.org/teiid/basics/virtualdatabases.html"&g... + <ulink url="http://www.jboss.org/teiiddesigner.html">Teiid Designer</ulink> or follow the instructions in the Reference Guide to + create a "Dynamic VDB" without Teiid Designer. </para> <sect1> @@ -15,49 +14,42 @@ <para>Once you have a "VDB" built it can be deployed in Teiid runtime in different ways.</para> <sect2> - <title>By Copying the File</title> + <title>Direct File Deployment</title> <para>Copy the VDB file into the "&lt;jboss-install&gt;/server/&lt;profile&gt;/deploy" directory. Make sure that there are no other VDB files with the same name. If a VDB already exists with the same name, then this VDB will be replaced with the new VDB. This is the simplest way to deploy a VDB. This is mostly designed for quick deployment during development, when the Teiid server is available locally on the developer machine.</para> </sect2> + + <sect2> + <title>Admin Console Deployment (Web)</title> + <para>Use the JOPR-based web console configuration system. Check out the JOPR plugin at:</para> + + <programlisting><![CDATA[http://<host>:<port>/admin-console]]></programlisting> + + <para>More details for this can be found in the <link linkend="vdb_deploy">Admin Console VDB deployment section.</link>This is the easiest way + to deploy a VDB to a remote server.</para> + </sect2> <sect2> - <title>By Using Admin API</title> + <title>AdminShell Deployment</title> + <para>Teiid provides a groovy based AdminShell scripting tool, which can be used to deploy + a VDB. Check out the "deployVDB" method. Consult the + <link linkend="adminshell">AdminShell documentation</link> for more information. Note that using the AdminShell scripting, you can automate + the deployment of artifacts in your environment.</para> + </sect2> + + <sect2> + <title>Admin API Deployment</title> <para>The Admin API (look in org.teiid.adminpi.*) provides Java API methods that lets a user connect to a Teiid runtime and deploy a VDB. If you need to programmatically deploy a VDB use this method. This method is preferable for OEM users, who are trying to extend the Teiid's capabilities through their applications.</para> </sect2> - - <sect2> - <title>By Using Admin Shell</title> - <para>Teiid provides "groovy" based Admin Shell scripting tool, which can be used to deploy - a VDB. Check out the "deployVDB" method. Check out more information about <emphasis>Admin Shell</emphasis> - <link linkend="adminshell_introduction">here</link>. Note that using the AdminShell scripting, you can automate - the deployment of artifacts in your environment.</para> - </sect2> - <sect2> - <title>By Using Admin-Console (JOPR Based Web tool )</title> - <para>Use the JOPR-based web console configuration system, which will enable users to connect - to a running Teiid and provide a way to deploy a VDB. Check out the JOPR plugin at:</para> - - <programlisting><![CDATA[ - http://<host>:<port>/admin-console - ]]></programlisting> - - <para>More details for this can be found <link linkend="vdb_deploy">here.</link> This is preferred way - to deploy a VDB, when the Teiid server is shared among multiple users and/or Teiid Server is in a remote - location.</para> - </sect2> </sect1> - <para>Option 1 can be used for local development VDB deployment or deployment in a - manually controlled environment. Options 2, 3 and 4 can be used when your Teiid runtime - instance is a remote instance or if you need a programmatic way to control your deployment.</para> - <sect1> <title>Deploying VDB Dependencies</title> <para>Apart from deploying the VDB, the user is also responsible for providing all the necessary @@ -67,71 +59,73 @@ <para>For example, if you are trying to integrate Oracle and File sources in your VDB, then you are responsible for providing the JDBC driver for the Oracle source, and any necessary documents and configuration that are needed by the File Translator.</para> + <para>Once the VDB and its dependencies are deployed, then client applications can connect using the JDBC API. If there are any errors in the deployment, a connection attempt will not be successful and a message will be logged. You can use the + <link linkend="admin-console">admin-console</link> tool or check the log files for errors and correct them before proceeding.</para> + <sect2> - <title>Creating Oracle Data source</title> + <title>Creating An Oracle Data Source</title> <orderedlist> <listitem> <para>Copy the Oracle JDBC JAR file into "&lt;jboss-install&gt;/server/&lt;profile&gt;/lib" directory </para> </listitem> <listitem> <para>Create a "data source" to the Oracle instance in the JBoss container. This typically done by creating "xxx-ds.xml" file and copying this file to the "&lt;jboss-install&gt;/server/%lt;profile&gt;/deploy" directory. The following shows a "-ds.xml" file template for Oracle. You can also use admin-console to create this data source. </para> - <programlisting><![CDATA[ - <?xml version="1.0" encoding="UTF-8"?> - <datasources> - <xa-datasource> - <jndi-name>OracleDS</jndi-name> - <!-- uncomment to enable interleaving <interleaving/> --> - <isSameRM-override-value>false</isSameRM-override-value> - <xa-datasource-class>oracle.jdbc.xa.client.OracleXADataSource</xa-datasource-class> - <xa-datasource-property name="URL">jdbc:oracle:oci8:@tc</xa-datasource-property> - <xa-datasource-property name="User">scott</xa-datasource-property> - <xa-datasource-property name="Password">tiger</xa-datasource-property> - <!-- Uses the pingDatabase method to check a connection is still valid before handing it out from the pool --> - <!--valid-connection-checker-class-name>org.jboss.resource.adapter.jdbc.vendor.OracleValidConnectionChecker</valid-connection-checker-class-name--> - <!-- Checks the Oracle error codes and messages for fatal errors --> - <exception-sorter-class-name>org.jboss.resource.adapter.jdbc.vendor.OracleExceptionSorter</exception-sorter-class-name> - <!-- Oracles XA datasource cannot reuse a connection outside a transaction once enlisted in a global transaction and vice-versa --> - <no-tx-separate-pools/> - <!-- corresponding type-mapping in the standardjbosscmp-jdbc.xml (optional) --> - <metadata> - <type-mapping>Oracle9i</type-mapping> - </metadata> - </xa-datasource> - </datasources> - ]]></programlisting> + <programlisting><![CDATA[<?xml version="1.0" encoding="UTF-8"?> +<datasources> + <xa-datasource> + <jndi-name>OracleDS</jndi-name> + <!-- uncomment to enable interleaving <interleaving/> --> + <isSameRM-override-value>false</isSameRM-override-value> + <xa-datasource-class>oracle.jdbc.xa.client.OracleXADataSource</xa-datasource-class> + <xa-datasource-property name="URL">jdbc:oracle:oci8:@tc</xa-datasource-property> + <xa-datasource-property name="User">scott</xa-datasource-property> + <xa-datasource-property name="Password">tiger</xa-datasource-property> + <!-- Uses the pingDatabase method to check a connection is still valid before handing it out from the pool --> + <!--valid-connection-checker-class-name> + org.jboss.resource.adapter.jdbc.vendor.OracleValidConnectionChecker + </valid-connection-checker-class-name--> + + <!-- Checks the Oracle error codes and messages for fatal errors --> + <exception-sorter-class-name> + org.jboss.resource.adapter.jdbc.vendor.OracleExceptionSorter + </exception-sorter-class-name> + + <!-- Oracles XA datasource cannot reuse a connection outside a transaction once enlisted in a global transaction and vice-versa --> + <no-tx-separate-pools/> + <!-- corresponding type-mapping in the standardjbosscmp-jdbc.xml (optional) --> + <metadata> + <type-mapping>Oracle9i</type-mapping> + </metadata> + </xa-datasource> +</datasources>]]></programlisting> </listitem> </orderedlist> <para>There are templates for all the data sources in the "&lt;jboss-install&gt;/docs/examples/jca" directory.</para> </sect2> <sect2> - <title>Creating File Data source</title> + <title>Creating A File Data Source</title> <para>File data source uses Teiid specific JCA connector. You need to create "-ds.xml" file and copy it to the - "&lt;jboss-install&gt;/server/%lt;profile&gt;/deploy" directory. The below is template for creating a File based data source</para> - - <programlisting><![CDATA[ - <?xml version="1.0" encoding="UTF-8"?> - <connection-factories> - <no-tx-connection-factory> - <jndi-name>text-source</jndi-name> - <rar-name>connector-file-{version}.rar</rar-name> - <connection-definition>javax.resource.cci.ConnectionFactory</connection-definition> - <config-property name="ParentDirectory" type="java.lang.String">path-to-the-directory-of-data-file</config-property> - <max-pool-size>1</max-pool-size> - </no-tx-connection-factory> - </connection-factories> - ]]></programlisting> + "&lt;jboss-install&gt;/server/%lt;profile&gt;/deploy" directory.</para> + <example> + <title>Template for creating a File based data source</title> + <programlisting><![CDATA[<?xml version="1.0" encoding="UTF-8"?> +<connection-factories> + <no-tx-connection-factory> + <jndi-name>text-source</jndi-name> + <rar-name>connector-file-{version}.rar</rar-name> + <connection-definition>javax.resource.cci.ConnectionFactory</connection-definition> + <config-property name="ParentDirectory" type="java.lang.String">path-to-the-directory-of-data-file</config-property> + <max-pool-size>1</max-pool-size> + </no-tx-connection-factory> +</connection-factories>]]></programlisting></example> </sect2> </sect1> - <para>Once the VDB and its dependencies are deployed, then your client application can connect to the - deployed VDB using the JDBC API. If there are any errors in the deployment, the connection will not be successful. You can use the - <link linkend="admin-console">admin-console</link> tool or check the log files for errors and correct them before proceeding.</para> - <sect1> <title>Migrating VDBs from 6.x</title> <para>VDBs from prior release contain an older configuration file version that is no longer supported. You can use the migration utility (bin/migrate.sh or bin/migrate.bat) supplied with the - <link linkend="adminshell_introduction">Admin Shell</link> download + <link linkend="adminshell">AdminShell</link> download to update these VDBs for use with Teiid 7. Note - XML and File based sources from previous releases are changed, so do not work as is. The VDB models need to be updated for this as these are breaking changes.</para> </sect1> Deleted: trunk/documentation/admin-guide/src/main/docbook/en-US/content/working-with-scripts.xml =================================================================== --- trunk/documentation/admin-guide/src/main/docbook/en-US/content/working-with-scripts.xml 2010-06-18 15:44:49 UTC (rev 2246) +++ trunk/documentation/admin-guide/src/main/docbook/en-US/content/working-with-scripts.xml 2010-06-18 15:46:33 UTC (rev 2247) @@ -1,51 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> -<chapter id="working_with_scripts"> - <title>Working with Scripts</title> - <sect1> - <title>Executing script file in interactive mode</title> - <para>To execute a script file "foo.groovy" in a directory "some/directory" in the shell tool, execute as - following</para> - <programlisting><![CDATA[ -. some/directory/foo.groovy - ]]></programlisting> - <para>"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.</para> - <para>Full execute syntax may also be used, and is required outside of the Shell tool:</para> - <programlisting><![CDATA[ -evaluate("some/directory/foo.groovy" as File) - ]]></programlisting> - </sect1> - <sect1> - <title>Executing script file in non-interactive mode</title> - <para>To execute a script file "foo.groovy" in a directory "some/directory" in non-interactive mode, execute as - following command at the command prompt</para> - <programlisting><![CDATA[ -adminshell.sh . some/directory/foo.groovy - ]]></programlisting> - <para>Parameters can be passed in as Java System properties. For example</para> - <programlisting><![CDATA[ -adminshell.sh -Dparam=value . some/directory/foo.groovy - ]]></programlisting> - <para>Inside the script file, you can access these properties using System.getProperty</para> - <programlisting><![CDATA[ -value = System.getProperty(“param”); // will return "value" - ]]></programlisting> - </sect1> - <sect1> - <title>Log File and Recorded Script file</title> - <para>During the interactive mode, input is recorded in a history file. This file can be accessed via the up arrow in the interactive shell. - </para> - <para>User can also capture the commands entered during a interactive session to their own script file by - using “startRecording” and “stopRecording” commands. For example,</para> - <para /> - <programlisting><![CDATA[ -record start directory/filename.txt -<commands and script ..> -record stop - ]]></programlisting> - <para>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.</para> - <para /> - </sect1> -</chapter> \ No newline at end of file Modified: trunk/documentation/quick-start-example/src/main/docbook/en-US/content/connect-vdb.xml =================================================================== --- trunk/documentation/quick-start-example/src/main/docbook/en-US/content/connect-vdb.xml 2010-06-18 15:44:49 UTC (rev 2246) +++ trunk/documentation/quick-start-example/src/main/docbook/en-US/content/connect-vdb.xml 2010-06-18 15:46:33 UTC (rev 2247) @@ -1,5 +1,8 @@ <?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +<!ENTITY % CustomDTD SYSTEM "../../../../../../docbook/custom.dtd"> +%CustomDTD; +]> <chapter id="OpenConnection"> <title>Connecting to a VDB through JDBC</title> <para>At this point you have deployed Teiid and your VDB. Now it's time to connect the sample application @@ -9,7 +12,7 @@ <title>Stand-alone Java Application Deployment</title> <para>Before you can make a JDBC connection to the Teiid VDB, add the Teiid's driver jar file to your application's classpath</para> - <programlisting><![CDATA[${jboss-install}/server/${profile}/lib/teiid-${version}-client.jar]]> </programlisting> + <programlisting>${jboss-install}/server/${profile}/lib/teiid-&versionNumber;-client.jar</programlisting> <para> For a Java application to connect to a JDBC source, it needs a URL, user-id, and password. To Modified: trunk/documentation/quick-start-example/src/main/docbook/en-US/content/download.xml =================================================================== --- trunk/documentation/quick-start-example/src/main/docbook/en-US/content/download.xml 2010-06-18 15:44:49 UTC (rev 2246) +++ trunk/documentation/quick-start-example/src/main/docbook/en-US/content/download.xml 2010-06-18 15:46:33 UTC (rev 2247) @@ -1,5 +1,8 @@ <?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +<!ENTITY % CustomDTD SYSTEM "../../../../../../docbook/custom.dtd"> +%CustomDTD; +]> <chapter id="download"> <title>Download</title> <para> @@ -12,7 +15,7 @@ <para>Teiid Source - contains all of the source code</para> </listitem> <listitem> - <para>Teiid Adminshell - contains the admin client</para> + <para>Teiid AdminShell - contains the admin client</para> </listitem> <listitem> <para>Teiid Runtime - contains the Teiid engine and required 3rd party @@ -21,11 +24,10 @@ </orderedlist> <para> For this Quick Start, download and install <ulink url="http://www.jboss.org/jbossas/downloads.html">JBoss AS 5.1.0</ulink>. - Then download Teiid runtime and unzip the contents of the Teiid under any of one of the JBoss AS profiles - like "default" or "all". The default profile is the typical installation location, for example "&lt;jboss-install&gt;/server/default". The Teiid runtime directory structure matches that - of the JBoss profile directly. + Then download the Teiid runtime and unzip the contents under any of the JBoss AS profiles, such as "default" or "all". + The default profile is the typical installation location, for example "&lt;jboss-install&gt;/server/default". The Teiid runtime directory structure matches JBoss profiles directly - it is just an overlay. </para> - <para>In the "&lt;jboss-install&gt;/server/&lt;profile&gt;/lib" directory, you will find "teiid-${version}-client.jar", which + <para>In the "&lt;jboss-install&gt;/server/&lt;profile&gt;/lib" directory, you will find "teiid-&versionNumber;-client.jar", which is the main client binary jar file for Teiid. This jar file contains the Teiid's JDBC driver and data source classes. </para> <note> <para>JBoss AS 5.1 requires <ulink url="http://java.sun.com/javase/downloads">Java 6</ulink> to run.