This appendix provides a reference of Oracle Data Integrator (ODI) tools. It describes how to use Open Tools to develop new scenarios in Oracle Data Integrator.
This appendix includes the following sections:
Oracle Data Integrator tools (also called Oracle Data Integrator commands) are commands provided for performing specific tasks at runtime. These tasks can be as simple as waiting for a certain time or producing a sound, or as sophisticated as executing Ant scripts or reading email from a server.
Oracle Data Integrator tools are used in Packages, Procedure Commands, Knowledge Modules Commands, or directly from a command line.
Note:
Previous versions of Oracle Data Integrator supported calling built-in tools from Jython or Java scripts using their internal Java classes (such asSnpsSendMail and SendMail). This approach is no longer supported.Note:
Carriage returns in commands are not permitted.Adding and using an Oracle Data Integrator tool in a Package is described in "Adding Oracle Data Integrator Tool Steps" in Developing Integration Projects with Oracle Data Integrator.
You can sequence the tool steps within the package and organize them according to their success and failure. For more information about sequencing, see "Arranging the Steps Layout" and "Defining the Sequence of Steps" in Developing Integration Projects with Oracle Data Integrator.
You can use variable values, sequences, or Oracle Data Integrator substitution method calls directly in tool parameters.
Using an Oracle Data Integrator tool in a Knowledge Module or Procedure is described in "Working with Procedures" in Developing Integration Projects with Oracle Data Integrator.
You can use variable values, sequences, Oracle Data Integrator substitution method calls, or the results from a SELECT statement directly in tool parameters.
Command line scripts for Oracle Data Integrator tools are run from the DOMAIN_HOME/bin directory. To run a tool from a command line, you must first create an ODI Physical Agent instance in the ODI Topology and configure an ODI Standalone Agent instance in a Domain. For more information about performing these tasks, see Installing and Configuring Oracle Data Integrator.
When you run a tool from a command line, you must specify the -INSTANCE parameter, where <agent_name> is the name of the physical agent you configured (for example, OracleDIAgent1).
To use an Oracle Data Integrator tool from a command line:
Launch the command shell for your environment (Windows or UNIX).
Navigate to the DOMAIN_HOME/bin directory.
Launch the startcmd.cmd (Windows) or startcmd.sh (UNIX) command and run an Oracle Data Integrator tool with the following syntax:
startcmd.<cmd|sh> -INSTANCE=<agent_name> <command_name> [<command_parameters>]*
Command names and command parameters are case-sensitive.
Note the following:
On Windows platforms, command arguments that contain equal (=) signs or spaces must be surrounded with double quotation marks. This differs from the UNIX command call. For example:
startcmd.cmd OdiSleep "-INSTANCE=OracleDIAgent1" "-DELAY=5000" ./startcmd.sh OdiSleep -INSTANCE=OracleDIAgent1 -DELAY=5000
The following tools do not support direct invocation through a command line:
OdiRetrieveJournalData
OdiRefreshJournalCount
The Open Tools feature provides an extensible platform for developing custom third-party tools that you can use in Packages and Procedures. As with the standard tools delivered with Oracle Data Integrator, Open Tools can interact with the operating system and manipulate data.
Open Tools are written in Java. Writing your own Open Tools is described in "Developing Open Tools".
Open Tools are delivered as a Java package (.zip or .jar) that contains several files:
A compiled Java .class file
Other resources, such as icon files
Before you can use an Open Tool, you must install and add it.
To install an Open Tool, you must add the Open Tool JAR into the classpath or the component using the tool.
Open Tool JARs must be added to the DOMAIN_HOME/lib directory. Drivers are added to the same location.
To deploy an Open Tool JAR with a Java EE agent, generate a server template for this agent. The Open Tool displays in the Libraries and Drivers list in the Template Generation Wizard. See "Creating a Server Template for the Java EE Agent" in Administering Oracle Data Integrator for more information.
Note:
This operation must be performed for each Oracle Data Integrator Studio from which the tool is being used, and for each agent that will run sessions using this tool.This operation declares an Open Tool in a master repository and enables the tool to display in Oracle Data Integrator Studio.
To declare an Open Tool a JAR must be added in <ide.user.dir>/oracledi/userlib
To declare a new tool:
In Oracle Data Integrator Studio, select the ODI menu and then select Add Remove/Open Tools. The Add Open Tools dialog displays.
Enter the name of the class in the Open Tool Class Name field.
or:
Click Find in the ClassPath, then browse to the name of the Open Tool's Java class. To search for the class by name, enter part of the name in the field at the top.
Click OK.
Note that all classes currently available to Oracle Data Integrator are displayed, including those that are not Open Tools. You must know the name of your class in order to add it.
Click Add Open Tool.
Select the line containing your Open Tool.
If the tool was correctly found on the classpath, the supplied icons, and the tool's syntax, description, provider, and version number are displayed.
If the tool was not found, an error message is displayed. Change the classpath, or move the Open Tool to the correct directory.
Note:
This operation to declare a new Open Tool must be performed only once for a given master repository.Note:
An Open Tool name cannot start withSnp or Odi. An Open Tool with a name that starts with these strings is ignored.An Open Tool is a Java package that contains a compiled Java class that implements the interface oracle.odi.sdk.opentools.IOpenTool. For a complete description of classes and methods, see the Oracle Data Integrator Open Tools Java API Reference (JavaDoc).
An Open Tool package typically should also contain two icons, which are used to represent the Open Tool in the Oracle Data Integrator graphical interface.
The following table lists and describes Open Tool classes and interfaces.
| Class or Interface | Description |
|---|---|
IOpenTool |
Interface that every Open Tool must implement. |
OpenToolAbstract |
Abstraction of the interface with some helper methods. Preferably extend this class rather than implementing the interface directly. |
IOpenToolParameter |
Interface that parameters used by Open Tools must implement. In most cases, OpenToolParameter should be used rather than implementing this interface. |
OpenToolParameter |
Complete implementation of IOpenToolParameter. Each OpenToolParameter holds one parameter. |
OpenToolsExecutionException |
Exception class that should be thrown if necessary by Open Tool methods. |
SimpleOpenToolExample |
A simple example of an Open Tool, which can be used as a starting point. |
The following steps describe the development of a basic Open Tool, SimpleMessageBox. The source code for this class is available in the demo/plugins/src directory.
Define the syntax. In this example, the Open Tool is called as follows:
SimpleMessageBox "-TEXT=<text message>" "-TITLE=<window title>"
Create 16x16 and 32x32 icons (usually in .gif format).
Create and implement the class. See "Implementing the Class".
Compile the class and create a package with the two icon files.
Install and declare the Open Tool as described in "Installing and Declaring an Open Tool".
Implementing the class consists of the following steps:
Before you declare the class, you must name the package.
Put the class in a package named appropriately. The package name is used to identify the Open Tool when installing it.
package com.myCompany.OpenTools;
There are two basic approaches to developing an Open Tool:
Extend an existing class that you want to convert into an Open Tool. In this case, simply implement the interface IOpenTool directly on the existing class.
Develop a new class. In this case, it is easiest to extend the abstract class OpenToolAbstract. This abstract class also contains additional helper methods for working with parameters.
public class SimpleMessageBox extends OpenToolAbstract {
Almost every Open Tool must import the following Open Tool SDK packages:
import oracle.odi.sdk.opentools.IOpenTool; /* All Open Tool classes need these three classes */ import oracle.odi.sdk.opentools.IOpenToolParameter; import oracle.odi.sdk.opentools.OpenToolExecutionException; import oracle.odi.sdk.opentools.OpenToolAbstract; /* The abstract extended for the Open Tool */ import oracle.odi.sdk.opentools.OpenToolParameter; /* The class used for parameters */
In this particular example, a package to create the message box is also needed:
import javax.swing.JOptionPane; /* Needed for the message box used in this example */
Add a property to store the OpenToolParameter objects. This is used to both define them for the syntax, and to retrieve the values of the parameters from the eventual user. It is easiest to define the parameters of the Open Tool with a static array as follows. This array should be private, as it will be accessed through an accessor function.
private static final IOpenToolParameter[] mParameters = new IOpenToolParameter[]
{
new OpenToolParameter("-TEXT", "Message text", "Text to show in the messagebox (Mandatory).", true),
new OpenToolParameter("-TITLE", "Messagebox title", "Title of the messagebox.", false)
};
The four parameters passed to the OpenToolParameter() constructor are as follows:
The code of the parameter, including the initial hyphen. This code must correspond to the syntax returned by getSyntax().
The user-friendly name, which is used if the user is using the graphical interface to set parameters.
A descriptive help text.
Whether the parameter is mandatory. This is an indication to the user.
Note:
Oracle Data Integrator does not enforce the mandatory flag on parameters. Your class must be able to handle any combination of parameters being provided.You must implement the accessor function getParameters() to retrieve the parameters:
public IOpenToolParameter[] getParameters()
{
return mParameters;
}
Implement functions to return information about your Open Tool: getDescription(), getVersion(), getProvider().
public String getDescription() { return "This Open Tool displays a message box when executed."; }
public String getVersion() { return "v1.0"; }
public String getProvider() { return "My Company, Inc."; }
The getSyntax() function determines the name of the Open Tool as it is displayed in the Oracle Data Integrator graphical interface, and also the initial values of the parameter. Make sure the names of the parameters here match the names of the parameters returned by getParameters().
public String getSyntax()
{
return "SimpleMessageBox \"-TEXT=<text message>\" \"-TITLE=<window title>\"";
}
The getIcon() method should then return paths to two appropriately sized images. It should look something like this:
public String getIcon(int pIconType)
{
switch (pIconType)
{
case IOpenTool.SMALL_ICON:
return "/com/myCompany/OpenTools/images/SimpleMessageBox_16.gif";
case IOpenTool.BIG_ICON:
return "/com/myCompany/OpenTools/images/SimpleMessageBox_32.gif";
default:
return "";
}
}
Finally, the execute() method, which carries out the functionality provided by the Open Tool. In this case, a message box is shown. If you are extending the OpenToolAbstract class, use the getParameterValue() method to easily retrieve the values of parameters, as they are set at runtime.
Note:
You must catch all exceptions and only raise anOpenToolExecutionException.
public void execute() throws OpenToolExecutionException
{
try
{
if (getParameterValue("-TITLE") == null || getParameterValue("-TITLE").equals("")) /* title was not filled in by user */
{
JOptionPane.showMessageDialog(null, (String) getParameterValue("-TEXT"), (String) "Message", JOptionPane.INFORMATION_MESSAGE);
} else
{
JOptionPane.showMessageDialog(null, (String) getParameterValue("-TEXT"),
(String) getParameterValue("-TITLE"),
JOptionPane.INFORMATION_MESSAGE);
}
}
/* Traps any exception and throw them as OpenToolExecutionException */
catch (IllegalArgumentException e)
{
throw new OpenToolExecutionException(e);
}
}
In general, your Open Tool class is instantiated only very briefly, and is used in the following ways.
When the user chooses to install an Open Tool, Oracle Data Integrator instantiates the class and calls the methods getDescription(), getProvider(), getIcon(), and getVersion() to retrieve information about the class.
When the Open Tool is used in a package, the class is instantiated briefly to call the methods getDescription(), getProvider(), getIcon(), and getVersion(). Additionally, getSyntax() is called to retrieve the code name of the Open Tool and its default arguments. The method getParameters() is called to display the list of arguments to the user.
Each time the Open Tool is executed in a package or procedure, the class is instantiated again; it has no persistence after its execution. The execute() method is called just once.
Tip:
See also Using Open Tools and Open Tools SDK documentation (JavaDoc).