Arnes Tech Stuff: Oracle Managed Files handson tutorial part 3: Custom Callouts

[Part 1] [Part 2] [Part 3] [Part 4]

The built-in functionality from MFT can be extended with custom code via Custom Callouts in Java.
Three things are necessary: the Java code itself, an xml file which describes what MFT should do with this code and a WST call to register that code to MFT.
The complete documentation can be found on OTN, this tutorial should demonstrate the creation and integration of Custom Callouts with a very simple example.
In this example, a Custom Callout will be developed, which replaces the file name with the actual system time.
For stepping through this tutorial, it should be known, how to create and compile a Java class and Part 1 of this tutorial should be completed.
Here is the Java code:

package com.oracle.callout.sample;

import java.io.IOException;
import java.io.InputStream;
import java.io.OutputStream;
import java.util.Map;
import java.util.Date;

import oracle.tip.mft.engine.processsor.plugin.PluginContext;
import oracle.tip.mft.engine.processsor.plugin.PluginOutput;
import oracle.tip.mft.engine.processsor.plugin.PreCalloutPlugin;


public class FilenameCallout implements PreCalloutPlugin {

 @Override
 public boolean isPayloadChangeRequired(PluginContext context,
   Map<String, String> calloutParams) {
  return false;
 }

 @Override
 public PluginOutput process(PluginContext context, InputStream input,
   OutputStream out, Map<String, String> calloutParams) {
  String type = calloutParams.get("Type");

  return null;
 }

 @Override
 public PluginOutput process(PluginContext context, InputStream input,
   Map<String, String> calloutParams) {

  PluginOutput pOutput = new PluginOutput();
  pOutput.setNewFileName("MFT " + new Date() );
  return pOutput;
 }
}

All imports, except java.util.Date are required by every Custom Callout.
The method isPayloadChangeRequired() gives MFT a hint, whether the payload will be changed or not - as the name implies. Depending on that, either of the following methods will be called. As in this example only the file name, but not the content, will be changed, isPayloadChangeRequired() returns false. The first process method is not needed and just returns null. Only the second process method will be called during runtime and does something. It changes the file name.

[oracle@oel6ab src]$ javac -classpath "/home/oracle/Oracle/Middleware/soa12103/mft/modules/oracle.mft_12.1.3.0/core-12.1.1.0.jar" com/oracle/callout/sample/FilenameCallout.java 
[oracle@oel6ab src]$ jar cf FilenameCallout.jar com/oracle/callout/sample/FilenameCallout.class 
[oracle@oel6ab src]$ ll
total 12
drwxr-xr-x. 3 oracle oinstall 4096 Feb  6 15:23 com
-rw-r--r--. 1 oracle oinstall 1187 Feb  9 16:42 FilenameCallout.jar

The class has to be compiles as shown above, the path names need to be adapted to your environment. As a result, we get a FilenameCallout.jar file and we are done with the Java part.
In the next step, an XML file will be created, so MFT knows what to do with this JAR file.

<?xml version="1.0" encoding="UTF-8"?>
<mft:Callouts xmlns:mft="http://xmlns.oracle.com/mft" 
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
 xsi:schemaLocation="http://xmlns.oracle.com/mft callout.xsd ">
 <mft:Callout description="Filename conversion"
  helpText="File name conversion"
  groupName="Source-pre,Target-pre,Target-post" 
  timeout="300" 
  implementationClass="com.oracle.callout.sample.FilenameCallout"
  libraryName="FilenameCallout.jar" 
  name="Filename conversion">
 </mft:Callout>
</mft:Callouts>

The XML file is very straight forward. Important is the name, which has to be unique in a MFT instance. The attributes libraryName and implementationClass are self explanatory (hopefully ;-).

Both files needed to be copied into the mft directory of the WLS domain. If the subfolder callouts doesn't already exist, it needs to be created manually. Then FilenameCallout.jar and FilenameCallout.xml have to be copied into the callouts-folder.

CLASSPATH=:/home/oracle/Oracle/Middleware/soa12103/mft/modules/oracle.mft_12.1.3.0/core-12.1.1.0.jar

Initializing WebLogic Scripting Tool (WLST) ...

Welcome to WebLogic Server Administration Scripting Shell

Type help() for help on available commands

wls:/offline> connect("weblogic","welcome1","t3://localhost:7003")
Connecting to t3://localhost:7003 with userid weblogic ...
Successfully connected to managed Server "mft_server1" that belongs to domain "soa_domain".

Warning: An insecure protocol was used to connect to the 
server. To ensure on-the-wire security, the SSL port or 
Admin port should be used instead.

wls:/soa_domain/serverConfig> crtCalls("/home/oracle/Oracle/Middleware/soa12103/user_projects/domains/soa_domain/mft/callouts/FilenameCallout.xml")
Callout Filename conversion created.

wls:/soa_domain/serverConfig> listCallouts() 
Callouts
-----------
[Name:Filename conversion, Library:FilenameCallout.jar, Impl Class:com.oracle.callout.sample.FilenameCallout, Description:Filename conversion, Group:Source-pre,Target-pre,Target-post]
wls:/soa_domain/serverConfig>

To inform MFT about the new callout, WLST will be used. For using the MFT specific commandos, the wlst.sh has to be started from the MFT directory under $MW_HOME/mft/common/bin. The first line of the output with the CLASSPATH shows, if the correct script has been used.
As always with WLST, first connect to the server. Then the callout will be registered by a crtCalls(...) call with the XML file as a parameter.
All registered callouts can be shown via listCallouts() and they can be deleted by deleteCallout(...).

Again, two directories for source and target are needed. This could be the ones from the first part of this tutorial, or just create new ones.

In the MFT Console, both directories are configured as source and target, as shown in part 1.
Then, a Transfer will be configured using both directories.

After clicking at <add pre-processing actions>, the new choice 'Filename conversion' can be added via the Add to List Button.

The result should look as shown above. Click on Save, then finish with Deploy.

After a short period of time, the successfull Transfer should be shown on the dashboard.

Also, the transferred file with the changed name should appear in the file system. That's it for the MFT Custom Callouts handson tutorial. The next part will explain the integration with the Oracle SOA Suite.

--> Next: Integration with SOA Suite

[Part 1] [Part 2] [Teil 3] [Part 4]

Thursday, 28 May 2015

Oracle Managed Files handson tutorial part 3: Custom Callouts