Talend Routines Tutorial
A site about Talend
Talend Routines Tutorial
Sometimes, you will want to write your own routines. This allows you to write code once, which you can call many times from within the same Job or from more than one of your Jobs. You may also want to Refactor complex code for readability, or use a routine to aid using external libraries that you've imported.
In this tutorial, we'll import the external Java library Google's Phone Number Handling Library, to demonstrate how to use imported libraries. You can, of course, use routines without importing external libraries if your requirement does not need one.
The Code->Routines section of the Talend Repository allows you to easily define new Java Classes, for use within your Jobs. You'll see that there's already a section named Code->Routines->System where Talend has some predefined Classes. As well as being able to use these Classes within your Jobs, you can also use them as templates for creating your own Classes.
A Simple Routine
In our Talend tLibraryLoad Component Tutorial, we use Google's Phone Number Handling Library to perform validation and formatting of incoming Phone Numbers. In this tutorial, we used a tJavaRow Component to make the calls to Google's library. We did this as this library may throw an exception and we can't simply catch or ignore this within a tMap Component's Mapping Expression. A cleaner approach, to what is shown in that tutorial, might be to create our own routine to encapsulate the Google library calls that we want to use and to handle any exceptions that are thrown.
Here's our original code from Talend tLibraryLoad Component Tutorial. If you're not familiar with tLibraryLoad and how we might use a library within a tJavaRow, then review that tutorial, now.
com.google.i18n.phonenumbers.PhoneNumberUtil pNU = com.google.i18n.phonenumbers.PhoneNumberUtil.getInstance();
output_row.Name = input_row.Name;
output_row.PhoneNumber = input_row.PhoneNumber;
try {
output_row.MappedPhoneNumber = pNU.format(pNU.parse(input_row.PhoneNumber, "GB"), com.google.i18n.phonenumbers.PhoneNumberUtil.PhoneNumberFormat.E164);
}
catch (Exception e)
{
output_row.MappedPhoneNumber = "bad number";
}
What are we doing here? We're instantiating PhoneNumberUtil and using the parse and format methods to validate and format the phone number. If the input value is found not to be a phone number, then parse will throw an exception. In this case, we return the value "bad number" rather than a correctly formatted number.
Refactoring Our Code in to a Routine
We'll now look at Refactoring the above code in to a routine. The basic steps we have taken in our current Phone Number handling code is: -
- Instantiate PhoneNumberUtil
- Parse and Format our input
- Handle exceptions
- Return our output
Create a new routine by right-clicking Code->Routines and selecting Create routine. Name the routine PhoneUtil.
Talend will now open the routine editor. Default code will be automatically added to your routine, including a sample method (Talend refers to this as a function).
Edit Routine Libraries
We need Google's Phone Number Handling Library to be available to our new routine. If you've already completed our Talend tLibraryLoad Component Tutorial, then you'll already have this library and it is likely to be installed in Talend's .../lib/java directory e.g. /Applications/TOS_DI-r100420-V5.3.0RC1/lib/java/libphonenumber-5.4.jar. If you haven't already downloaded the library, Download it now.
You can make the library available by right-clicking the routine PhoneUtil in the Repository Browser and selecting Edit Routine Libraries.
The Import External Library dialog will now be displayed. Now select New and then the New Module dialog will be also displayed. Here you can select Browse library file and then press the Browse... button. You can now navigate to select the library file that you want to import e.g. /Applications/TOS_DI-r100420-V5.3.0RC1/lib/java/libphonenumber-5.4.jar. Once you've selected this file, press the Ok button to close the New Module dialog.
You can now see that the library file is ready to import. Press Finish to complete the import.
Routine Structure
Let's now look at the important parts of the code that has been generated in our routine. If the Routine edit window is not already open, open it now by double-clicking the routine.
Routine Package
All of your custom routines are placed in a Java package named routines package routines;. You cannot change the package.
Class Comments
Talend adds some class-level comments. These provide you with some helpful information on how to write the comments for your methods.
Class Definition
A new Class has been defined with the name that you entered when you created your routine public class PhoneUtil {.
Method Implementation
A new Public Static Method has been implemented public static void helloExample(String message) {. This is simply created as a helper to get you going.
Method Implementation Comments
The method comments that are created by Talend are more than simple comments. These comments control how your new method features in the Talend Designer. You will have seen the structure of these comments documented in the Class comments; but we'll now look at these in a little more depth.
First Comment Lines
The first comment line provides the text that will be shown in the in-line help. This is optional.
{talendTypes}
This value is used to tell the interpreter the Talend return type of the method.
{Category}
This value defines the Class' category. This is used within the Talend Designer, to navigate to the method.
{param}
This value defines the parameter types that are passed to the method. Again, this is for use with in the Talend Designer.
{example}
Used to show example usage, within the Talend Designer.
//$NON-NLS-1$
You may see comments similar to this, following String declarations. This is a directive to Eclipse to silence warnings if it encounters string literals (when it has been configured to complain).
User Interface (UI) messages should not be embedded as string literals; but rather sourced from a Java Resource Bundle (so that they can be translated, etc.). Consequently, Eclipse may be configured to detect string literals, preventing you from accidentally leaving non-externalised UI strings in your code.
formatNumber Method Implementation
Below, is the entire source code for our new routine. You may simply replace the code that has been auto-generated by Talend. Compare the difference between this code and our original code shown at the start of this tutorial.
package routines;
public class PhoneUtil {
/**
* Uses Google's Phone Number Handling Library to parse and format (GB) an
* input phone number. If the number cannot be parsed, "bad number" is returned.
*
* Numbers are returned in E164 format.
*
* {talendTypes} String
*
* {Category} PhoneUtil
*
* {param} string("phone number") input: The phone number to parse and format.
*
* {example} formatNumber("07768 555 555") # +44 7768 555555.
*/
public static String formatNumber(String phoneNumber) {
if (phoneNumber == null) {
return null;
}
else {
try {
com.google.i18n.phonenumbers.PhoneNumberUtil pNU = com.google.i18n.phonenumbers.PhoneNumberUtil.getInstance();
return pNU.format(pNU.parse(phoneNumber, "GB"), com.google.i18n.phonenumbers.PhoneNumberUtil.PhoneNumberFormat.E164);
}
catch (Exception e) {
return "bad number"; //$NON-NLS-1$
}
}
}
}
PhoneUtil.formatNumber in Action
The following screenshot shows PhoneUtil.formatNumber in action, within the Talend Designer. This screenshot shows the Expression Builder of a tMap Component. You can see Categories, Help and Hints in action.
Review
Although simple in its nature, this tutorial has shown you all of the features of a routine. Try taking our Talend tLibraryLoad Component Tutorial and then modifying it to use a routine instead of tLibraryLoad and tJavaRow components. You may also create your own simple Job to read phone numbers and use a tMap component to map them using your new routine.
comments powered by Disqus