www.dextsolution.com
DEXTUPLOAD
X5
menu toggle제품설명 > HD 응용프로그램을 이용하여 다운로드하기

HD 응용프로그램을 이용하여 다운로드하기

DEXTUploadX5는 2.0.0.0 버전부터 HD 응용프로그램을 사용하여 파일을 다운로드할 수 있는 기능을 지원한다. HD는 윈도우 데몬(HDD)과 윈도우 응용프로그램(HDM)를 합하여 부르는 말이다.

HD 응용프로그램은 사용자 데스크톱에서 실행되며, 브라우저와 HTTP 통신을 하여 파일 다운로드를 수행한다. HD 응용프로그램은 설치가 되더라도 브라우저에 어떠한 플러그인도 설치가 되지 않는다.

dextuploadx5-configuration.js 파일에 hdDownloadURL 속성 설정하기

dextuploadx5Configuration은 컴포넌트 설정을 담은 자바스크립트 객체이다. dextuploadx5Configuration 객체에는 HD 응용프로그램의 설치 프로그램을 다운로드할 수 있는 페이지 경로를 설정할 때 사용하는 hdDownloadURL 속성이 있는데, 기본 위치를 사용한다면, 속성을 생략(4.0.0.0부터)할 수 있다. 

# dextuploadx5-configuraiton.js
win.dextuploadx5Configuration = {
    // 생략 가능
    hdDownloadURL: location.origin + "/dx5/client/dextuploadx5-hd-download.html"
}

HD 응용프로그램이 설치 되지 않았을 경우, hdDownloadURL에 설정된 주소가 팝업으로 열린다. 만일 설치된 HD 응용프로그램이 DEXTUploadX5 버전보다 낮은 하위 버전이라면, 상위 버전을 다운로드할 수 있도록 hdDownloadURL에 설정된 주소의 페이지가 팝업으로 열릴 수 있다.

not install or lower version

* 위의 페이지는 제품에서 기본적으로 제공하는 다운로드 페이지이며, 각 사이트에 맞도록 만들어진 고유 페이지를 사용하는 것을 권고한다.

security

* 윈도우 OS의 경우, HD 응용 프로그램을 설치할 때 User Account Control 창에서 허용을 해줘야만 사용이 가능하다.

다운로드 항목 등록하기

가상 파일을 등록하려면 addVirtualFile 함수를 사용하거나 addVirtualFileList 함수를 사용한다.

  • vindex: 가상 파일을 구분 짓는 유일한 키로써, 어떤 형식이라도 상관이 없지만, 중복되지 않아야 한다. (필수항목)
  • name: 가상 파일의 이름이다. (필수항목)
  • size: 가상 파일의 크기이며 byte 단위를 사용한다. (필수항목)
  • lock: 잠금 상태가 true이면 파일을 삭제할 수 없다.
var dx = dx5.get(id);
// 개별로 등록할 때
dx.addVirtualFile({ vindex: "IDX0001", name: "가상파일.txt", size: 12345 });
dx.addVirtualFile({ vindex: "IDX0002", name: "잠긴-가상파일.txt", size: 45678, lock: true });
dx.addVirtualFile({ vindex: "IDX0003", name: "코스모스.jpg", size: 195779 });
// 여러 개를 한 번에 등록할 때
dx.addVirtualFileList([
  { vindex: "IDX0001", name: "가상파일.txt", size: 12345 },
  { vindex: "IDX0002", name: "잠긴-가상파일.txt", size: 45678, lock: true },
  { vindex: "IDX0003", name: "코스모스.jpg", size: 195779 }
]);

가상 파일이 다운로드 대상이 되려면 json 속성 중에 downUrl 또는 url 속성이 설정되어 있어야 한다.

// 다운로드 경로 정보가 없어서 다운로드할 수 없는 가상 파일이다.
dx.addVirtualFile({ vindex: "IDX0001", name: "가상파일.txt", size: 12345 });
// 다운로드 경로가 있으면 다운로드할 수 있다.
dx.addVirtualFile({ vindex: "IDX0003", name: "서강대교_509147.jpg", size: 509147, url: "http://domain/path/file/attach/서강대교_509147.jpg" });
dx.addVirtualFile({ vindex: "IDX0003", name: "서강대교_509147.jpg", size: 509147, url: "http://domain/path/common-download.do?key=FID0001" });

downUrl 또는 url 속성 값은 반드시 스키마(http, https)로 시작하는 웹 URL이어야 한다.

URL에 다국어 및 특수 문자가 들어간 경우에는 대상을 못 찾거나, 다운로드가 실패하는 경우가 있다. (반드시 안되는 것이 아니라, 브라우저 종류 혹은 버전마다 차이가 있을 수 있다.)

이런 경우 다국어 및 특수 문자가 사용되는 구간을 encodeURIComponent 자바스크립트 함수를 사용하여 인코딩을 하면 된다.

dx.addVirtualFile({
  vindex: "IDX0003", 
  // 인코딩 불필요
  name: "서강대교_509147.jpg",
  size: 509147, 
  // 인코딩 필요
  url: "http://domain/path/file/attach/" + encodeURIComponent("서강대교_509147.jpg") 
});

HD는 파일을 다운로드할 때, 대상을 분할하여 다운로드할 수 있다. 가상 파일을 등록할 때, chunkSize 속성을 사용하면, 분할되는 크기를 지정할 수 있다. 개별 사용자의 입장에서는 큰 체감은 없지만, 서버의 입장에서는 요청에 대한 응답성을 높이는데 도움이 된다.

chunkSize 속성을 지정하지 않거나 0으로 설정하면 분할하지 않고 다운로드를 진행한다.

dx.addVirtualFile({
  vindex: "IDX0003",
  name: "서강대교_509147.jpg",
  size: 509147,
  url: "http://domain/path/file/attach/" + encodeURIComponent("서강대교_509147.jpg"),
  // 10MB로 분할 크기를 지정한다. (MB 단위로만 지정 가능)
  chunkSize: 10
});
버튼 연결하기

HD 응용프로그램을 사용하여 다운로드할 때, DEXTUploadX5 제품은 항목에 다운로드 버튼을 따로 제공하지 않는다.

대신에 스크립트를 사용하여 외부 HTML 버튼과 컴포넌트 기능을 연결해줘야 한다.

<button type="button" onclick="download('component-id');">다운로드</button>
<script>
function download(id) {
  // 플래그 값에 따라 다운로드를 수행한다.
  // AUTO: 가상 파일들을 다운로드한다.
  // SELECTED: 선택된 가상 파일들을 다운로드한다.
  // CHECKED: 체크된 가상 파일들을 다운로드한다.
  dx5.get(id).downloadToHD("AUTO");
}
</script>

복잡한 스크립트를 사용하지 않고서 컴포넌트 로드 시점에 자동 바인딩이 되는 기능도 함께 제공하고 있다.

<button type="button" id="btn-down-auto">다운로드</button>
<button type="button" id="btn-down-selected">선택 다운로드</button>
<button type="button" id="btn-down-checked">체크 다운로드</button>
<script>
  dx5.create({
    ...,
    // 컴포넌트가 생성될 때, 파일 다운로드 기능이 자동으로 연결하도록 한다.
    btnDownloadToHDAuto: "btn-down-auto", 
    btnDownloadToHDSelected: "btn-down-selected", 
    btnDownloadToHDChecked: "btn-down-checked"
  });
</script>

자동 바인딩 기능은 매우 편리하나, 복잡한 기능을 구현하기에는 적합치 않을 수 있다.

다운로드 요청에 따른 서버 측 처리
// 다운로드할 대상이 웹 주소로 노출되어 있는 경우
{ vindex: "IDX0003", name: "서강대교_509147.jpg", size: 509147, url: "http://domain/path/files/attach/서강대교_509147.jpg" }
// 다운로드할 대상이 웹 주소에 없거나, URL 은닉 처리를 위해서 웹 애플리케이션을 사용하는 경우
{ vindex: "IDX0003", name: "서강대교_509147.jpg", size: 509147, url: "http://domain/path/files/service/common-download.do?key=FID0001" }

다음은 자바 JSP 혹은 서블릿 환경에서 DEXTUploadNJ 제품을 사용하여 서비스를 구현한 경우이다.

주어진 매핑 서블릿(JSP도 가능)에서 FileDownload 클래스를 사용하여 다운로드를 처리할 수 있다.

# 서버 측 설정이다.
File target = null;
		
String key = request.getParameter("key");
if (key.equals("FID0001")) target = new File(fileRoot, "서강대교_509147.jpg");
else if (key.equals("FID0002")) target = new File(fileRoot, "우도해변_239826.jpg");
else if (key.equals("FID0003")) target = new File(fileRoot, "코스모스 (빈공간) 195779.jpg");
if (target == null  || target.exists() == false || target.isFile() == false) {
  response.sendError(HttpServletResponse.SC_NOT_FOUND, "주어진 키에 해당하는 파일 정보가 없다.");
  return;
}
try {
  // FileDownload 객체를 생성한다.
  FileDownload dextnj = new FileDownload();
  // 인코딩을 UTF-8로 설정한다.
  response.setCharacterEncoding("UTF-8");
  dextnj.setAllowingWeakRange(true);
  // 파일을 첨부 파일 형식으로 다운로드한다.	
  dextnj.download(request, response, target);
} catch (Exception e) {
  throw new ServletException(e);
}

다음은 자바 Spring 웹 프레임워크 환경에서 DEXTUploadNJ 제품을 사용하여 서비스를 구현한 경우이다.

주어진 요청에 매핑된 컨트롤러의 메소드에서 DEXTUploadNJFileDownloadView 클래스를 사용하여 다운로드를 처리할 수 있다.

# 서버 측 설정이다.						
File target = null;
		
String fileRoot = request.getSession().getServletContext().getRealPath("/files/attach");
if (key.equals("FID0001")) target = new File(fileRoot, "서강대교_509147.jpg");
else if (key.equals("FID0002")) target = new File(fileRoot, "우도해변_239826.jpg");
else if (key.equals("FID0003")) target = new File(fileRoot, "코스모스 (빈공간) 195779.jpg");
// 인코딩을 UTF-8로 설정한다.
response.setCharacterEncoding("UTF-8");
if (target == null  || target.exists() == false || target.isFile() == false) {
  response.sendError(HttpServletResponse.SC_NOT_FOUND, "주어진 키에 해당하는 파일 정보가 없다.");
  return null;
} else {
  // DEXTUploadNJFileDownloadView 뷰 클래스를 사용하여 파일을 다운로드할 수 있다.
  DEXTUploadNJFileDownloadView dextnj = new DEXTUploadNJFileDownloadView(target);
  dextnj.setAllowingWeakRange(true);
  return new ModelAndView(dextnj);
}
HD 응용프로그램 화면 설명

다운로드 버튼을 클릭하거나 downloadToHD 메소드가 호출되면 아래와 같이 HD 프로그램이 실행되며, 대상 항목들이 추가가 된 후, 바로 다운로드가 시작된다.

HD execution

다운로드 대상 항목이 다운로드 완료된 상태라면 우측에 초록색 확인 아이콘이 보이다. 이 아이콘을 클릭하면 대상이 다운로드된 위치가 열리며, 엑스 아이콘을 클릭하면 항목을 목록에서 제거한다.

HD execution

만일 자동 다운로드 옵션이 지정되지 않았다면, 파일들은 다운로드할 대기 상태에 있게 되며, 우측에 주황색 아래화살표(다운로드) 아이콘으로 표시가 되고, 이 아이콘을 클릭하면 해당 항목만 다운로드를 수행한다.

하단바 왼쪽에는 전체 항목을 다운로드, 전체 항목을 중지, 전체 항목을 삭제하는 버튼이 있고, 하단바 우측에는 선택된 항목의 다운로드 순서를 변경하는 버튼이 있다.

HD 응용프로그램 옵션

HD configuration

HD 응용프로그램 타이틀 바의 별 모양의 아이콘을 클릭하거나, 마우스 우클릭을 하여 '환경 설정' 창을 띄워 옵션을 조정할 수 있다.

HD configuration

HD configuration

  • 저장 경로

    파일을 다운로드할 기준 경로를 나타내며, 변경이 가능하다.

  • 항목을 추가할 때마다 프로그램 활성화

    HD 응용프로그램으로 항목이 추가될 때, 이를 확인할 수 있도록 HD 응용프로그램이 나타난다. (간혹 다른 프로그램이 선점하여 HD 응용프로그램이 맨 앞으로 나타나지 못 할 경우도 있다.)

  • 새 항목이 추가될 때 바로 다운로드 시작

    HD 응용프로그램이 추가될 때 바로 대상을 다운로드하거나 다운로드할 수 있도록 대기 상태가 된다. 기본값은 체크 상태이지만, 체크 해지하면 사용자가 직접 다운로드 버튼을 눌러 다운로드를 수행해야 한다.

  • 항목 삭제 시 임시파일 삭제(이어받기 지원 안함)

    HD 응용프로그램은 이어받기가 기본 동작하며, 목록에서 대상이 제거가 되었다고 하더라도 다음에 다운로드할 때는 이어받기가 진행된다. 그러나 이 옵션을 체크하면, 대상 항목을 다시 추가하여 다운로드를 하면 처음부터 내려받기 시작한다.(이 옵션을 사용하는 이유는 서버에 문제가 있어, 다운로드하는 대상에 변동이 있거나 하는 경우에 다운로드 작업에 문제가 발생할 수 있기 때문이다.) 이 옵션은 항목이 삭제된 후의 이어받기 동작에 관련된 것으로써, 그 외의 과정에서 발생하는 이어받기에는 영향을 미치지 않는다.

  • 미완료 상태로 종료된 항목을 프로그램 시작할 때 자동으로 다운로드 시작

    파일을 다운로드하고 있는 중간에 프로그램 실행이 중단(Exit 명령을 사용하여 완전히 종료되는 경우)되어 꺼지면, 다음에 다시 프로그램이 시작될 때, 중단되었던 다운로드가 다시 재개가 되도록 하는 옵션이다. 다운로드가 되는 대상은 프로그램이 중단된 시점에 다운로드 중이었던 항목으로 한정한다.

  • 파일정보 저장 옵션

    프로그램 실행이 중단되었을 때, 목록에 있던 항목들 중에서 다음에 프로그램이 다시 실행될 때, 복구(목록에 포함될)할 대상을 가리킨다. (만약 '다운로드 중'이 체크 해지가 된 상태라면 '미완료 상태로 종료된 항목을 프로그램 시작할 때 자동으로 다운로드 시작' 옵션이 체크된 상태라 하더라도 불러올 대상이 없으므로 다운로드 작업이 진행되지 않는다.)

HD 응용프로그램 삭제

  • 윈도우용 HD 응용프로그램은 '제어판' 하위의 '프로그램 및 기능' 메뉴에서 DEXTUploadX5 HD를 선택하여 삭제할 수 있다.

HD 응용프로그램 제한

  • 사용자 로그인 계정이 관리자 권한을 가지고 있지 않는 경우, HD 응용프로그램은 자동으로 시작되지 않는다.

    HD 응용프로그램을 수동으로 시작하려면, 제품 설치 위치에 있는 'DEXTUploadX5-HDD.exe' 파일을 실행시킨다.

  • HD 응용프로그램은 파일을 바로 실행하는 기능을 제공하지 않는다.

  • HD 응용프로그램은 브라우저를 통해 파일을 다운로드하는 것이 아니므로 브라우저의 쿠키 및 세션 그리고 인증 정보를 공유하지 않는다.

  • localhost를 제외한 비-보안 연결을 사용하는 웹 응용프로그램에서는 HD와 통신을 할 수 없다. '알려진 문제점' 문서의 'Private Network Access 스펙에 따른 HD 응용프로그램과 통신 실패 현상' 항목을 참고한다.
  • Amazon S3, NAVER CLOUD PLATFORM Object Storage, Microsoft Azure Blob Storage로부터 객체를 다운로드하는 기능은 지원하지 않는다.
Copyright ⓒ DEXTSolution Inc. All rights reserved