C Using Groovy Scripting in Oracle Data Integrator

This appendix provides an introduction to the Groovy language and explains how to use Groovy scripting in Oracle Data Integrator. This appendix contains the following sections:

• Section C.1, "Introduction to Groovy"

• Section C.2, "Introduction to the Groovy Editor"

• Section C.3, "Using the Groovy Editor"

• Section C.4, "Automating Development Tasks - Examples"

C.1 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. Groovy language expressions in ADF Business Components differs from the Java code that you might use in a Business Components custom Java class because Groovy expressions are executed at runtime, while the strongly typed language of Java is executed at compile-time. Additionally, because Groovy expressions are dynamically compiled, they are stored in the XML definition files of the business components where you use it. ADF Business Components supports the use of the Groovy scripting language in places where access to entity object and view object attributes is useful, including attribute validators (for entity objects), attribute default values (for either entity objects or view objects), transient attribute value calculations (for either entity objects or view objects), bind variable default values (in view object query statements and view criteria filters), and placeholders for error messages (in entity object validation rules). Additionally, ADF Business Components provides a limited set of built-in keywords that can be used in Groovy expressions.

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

http://groovy.codehaus.org/

C.2 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 C-1 gives an overview of the Groovy editor.

Figure C-1 Groovy Editor

Description of "Figure C-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

  • Macro Toggle Recording

  • Macro Playback

• Indent Block

• Unindent Block

C.3 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

C.3.1 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.

C.3.2 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.

C.3.3 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 and Save All toolbar options are not associated with the Groovy Editor.

C.3.4 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.

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

C.3.5 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.

C.3.6 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 C-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 C-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 C-2 shows how you can use the odiInstance variable.

C.4 Automating Development Tasks - Examples

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

• Example C-2, "Creating a Project"

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

• Example C-3, "External Groovy File"

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

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

Example C-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 C-3 shows how to import an external Groovy script.

Example C-3 External Groovy File

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

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

Example C-4 Class from External File

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

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

Example C-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()