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.
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.
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.
You can create a new File control and add it to your business process. To define a new File control:
Note: | If the Data Palette view is not visible in Oracle Workshop for WebLogic, click Window > Show View > Data Palette from the menu bar. |
The Insert control: File dialog box appears.
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:
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. |
*
), 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.
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.readLine()
method is created with support for large files.You can define a line by specifying either its record size or a delimiter string:
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. |
To learn about the methods available on the File control, see the Interface FileControl.
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 @FileControl
annotation 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.
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.
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.
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.
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.
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.
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.
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:
Note: | SPI can be extended to support any other authentication method. |
To configure file control for SFTP, complete the following steps:
@FileControl.SFtp
to the code in the Source view, and add the annotations, as required (see Figure 6-2).File control supports the following annotations:
@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:
@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):
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 .
|
||
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.
|
||
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 .
|
||
WLI provides a framework for SFTP, and you can plug in your own libraries. To install SSHTools, do the following:
J2SSH 0.2.9
, from the following location:
http://sourceforge.net/projects/sshtools to your local directory. 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:
This enumeration represents the SSH version and defines the following constants:
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.
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 constructorpublic SFtpClientException(String message)
: Constructs the SFTP client exception with the specified detail messagepublic SFtpClientException(String message, Throwable cause)
: Constructs the SFTP client exception with the specified detail message and the original exceptionpublic SFtpClientException(Throwable cause)
: Constructs the SFTP client exception given the original exceptionThis enumeration represents the attributes of the file on the SFTP server. Table 6-4, lists the interfaces in this enumeration.
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:
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.
|
|
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.
|
|
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.
|
|
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.
|
|
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.
|
|
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.
|
|
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.
|
|
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.
|
|
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.
|
|
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.
|
|
In addition to implementing the above methods, the user must define the following constructors in their implementation of SFtpClient
:
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.
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.To plug in third-party SFTP client implementation using SPI, complete the following steps:
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. |
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. |
The Current SFTP Settings page is displayed.
To add the SPI implementation to the server class path, complete the following steps:
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).
To build an SFTP reference implementation, complete the following steps:
\BEA_Home\wlserver_10.3\commom\bin
directory.\BEA_Home\wli_10.3\samples\sftp_ref_impl
.
to delete the generated artifacts.\BEA_Home\wli_10.3\samples\sftp_ref_impl\build\ar
.
Here is an example of how you can design an application to test the SFTP implementation.
For information about business process, refer Guide to Building Business Process and Tutorial Building your First Business Process.
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:
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:
In this scenario, you add one instance of the File control to your business process.
The Insert Control: File dialog box is displayed.
An instance of a File control, named myFile, is created in your project and displayed in the Data Palette.
FileControlPropertiesDocument write(XmlObject someData)
FileControlPropertiesDocument write(com.bea.xml.XmlObject someData)
write
() method: XmlObject someData
.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).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.