15 Using Groovy Scripting

This chapter provides an introduction to the Groovy language and explains how to use Groovy scripting in Oracle Data Integrator.

This appendix includes the following sections:

• Introduction to Groovy

• Introduction to the Groovy Editor

• Using the Groovy Editor

• Automating Development Tasks - Examples

Introduction to Groovy

Groovy is a scripting language with Java-like syntax for the Java platform. The Groovy scripting language simplifies the authoring of code by employing dot-separated notation, yet still supporting syntax to manipulate collections, Strings, and JavaBeans.

For more information about the Groovy language, see the following web site:

http://groovy.codehaus.org/

Introduction to the Groovy Editor

The Groovy editor provides a single environment for creating, editing, and executing Groovy scripts within the ODI Studio context. Figure 15-1 gives an overview of the Groovy editor.

Figure 15-1 Groovy Editor

Description of "Figure 15-1 Groovy Editor"

The Groovy editor provides all standard features of a code editor such as syntax highlighting and common code editor commands except for debugging. The following commands are supported and accessed through the context menu or through the Source main menu:

• Show Whitespace

• Text Edits

  • Join Line

  • Delete Current Line

  • Trim Trailing Whitespace

  • Convert Leading Tabs to Spaces

  • Convert Leading Spaces to Tabs

• Indent Block

• Unindent Block

• Move Up

• Move Down

Using the Groovy Editor

You can perform the following actions with the Groovy editor:

• Create a Groovy Script

• Open and Edit an Existing Groovy Script

• Save a Groovy Script

• Execute a Groovy Script

• Stop the Execution of a Groovy Script

• Perform Advanced Actions

Create a Groovy Script

To create a Groovy script in ODI Studio:

1. From the Tools Main menu select Groovy > New Script.

   This opens the Groovy editor.

2. Enter the Groovy code.

You can now save or execute the script.

Open and Edit an Existing Groovy Script

To edit a Groovy Script that has been previously created:

1. From the Tools Main menu select Groovy > Open Script or Recent Scripts.

2. Select the Groovy file and click Open.

   This opens the selected file in the Groovy editor.

3. Edit the Groovy script.

You can now save or execute the script.

Save a Groovy Script

To save a Groovy script that is currently open in the Groovy editor:

From the Tools Main menu select Groovy > Save Script or Save Script As.

Note:

The Save main toolbar option is not associated with the Groovy Editor.

Execute a Groovy Script

You can execute one or several Groovy scripts at once and also execute one script several times in parallel.

You can only execute a script that is opened in the Groovy editor. ODI Studio does not execute a selection of the script, it executes the whole Groovy script.

To execute a Groovy script in ODI Studio:

1. Select the script that you want to execute in the Groovy editor.

2. Click Execute in the toolbar.

3. The script is executed.

You can now follow the execution in the Log window.

Notes:

• Each script execution launches its own Log window. The Log window is named according to the following format: Running <script_name>

• Groovy writes output to two different streams. If it is a class, it writes to System.out, which is a global output stream. If it is from a script (non-class), then it creates one stream for every execution. This can be captured by ODI. So, only output written to a script is shown in the Log window.

  You can add System.setOut(out) in the beginning of a Groovy script so that the messages printed by an external class can be redirected to messages log.

Stop the Execution of a Groovy Script

You can only stop running scripts. If no script is running, the Stop buttons are deactivated.

The execution of Groovy scripts can be stopped using two methods:

• Clicking Stop in the Log tab. This stops the execution of the particular script.

• Click Stop on the toolbar. If several scripts are running, you can select the script execution to stop from the drop down list.

Perform Advanced Actions

This section describes some advanced actions that you can perform with the Groovy editor.

Use Custom Libraries

The Groovy editor is able to access external libraries for example if an external driver is needed.

To use external libraries, do one of the following:

• Copy the custom libraries to the userlib folder. This folder is located:

  • On Windows operating systems:

    %APPDATA%/odi/oracledi/userlib

  • On UNIX operating systems:

    ~/.odi/oracledi/userlib

• Add the custom libraries to the additional_path.txt file. This file is located in the userlib folder and has the following content:

  ; Additional paths file
  ; You can add here paths to additional libraries
  ; Examples:
  ;       C:\ java\libs\myjar.jar
  ;       C:\ java\libs\myzip.zip
  ;       C:\java\libs\*.jar will add all jars contained in the C:\java\libs\ directory
  ;       C:\java\libs\**\*.jar will add all jars contained in the C:\java\libs\ directory and subdirectories
  

Define Additional Groovy Execution Classpath

You can define a Groovy execution classpath in addition to all classpath entries available to ODI Studio.

To define an additional Groovy execution classpath:

1. Before executing the Groovy script, select from the Tools Main menu Preferences...

2. In the Preferences dialog, navigate to the Groovy Preferences page.

3. Enter the classpath and click OK.

   Note:

   You do not need to restart ODI Studio after adding or changing the classpath.

Read Input with odiInputStream Variable

Oracle Data Integrator provides the odiInputStream variable to read input streams. This variable is used as follows:

odiInputStream.withReader { println (it.readLine())}

When this feature is used an Input text field is displayed on the bottom of the Log tab. Enter a string text and press ENTER to pass this value to the script. The script is exited once the value is passed to the script.

Example 15-1 shows another example of how to use an input stream. In this example you can provide input until you click Stop <script_name>.

Example 15-1 InputStream

odiInputStream.withReader { reader ->
  while (true) {
    println reader.readLine(); 
  }
}
 

Using Several Scripts

If you are using several scripts at once, note the following:

• A log tab is opened for each execution.

• If a script is referring to another script, the output of the second will not be redirected to the log tab. This is a known Groovy limitation with no workaround.

Using the ODI Instance

Oracle Data Integrator provides the variable odiInstance. This variable is available for any Groovy script running within ODI Studio. It represents the ODI instance, more precisely the connection to the repository, in which the script is executed. Note that this instance will be null if ODI Studio is not connected to a repository.

The odiInstance variable is initialized by the ODI Studio code before executing the code. You can use bind APIs of the Groovy SDK for this purpose. Example 15-2, "Creating a Project" shows how you can use the odiInstance variable.

Automating Development Tasks - Examples

Oracle Data Integrator provides support for the use of Groovy to automate development tasks. These tasks include for example:

• Example 15-2, "Creating a Project"

• Example 15-3, "External Groovy File"

• Example 15-4, "Class from External File"

• Example 15-5, "For Studio UI Automation"

Example 15-2 shows how to create an ODI Project with a Groovy script.

Example 15-2 Creating a Project

import oracle.odi.core.persistence.transaction.ITransactionDefinition;
import oracle.odi.core.persistence.transaction.support.DefaultTransactionDefinition;
import oracle.odi.core.persistence.transaction.ITransactionManager;
import oracle.odi.core.persistence.transaction.ITransactionStatus;
import oracle.odi.domain.project.OdiProject;
import oracle.odi.domain.project.OdiFolder;
 
 
ITransactionDefinition txnDef = new DefaultTransactionDefinition();
ITransactionManager tm = odiInstance.getTransactionManager()
ITransactionStatus txnStatus = tm.getTransaction(txnDef)
OdiProject myProject = new OdiProject("New Project 1","NEW_PROJECT_1")
OdiFolder myFolder = new OdiFolder(myProject,"Test Folder 001")
odiInstance.getTransactionalEntityManager().persist(myProject)
tm.commit(txnStatus)

Example 15-3 shows how to import an external Groovy script.

Example 15-3 External Groovy File

//Created by ODI Studio
import gd.Test1;
println "Hello World"
Test1 t1 = new Test1()
println t1.getName()
 

Example 15-4 shows how to call a class from a different Groovy script.

Example 15-4 Class from External File

import gd.GroovyTestClass
 
GroovyTestClass tc = new GroovyTestClass()
println tc.getClassLoaderName()
 

Example 15-5 shows how to implement Studio UI automation.

Example 15-5 For Studio UI Automation

import javax.swing.JMenuItem;
import javax.swing.JMenu;
import oracle.ide.Ide;
 
((JMenuItem)Ide.getMenubar().getGUI(false).getComponent(4)).doClick();
JMenu mnu = ((JMenu)Ide.getMenubar().getGUI(false).getComponent(4));
((JMenuItem)mnu.getMenuComponents()[0]).doClick()