Uploading and downloading

Uploading and downloading

You can set up your Web UI Framework (WUF) and Rich Client Platform (RCP) applications to
attach files to records of a table, upload files, and download attached files. Uploads and downloads
flow between internal file systems and the application database.

With this feature, you can do the following:

  • Perform a file upload or download in a single transaction.
  • Have multiple file uploads within a single API call.
  • Restrict the types and sizes of files being uploaded.
  • Perform authentication during a file download.
  • Perform authorization during a file download.
  • Download one file at a time.
  • Attach more than one document per record.

This feature has the following limitations:

  • Two or more files with the same name cannot be uploaded and attached
    to a particular record of a database table. The application must
    have customized validation to prevent two or more files with the same
    name from being uploaded.
  • It is not supported for the Console UI Framework, HTTPTester,
    End Point, and remote clients.
  • In Windows, file names
    are case-insensitive within a particular directory, but in Linux, file names are case-sensitive.
    At the Sterling Application Platform level, the case insensitivity
    of file names will not be checked before the files are imported into
    the database. That is, at the Sterling Application Platform level,
    abc.txt and ABC.txt are two different files. Application developers
    will have to decide if the application allows files of the same name
    but in different cases to be uploaded for a record of a database table.

Using yfs.properties to configure file uploads

The yfs.properties file includes several properties that you need to set to upload files
in the Web UI Framework and the Rich Client Platform.

Note: Do not directly edit or change the yfs.properties* files. To make changes to the properties in
these files, you must use the customer_overrides.properties file. IBM does not recommend that you modify or
change any properties in files ending with .in because newer versions or patches of the product will
overwrite your changes. IBM also does
not recommend that you change a property file that has a corresponding .in file because the
setupfiles script will re-create the properties file again, thus causing you to lose your
changes.

Configuring file uploads

To create a field for uploading files in the Web UI Framework, use the File Upload
Widget, which is an extension of the textfield control in Ext JS.

The following graphic shows an example of a file upload control
created using Ext JS (the Attach Photo control). In a web
browser, the input field is used as a file. The following graphic
shows a text field with a Browse button.
When you click Browse, a file selection dialog
box opens. The dialog box is operating system-specific and cannot
be customized.

file upload

You also need to adjust the following properties in yfs.properties
to configure file uploads.

  • Use the sc.file.upload.maxfilesize and sc.file.upload.maxfilesize.table_name
    properties to specify the size of files that can be uploaded.

    Use
    the sc.file.upload.allowedfiletypes and sc.file.upload.allowedfiletypes.table_name properties
    to specify the type of files that can be uploaded.

  • Use the sc.file.upload.dir property to specify a directory that
    will temporarily hold uploaded files.
  • Use the sc.file.upload.type property to decide when to upload
    the file to the server.
With the Web UI Framework, the filter mapping of the Struts filter
and the Struts-cleanup filter’s <url-pattern> should be changed
from * to *.do so that the upload servlet requests do not pass through
the Struts filter. If the URL pattern is not changed, then the file
upload request gets parsed before it hits the upload servlet, in which
case the file will be lost. The following code shows how to set
this up:

{{{
   <filter-mapping>
          <filter-name>struts</filter-name>
          <url-pattern>*.do</url-pattern>
   </filter-mapping>
   <filter-mapping>
          <filter-name>struts-cleanup</filter-name>
          <url-pattern>*.do</url-pattern>
   </filter-mapping>
}}}
In WUF file uploads, the following happens:

  • File validation for type is performed. Validations are done also
    on the server side for the name and file type. Size validation is
    not possible in the browser.
  • The files are placed within a subdirectory of the temporary directory
    that is specified in the sc.file.upload.dir property in the yfs.properties
    file ({sc.file.upload.dir}/{App_Server_Name}/{userID of
    the user uploading the files}/{session ID of the session which is
    uploading the files}
    ). The App_Server_Name,
    userID, and JsessionID values
    will be stripped of all special characters.
  • The internal data value of the file upload widget (FileUploadField)
    is changed to SCFile:<Element_ID>. For example:

    {User : { 
          UserId : "user1",
          attachFile : "SCFile:ext-comp-1037"
       }
    }

  • After files are successfully streamed to the server, the FileAttachments
    element with the file information (such as unique file ID, file location,
    and widget ID) is appended to the screen’s data object that is used
    in the upload. The actual API call to send file information to the
    database is made with this input.

    The following shows the change
    for a sample data model after appending the information:

    {User : { 
          UserId : "user1",
          attachFile : "user1_1267599880675_1"
       }
    FileAttachments : {
         FileAttachment :
           {
            file_id : "user1_1267599880675_1",
            file_path : "att2.bmp",
            Element_ID : "ext-comp-1037"
           }
        }   
    }
An API failure occurs when:

  • There is a failure to send across files to the server.
  • There is an exception while trying to persist files in the database
    as part of the API call (that is, after the files have been placed
    successfully on the server).

Events are called when files are deleted from their temporary location
on the server.

Securing file delete

The ISecureFileDelete
Interface allows you to securely delete a file that is uploaded to
the temporary server location. Use the following property in the yfs.properties
file to plug in the ISecureFileDelete Interface:

sc.secure.file.delete.impl=/*

Ensure
that sc.secure.file.delete.impl=/* is a fully qualified path to the Java™ class implementation of the
ISecureFileDelete Interface. The ISecureFileDelete Interface definition
has a method, which must be implemented:

         +
                   /**
                    * @param file is an existing file which has to be deleted
                    * from temporary location of the server. This method
                    * implementation gets called only when file exists
                    * on the server location. 
                    * @return true if the file delete is successful, false otherwise.
                    */
                    boolean deleteFile(File file);

By default,
secure file delete is available. A default implementation for secure
file delete is plugged in. The default implementation class is ‘com.sterlingcommerce.woodstock.util.frame.file.impl.PLTSecureFileDeleteImpl’.
If the plugged-in implementation class is invalid or not accessible,
the file is deleted using the Java File
Delete API.

Securing uploaded files

Virus scans, encoding/decoding files, and Compression/decompression of BLOB data help to
secure uploaded files.

Interfaces for the following tasks help with securing uploaded
files in the Web UI Framework and the Rich Client Platform:

  • Virus scan
  • Encoding/decoding of files

Virus
scan

You can plug in logic to scan an uploaded file for
viruses. Use the yfs.properties file to plug in the scanner.
A default implementation of virus scanning is not available.

The
virus scanner interface includes the following methods. For more
information, refer to the Javadocs.

  • public PLTVirusScanResponse scan(InputStream stream, PLTFileHandlerObj
    fileObject)

    Called first during uploads and downloads to scan the
    file input stream as is during the upload/download request.

  • public PLTVirusScanResponse scan(PLTFileHandlerObj fileObject)

    Called
    only during uploads to enable the scanning of the file written to
    temporary directory.

Encoding/decoding
of files

Files that are uploaded can be encoded before they
are streamed to a temporary server folder as part of the upload process.
These files are encoded by objects of the IFileEncoderDecoder interface,
which has two methods (encode and decode). A default implementation
is provided for this interface. Use the sc.file.upload.encoder
property of the yfs.properties file to plug in the encoder/decoder.

Note: The
default encoder increases file sizes significantly.

The
following includes basic information about each method. For more
information, refer to the Javadocs.

  • public void encode(InputStream iStream, OutputStream oStream)

    Encodes
    the input stream and places it in the output stream. Called during
    file upload.

  • public void decode(InputStream iStream, OutputStream oStream)

    Decodes
    the input stream and places it in the output stream. Called during
    file download.

Encoding and decoding can negatively affect performance.
If the sc.file.upload.encoder property is not set, then encoding
and decoding are skipped.

Compression/decompression of BLOB data

You
can compress and decompress data that is stored in columns and tables.
The actual file content, stored as bytes in the PLT_FILE_DATA
table, follows this mechanism by marking the column as CompressionSupported=true and UseCompression=true.

Upload error messages

There are eighteen different upload error messages.

Number Error Code Error Condition Error-Related More Information or Any Message
1

PLTF001

If sc.file.upload.dir is not set Mandatory temporary directory not configured
in properties file.
2 PLTF007 If user is not authenticated. File Upload – Authentication Failed.
3 PLTF006 Session is not valid. InvalidSession
4 PLTF009 If the file size exceeds the allowed size. Cannot proceed with file upload. Maximum file
size exceeded for file :<filename>. Maximum file size allowed(bytes):<max_size>
5 PLTF011 If the file type is not allowed. Cannot proceed with file upload. File type not
allowed. File :<filename>. Allowed file types:<allowed_types>
6 PLTF004 If file is not found after virus scan in quarantine
directory.
File is not found in the directory specified
after virus scan.
7 PLTF008 If virus scan fails. Error message sent by the virus scan implementation
should be shown.
8   If file cannot be deleted after it is placed
in the temporary directory.
Error: Cannot delete file at location:
9   If file is not found at the specified location,
during file delete.
Error: File not present at location:
10   If during file delete, if yfs.properties is
not configured or file location is not provided.
Error: File upload temporary is not configured
in yfs.properties or file location is not provided.
11   If file is successfully deleted in temporary
location.
File deleted at location:
12 PLTF013 Virus scan implementation class cannot be found
or is incorrect.
Error message sent will be available on the
client.
13 PLTF014 Encoder-decoder implementation class cannot
be found or is incorrect.
Error message sent will be available on the
client.
14 PLTF015 File upload temporary directory is not found. Error message sent will be available on the
client.
15 PLTF016 File upload quarantine directory is not found. Error message sent will be available on the
client.
16 PLTF017 Processing of multipart/form-data request failed. Error message sent will be available on the
client.
17 PLTF018 File upload property is not defined correctly. Error message sent will be available on the
client.
18 PLTF019 Secure file delete implementation class cannot
be found or is incorrect.
Error message sent will be available on the
client.

Configuring file downloads

A method is used to download files in the Web UI Framework. The method call will take in
the file download input, the API input, and the API name.

The syntax of the method is:

  • class: sc.plat.FileAttachmentHelper
  • function: downloadFileAttachement
  • Parameter to be passed: A JSON object as:
    {
       FileDownloadInput: <File_Download_Input_JSON_String>, 
       APIInput: <API_Input_JSON_String>, 
       APIName: <API_Name>
    }

    where:

    File_Download_Input_JSON_String:
    The input required to download the file.

    API_Input_JSON_String:
    The output of this API should return file information.

    API_Name:
    The name of the API to be called with APIInput.

Securing downloaded files

When downloading files in the Web UI Framework and the Rich Client Platform, to
authenticate and authorize the file download request, an API and API input has to be passed along
with the file download input. The API will be called with the API input passed. If the API is
successful, the file specified in the file download input will be downloaded.

The API which has to be called for file download authorization
has to be registered with the class PLTFileDownloadAPIRegistry using
the method API(String appCode, String appName). The client request
should provide the API name and input. The following is an example
of the API input (for the getUserList API):

<User UserKey="">
  <FileAttachments> 
    <FileAttachment FileName=""/> 
  </FileAttachments>
</User>

As part of the API invocation, authorization and other security
tasks are handled by API security, token validation, and other tasks.
This API is invoked to check if the API succeeds. If it does,
then the user is authorized to download files. Then the file for
which FileAttachmentKey is provided in the file download input XML
file will be downloaded.

The API template is provided inside the template/filedownloadapi
folder in the resources.jar file. This is the template for the API
which has to be called for authorization. It should be as small
as possible, for example:

<User UserKey="">
  <FileAttachments> 
    <FileAttachment FileName="" FileAttachmentKey=""/> 
  </FileAttachments>
</User>

Authorization for the file download servlet (PLTFileDownloadServlet)
is configured via web.xml. The context parameter is sc-file-download-authorization-required.
By default, this property value is TRUE.

For download, APIName,APIInputXML, and FileDownloadInputXML are
all required and have to be passed from the client. If the web.xml
entry sc-file-download-authorization-required is
set to FALSE, then the FileAttachmentKey in FileDownloadInputXML
is used to fetch the file. If sc-file-download-authorization-required is
set to TRUE, then the API passed by the client is called with
the API input passed. The template for this API call is described
earlier in this topic. If the API call succeeds, then the file is
downloaded.

The user invoking the servlet should have permission for the API.
On the successful completion of this API, the file data is decompressed,
decoded, and the client is served with the file it requested for download.

Download error messages

There are twelve different download error messages.

Number Error Code Error Condition Error-Related More Information or Any Message
1

PLTF006

Session is not valid. InvalidSession
2 PLTF002 File download input is not provided. File download input is not provided.
3 PLTF012 FileAttachment key is not provided in file download
input.
FileAttachment key is not provided
4 PLTF003 File download authorization is required, but
API input is not provided.
API input to download file is not provided.
5 PLTF003 File download authorization is required, but
API name is not registered.
API provided for file download file authorization
is not registered.
6 PLTF003 File download authorization is required, but
API template is not found at location template/FileDownloadapi.
Template not found for API authorization.
7 YCP0045 If after authorization, FileAttachment key cannot
be found in the output.
File attachment record does not exist or the
user is not authorized to access it.
8 YCP0045 If the file attachment record is not found in
the file attachment table.
File attachment record does not exist.
9 PLTF008 If virus scan implementation finds virus. Error message sent by the virus scan implementation
should be shown.
10 PLTF004 If after virus scan, the file is not found within
the quarantine directory.
File is not found in the directory specified
after the virus scan.
11 PLTF013 Virus scan implementation class cannot be found
or is incorrect.
Error message sent will be available on the
client.
12 PLTF014 Encoder-decoder implementation class cannot
be found or is incorrect.
Error message sent will be available on the
client.

Structuring the file upload and download

You can implement file upload/download functionality through interface contracts in the
Web UI Framework and the Rich Client Platform. The upload/download implementations can be plugged in
either through web.xml as context parameters or programmatically using exposed methods.

This enables you to do the following:

  • Customize upload/download functionality in the same way that you
    can customize authorization, authentication, and other tasks.
  • Implement upload/download functionality for applications that
    do not use the Sterling Application Platform.

These tasks use the following base classes which are present both
in the Sterling Application Platform (the platform_afc.jar file) and
in the base file attachment jar file (platform_fa.jar) that is used
when not using the Sterling Application Platform:

  • The interfaces IFileUploadProvider and IFileDownloadProvider
  • The abstract class PLTFileUploadProvider
  • The servlets PLTFileUploadservlet and PLTFileDownloadServlet
Note: For applications consuming the platform_afc.jar file, the platform_fa.jar
file does not have to be added in the classpath since the file attachment
base classes of the platform_fa.jar file are included in the platform_afc.jar
file.

Default file upload/download implementations

The
following graphic shows the default implementation of upload/download
functionality in applications based on the Sterling Application Platform
but which do not use the Web UI Framework (like the Rich Client Platform):

In
the graphic, Platform and Platform_AFC refer to the Sterling Application
Platform.

upload download

Default implementation classes are as follows:

  • For upload – com.sterlingcommerce.woodstock.util.frame.file.impl.PLTFileUploadProviderImpl
  • For download – com.sterlingcommerce.woodstock.util.frame.file.impl.PLTFileDownloadProviderImpl

The following graphic shows the default implementation of
upload/download functionality in applications based on the Sterling
Application Platform and use the Web UI Framework:

In the graphic,
Platform and Platform_AFC refer to the Sterling Application Platform.

upload download 2

Default implementation
classes are as follows:

  • For upload – com.sterlingcommerce.ui.web.platform.file.SCUIFileUploadProviderImpl
  • For download – com.sterlingcommerce.ui.web.platform.file.SCUIFileDownloadProviderImpl

Plugging in file upload/download implementations through web.xml

The following context parameters are used when plugging
in file upload/download implementations through web.xml:

  • For upload – sc-file-upload-provider
  • For download – sc-file-download-provider

The value of the above mentioned context parameters should
be a qualified Java class path
which implements IFileUploadProvider and IFileDownloadProvider for
upload and download, respectively.

Sample context parameters
to be plugged in applications based on the Sterling Application Platform
but which do not use the WUF (note the PLT prefix in the method name):

   <context-param>
        <param-name>sc-file-upload-provider</param-name>
        <param-value>
com.sterlingcommerce.woodstock.util.frame.file.impl.PLTFileUploadProviderImpl
        </param-value>
   </context-param>
   <context-param>
        <param-name>sc-file-download-provider</param-name>
        <param-value>
com.sterlingcommerce.woodstock.util.frame.file.impl.PLTFileDownloadProviderImpl
        </param-value>
   </context-param>
Sample context parameters
to be plugged in applications based on the Sterling Application Platform
and are on WUF (note the SCUI prefix in the method name):

   <context-param>
        <param-name>sc-file-upload-provider</param-name>
        <param-value>
com.sterlingcommerce.ui.web.platform.file.SCUIFileUploadProviderImpl
        </param-value>
   </context-param>
   <context-param>
        <param-name>sc-file-download-provider</param-name>
        <param-value>
com.sterlingcommerce.ui.web.platform.file.SCUIFileDownloadProviderImpl
        </param-value>
   </context-param>
Note: By default, the context
parameters required to plug in the default implementations will not
be provided. Consuming applications will have to add the context parameters
in the web.xml file or set it using setFileUploadProvider and setFileDownloadProvider
methods exposed in the PLTFileUploadDownloadHelper class.

Plugging in file upload/download implementations programmatically using exposed methods

The methods setFileUploadProvider
and setFileDownloadProvider are exposed in the PLTFileUploadDownloadHelper
class to plug in file upload/download implementations programmatically
using interface contracts.

Sample usage of the above mentioned
set methods:

PLTFileUploadDownloadHelper.setUploadProviderImpl(uploadImpl);  
PLTFileUploadDownloadHelper.setDownloadProviderImpl(downloadImpl);

Here,
uploadImpl and downloadImpl are class objects which implement IFileUploadProvider
and IFileDownloadProvider, respectively.

Join The Discussion

Your email address will not be published. Required fields are marked *