Using Integration Controls

File Control

A File control makes it easy to read, write, or append to a file in a file system. The topics in this section describe how to work with the File control. For information on how to add control instances to business processes, see Using Controls in Business Processes.

Topics Included in This Section

Overview: File Control

Provides an overview of the File control.

Creating a New File Control

Describes how to create a new File control using the Oracle Workshop for WebLogic graphical design interface.

Using a File Control

Describes how to use a File control in your business processes. Describes the default methods and the methods you can customize.

Using File Control for SFTP

Describes how to use SSH File Transfer Protocol (SFTP) with your File control.

Service Provider Interface

Provides an example of a File control in the context of a business process.

Overview: File Control

A File control makes it easy to read, write, or append to a file in a file system. The files can be one of the following types: XmlObject, RawData (binary), or String. When creating a File control, select the file type that matches the files present in the specified directory.

In addition, the File control supports file manipulation operations such as copy, rename, and delete. You can also retrieve a list of the files stored in the specified directory.

Creating a New File Control

A File control performs an operation on a file. Each File control is customized to perform certain operations.

This topic describes how to create a new File control and provides an example of the File control’s declaration in the java file.

For information on how to add control instances to business processes, see Using Controls in Business Processes.

Creating a New File Control

You can create a new File control and add it to your business process. To define a new File control:

In the Package Explorer pane, double-click the business process (Process.java file) to which you want to add the File control. The business process is displayed in the Design view.
Click on the Data Palette and from the drop-down list choose Integration Controls to display the list of controls used for integrating applications.

Note:

If the Data Palette view is not visible in Oracle Workshop for WebLogic, click Window > Show View > Data Palette from the menu bar.

Select File.

The Insert control: File dialog box appears.

Figure 6-1 Insert Control: File

Insert Control: File

In the Insert control: File dialog box enter the following details:

In the Field Name, type the variable name used to access the new File control instance from your business process. The name you enter must be a valid Java identifier.
In the Insertion point: from the drop-down list select the point where you want the field name to be inserted in the process file.
Decide whether you want to make this a control factory and select or clear the Make this a control factory that can create multiple instances at runtime check box.
Click Next.

The Create Control dialog-box appears.

In the Create Control dialog box enter the following details:

In the Name field, type the name of your new control extension file.
Decide whether you want to add comments as configured in the properties of the current project and select or clear the Generate comments check box.
Click Next.

The Insert control -File dialog-box appears.

In the Insert control -File dialog-box enter the following.

In the Directory Name field, enter the name of the directory where the File control looks for files. Alternatively, you can click the Browse button to locate a directory on your hard disk.

A directory name is the absolute path name for the directory; it includes the drive specification as well as the path specification. For example, the following are valid directory names:

C:\directory (Windows)

/directory (Unix)

\\servername\sharename\directory (Win32 UNC)

You can also enter a period (.), which specifies the current working directory. When you enter a forward slash (/) in the Directory Name field, it is interpreted as follows:

UNIX systems—the root directory
Windows systems—the root of the user directory (for example, C: if the user directory is C:\bea).

The Directory Name field is required. Leaving the Directory Name field empty results in an error.

Note:

When writing files locally, if the specified directory does not already exist, it is created and the file is written into the new directory.

In the File name filter field, enter the file name filter, either a file name or file mask. Use file names for read, write and append operations. If the file name field contains a wild-card character, such as an asterisk (*), it is treated as a file mask. A wild-card character is specified to get the list of files in a directory. Wild-card characters are not valid for any other operation.

The File name filter field is optional when inserting a control, but this property must then be set dynamically before performing a file operation.

Select the type of data contained in the file using the Type of Data menu. The file type indicates the type of files present in the directory specified in the Directory Name field. Based on this type, appropriate methods (such as write(String data) or write(XmlObject data) or write(RawData data)) are generated for the File control. For example, if the directory contains XML documents, the type should be set to XmlObject so that read/write methods generated for the control will accept XmlObject variables. The same is true for RawData and String types.
If you are operating on a file of type String or XmlObject, you can optionally specify the character set encoding by entering the character set code in the Encoding field. This option can not be used with the large files option.
If the specified directory contains files you want to read one line at a time, select the button labeled The directory contains large files to be processed. The resulting readLine() method is created with support for large files.

You can define a line by specifying either its record size or a delimiter string:

If you enter a record size in the Record Size field, the file is read that number of bytes at a time.
If you are operating on a file of type String and you enter characters in the Delimiter string field, the file is read by record with each record defined as being terminated by that delimiter. Click Read file content including delimiter string to include the delimiter in the record.

WARNING:

If the specified delimiter string does not exist in a file being processed, application behavior is unpredictable.

If no record size or string delimiter is specified, the file is processed one line at a time. A line is considered to be terminated by any one of a line feed ('\n'), a carriage return ('\r'), or a carriage return followed immediately by a linefeed. This style of file processing can be used with any size file.

Note:

You cannot define a line by specifying both a record size and a string delimiter.

Click Finish.

File Control Methods

To learn about the methods available on the File control, see the Interface FileControl.

Example: File Control Declaration

When you create a new File control, its declaration appears in the java file. The following code snippet is an example of the File Control declaration:

package requestquote;

import com.bea.control.FileControl;

import org.apache.beehive.controls.api.bean.ControlExtension;

import com.bea.wli.control.dynamicProperties.FileControlPropertiesDocument;

/*

 * A custom File control.

*/

@ControlExtension

@FileControl.FileInfo(directoryName = "C:/bea/")

public interface FileCntrl extends com.bea.control.FileControl {

	@FileControl.IOOperation(ioType = FileIOType.READLINE, delimiterString = "")

	String readline();

	static final long serialVersionUID = 1L;

	public FileCntrl create();

The actual attributes that are present on the @FileControl.FileInfo and com.bea.control.FileControl.IOOperation annotations depend on the values you entered in the Insert Control dialog.

The @FileControlannotation controls the behavior of the File control. All of the attributes of the @FileControl annotation are optional and have default values.

To learn more, see FileControl Annotation.

The File control, named TaxControlFile in the example above, is declared as an extension of FileControl. The com.bea.control.FileControl.IOOperation annotations indicate that the file operation is readline (read tax_file.txt record by record) and specifies the record size.

Using a File Control

A File control performs operations on a file such as reading a file, writing a file, and appending data to a file. You can also use the File control to copy, rename, and delete files.

You usually configure a separate File control for each file you want to manipulate. You can specify settings for a File control in several different ways. One way is to set the File control’s properties in Design view. Another way is to call the setProperties method of the FileControl interface. You can change File control configuration properties dynamically. To get the current property settings, use the getProperties() method.

The following sections describe how to configure the File control.

Setting Default File Control Behavior

You can specify the behavior of a File control in Design View by setting the control’s properties in the Properties pane. These properties correspond to attributes of the @FileControl and @FileControl.Operation annotations, which identify the File control in your code. The following attributes specify class- and method-level configuration attributes for the File control.

Annotation

Attribute

Description

@FileControl.FileInfo

createMode

Specifies whether a file is overwritten or renamed when a new file of the same name is created.

Note: When you use create-mode="rename=old" to rename a file, make sure that you mention the suffix-name and the suffix-type attributes for the new file name. If the suffix attributes are not indicated, then the File control overwrites the old file, instead of renaming it.

directory-name

The absolute path name for the directory. (When writing files locally, if the specified directory does not already exist, it is created and the file is written into the new directory.)

file-mask

Either a file name or a file mask.

suffix-name

Suffix to be used with a timestamp or incrementing index for creating file names.

suffix-type

Specifies whether a timestamp or an incrementing index should be used as a suffix for file names.

FileControl.FTP

hostName

Name of the FTP host, for example, ftp://ftp.bea.com.

localDirectory

Directory used for transferring files between the remote file system and the local file system. When reading a remote file, the file is copied from the remote system to the local directory and then read. Similarly, when writing to a remote file system, the file is written to the local directory and then copied to the remote system.

Note: This is a temporary working directory for the File control. It should not be treated as a user-archive directory. The contents of ftp-local-directory are deleted after the FTP operation is performed.

password

FTP user’s password. If you specify this attribute, you cannot specify the ftp-password-alias attribute.

passwordAlias

Alias for a user’s password. The alias is used to look up a password in a password store. If you specify this attribute, you cannot specify the ftp-password attribute.

userName

Name of the FTP user.

@FileControl.IOOperation

encoding

Character set encoding of the file.

fileContent

Contents of the identified variable which will be written to the file.

ioType

Type of file operation (read, readline, write, or append).

recordSize

Size of an individual record (in bytes) within a file to be processed record by record.

For information on FileControl.SFtp annotation, see File Control Annotations for SFTP.

When you use the binary files for transferring using FtpToLocal() of file control, place the annotation listed below in your Source view.

@Retention(RetentionPolicy.RUNTIME)

    @Target({ElementType.TYPE, ElementType.METHOD})

    @PropertySet(

            prefix = 'FileTransferMode',

            externalConfig = false,

            optional = true,

            hasSetters = false

    public @interface FileTransferMode

/**

         * This option specifes SFTP properties as a list of name/value pairs

*/

        @FeatureInfo(shortDescription = 'File Transfer Mode when using

SFTP/FTP')

        TransferMode value() default TransferMode.BINARY;

Note:

If you dont use the above annotation, the binary files will get corrupted. The above procedure should also be followed while using SFTP.

To learn more about specifying default File control behavior with attributes of the @FileControl annotation, see FileControl Annotation.

Using Methods of the FileControl Interface

Once you have declared and configured a File control, you can invoke its methods from within your application to perform file operations and to change its configuration. For complete information on each method, see the Interface FileControl.

Use the following methods of the FileControl interface to perform file operations and reconfigure the File control.

Table 6-2 Methods
Method	Description
setProperties	Sets the properties for the control
getProperties	Gets the properties for the control
getFiles	Returns the `FileControlFileListDocument` XML Beans document defined in `DynamicProperties.xsd`
rename	Renames the current file
delete	Deletes the current file
copy	Copies the current file to a different location
reset	Reset the control by closing any operations in progress, such as `readLine`, `readRecord` and `append`.

The File control does not provide callbacks to wait for a file to appear. If the business process needs to wait for a file to appear, use the File Event Generator functionality. The business process can use the Message Broker Subscribe control to subscribe to a channel if it is interested in processing the files in a given directory. A File Event Generator is then configured so that when a file appears in that directory, it publishes a message to the associated channel containing the contents of the file.

Error Handling When Reading Files

The File control invokes an error handler when exceptions are encountered in read() methods. (Exceptions can occur when the contents of the file are invalid.) The error handler moves the file to an error directory. However, if the error directory is not configured, the error handler throws the following exception: File or Directory does not exist. To ensure that useful information about the exception is available, the exception thrown by the error handler is logged and appears on the Oracle WebLogic Server Console and the original exception is rethrown.

Using File Control for SFTP

SSH File Transfer Protocol (SFTP) is a communication protocol that provides secure and reliable file transfer capabilities. It is generally used with the SSH-2 protocol.

File control provides support to read, write, and append to a file on the file system or the FTP server. It supports copying, renaming, and deleting files on the file system and FTP server. In addition, you can manipulate files on the SFTP server using file control.

SFTP includes a Service Provider Interface (SPI), which allows third-party client implementations of SFTP to plug in to the file event generator and the file control. The default SPI implementation that is provided with WLI uses the SFTP Client API (J2SSH) from SSHTools. It supports both RSA and DSA key pairs.

The Default SFTP SPI implementation using J2SSH supports the following authentication methods:

Password Authentication – In this method, users are authenticated based on the credentials (username/password pair) provided by them. The username/password pair is sent over an encrypted connection to the server, and the credentials are validated.
Host-based Authentication – In this method, users are authenticated based on the common private host key. You must configure the SFTP server with all the managed servers and their public keys within the cluster as the request for connection or authentication can originate from any of the managed servers.
Public Key Authentication – In this method, users are authenticated based on their private key. In a clustered environment, the private key that is configured to connect to the SFTP server must be accessible from all the managed servers in the cluster.

Note:

SPI can be extended to support any other authentication method.

Configuring File Control for SFTP

To configure file control for SFTP, complete the following steps:

Create a file Control, as described in Creating a New File Control.
Right-click the file control, and select Edit.
Add @FileControl.SFtp to the code in the Source view, and add the annotations, as required (see Figure 6-2).

Figure 6-2 Adding SFTP to File Control

Adding SFTP to File Control

File Control Annotations for SFTP

File control supports the following annotations:

SFtpCustomProperty- You can use this annotation to specify any additional properties for authentication and to define a name/value pair. The annotation looks like the following:

@Retention(RetentionPolicy.RUNTIME)

@Target({ElementType.TYPE, ElementType.FIELD})

@PropertySet(

        prefix = "SFtpCustomProperty",

        externalConfig = false,

        optional = true,

        hasSetters = false

public @interface SFtpCustomProperty

        @FeatureInfo(shortDescription = "SFTP property name")

        @AnnotationMemberTypes.Text

        String name() default Constants.ANNOTATION_VAL_NOT_SPECIFIED;

        @FeatureInfo(shortDescription = "SFTP property value")

        @AnnotationMemberTypes.Text

        String value() default Constants.ANNOTATION_VAL_NOT_SPECIFIED;

The annotation attributes are as follows:

name: The name of the property used for connecting or authenticating with the SFTP server.
value: The value for the property used for connecting or authenticating with the SFTP server.

Note: This annotation must be used only when the @SFtp annotation is used.

SFtp- You can use this annotation to specify the properties of the SFTP server so that file control can interact with the SFTP server using the properties in this annotation. This annotation specifies the authentication method used to connect to the SFTP server, and the local directory in which files downloaded from the SFTP server are copied. The annotation looks like the following:

@Retention(RetentionPolicy.RUNTIME)

@Target({ElementType.TYPE, ElementType.FIELD})

@PropertySet(

            prefix = "SFtp",

            externalConfig = false,

            optional = true,

            hasSetters = false

public @interface SFtp {

        @FeatureInfo(shortDescription="specifies the name of the SFTP host, for example, sftp://sftp.bea.com")

        @AnnotationMemberTypes.Text

        String hostName() ;

        @FeatureInfo(shortDescription = "specifies the SFTP server port number")

        @AnnotationMemberTypes.Int

        int port() default 22;

        @FeatureInfo(shortDescription = "specifies the authentication method to use for authenticating to SFTP server")

        SFtpAuthMethod authMethod() default SFtpAuthMethod.PASSWORD_BASED_AUTHENTICATION;

        @FeatureInfo(shortDescription="specifies the login name of the SFTP user")

        @AnnotationMemberTypes.Text

        String userName()default Constants.ANNOTATION_VAL_NOT_SPECIFIED;

        @FeatureInfo(shortDescription="the SFTP user's password in case of PASSWORD_BASED_AUTHENTICATION")

        @AnnotationMemberTypes.Text

        String password() default Constants.ANNOTATION_VAL_NOT_SPECIFIED;

        @FeatureInfo(shortDescription="alias for a user's password")

        @AnnotationMemberTypes.Optional

        @AnnotationMemberTypes.Text

        String passwordAlias()default Constants.ANNOTATION_VAL_NOT_SPECIFIED;

        @FeatureInfo(shortDescription = "path to the user/host private key file")

        @AnnotationMemberTypes.Text

        String privateKey() default Constants.ANNOTATION_VAL_NOT_SPECIFIED;

        @FeatureInfo(shortDescription = "Passphrase for the private key")

        @AnnotationMemberTypes.Text

        String passphrase() default Constants.ANNOTATION_VAL_NOT_SPECIFIED;

        @FeatureInfo(shortDescription = "alias for the private key's passphrase")

        @AnnotationMemberTypes.Text

        String passphraseAlias() default Constants.ANNOTATION_VAL_NOT_SPECIFIED;

        @FeatureInfo(shortDescription = "additional SFTP properties as a list of name/value pairs")

        @AnnotationMemberTypes.Optional

        SFtpCustomProperties customProperties()default @SFtpCustomProperties({});

        @FeatureInfo(shortDescription="local directory when transferring files between remote file system and the local directory")

        @AnnotationMemberTypes.Text

        String localDirectory() ;

The following annotation attributes appear in the Properties pane of Oracle Oracle Workshop for WebLogic(see Figure 6-3):

Figure 6-3 Properties Pane

Table 6-3 SFTP Configuration
Annotation	Attribute	Description
`FileControl.SFtp`	`authMethod`	Specifies the authentication method for connecting to the SFTP server. The supported authentication methods are password based, host based, public key based and other. The default authentication method is password based.
	`customProperties`	Represents any additional properties required for authenticating with the SFTP server. You can specify these as a list of name/value pairs by using the annotation `@SFtpCustomProperties`. This attribute enables you to use any other authentication method that is not provided in WLI, if `authMethod` is set to `OTHER_AUTHENTICATION_METHOD`. If necessary, you can specify additional properties when `authMethod` is set to either `HOST_BASED_AUTHENTICATION` or `PUBLIC_KEY_BASED_AUTHENTICATION`.
	`hostName`	The name or IP address of the SFTP server that the file event generator or control communicates with.
	localDirectory	The path to the directory on the local file system in which files downloaded from the SFTP server are copied.
	passphrase	The pass-phrase for the private key if the key is protected with a pass-phrase. If this attribute is specified, then `passphraseAlias` must not be specified. The attribute is required only when `authMethod` is set to either `HOST_BASED_AUTHENTICATION` or `PUBLIC_KEY_BASED_AUTHENTICATION`.
	passphraseAlias	The password alias for the pass-phrase if the private key is protected with a pass-phrase. If this attribute is specified, then the `passphrase` attribute must not be specified. The attribute is required only when the `authMethod` is set to either `HOST_BASED_AUTHENTICATION` or `PUBLIC_KEY_BASED_AUTHENTICATION.`
	password	The password used for authenticating with the SFTP server. If this attribute is specified, then `passwordAlias` must not be specified. It is required only when `authMethod` is set to `PASSWORD_BASED_AUTHENTICATION`.
	passwordAlias	The password alias for authenticating with the SFTP server. If this attribute is specified, the password must not be specified. It is required only when `authMethod` is set to `PASSWORD_BASED_AUTHENTICATION`.
	port	The port number on which the SFTP daemon is running. The default port number is 22.
	privateKey	The path to the private key file for authenticating with the SFTP server. If the `authMethod` attribute is set to `HOST_BASED_AUTHENTICATION`, then this attribute represents the host’s private key. If `authMethod` is set to `PUBLIC_KEY_BASED_AUTHENTICATION`, then this attribute represents the private key of the users. The attribute is required only when the `authMethod` is set to either `HOST_BASED_AUTHENTICATION` or `PUBLIC_KEY_BASED_AUTHENTICATION`.
	userName	The user name used for authenticating with the SFTP server. This attribute is required in all the authentication methods that are supported in WLI.

Service Provider Interface

WLI provides a framework for SFTP, and you can plug in your own libraries. To install SSHTools, do the following:

Download J2SSH 0.2.9, from the following location: http://sourceforge.net/projects/sshtools to your local directory.
Copy the j2ssh-core-0.2.9.jar and j2ssh-common-0.2.9.jar to the following directory: BEA_HOME\wli_10.3\lib directory.

Note:

In this pathname, BEA_HOME represents the directory in which you installed Oracle WebLogic Integration.

SPI includes the following enumeration types:

SFtpVersion

This enumeration represents the SSH version and defines the following constants:

SSH_VERSION_1: SSH Version 1
SSH_VERSION_2: SSH Version 2
SSH_VERSION_OTHER: Any other version of SSH

SFtpAuthMethod

This enumeration represents the authentication method to be used with the SFTP server. It defines the following constants:

PASSWORD_BASED_AUTHENTICATION: This constant defines the password-based authentication. The user must provide the username/password pair to use this authentication method.
HOST_BASED_AUTHENTICATION: This constant defines the host-based authentication. The user must provide the private key of the client computer, that is trying to connect to the SFTP server.
PUBLIC_KEY_BASED_AUTHENTICATION: This constant defines the public key based authentication. The user must provide the private key of the user who is trying to connect to the SFTP server.
OTHER_AUTHENTICATION_METHOD: This constant defines any other authentication method, which is not supported by WLI.

SFtpClientException

This class represents the SFTP client exception, a generic exception category that must be thrown from the SPI implementation. When implementing SPI, you can throw any exception by wrapping it SFtpClientException and throwing it to the upper level. The interface of this exception is as follows:

public SFtpClientException(): Default constructor
public SFtpClientException(String message): Constructs the SFTP client exception with the specified detail message
public SFtpClientException(String message, Throwable cause): Constructs the SFTP client exception with the specified detail message and the original exception
public SFtpClientException(Throwable cause): Constructs the SFTP client exception given the original exception

SFtpFile

This enumeration represents the attributes of the file on the SFTP server. Table 6-4, lists the interfaces in this enumeration.

Table 6-4 SFtp File Interface
Interface	Description
`public SFtpFile()`	Default constructor.
`public SFtpFile(String absolutePath)`	Constructs the `SFtpFile` object based on the path of the file. If the absolute path contains the file name, the file name is retrieved.
`public void setAbsolutePath(String absolutePath)`	Sets the absolute path for the file represented by this `SFtpFile` object. This method retrieves the file name from the given absolute path if the file name is present.
`public String getAbsolutePath()`	Returns the absolute path of the file represented by this object.
`public String getFilename()`	Returns the name of the file represented by this object.
`public void setFileName(String filename)`	Sets the name of the file represented by this object.
`public void setParent(String parent)`	Sets the directory in which the file resides on the remote server.
`public String getParent()`	Returns the directory in which the file resides on the remote server.
`public void setSize(long size)`	Sets the size of the file represented by this object.
`public long size()`	Returns the size of the file represented by this object.
`public void setModifiedTime(long time)`	Sets the modified time of the file represented by this object.
`public long getModifiedTime()`	Returns the modified time of the file represented by this object.
`public void setFile(boolean isFile)`	Sets a flag to determine whether the file is a disk file.
`public boolean isFile()`	Returns a value to indicate whether the file is a disk file.
`public boolean isDirectory()`	Returns a value to indicate whether the file represented by this object is a directory.
`public void setDirectory(boolean isDirectory)`	Sets a flag to determine whether the file is a directory.
`public boolean canRead()`	Returns a value to indicate whether the file represented by this object can be read.
`public void setRead(boolean canRead)`	Sets a flag to determine whether the file represented by this object can be read.
`public boolean canWrite()`	Returns a value to indicate whether the file represented by this object can be written.
`public void setWrite(boolean canWrite)`	Sets a flag to determine whether the file represented by this object can be written.
`public boolean isLink()`	Returns a value to indicate whether the file represented by this object is a link.
`public void setLink(boolean isLink)`	Sets a flag to determine whether the file represented by this object is a link.
`public boolean isSocket()`	Returns a value to indicate whether the file represented by this object is a socket.
`public void setSocket(boolean isSocket)`	Sets a flag to determine whether the file represented by this object is a socket.
`public boolean isOpen()`	Returns a value to indicate whether the file represented by this object is opened.
`public void setOpen(boolean isOpen)`	Sets a flag to determine whether the file represented by this object is opened.
`public void setStageFilepath(String filepath)`	Sets the path whether the file is staged: that is, the path where the file is copied to the local file system.
`public String getStageFilepath()`	Returns the staging path for the file. This path is the location where the file is copied locally.
`public boolean equals(Object object)`	Checks whether two SFTP files are equal.

SFtpClient

This enumeration represents the SFTP client interface that users must implement to plug in any third-party SFTP client implementation to file event generator and file control. This interface provides methods for connecting and authenticating with the SFTP server, retrieving files, listing files, renaming or deleting files, and transferring files to the SFTP server. The interface is described in Table 6-5:

Table 6-5 SFtp Client Interface
Interface	Description
`public void setAuthenticationMethod(SFtpAuthMethod authMethod)`	Sets the authentication method the client uses to connect to the SFTP server. For the list of authentication methods supported by the SPI, see SFtpAuthMethod.
`public SFtpAuthMethod getAuthenticationMethod()`	Returns the authentication method used by the client to connect to the SFTP server.
`public void setSshVersion(SFtpVersion sshVersion)`	Sets the SSH version that client uses to connect to the SFTP server. See SFtpVersion, for the list of SSH versions supported by the SPI.
`public SFtpVersion getSshVersion()`	Returns the SSH version the client uses to connect to the SFTP server.
`public void setAcceptUnknownHostKeys(boolean accept)`	Sets whether public keys from unknown SFTP servers are accepted. You can use this method to override the default behavior of accepting the public keys from unknown SFTP servers and updating known host files.
`public boolean acceptUnknownHostKeys()`	Accepts public keys from unknown SFTP servers and to update the known host’s file.
`public void connect() throws SFtpClientException`	Connects to the SFTP server, based on the authentication method configured. If any exception is thrown by the actual SFTP client API (for example J2SSH), that exception is wrapped in `SFtpClientException` and thrown to the caller.
`public void setUserName(String userName)`	Sets the username for authenticating with the SFTP server. The username is required for `PASSWORD_BASED_AUTHENTICATION`, and it is also required for `HOST_BASED_AUTHENTICATION` and `PUBLIC_KEY_BASED_AUTHENTICATION.`
`public String getUserName()`	Returns the user name the client uses for authenticating with the SFTP server.
`public String getHostname()`	Returns the host name of the SFTP server to which the client is trying to connect.
`public int getPort()`	Returns the port number on which the SFTP daemon is running.
`public void setPassword(char[] pwd)`	Sets the password used for authentication when the authentication method is set to `PASSWORD_BASED_AUTHENTICATION`.
`public void setPassPhrase(char[] phrase)`	Sets the pass phrase for the private key file if the private key is protected by a password. This method is used only when the authentication method is either `HOST_BASED_AUTHENTICATION` or `PUBLIC_KEY_BASED_AUTHENTICATION`.
`public void setPrivateKeyFile(String path)`	Sets the path of the private key file used for authentication when the authentication method is either `HOST_BASED_AUTHENTICATION` or `PUBLIC_KEY_BASED_AUTHENTICATION`.
`public void setCustomProperties(HashMap<String, Object> props)`	Sets any additional properties that users may specify when authenticating with the SFTP server. It provides a way to extend the SPI if the third-party SFTP client requires any additional properties.
`public HashMap<String, Object> getCustomProperties()`	Returns the additional properties that users may use when authenticating with the SFTP server.
`public String pwd() throws SFtpClientException`	Returns the absolute path name of the current remote working directory. If any exception is thrown, the exception must be wrapped in `SFtpClientException`, and the exception is thrown back to the caller.
`public void cd(String dir) throws SFtpClientException`	Changes the working directory on the SFTP server. If any exception is thrown, the exception must be wrapped in `SFtpClientException`, and the exception is thrown back to the caller.
`public void mkdir(String dir) throws SFtpClientException`	Creates a directory on the SFTP server. If the directory already exists, this method fails and an exception is thrown. The path can be either absolute or relative to the current working directory. If any exception is thrown, the exception must be wrapped in `SFtpClientException`, and the exception is thrown back to the caller.
`public void mkdirs(String dir) throws SFtpClientException`	Creates a directory or a set of directories recursively. For example, consider a scenario where the path to the directory is `/tmp/test/test1/test2`. If the `tmp` directory already exist, then this method creates the directories `test`, `test1`, and `test2`. This method does not fail even if a directory already exists. The path can be either absolute or relative to the current working directory. If any exception is thrown, the exception must be wrapped in `SFtpClientException`, and the exception is thrown back to the caller.
`public void rm(String path) throws SFtpClientException`	Removes a file on the SFTP server. The path can be either absolute or relative to the current working directory. If any exception is thrown, the exception must be wrapped in `SFtpClientException`, and the exception is thrown back to the caller.
`public void rmdir(String path) throws SFtpClientException`	Removes a directory on the SFTP server. The path to the directory to be removed can be absolute or relative to the current working directory. If any exception is thrown, the exception must be wrapped in `SFtpClientException`, and the exception is thrown back to the caller.
`public void rename(String oldPath, String newPath) throws SFtpClientException`	Renames a file on the SFTP server. The path can be either absolute or relative to the current working directory. If any exception is thrown, the exception must be wrapped in `SFtpClientException`, and the exception is thrown back to the caller.
`public List<SFtpFile> list(String path) throws SFtpClientException`	Returns the list of files available on the SFTP server in the directory at the specified path. If the path given represents a file, then this method returns the details about that file. The user is expected to populate the `SFtpFile` objects and return a list of `SFtpFile` objects. The path to the directory/file to be listed can be absolute or relative to the current working directory. If any exception is thrown, the user must wrap that exception in `SFtpClientException`, and throw the exception back to the caller.
`public List<SFtpFile> list() throws SFtpClientException`	Returns the list of files available in the current working directory on the SFTP server. The user must populate the `SFtpFile` objects and return a list of `SFtpFile` objects. If any exception is thrown, the exception must be wrapped in `SFtpClientException`, and the exception is thrown back to the caller.
`public abstract InputStream get(String s, SFtpFileTransferMode sftpfiletransfermode)` `throws SFtpClientException;`	Retrieves the file on the SFTP server as a stream. The path can be either absolute or relative to the current working directory. If any exception is thrown, the exception must be wrapped in `SFtpClientException`, and the exception is thrown back to the caller.
`public abstract void get(String s, String s1, SFtpFileTransferMode sftpfiletransfermode)` `throws SFtpClientException;`	Retrieves the file on the SFTP server and copy it to the local system on the local file system. The path can be either absolute or relative to the current working directory. If any exception is thrown, the exception must be wrapped in `SFtpClientException`, and the exception is thrown back to the caller.
`public abstract void get(String s, OutputStream outputstream, SFtpFileTransferMode sftpfiletransfermode)` `throws SFtpClientException;`	Retrieves a file on the SFTP server and copies the contents of the file to an output stream. The path can be either absolute or relative to the current working directory. If any exception is thrown, the exception must be wrapped in `SFtpClientException`, and the exception is thrown back to the caller.
`public abstract void put(String s, String s1, SFtpFileTransferMode sftpfiletransfermode)` `throws SFtpClientException;`	Copies a file on the local file system to the remote SFTP server. The path to the file on the SFTP server be a file or a directory. The path can be either absolute or relative to the current working directory. If any exception is thrown, the exception must be wrapped in `SFtpClientException`, and the exception is thrown back to the caller.
`public abstract void put(InputStream inputstream, String s, SFtpFileTransferMode sftpfiletransfermode)` `throws SFtpClientException;`	Copies the file contents from a stream on the remote SFTP server on the SFTP server. The path to the file on the SFTP server can be a file or a directory. The path can be either absolute or relative to the current working directory. If any exception is thrown, the exception must be wrapped in `SFtpClientException`, and the exception is thrown back to the caller.
`public void disconnect() throws SFtpClientException`	Disconnects from the SFTP server and to clean up any resources held by this client. If any exception is thrown, the exception must be wrapped in `SFtpClientException`, and the exception is thrown back to the caller.

In addition to implementing the above methods, the user must define the following constructors in their implementation of SFtpClient:

public XXXSFtpClient (String hostname): Constructs the SFTP client object, when the host name with a default port number of 22 is provided.
Public XXXSFtpClient(String hostname, int portnumber): Constructs the SFTP client object, after the host name and port number are provided.

AbstractSFtpClient

This class implements the SFtpClient interface and provides a default implementation for all the methods in the SFtpClient interface. Although many of these implemented methods do not require any modifications, this class allows you to set properties, such as user name, password, private key, pass-phrase, authentication method, and custom properties.

SFtpClientFactory

This class represents the factory class for SFtpClient. You can create instances of SFtpClient by using this class. You must implement this class for adding any third-party SFTP client implementation to file event generator and file control by using the WLI console. For more information, see “Configuring SPI”. If the implementation class is not configured, then the default implementation of the SFtpClientFactory is used. The default implementation is provided by com.bea.wli.sftp.j2ssh.impl.J2SSHSFtpClientFactory and relies on the SFTP client implementation (J2SSH) from SSHTools.

public static SFtpClientFactory newInstance(String factoryName) throws SFtpClientException: This static method is used to create a new instance of SFtpClientFactory. The new instance is created based on the SFTP client factory class name that is configured through the Oracle WebLogic Integration administration console. If this property is not configured, then the default implementation of the SFTP client factory com.bea.wli.sftp.j2ssh.impl.J2SSHSFtpClientFactory is returned.
public abstract SFtpClient createSFtpClient(String hostName): This method is used to create an instance of the SFtpClient given the host name and the default port number of 22.
public abstract SFtpClient createSFtpClient(String hostName, int portNumber): This method is used to create a new instance of the SFtpClient, when the host name and port number are provided.

Configuring SPI

To plug in third-party SFTP client implementation using SPI, complete the following steps:

Open a web browser, such as Internet Explorer, and enter following URL in the address bar of the browser: http://adminserver:port/wliconsole.

Note: Here adminserver is the host name or IP address of the Oracle WebLogic Integration Administrative server, and port is the server’s listening port. For example, you can type the following to open the Oracle WebLogic Integration administration console: http://localhost:7001/wliconsole.

Enter the username and password in the Console window.

The Oracle WebLogic Integration Administration Console home page is displayed.

Note:

The Oracle WebLogic Integration administration console is password protected. You must create a WLI domain using the Configuration Wizard before you start the server. For more information about creating a domain using Configuration Wizard, see Domain Configuration Wizard Guide.

Click System Configuration on the left pane.
Click Configure on the left pane under SFTP.

The Current SFTP Settings page is displayed.

Click Configure, on the Current SFTP Settings page.
Enter the following properties:

SFTP Client Factory: Specify the class name that represents the third-party implementation of the SFTP client factory. If this property is not specified, then the default implementation is used.
Accept Server Keys: Set whether the public key sent by an unknown SFTP server during handshake is accepted. By default, the implementation accepts the keys from the unknown SFTP server, updates the known hosts file with this entry, and connects to that SFTP server. If this behavior is turned off, then connection to any SFTP server is established only if there is an entry for that server in the known hosts file.

Adding the SPI Implementation to the Server Class Path

To add the SPI implementation to the server class path, complete the following steps:

Edit the setDomainEnv.cmd\sh file located in \BEA_Home\DOMAIN_HOME\bin.
Add the jar file containing the SPI implementation to POST_CLASSPATH.

SFTP Reference Implementation

An SFTP reference implementation is available with WLI, which is available in the \BEA_Home\wli_10.3\samples\sftp_ref_impl directory, and a default build script is provided for building the source file. This reference implementation is based on the J2SSH (from SSH Tools).

Build an SFTP Reference Implementation

To build an SFTP reference implementation, complete the following steps:

Run the commEnv.cmd script, which is located in the \BEA_Home\wlserver_10.3\commom\bin directory.
Change the directory path to \BEA_Home\wli_10.3\samples\sftp_ref_impl.
Run ant clean to delete the generated artifacts.
To build the jar file, run ant deploy. The jar file is created in \BEA_Home\wli_10.3\samples\sftp_ref_impl\build\ar.
To re-deploy the jar file, run ant redeploy.
Plug in the reference implementation, as described in Configuring SPI and Adding the SPI Implementation to the Server Class Path.

Designing an Application to Test the Implementation

Here is an example of how you can design an application to test the SFTP implementation.

Create a business process (process.java) with file control.
Add @FileControl.SFtp to the file control in the Source view.
Build and deploy the application.

For information about business process, refer Guide to Building Business Process and Tutorial Building your First Business Process.

Example: File Control

This section provides an example of a File control used in the context of a business process. In this case, the File control instance writes a file to a specified location, triggered by a user request. This example assumes that you have created a new business process containing a client request node.

The business process is shown in the following figure:

Figure 6-4 Example File Control

The business process starts with a client request node, File Request, representing a point in the process at which a client sends a request to a process. In this case, the client invokes the fileRequest() method on the process to write a file with information on a new customer to the file system.

Complete the following tasks to design your business process to write the requested file to your file system:

To Create an Instance of a File Control in Your Project

In this scenario, you add one instance of the File control to your business process.

Click on the Data Palette and from the drop-down list choose Integration Controls to display the list of controls used for integrating applications.
Choose File.

The Insert Control: File dialog box is displayed.

In the Insert Control: File dialog box do the following:, enter myFile as the Field Name for this control and click Next.
Enter MyFile in the Name field, and click Next.
In the Create Control, enter the following:

Directory Name—Enter the location in which you want the File control to write the file. You can use any location on your file system. In this case, the directory name is C:/temp/customers.
Type of Data—Select XmlObject from the drop-down list.

Click Finish.

An instance of a File control, named myFile, is created in your project and displayed in the Data Palette.

Select File > Save to save your work.

To Design a Control Send Node in Your Business Process to Interact With Your File Control

Expand the myFile control instance in the Data Palette. Then click the following method:

FileControlPropertiesDocument write(XmlObject someData)

Drag the method from the Data Palette and drop it on your FileWrite business process in the Design view, placing it immediately after the File Request node. The node is named write by default.
Rename the node, replacing write with Write CustFile.
Double-click the Write CustFile node. Its node builder opens on the General Settings tab.
Confirm that myFile is displayed in the Control field and that the following method is selected in the Method field:

FileControlPropertiesDocument write(com.bea.xml.XmlObject someData)

Click Send Data to open the second tab in the node builder. The Method Expects field is populated with the data type expected by the write() method: XmlObject someData.
In the Select variables to assign field, click the arrow to display the list of variables in your project. Then choose requestCustFile(InputDocument). If the variable does not already exist, you can choose Create new variable... to create it now.
Click Close.
Double click on the client request node (File Request) to open the node builder.
Click Receive Data to open the second tab on the node builder. The Method Expects field is populated with the data type expected, in this case InputDocument CustFile. In the Select variables to assign field, click the arrow to display the list of variables in your project. Then choose requestCustFile(InputDocument).
Click Close.

This step completes the design of your File control node.

At run time, pass a variable of type XmlObject to the Client Request method. The customer document is written to your file system in the location specified.