Filetransfer Client

Introduction

The SwiftMQ Filetransfer client is an easy-to-use client to transfer files of unlimited size between JMS clients and a SwiftMQ Router. It uses an existing JMS connection and can be easily integrated with any JMS application.

The client API consists of only 3 classes:

Class	Package	Description
`Filetransfer`	com.swiftmq.filetransfer	Provides the Filetransfer client.
`FiletransferException`	com.swiftmq.filetransfer	A filetransfer exception class.
`ProgressListener`	com.swiftmq.filetransfer	Provides information about the progress of a file transfer.

Samples

There are several example programs provided under the SwiftMQ distribution's directory "samples/filetransfer". Please have a look!

Protecting Files

A file can be protected by a password that needs to be specified during receive. A file can also be declared as private. Links to private files are not returned from a query, rather the link needs to be known.

File Expiration

Similar to JMS messages, a file can have an expiration which is specified in milliseconds. The file is automatically deleted after it has expired.

Maximum Downloads

The maximum number of downloads can be specified for a file. The file is automatically deleted after this number has been reached.

Message Properties and Selectors

The following message properties are automatically set during send:

Property	Type	Value
`JMS_SWIFTMQ_FT_USERNAME`	`String`	The JMS user who sent the file.
`JMS_SWIFTMQ_FT_FILENAME`	`String`	The original filename
`JMS_SWIFTMQ_FT_SIZE`	`long`	File size in bytes
`JMS_SWIFTMQ_FT_EXPIRATION`	`long`	The absolute expiration time in ms (since 01/01/1970)
`JMS_SWIFTMQ_FT_DIGESTTYPE`	`String`	The digest type, e.g. "SHA1".
`JMS_SWIFTMQ_FT_STORETIME`	`long`	The absolute store time in ms (since 01/01/1970)
`JMS_SWIFTMQ_FT_DELAFTDL`	`int`	The number of downloads after which the file will be deleted.
`JMS_SWIFTMQ_FT_DOWNLOADCOUNT`	`String`	The current number of downloads.

The sender can add arbitrary custom JMS message properties to a file, e.g. by setting an "orderid" property to mark a file containing a purchase order.

In addition to the Filetransfer properties listed above, all custom properties can be used in a message selector, too. For example, if custom property "orderid" was set as a custom property and one wants to get all PDF files for a particular order id, a query might look like this:

SQL

  orderid = 12345 and JMS_SWIFTMQ_FT_FILENAME like '%.pdf'

To select all zip-files of a particular customerId range which are bigger than 1 MB, use this selector:

SQL

  JMS_SWIFTMQ_FT_FILENAME like '%.zip'
    and customerid between 10000 and 11500
      and JMS_SWIFTMQ_FT_SIZE > 1024 * 1024

Sending Files

The most basic usage of a Filetransfer object to send files is to create it, set the file to send, send and close it:

JAVA

         Filetransfer filetransfer = Filetransfer.create(connection, routerName, cacheName);
         String link = filetransfer.withFile(file).send();
         filetransfer.close();

A Filetransfer object can be used to send multiple files sequentially but can not be used by multiple threads (use a dedicated Filetransfer object per thread, see Filetransfer samples):

JAVA

         Filetransfer filetransfer = Filetransfer.create(connection, routerName, cacheName);
         for (int i=0; i < files.length; i++)
           filetransfer.withFile(file[i]).send();
         filetransfer.close();

Various other settings can be applied in a builder style fashion:

JAVA

         Filetransfer filetransfer = Filetransfer.create(connection, routerName, cacheName);
         String link = filetransfer.withDigestType("SHA1")
                                   .withFileIsPrivate(isPrivate)
                                   .withPassword("Cheers")
                                   .withFile(file)
                                   .send();
         filetransfer.close();

In addition to a bunch of message properties that are automatically set from the Filetransfer, custom message properties can be added to each file that can be used to select them through a message selector:

JAVA

         Map props = new HashMap();
         props.put("orderid", orderId);
         props.put("customerid", customerId);
         props.put("documenttype", docType);
         Filetransfer filetransfer = Filetransfer.create(connection, routerName, cacheName);
         String link = filetransfer.withDigestType("SHA1")
                                   .withFileIsPrivate(isPrivate)
                                   .withPassword("Cheers")
                                   .withProperties(props)
                                   .withFile(file)
                                   .send();
         filetransfer.close();

A ProgressListener can be used too:

JAVA

         Filetransfer filetransfer = Filetransfer.create(connection, routerName, cacheName);
         String link = filetransfer.withFile(file).send(new ProgressListener()
         {
           public void progress(String filename, int chunksTransferred,
                                long fileSize, long bytesTransferred,
                                int transferredPercent)
           {
             System.out.println("  " + filename + ": " + chunksTransferred +
                                " chunks, "+ bytesTransferred + " of " + fileSize +
                                " transferred (" + transferredPercent + "%)");
           }
         });
         filetransfer.close();

Receiving Files

The most basic usage of a Filetransfer object to receiving a file is to create it with a link, set the output file, receive and close it:

JAVA

         Filetransfer.create(connection, link)
                     .withFile(file)
                     .receive()
                     .close();

To delete the file at the file cache after receive, call:

JAVA

         Filetransfer.create(connection, link)
                     .withFile(file)
                     .receive()
                     .delete()
                     .close();

One can also use the original filename. In that case the output directory needs to be specified:

JAVA

         Filetransfer.create(connection, link)
                     .withOutputDirectory(outDir)
                     .withOriginalFilename(true)
                     .receive()
                     .delete()
                     .close();

The password needs to be specified if file is protected:

JAVA

         Filetransfer.create(connection, link)
                     .withOutputDirectory(outDir)
                     .withOriginalFilename(true)
                     .withPassword("Cheers")
                     .receive()
                     .delete()
                     .close();

A ProgressListener can be used too:

JAVA

         Filetransfer.create(connection, link)
                     .withOutputDirectory(outDir)
                     .withOriginalFilename(true)
                     .receive(new ProgressListener()
         {
            public void progress(String filename, int chunksTransferred,
                                 long fileSize, long bytesTransferred,
                                 int transferredPercent)
            {
              System.out.println("  " + filename + ": " + chunksTransferred +
                                 " chunks, "+ bytesTransferred + " of " + fileSize +
                                 " transferred (" + transferredPercent + "%)");
            }
         }).delete().close();

Querying Links

There are 2 ways to get a link to a file:

The sending client sends it to the receiving client by using JMS (e.g. sends a JMS TextMessage). This is required for private files.
The receiving client queries the file cache.

To query a file cache, any existing or a new Filetransfer object can be used:

JAVA

        Filetransfer filetransfer = Filetransfer.create(connection, routerName, cacheName);
        List<String> result = filetransfer.query();
        filetransfer.close();
        final CountDownLatch countDownLatch = null;
        if (result != null && result.size() > 0)
        {
          countDownLatch = new CountDownLatch(result.size());
          for (int i = 0; i < result.size(); i++)
          {
            final String link = result.get(i);
            executorService.execute(new Runnable()
            {
              public void run()
              {
                transfer(link); // Uses a dedicated Filetransfer object to receive a file
                countDownLatch.countDown();
              }
            });
          }
        }
        if (countDownLatch != null)
          countDownLatch.await();

A JMS message selector can be used to select specific files:

JAVA

        Filetransfer filetransfer = Filetransfer.create(connection, routerName, cacheName);
        List<String> result = filetransfer.withSelector(selector).query();
        filetransfer.close();
        // ....

Querying Properties

Sometimes it is necessary to retrieve the properties of a file before the file itself will be downloaded. This can be done as follows:

JAVA

        Filetransfer filetransfer = Filetransfer.create(connection, routerName, cacheName);
        Map<String, Map<String, Object>> result = filetransfer.queryProperties();
        // ....
        filetransfer.close();

A Map is returned where the keys are links and the values are another Map with the properties. The properties contain those listed in the above section as well as all custom properties.

A JMS message selector can be used to select specific files:

JAVA

        Filetransfer filetransfer = Filetransfer.create(connection, routerName, cacheName);
        Map<String, Map<String, Object>> result = filetransfer.withSelector(selector).queryProperties();
        // ....
        filetransfer.close();

To query the properties of a particular file, specify the link:

JAVA

        Filetransfer filetransfer = Filetransfer.create(connection, routerName, cacheName);
        Map<String, Map<String, Object>> result = filetransfer.withLink(link).queryProperties();
        // ....
        filetransfer.close();

If the file cache contains many files it is recommended to use a selector or a link to reduce the result because the result is returned in a single message internally which becomes quite big.