www.dextsolution.com
DEXTUPLOAD
X5
Product description > Downloading files

# Downloading files

In general, when the browser makes a GET/POST request to the server, the server returns the response data. If the response data is a format that the browser can not directly interpret on the screen, the response data is downloaded to the file. Anchor (a) for example, if the hyperlink value set in the tag is an image (jpg) file that can be interpreted by a browser, the image is displayed in a new window (or tab) or the current window. If you want to download the jpg file directly to disk without opening it, you have to rely on the browser's own functionality (Context Menu - Save As) or send a response header to force the browser to download from the server.

Note) In macOS, if the file to be downloaded is an image or a zip file, the connection program is automatically executed. HTML5 has a new attribute that forces files to be downloaded regardless of the mime type. However, since all browsers do not support this feature (as of early 2016), you can not download files to disk with HTML or JavaScript alone.

To ensure that files are downloaded (not opened) the same in different browsers, you should use the server's response headers, as they are affected by browser characteristics when trying to download files from DEXTUploadX5.

Registering item to be downloaded

  You must register the item to be downloaded as a virtual file.

  A virtual file is a fake file that does not exist on the user's local PC and has no substance. That is, the file is not a file to be uploaded because it is a file that does not exist locally. In general, virtual files are used to keep information about already uploaded files. (An indication that the file exists on the server)

  To register a virtual file, use the addVirtualFile function or the addVirtualFileList function.

  - vindex: The unique key that distinguishes a virtual file. It can be in any format, but it should not be duplicated. (Required field)
  - name: The name of the virtual file. (Required field)
  - size: The size of the virtual file, in bytes. (Required field)
  - lock: If the lock status is true, the file can not be deleted.

      var dx = dx5.get(id);
      // When registering individually
      dx.addVirtualFile({ vindex: "IDX0001", name: "virtual_file.txt", size: 12345 });
      dx.addVirtualFile({ vindex: "IDX0002", name: "virtual_file_lock.txt", size: 45678, lock: true });
      dx.addVirtualFile({ vindex: "IDX0003", name: "cosmos.jpg", size: 195779 });

      // When adding at once
      dx.addVirtualFileList([
        { vindex: "IDX0001", name: "virtual_file.txt", size: 12345 },
        { vindex: "IDX0002", name: "virtual_file_lock.txt", size: 45678, lock: true },
        { vindex: "IDX0003", name: "cosmos.jpg", size: 195779 }
      ]);

  The url property (or downUrl property) must be set in the JSON property in order for the virtual file to be downloaded.

      // It is a virtual file that can not be downloaded because there is no download path information.
      dx.addVirtualFile({ vindex: "IDX0001", name: "virtual_file.txt", size: 12345 });
      // You can download these if they have download paths.
      dx.addVirtualFile({ vindex: "IDX0003", name: "bridge_509147.jpg", size: 509147, url: "http://domain/file/attach/bridge_509147.jpg" });
      dx.addVirtualFile({ vindex: "IDX0003", name: "bridge_509147.jpg", size: 509147, url: "http://domain/common-download.do?key=FID0001" });

  The url (or downUrl) property value must be a web URL that starts with a schema (http, https). If the URL contains multilingual characters or special characters, the target may not be found or the download may fail. (Not necessarily, it may be different by browser type or version.) In this case, you can encode multilingual and special characters using encodeURIComponent JavaScript function.

      dx.addVirtualFile({
        vindex: "IDX0003",
        name: "bridge_509147.jpg",
        size: 509147,
        // Encoding
        downUrl: "http://domain/file/attach/" + encodeURIComponent("bridge_509147.jpg")
      });

Setting button events

  The DEXTUploadX5 component only displays a download button for items with a url (or downUrl) set. If you don't want to use the download button displayed on the target and want to use an external HTML button, you need to use a script to connect the component functionality.

      <button type="button" onclick="download('component-id');">Download</button>
      <script>
      function download(id) {
        // Perform to download according to the flag value.
        // AUTO: Download the first virtual file.
        // SELECTED: Download the first selected virtual file.
        // CHECKED: Download the first checked virtual file.
        dx5.get(id).download("AUTO");
      }
      </script>

  It also provides automatic binding at component loading time without using complex scripts.

      <button type="button" id="btn-down-auto">Download</button>
      <button type="button" id="btn-down-selected">Download selected</button>
      <button type="button" id="btn-down-checked">Download checked</button>
      <script>
        dx5.create({
          ...,
          // The file download function automatically sets when the component is created.
          btnDownloadAuto: "btn-down-auto",
          btnDownloadSelected: "btn-down-selected",
          btnDownloadChecked: "btn-down-checked"
        });
      </script>

  The automatic binding functionality is very convenient, but it may not be suitable for implementing complex functions.

Server-Side processing

      // If the download target is exposed as a web address
      { vindex: "IDX0003", name: "bridge_509147.jpg", size: 509147, url: "http://domain/files/attach/bridge_509147.jpg" }

  If the target you want to download has a web resource address, you can add a "Content-Disposition: attachment" to the response header in the server to allow downloading when the target is called.

  How to set response headers for Web server or WAS for downloading is not provided in this manual.

  If the target does not have a web resource address, or if URL concealment is required, then you must configure the service so that it can be downloaded using a web application.

      // If you do not have the web resource address to download, or you use a web application to handle URL hiding
      { vindex: "IDX0003", name: "bridge_509147.jpg", size: 509147, downUrl: "http://domain/files/service/common-download.do?key=FID0001" }

  The following is a case where the service is implemented using DEXTUploadNJ product in Java JSP or Servlet environment. You can use the FileDownload class to handle downloads in a given mapping servlet (which can also be a JSP).

      # Server-side
      File target = null;

      String key = request.getParameter("key");

      if (key.equals("FID0001")) target = new File(fileRoot, "bridge_509147.jpg");
      else if (key.equals("FID0002")) target = new File(fileRoot, "beach_239826.jpg");
      else if (key.equals("FID0003")) target = new File(fileRoot, "cosmos (empty) 195779.jpg");

      if (target == null  || target.exists() == false || target.isFile() == false) {
        response.sendError(HttpServletResponse.SC_NOT_FOUND, "Not found files for the key");
        return;
      }

      try {
        // Create a FileDownload object.
        FileDownload dextnj = new FileDownload();
        // Set the encoding to UTF-8.
        response.setCharacterEncoding("UTF-8");
        // Download the file as an attachment file.
        dextnj.download(request, response, target);
      } catch (Exception e) {
        throw new ServletException(e);
      }

  The following is an example of implementing a service using the DEXTUploadNJ product in the Java Spring web framework environment. You can use the DEXTUploadNJFileDownloadView class in the controller's method mapped to a given request to handle the download.

      # Server-side
      File target = null;

      String fileRoot = request.getSession().getServletContext().getRealPath("/files/attach");

      if (key.equals("FID0001")) target = new File(fileRoot, "bridge_509147.jpg");
      else if (key.equals("FID0002")) target = new File(fileRoot, "beach_239826.jpg");
      else if (key.equals("FID0003")) target = new File(fileRoot, "cosmos (empty) 195779.jpg");

      // Set the encoding to UTF-8.
      response.setCharacterEncoding("UTF-8");

      if (target == null  || target.exists() == false || target.isFile() == false) {
        response.sendError(HttpServletResponse.SC_NOT_FOUND, "Not found files for the key");
        return null;
      } else {
        // You can download the file using the DEXTUploadNJFileDownloadView view class.
        DEXTUploadNJFileDownloadView dextnj = new DEXTUploadNJFileDownloadView(target);
        return new ModelAndView(dextnj);
      }

Downloaidng multiple files (supported from version 1.1.0.0)

  The above-mentioned downloading method explains how to download the files one by one by clicking the download icon on the screen or using the download and downloadById methods.

  HTML5 is a common idea that multiple files can not be downloaded without the use of plug-in technology that makes it easier to access local resources because of the sandbox issue. However, if you limit the file size and leave the download path settings to the browser, you can implement multiple files downloading functions that sequentially using pure browser technology alone.

  Multiple files download is used by calling the download method directly because there is no icon to perform the download.

  If the second value of the download method is true, the download operation is performed using the multiple files download method.

      <button type="button" onclick="download('component-id');">Download</button>
      <script>
      function download(id) {
        // Perform to download according to the flag value.
        // AUTO: Download all virtual files
        // SELECTED: Download all selected virtual files
        // CHECKED: Download all checked virtual files
        dx5.get(id).download("AUTO", true);
      }
      </script>

  When using multiple files download, cache option adjustment is required when using server components.

  When processing a download using the FileDownload class in a servlet (JSP) environment,

      # Server-side
      ...
      // Create a FileDownload object.
      FileDownload dextnj = new FileDownload();
      // Set the encoding to UTF-8.
      response.setCharacterEncoding("UTF-8");
      // dextnj.download(request, response, target);
      // Do not use caching. (set the useClientCache parameter value to false)
      dextnj.download(request, response, target, target.getName(), "application/octet-stream", false, false);

  If you are using the DEXTUploadNJFileDownloadView class in the Java Spring web framework environment:

      # Server-side
      ...
      // You can download the file using the DEXTUploadNJFileDownloadView view class.
      DEXTUploadNJFileDownloadView dextnj = new DEXTUploadNJFileDownloadView(target);
      // Set the cache to false.
      dextnj.setUseClientCache(false);
      return new ModelAndView(dextnj);

  File downloads impose a size limit due to browser memory management constraints. The default limit is 100MB. To allow files larger than this, you must modify the size limit using the setLimitMultiDownloadSize method.

  When using HTML5 features to download files sequentially, large files like video files can place a load on browser memory because the download target is temporarily loaded into memory. In severe cases, this can cause crashes. The setLimitMultiDownloadSize method changes the size of files allowed for download; it does not improve browser memory performance.

      // Set the download limit size to 300MB.
      dx.setLimitMultiDownloadSize(1024 * 1024 * 300);

Common and Differences in Single and Multiple File(s) Download

  Single | Multiple
  --- | ---
  The download path (local PC) is determined by browser settings and can not be changed by the component.
  If there is a file with the same file name in the download path, the browser automatically appends suffix (such as a number).
  Starting from version 4.0.0.0, there is a limit on the file size that can be downloaded (default 100MB), but even if this limit is removed, it does not place a load on the browser's memory. | There is a limit on the file size that can be downloaded (default 100MB).
  Before a target is downloaded (GET), a HEAD request is sent in advance to confirm existence of the file. | Multi-file downloads do not send HEAD requests to check for the existence of files. (Starting in version 3.8.0.0, multi-file downloads also send a HEAD request).
  Depending on the format of the target, it may not be downloaded as an attachment, so you must set the Content-Disposition: attachment response header using a server or server component. | Multiple files download can download objects regardless of the Content-Disposition response header setting.
  No download progress window is provided. | Provide download progress window. Since there is a stage (uncontrollable) in which the browser finally stores the file, there may be additional operations such as launching a dialog in the browser or copying the temporary file, even if the download is completed.
  Supported by all modern browsers that support HTML5 (Edge, IE, Safari, Chrome, Firefox, Opera). On iOS and iPad, only Safari (version 13 or later) supports single-file downloads. | On macOS, Safari 10.1 or later is supported. On iOS and iPad, only Safari version 17 or later is supported, and only when there are fewer files to download (10 or fewer) to avoid missing files.
  Button and automatic binding. | Multiple files download does not support button and automatic binding.