FTPS 컴포넌트

원문 보기 위키 갱신 2026.10.11

FTPS 컴포넌트 (FTPS Component)

FTPS 컴포넌트는 FTP secure(FTPS)와 SFTP 프로토콜로 원격 파일 시스템에 접근하게 해 주는 컴포넌트예요. Camel 2.2부터 제공됐고 producer와 consumer를 모두 지원합니다. 파일 소비·전송 관련 옵션과 readLock 같은 잠금 전략, 보안 데이터 채널(execPbsz/execProt) 설정까지 폭넓게 제공해요.

출처: 문서

본문

Camel 2.2부터 지원

producer와 consumer 모두 지원해요

이 컴포넌트는 FTP secure(FTPS)와 SFTP 프로토콜을 통해 원격 파일 시스템에 접근하게 해 줘요.

Maven 사용자는 이 컴포넌트를 쓰려면 pom.xml에 다음 의존성을 추가해야 해요:

<dependency>
    <groupId>org.apache.camel</groupId>
    <artifactId>camel-ftp</artifactId>
    <version>x.x.x</version>
    <!-- use the same version as your Camel core version -->
</dependency>

옵션 설정 방법 (Configuring Options)

Camel 컴포넌트는 서로 다른 두 단계로 설정해요:

컴포넌트(component) 레벨
엔드포인트(endpoint) 레벨

컴포넌트 옵션 설정 (Configuring Component Options)

컴포넌트 레벨에서는 엔드포인트들이 이어서 물려받는 일반적이고 공유되는 설정을 해요. 가장 상위의 설정 레벨이죠.

예를 들어 컴포넌트에는 보안 설정, 인증용 자격 증명, 네트워크 연결 URL 같은 것들이 있을 수 있어요.

컴포넌트에 따라 옵션이 몇 개뿐인 것도 있고 아주 많은 것도 있어요. 컴포넌트는 보통 널리 쓰이는 기본값이 미리 설정되어 있어서, 몇 가지 옵션만 설정하거나 아예 하나도 건드리지 않아도 되는 경우가 많아요.

컴포넌트는 다음 방법으로 설정할 수 있어요:

the Component DSL.
설정 파일(application.properties, *.yaml 파일 등).
Java 코드에서 직접.

엔드포인트 옵션 설정 (Configuring Endpoint Options)

엔드포인트는 옵션이 많아서 설정에 시간을 더 쓰게 될 거예요. 이 옵션들이 엔드포인트가 원하는 일을 하도록 커스터마이즈해 줘요. 옵션은 엔드포인트가 컨슈머(from)로 쓰이는지, 프로듀서(to)로 쓰이는지, 둘 다인지에 따라 분류되기도 해요.

엔드포인트 설정은 대부분 엔드포인트 URI에 _path_와 query 파라미터로 바로 하는 경우가 많아요. Endpoint DSL과 DataFormat DSL을 쓰면 자바에서 엔드포인트와 데이터 포맷을 _타입 세이프_하게 설정할 수도 있어요.

옵션을 설정할 때 좋은 습관은 Property Placeholders를 사용하는 거예요.

프로퍼티 플레이스홀더는 이런 장점이 있어요:

URL, 포트 번호, 민감한 정보 같은 설정을 하드코딩하는 걸 막아 줘요.
설정을 코드 밖으로 분리할 수 있어요.
코드가 더 유연해지고 재사용하기 좋아져요.

다음 두 섹션에서 모든 옵션을 나열해요. 먼저 컴포넌트 옵션, 그다음 엔드포인트 옵션 순서예요.

컴포넌트 옵션 (Component Options)

FTPS 컴포넌트가 지원하는 옵션은 아래 나열된 것과 같아요.

Name	Description	Default	Type
bridgeErrorHandler (consumer)	컨슈머를 Camel 라우팅 에러 핸들러(Error Handler)에 브리지할 수 있게 해줘요. 즉 Camel 컨슈머가 들어오는 메시지를 집어 올리는 동안 등에서 (가능한 경우) 예외가 발생하면, 그 예외를 메시지로 처리해서 라우팅 에러 핸들러가 다루게 돼요. 중요: 서드파티 컴포넌트가 예외가 던져졌을 때 Camel에 알릴 수 있도록 허용하는 경우에만 가능해요. 일부 컴포넌트는 내부에서만 처리하기 때문에 bridgeErrorHandler를 쓸 수 없어요. 다른 상황에서는 이를 가능하게 하려고 Camel 컴포넌트가 서드파티 컴포넌트에 연결(hook)하도록 개선될 수도 있어요. 기본으로 컨슈머는 org.apache.camel.spi.ExceptionHandler로 예외를 처리하는데, WARN 또는 ERROR 레벨로 로그를 남기고 무시해요.	false	boolean
lazyStartProducer (producer)	producer를 lazy(첫 메시지 시점)로 시작할지 여부예요. lazy 시작을 쓰면 producer가 시작 중 실패해서 라우트 시작이 실패할 수 있는 상황에서도 CamelContext와 라우트가 시작될 수 있고, 시작 실패 처리를 Camel의 라우팅 에러 핸들러로 넘길 수 있어요. 다만 첫 메시지를 처리하는 시점에 producer를 만들고 시작하는 데 시간이 좀 걸려 전체 처리 시간이 길어질 수 있는 점은 유의하세요.	false	boolean
autowiredEnabled (advanced)	오토와이어링 사용 여부예요. 레지스트리에서 일치하는 타입의 인스턴스가 하나만 있는지 찾아 컴포넌트에 자동으로 설정하는(옵션이 autowired로 표시돼 있어야 함) 자동 오토와이어링에 쓰입니다. JDBC 데이터 소스, JMS 커넥션 팩토리, AWS 클라이언트 등을 자동 설정할 때 유용해요.	true	boolean
healthCheckConsumerEnabled (health)	이 컴포넌트의 consumer 기반 헬스 체크를 모두 켜고 끄는 데 써요.	true	boolean
healthCheckProducerEnabled (health)	이 컴포넌트의 producer 기반 헬스 체크를 모두 켜고 끄는 데 써요. 참고: Camel은 기본으로 producer 기반 헬스 체크를 모두 꺼두고, camel.health.producersEnabled=true로 설정하면 전역으로 켤 수 있어요.	true	boolean
useGlobalSslContextParameters (security)	전역 SSL 컨텍스트 파라미터 사용을 켜요.	false	boolean

엔드포인트 옵션 (Endpoint Options)

FTPS 엔드포인트는 다음 URI 문법으로 설정해요:

ftps:host:port/directoryName

다음 path 및 query 파라미터를 사용해요:

경로 파라미터 (Path Parameters)

Name	Description	Type
host (common)	필수 FTP 서버의 호스트 이름이에요.	String
port (common)	FTP 서버의 포트예요.	int
directoryName (common)	시작 디렉터리예요.	String

쿼리 파라미터 (Query Parameters)

Name	Description	Default	Type
binary (common)	파일 전송 모드를 지정해요. BINARY 또는 ASCII. 기본은 ASCII(false)예요.	false	boolean
charset (common)	파일의 인코딩을 지정하는 옵션이에요. consumer에서는 파일의 인코딩을 지정해서, 파일 내용에 접근할 때 Camel이 어떤 문자셋으로 내용을 불러와야 하는지 알 수 있게 해줘요. 마찬가지로 파일을 쓸 때도 이 옵션으로 어떤 문자셋으로 쓸지 지정할 수 있어요. 다만 파일을 쓸 때는 설정한 문자셋으로 데이터를 변환하려고 메시지 내용을 메모리로 읽어 들여야 할 수 있으니, 큰 메시지에는 이 옵션을 쓰지 마세요.		String
disconnect (common)	사용 직후 원격 FTP 서버와 연결을 끊을지 여부예요. disconnect는 현재 FTP 서버 연결만 끊어요. 멈추고 싶은 consumer가 있다면 consumer/route를 멈추는 쪽이 맞아요.	false	boolean
doneFileName (common)	producer: 설정하면 원본 파일을 쓴 뒤 두 번째 done 파일을 써요. done 파일은 비어 있어요. 이 옵션으로 그 파일 이름을 정하는데, 고정 이름을 지정하거나 동적 플레이스홀더를 쓸 수 있어요. done 파일은 항상 원본 파일과 같은 폴더에 쓰입니다. consumer: 설정하면 done 파일이 존재할 때만 파일을 소비해요. 이 옵션으로 그 파일 이름을 정하고, 고정 이름이나 동적 플레이스홀더를 쓸 수 있어요. done 파일은 항상 원본 파일과 같은 폴더에 있는 걸로 기대해요. 동적 플레이스홀더는 ${file.name}과 ${file.name.next}만 지원해요.		String
fileName (common)	File Language 같은 Expression으로 파일 이름을 동적으로 설정해요. consumer에서는 파일 이름 필터로, producer에서는 쓸 파일 이름을 평가하는 데 써요. 표현식이 설정되면 CamelFileName 헤더보다 우선해요(참고: 헤더 자체도 Expression일 수 있어요). 표현식 옵션은 String과 Expression 타입을 모두 지원하는데, String이면 항상 File Language로 평가하고 Expression 타입이면 지정한 Expression 타입을 써서(예: OGNL 표현식도 가능) 평가해요. consumer에서는 파일 이름을 걸러 내는 데 쓸 수 있어서, 예컨대 File Language 문법 mydata-${date:now:yyyyMMdd}.txt로 오늘 파일을 소비할 수 있어요. producer는 CamelOverruleFileName 헤더를 지원하는데, 기존 CamelFileName 헤더보다 우선하며 한 번만 쓰이고 나면 제거돼서 CamelFileName을 임시로 저장했다가 복원하는 번거로움을 피하게 해줘요.		String
jailStartingDirectory (common)	파일 쓰기를 시작 디렉터리(및 하위)로만 제한(jail)하는 데 쓰여요. 기본으로 켜져 있어서 Camel이 바깥 디렉터리에 파일을 쓰지 못하게 막아요(기본 설정이 더 안전해서예요). 끄면 부모나 루트 폴더 같은 시작 디렉터리 밖의 디렉터리에 파일을 쓸 수 있어요. localWorkDirectory를 쓰는 consumer에서는 다운로드한 파일도 설정한 localWorkDirectory 안에 머물도록 제한해요.	true	boolean
passiveMode (common)	패시브 모드 연결을 설정해요. 기본은 액티브 모드 연결이에요.	false	boolean
separator (common)
사용할 경로 구분자(path separator)를 설정해요. UNIX = 유닉스 스타일 경로 구분자를 써요. Windows = 윈도우 스타일 경로 구분자를 써요. Auto = (기본값) 파일 이름에 이미 있는 경로 구분자를 그대로 써요.

Enum values:

UNIX
Windows
Auto

업로드와 다운로드 작업의 진행 상황을 로그로 남길 때 쓸 로깅 레벨을 설정해요.

Enum values:

TRACE
DEBUG
INFO
WARN
ERROR
OFF

pre-sort가 켜져 있으면 consumer가 파일 시스템에서 가져온 파일과 디렉터리 이름을 폴링 중에 정렬해요. 파일을 정렬된 순서로 다뤄야 할 때 필요할 수 있어요. pre-sort는 consumer가 파일을 걸러서 Camel이 처리할 파일로 받아들이기 전에 실행돼요. 이 옵션은 기본 false로 꺼져 있어요. 지원 값은 이래요: name(파일 이름 정렬), modified(마지막 수정 타임스탬프 정렬), size(파일 크기 정렬). 내림차순(역순)으로 정렬하려면 값 앞에 마이너스 기호를 붙이세요(예: -modified는 최신 파일 먼저). true는 name의 별칭이에요(하위 호환).

Enum values:

true
false
name
-name
modified
-modified
size
-size

| | String | | recursive (consumer) | 디렉터리라면 모든 하위 디렉터리의 파일도 찾아요. | false | boolean | | resumeDownload (consumer) | 이어받기(resume download)를 켤지 설정해요. FTP 서버가 이를 지원해야 해요(거의 모든 FTP 서버가 지원해요). 또한 다운로드한 파일을 로컬 디렉터리에 저장하도록 localWorkDirectory 옵션을 설정해야 하고, 이어받기에 필요하니 binary 옵션도 켜야 해요. | false | boolean | | sendEmptyMessageWhenIdle (consumer) | 폴링 consumer가 파일을 하나도 폴링하지 못했을 때 이 옵션을 켜면 빈 메시지(본문 없음)를 대신 보내요. | false | boolean | | streamDownload (consumer) | 로컬 작업 디렉터리를 쓰지 않을 때의 다운로드 방식을 설정해요. true면 원격 파일을 읽는 대로 라우트로 스트리밍해요. false면 원격 파일을 라우트에 넣기 전에 메모리로 불러와요. 이 옵션을 켜면 stepwise=false로 설정해야 해요. 둘은 동시에 쓸 수 없거든요. | false | boolean | | bridgeErrorHandler (consumer (advanced)) | 컨슈머를 Camel 라우팅 에러 핸들러(Error Handler)에 브리지할 수 있게 해줘요. 즉 Camel 컨슈머가 들어오는 메시지를 집어 올리는 동안 등에서 (가능한 경우) 예외가 발생하면, 그 예외를 메시지로 처리해서 라우팅 에러 핸들러가 다루게 돼요. 중요: 서드파티 컴포넌트가 예외가 던져졌을 때 Camel에 알릴 수 있도록 허용하는 경우에만 가능해요. 일부 컴포넌트는 내부에서만 처리하기 때문에 bridgeErrorHandler를 쓸 수 없어요. 다른 상황에서는 이를 가능하게 하려고 Camel 컴포넌트가 서드파티 컴포넌트에 연결(hook)하도록 개선될 수도 있어요. 기본으로 컨슈머는 org.apache.camel.spi.ExceptionHandler로 예외를 처리하는데, WARN 또는 ERROR 레벨로 로그를 남기고 무시해요. | false | boolean | | download (consumer (advanced)) | FTP consumer가 파일을 다운로드할지 여부예요. false로 하면 메시지 본문은 null이지만, consumer는 여전히 파일 이름·파일 크기 등 파일 정보를 담은 Camel Exchange를 발생시켜요. 다만 파일 자체는 다운로드하지 않아요. | false | boolean | | exceptionHandler (consumer (advanced)) | consumer가 커스텀 ExceptionHandler를 쓰게 해줘요. bridgeErrorHandler 옵션이 켜져 있으면 이 옵션은 쓰이지 않아요. 기본으로 컨슈머는 예외를 WARN 또는 ERROR 레벨로 기록하고 무시해요. | | ExceptionHandler | | exchangePattern (consumer (advanced)) |

consumer가 exchange를 만들 때 교환 패턴을 설정해요.

Enum values:

InOnly
InOut

| | ExchangePattern | | handleDirectoryParserAbsoluteResult (consumer (advanced)) | 디렉터리 파서가 절대 경로를 돌려줄 때 consumer가 경로 안의 하위 폴더와 파일을 어떻게 다룰지 설정해요. 일부 FTP 서버는 파일 이름을 절대 경로로 돌려줄 수 있어서, 그런 경우 FTP 컴포넌트가 돌려받은 경로를 상대 경로로 바꿔 처리해야 하기 때문이에요. | false | boolean | | ignoreFileNotFoundOrPermissionError (consumer (advanced)) | 디렉터리의 파일을 나열하거나 파일을 다운로드할 때 파일이 없거나 권한 오류가 나면 무시할지 여부예요. 기본으로는 디렉터리나 파일이 없거나 권한이 부족하면 예외를 던져요. 이 옵션을 true로 하면 그런 상황을 무시해요. | false | boolean | | inProgressRepository (consumer (advanced)) | 플러그 가능한 in-progress 리포지터리(org.apache.camel.spi.IdempotentRepository)예요. in-progress 리포지터리는 현재 소비 중인 파일을 기록하는 데 쓰여요. 기본은 메모리 기반 리포지터리예요. | | IdempotentRepository | | localWorkDirectory (consumer (advanced)) | 소비할 때 로컬 작업 디렉터리를 쓰면 원격 파일 내용을 메모리로 불러오지 않고 바로 로컬 파일에 저장할 수 있어요. 아주 큰 원격 파일을 소비할 때 메모리를 아낄 수 있어서 유익해요. | | String | | onCompletionExceptionHandler (consumer (advanced)) | consumer가 commit 또는 rollback을 수행하는 파일 onCompletion 과정에서 던져지는 예외를 처리하려고 커스텀 org.apache.camel.spi.ExceptionHandler를 쓰게 해줘요. 기본 구현은 예외를 WARN 레벨로 기록하고 무시해요. | | ExceptionHandler | | pollStrategy (consumer (advanced)) | org.apache.camel.PollingConsumerPollingStrategy를 플러그인으로 제공해서, Exchange가 만들어져 Camel에서 라우팅되기 전에 폴링 작업 중에 주로 일어나는 오류 처리를 직접 제어할 수 있어요. | | PollingConsumerPollStrategy | | processStrategy (consumer (advanced)) | org.apache.camel.component.file.GenericFileProcessStrategy를 플러그인으로 제공해서 자신만의 readLock 옵션 등을 구현할 수 있어요. 특별한 ready 파일이 존재해야 한다 같은 특수 조건을 충족해야 파일을 소비할 수 있을 때도 쓸 수 있어요. 이 옵션을 설정하면 readLock 옵션은 적용되지 않아요. | | GenericFileProcessStrategy | | throwExceptionOnConnectFailed (consumer (advanced)) | 연결 실패(소진) 시 예외를 던질지 여부예요. 기본은 예외를 던지지 않고 WARN을 기록해요. 이 옵션을 켜면 예외가 던져지게 하고, org.apache.camel.spi.PollingConsumerPollStrategy의 rollback 메서드에서 던져진 예외를 처리할 수 있어요. | false | boolean | | useList (consumer (advanced)) | 파일을 다운로드할 때 LIST 명령 사용을 허용할지 여부예요. 기본은 true예요. 특정 파일만 다운로드하고 싶은데 LIST 명령 사용이 허용되지 않는 사용 사례가 있어서, 그럴 때 이 옵션을 false로 하면 돼요. 이 옵션을 쓰면 다운로드할 특정 파일에 파일 크기·타임스탬프·권한 같은 메타데이터 정보가 없다는 점에 유의하세요. 그 정보들은 LIST 명령을 쓸 때만 가져올 수 있어요. | true | boolean | | checksumFileAlgorithm (producer) |

설정하면 Camel이 쓴 파일로 체크섬을 계산해서 그 결과를 CamelFileChecksum 헤더에 저장해요.

Enum values:

MD2
MD5
SHA_1
SHA_224
SHA_256
SHA_384
SHA_512
SHA_512_224
SHA_512_256
SHA3_224
SHA3_256
SHA3_384
SHA3_512

같은 이름의 파일이 이미 있을 때 어떻게 할지 정해요. 기본인 Override는 기존 파일을 대체해요. - Append - 기존 파일에 내용을 추가해요. - Fail - 이미 파일이 존재한다는 뜻의 GenericFileOperationException을 던져요. - Ignore - 문제를 조용히 무시하고 기존 파일을 대체하지 않지만 모두 잘 된 것으로 간주해요. - Move - moveExisting 옵션도 함께 설정해야 해요. eagerDeleteTargetFile 옵션으로 파일을 옮길 때 기존 파일이 이미 있을 때의 동작을 제어할 수 있고, 설정하지 않으면 move 작업이 실패해요. Move 옵션은 대상 파일을 쓰기 전에 기존 파일들을 옮겨요. - TryRename은 tempFileName 옵션을 쓸 때만 적용돼요. 존재 검사 없이 임시 이름에서 실제 이름으로 이름 바꾸기를 시도하게 해줘요. 이 검사는 일부 파일 시스템, 특히 FTP 서버에서 더 빠를 수 있어요.

Enum values:

Override
Append
Fail
Ignore
Move
TryRename

| Override | GenericFileExist | | flatten (producer) | 파일 이름 경로를 평탄화해서 선행 경로를 벗기고 파일 이름만 남겨요. 이러면 하위 디렉터리까지 재귀적으로 소비하면서도, 다른 디렉터리에 쓸 때는 파일이 한 디렉터리에 담기게 돼요. producer에서 true로 하면 CamelFileName 헤더의 어떤 파일 이름에서도 선행 경로가 제거돼요. | false | boolean | | moveExisting (producer) | fileExist=Move가 설정됐을 때 옮길 파일 이름을 계산하는 데 쓰는 표현식(File Language 같은)이에요. 파일을 backup 하위 디렉터리로 옮기려면 그냥 backup만 입력하면 돼요. 이 옵션은 file:name, file:name.ext, file:name.noext, file:onlyname, file:onlyname.noext, file:ext, file:parent File Language 토큰만 지원해요. FTP 컴포넌트는 현재 디렉터리를 기준으로 한 상대 디렉터리로만 기존 파일을 옮길 수 있어서 file:parent는 지원하지 않는 점에 유의하세요. | | String | | tempFileName (producer) | tempPrefix 옵션과 같지만 File Language를 쓰기 때문에 임시 파일 이름을 더 세밀하게 제어할 수 있어요. tempFilename의 위치는 기본 URI의 대상 디렉터리가 아니라 'fileName' 옵션의 최종 파일 위치를 기준으로 해요. 예컨대 fileName 옵션에 dir/finalFilename처럼 디렉터리 접두어가 들어 있으면 tempFileName은 그 하위 디렉터리 dir 기준이에요. | | String | | tempPrefix (producer) | 임시 이름으로 파일을 쓰고, 쓰기가 끝난 뒤 실제 이름으로 이름을 바꾸는 옵션이에요. 쓰기 중인 파일을 식별하는 데 쓸 수 있고, (배타적 읽기 잠금을 쓰지 않는) consumer가 쓰기 중인 파일을 읽는 걸 피하게 해줘요. 큰 파일을 업로드할 때 FTP에서 자주 쓰는 방식이에요. | | String | | allowNullBody (producer (advanced)) | 파일 쓰기 중 null 본문을 허용할지 지정해요. true면 빈 파일이 만들어지고, false인 상태로 null 본문을 파일 컴포넌트에 보내려 하면 'Cannot write null body to file.'이라는 GenericFileWriteException이 던져져요. fileExist 옵션이 'Override'면 파일이 잘리고(truncate), append면 파일은 그대로 유지돼요. | false | boolean | | chmod (producer (advanced)) | 저장되는 파일에 chmod를 설정하게 해줘요. 예컨대 chmod=640처럼 쓰면 돼요. | | String | | disconnectOnBatchComplete (producer (advanced)) | 배치 업로드가 끝나자마자 원격 FTP 서버와 연결을 끊을지 여부예요. disconnectOnBatchComplete는 현재 FTP 서버 연결만 끊어요. | false | boolean | | eagerDeleteTargetFile (producer (advanced)) | 기존 대상 파일을 미리(eagerly) 삭제할지 여부예요. fileExists=Override와 tempFileName 옵션을 함께 쓸 때만 적용돼요. 임시 파일을 쓰기 전에 대상 파일을 삭제하지 않으려면(false로 설정) 이걸 쓰세요. 예컨대 큰 파일을 쓰면서 임시 파일을 쓰는 동안 대상 파일이 남아 있길 원할 수 있죠. 이러면 대상 파일은 임시 파일이 대상 파일 이름으로 바뀌기 직전, 아주 마지막 순간까지 삭제되지 않아요. fileExist=Move가 켜져 있고 기존 파일이 있을 때 기존 파일을 삭제할지도 이 옵션이 제어해요. 이 옵션의 copyAndDeleteOnRenameFails가 false면 기존 파일이 있을 때 예외가 던져지고, true면 move 작업 전에 기존 파일이 삭제돼요. | true | boolean | | keepLastModified (producer (advanced)) | 원본 파일의 마지막 수정 타임스탬프가 있으면 그걸 유지해요. 타임스탬프를 찾으려고 FileConstants.FILE_LAST_MODIFIED 헤더를 쓰는데, 이 헤더는 java.util.Date나 타임스탬프를 담은 long을 가질 수 있어요. 타임스탬프가 존재하고 이 옵션이 켜져 있으면 쓴 파일에 그 타임스탬프를 설정해요. 참고: 이 옵션은 파일 producer에만 적용되고 FTP 계열 producer에는 쓸 수 없어요. | false | boolean | | lazyStartProducer (producer (advanced)) | producer를 lazy(첫 메시지 시점)로 시작할지 여부예요. lazy 시작을 쓰면 producer가 시작 중 실패해서 라우트 시작이 실패할 수 있는 상황에서도 CamelContext와 라우트가 시작될 수 있고, 시작 실패 처리를 Camel의 라우팅 에러 핸들러로 넘길 수 있어요. 다만 첫 메시지를 처리하는 시점에 producer를 만들고 시작하는 데 시간이 좀 걸려 전체 처리 시간이 길어질 수 있는 점은 유의하세요. | false | boolean | | moveExistingFileStrategy (producer (advanced)) | fileExist=Move가 설정됐을 때 특수 이름 토큰으로 파일을 옮기는 데 쓰는 전략(Custom Strategy)이에요. 커스텀 전략을 제공하지 않으면 기본 구현이 쓰여요. | | FileMoveExistingStrategy | | sendNoop (producer (advanced)) | FTP 서버에 파일을 올리기 전에 pre-write 검사로 noop 명령을 보낼지 여부예요. 연결이 아직 유효한지 검증하는 기본 동작이고, 이 덕분에 조용히 재연결해서 파일을 올릴 수 있어요. 다만 문제가 생기면 이 옵션을 끄면 돼요. | true | boolean | | activePortRange (advanced) | 액티브 모드에서 클라이언트 쪽 포트 범위를 설정해요. 문법은 minPort-maxPort이고 두 포트 번호 모두 포함 범위예요. 예컨대 10000-19999로 하면 1xxxx 포트 전부를 포함해요. | | String | | autoCreate (advanced) | 파일 경로에 없는 디렉터리를 자동으로 만들어요. 파일 consumer에서는 시작 디렉터리 만들기를, 파일 producer에서는 파일이 쓰일 디렉터리 만들기를 뜻해요. | true | boolean | | browseLimit (advanced) | 브라우징용으로 메모리에 유지할 최대 메시지 수예요. 무제한은 0. | 100 | int | | bufferSize (advanced) | 파일을 쓸 때(FTP의 경우 파일을 업/다운로드할 때) 쓰는 버퍼 크기(바이트)예요. | 131072 | int | | connectTimeout (advanced) | 연결이 맺어지기를 기다리는 연결 타임아웃을 설정해요. FTPClient와 JSCH 둘 다 써요. | 10000 | int | | ftpClient (advanced) | 커스텀 FTPClient 인스턴스를 쓰게 해줘요. | | FTPClient | | ftpClientConfig (advanced) | 엔드포인트가 쓸 FTP 클라이언트를 설정하려고 커스텀 FTPClientConfig 인스턴스를 쓰게 해줘요. | | FTPClientConfig | | ftpClientConfigParameters (advanced) | FtpComponent가 FTPClientConfig에 추가 파라미터를 제공하는 데 써요. 접두어가 ftpClientConfig인 다중 값 옵션이에요. | | Map | | ftpClientParameters (advanced) | FtpComponent가 FTPClient에 추가 파라미터를 제공하는 데 써요. 접두어가 ftpClient인 다중 값 옵션이에요. | | Map | | maximumReconnectAttempts (advanced) | 원격 FTP 서버에 연결하려고 시도할 때 Camel이 수행할 최대 재연결 시도 횟수를 지정해요. 이 동작을 끄려면 0을 쓰세요. | | int | | reconnectDelay (advanced) | 재연결 시도 전에 Camel이 기다릴 지연(밀리초)이에요. | 1000 | long | | siteCommand (advanced) | 로그인에 성공한 뒤 실행할 선택적 site 명령(들)을 설정해요. 여러 site 명령은 줄바꿈 문자로 구분할 수 있어요. | | String | | soTimeout (advanced) | FTP와 FTPS의 so 타임아웃을 설정해요. 밀리초 단위의 SocketOptions.SO_TIMEOUT 값이에요. 연결이 매달리는 일을 막으려면 300000으로 설정하는 걸 권해요. SFTP에서는 이 옵션이 JSCH Session 인스턴스의 타임아웃으로 설정돼요. | 300000 | int | | stepwise (advanced) | 파일을 다운로드할 때, 또는 디렉터리에 파일을 업로드할 때 파일 구조를 순회하며 디렉터리를 단계적(stepwise)으로 바꿀지 설정해요. 보안 문제로 FTP 서버에서 디렉터리를 바꿀 수 없는 상황이라면 끌 수 있어요. stepwise는 streamDownload와 함께 쓸 수 없어요. | true | boolean | | timeout (advanced) | 응답을 기다리는 데이터 타임아웃을 설정해요. FTPClient만 써요. | 30000 | int | | antExclude (filter) | Ant 스타일 필터 제외예요. antInclude와 antExclude를 둘 다 쓰면 antExclude가 antInclude보다 우선해요. 여러 개는 쉼표로 구분해서 지정할 수 있어요. | | String | | antFilterCaseSensitive (filter) | ant 필터에 대소문자 구분 플래그를 설정해요. | true | boolean | | antInclude (filter) | Ant 스타일 필터 포함이에요. 여러 개는 쉼표로 구분해서 지정할 수 있어요. | | String | | eagerMaxMessagesPerPoll (filter) | maxMessagesPerPoll의 한도를 이른(eager) 방식으로 적용할지 제어해요. 이른 방식이면 파일을 스캔하는 동안 한도를 적용하고, false면 모든 파일을 스캔한 뒤 정렬해요. false로 하면 모든 파일을 먼저 정렬한 다음 폴링 한도를 적용할 수 있어요. 다만 정렬을 위해 모든 파일 정보가 메모리에 있어야 하니 메모리 사용량이 더 커진다는 점은 유의하세요. | true | boolean | | exclude (filter) | 파일 이름이 정규식 패턴과 매칭되면(대소문자 무시) 파일을 제외하는 데 써요. 플러스 기호 같은 기호를 쓴다면 엔드포인트 URI로 설정할 때 RAW() 문법으로 설정해야 해요. 자세한 내용은 configuring endpoint uris 문서를 보세요. | | String | | excludeExt (filter) | 파일 확장자 이름으로(대소문자 무시) 파일을 제외하는 데 써요. 예컨대 bak 파일을 제외하려면 excludeExt=bak으로 해요. 확장자는 쉼표로 여러 개 쓸 수 있어서, bak과 dat 파일을 제외하려면 excludeExt=bak,dat으로 해요. 파일 확장자는 모든 부분을 포함한다는 점에 유의하세요. 예컨대 mydata.tar.gz 파일의 확장자는 tar.gz이에요. 더 유연하게 쓰려면 include/exclude 옵션을 쓰세요. | | String | | filter (filter) | org.apache.camel.component.file.GenericFileFilter 클래스로 제공하는 플러그 가능 필터예요. accept() 메서드가 false를 반환하면 파일을 건너뛰어요. | | GenericFileFilter | | filterDirectory (filter) | Simple 언어 기반으로 디렉터리를 필터링해요. 예컨대 현재 날짜로 필터링하려면 ${date:now:yyyMMdd} 같은 간단한 날짜 패턴을 쓸 수 있어요. | | String | | filterFile (filter) | Simple 언어 기반으로 파일을 필터링해요. 예컨대 파일 크기로 필터링하려면 ${file:size} 5000처럼 쓸 수 있어요. | | String | | idempotent (filter) | Idempotent Consumer EIP 패턴을 써서 Camel이 이미 처리한 파일은 건너뛰게 하는 옵션이에요. 기본으로 1000개 항목을 담는 메모리 기반 LRUCache를 써요. noop=true면 같은 파일을 반복해서 소비하지 않도록 idempotent도 함께 켜져요. | false | Boolean | | idempotentEager (filter) | 파일 이름을 idempotent 리포지터리에 즉시(eagerly) 추가할지, exchange가 끝날 때까지 기다릴지 설정해요. | true | Boolean | | idempotentKey (filter) | 커스텀 idempotent 키를 쓰게 해줘요. 기본은 파일의 절대 경로예요. File Language를 쓸 수 있어서, 예컨대 파일 이름과 파일 크기를 키로 쓰려면 idempotentKey=${file:name}-${file:size}처럼 하면 돼요. | | String | | idempotentRepository (filter) | 플러그 가능한 리포지터리(org.apache.camel.spi.IdempotentRepository)예요. 지정하지 않고 idempotent가 true면 기본으로 MemoryIdempotentRepository를 써요. | | IdempotentRepository | | include (filter) | 파일 이름이 정규식 패턴과 매칭되면(대소문자 무시) 파일을 포함하는 데 써요. 플러스 기호 같은 기호를 쓴다면 엔드포인트 URI로 설정할 때 RAW() 문법으로 설정해야 해요. 자세한 내용은 configuring endpoint uris 문서를 보세요. | | String | | includeExt (filter) | 파일 확장자 이름으로(대소문자 무시) 파일을 포함하는 데 써요. 예컨대 txt 파일을 포함하려면 includeExt=txt으로 해요. 확장자는 쉼표로 여러 개 쓸 수 있어서, txt와 xml 파일을 포함하려면 includeExt=txt,xml으로 해요. 파일 확장자는 모든 부분을 포함한다는 점에 유의하세요. 예컨대 mydata.tar.gz 파일의 확장자는 tar.gz이에요. 더 유연하게 쓰려면 include/exclude 옵션을 쓰세요. | | String | | maxDepth (filter) | 디렉터리를 재귀적으로 처리할 때 탐색할 최대 깊이예요. | 2147483647 | int | | maxMessagesPerPoll (filter) | 폴링마다 모을 최대 메시지 수를 정의해요. 기본은 무제한이에요. 서버 시작 시 수천 개 파일이 있는 상황을 피하려고 예컨대 1000으로 한도를 정하는 데 쓸 수 있어요. 0이나 음수는 끄는 거예요. 참고: 이 옵션을 쓰면 File과 FTP 컴포넌트가 정렬 전에 한도를 적용해요. 예컨대 100000개 파일에 maxMessagesPerPoll=500을 쓰면 먼저 500개 파일만 집어 올린 다음 정렬해요. eagerMaxMessagesPerPoll 옵션을 false로 설정하면 모든 파일을 먼저 스캔한 다음 정렬하게 할 수 있어요. | | int | | minDepth (filter) | 디렉터리를 재귀적으로 처리할 때 처리를 시작할 최소 깊이예요. minDepth=1은 기본 디렉터리, minDepth=2는 첫 하위 디렉터리를 뜻해요. | | int | | move (filter) | 처리 후에 파일을 옮길 때 파일 이름을 동적으로 정하는 데 쓰는 표현식(Simple Language 같은)이에요. 파일을 .done 하위 디렉터리로 옮기려면 그냥 .done만 입력하면 돼요. | | String | | exclusiveReadLockStrategy (lock) | org.apache.camel.component.file.GenericFileExclusiveReadLockStrategy 구현으로 제공하는 플러그 가능 읽기 잠금(read-lock)이에요. | | GenericFileExclusiveReadLockStrategy | | readLock (lock) |

consumer가 파일에 배타적 읽기 잠금을 쥐고 있을 때만(즉 파일이 처리 중이거나 쓰이는 중이 아닐 때) 파일을 폴링하는 데 써요. Camel은 파일 잠금이 허용될 때까지 기다려요. 이 옵션이 제공하는 내장 전략은 이래요: - none - 읽기 잠금을 쓰지 않아요. - markerFile - Camel이 마커 파일(fileName.camelLock)을 만들고 그 파일을 잠가요. 이 옵션은 FTP 컴포넌트에서는 쓸 수 없어요. - changed - 파일 길이/수정 타임스탬프로 파일이 현재 복사 중인지 탐지해요. 판단에 최소 1초를 쓰기 때문에 다른 방식만큼 빠르게 파일을 소비할 수는 없지만, JDK IO API가 파일이 다른 프로세스에 쓰이는 중인지 늘 정확히 알 수 있는 건 아니라서 더 신뢰할 수 있을 때가 있어요. readLockCheckInterval 옵션으로 검사 빈도를 정할 수 있어요. - fileLock - java.nio.channels.FileLock을 쓰는 방식이에요. Windows OS와 FTP 컴포넌트에서는 쓸 수 없어요. mount/share로 원격 파일 시스템에 접근할 때는 그 파일 시스템이 분산 파일 잠금을 지원하지 않는 한 피해야 해요. - rename - 파일 이름 바꾸기를 시도해서 배타적 읽기 잠금을 얻을 수 있는지 검사하는 방식이에요. - idempotent - (file 컴포넌트 전용) idempotentRepository를 읽기 잠금으로 쓰는 방식이에요. idempotent 리포지터리 구현이 지원한다면 클러스터링을 지원하는 읽기 잠금을 쓸 수 있어요. - idempotent-changed - (file 컴포넌트 전용) idempotentRepository와 changed를 조합한 읽기 잠금이에요. idempotent 리포지터리 구현이 지원한다면 클러스터링을 지원하는 읽기 잠금을 쓸 수 있어요. - idempotent-rename - (file 컴포넌트 전용) idempotentRepository와 rename을 조합한 읽기 잠금이에요. idempotent 리포지터리 구현이 지원한다면 클러스터링을 지원하는 읽기 잠금을 쓸 수 있어요. 참고: 여러 읽기 잠금이 모두 클러스터 모드에 적합한 건 아니에요. 공유 파일 시스템에서 서로 다른 노드의 동시 consumer가 같은 파일을 두고 경쟁하는 상황에서는 말이죠. markerFile은 거의 원자적 작업으로 빈 마커 파일을 만들지만 클러스터에서 동작한다고 보장하긴 어려워요. fileLock이 더 나을 수 있지만 그러려면 파일 시스템이 분산 파일 잠금을 지원해야 하고요. idempotent 읽기 잠금은 idempotent 리포지터리가 Hazelcast Component나 Infinispan 같은 클러스터링을 지원하면 클러스터링을 지원할 수 있어요.

Enum values:

none
markerFile
fileLock
rename
changed
idempotent
idempotent-changed
idempotent-rename

| none | String | | readLockCheckInterval (lock) | 읽기 잠금이 지원하는 경우 읽기 잠금의 간격(밀리초)이에요. 이 간격으로 읽기 잠금 획득 시도 사이에 잠들어요. 예컨대 changed 읽기 잠금을 쓸 때 느린 쓰기에 대응하려고 간격을 더 길게 설정할 수 있어요. 기본 1초는 producer가 파일을 아주 느리게 쓰는 경우 너무 빠를 수 있어요. 참고: FTP의 기본 readLockCheckInterval은 5000이에요. readLockTimeout 값은 readLockCheckInterval보다 커야 하고, 대략 timeout이 check interval의 2배 이상이 되도록 잡는 게 경험칙이에요. 타임아웃에 걸리기 전에 읽기 잠금 과정이 잠금을 잡을 충분한 시간을 갖도록 하기 위해서예요. | 1000 | long | | readLockDeleteOrphanLockFiles (lock) | 마커 파일을 쓰는 읽기 잠금에서, Camel이 제대로 종료되지 않았을 때(JVM 크래시 같은) 파일 시스템에 남을 수 있는 고아(orphan) 읽기 잠금 파일을 시작 시 삭제할지 여부예요. false로 하면 고아 잠금 파일이 남아 있는 파일은 Camel이 집어 올리려 하지 않아요. 이는 다른 노드가 같은 공유 디렉터리에서 동시에 파일을 읽고 있는 경우에도 생길 수 있어요. | true | boolean | | readLockLoggingLevel (lock) |

읽기 잠금을 획득하지 못했을 때 쓰는 로깅 레벨이에요. 기본은 DEBUG예요. 이 레벨을 바꿀 수 있어서, 예컨대 OFF로 하면 로그를 아예 남기지 않아요. 이 옵션은 changed, fileLock, idempotent, idempotent-changed, idempotent-rename, rename 타입의 readLock에만 적용돼요.

Enum values:

TRACE
DEBUG
INFO
WARN
ERROR
OFF

| DEBUG | LoggingLevel | | readLockMarkerFile (lock) | changed, rename 또는 배타적 읽기 잠금 타입에서 마커 파일을 쓸지 여부예요. 기본으로 마커 파일도 써서 다른 프로세스가 같은 파일을 집어 올리지 않게 막아요. Camel 애플리케이션이 파일 시스템에 마커 파일을 쓰지 않게 하고 싶은 등의 경우 이 옵션을 false로 하면 이 동작을 끌 수 있어요. | true | boolean | | readLockMinAge (lock) | readLock=changed일 때만 적용되는 옵션이에요. 읽기 잠금을 시도하기 전에 파일이 지녀야 하는 최소 나이(경과 시간)를 지정할 수 있어요. 예컨대 readLockMinAge=300s로 하면 파일이 최소 5분은 되어야 해요. 조건을 만족하는 파일에만 잠금을 시도하니 changed 읽기 잠금이 빨라질 수 있어요. | 0 | long | | readLockMinLength (lock) | readLock=changed일 때만 적용되는 옵션이에요. 최소 파일 길이를 설정할 수 있어요. 기본으로 Camel은 파일에 데이터가 있으리라 기대하기 때문에 기본값은 1이에요. 이 옵션을 0으로 하면 길이가 0인 파일도 소비할 수 있어요. | 1 | long | | readLockRemoveOnCommit (lock) | readLock=idempotent일 때만 적용되는 옵션이에요. 파일 처리가 성공하고 commit이 일어났을 때 idempotent 리포지터리에서 파일 이름 항목을 제거할지 지정해요. 기본은 제거하지 않는 거예요. 그래야 경합 조건이 생기지 않아서 다른 활성 노드가 그 파일을 획득하려 하지 않아요. 대신 idempotent 리포지터리가 축(eviction) 전략을 지원한다면 X분 후에 파일 이름 항목을 축출하도록 설정할 수 있어요. 이러면 경합 조건 문제가 없어요. 자세한 내용은 readLockIdempotentReleaseDelay 옵션을 보세요. | false | boolean | | readLockRemoveOnRollback (lock) | readLock=idempotent일 때만 적용되는 옵션이에요. 파일 처리가 실패하고 rollback이 일어났을 때 idempotent 리포지터리에서 파일 이름 항목을 제거할지 지정해요. false면 파일 이름 항목이 확인(commit한 것처럼)돼요. | true | boolean | | readLockTimeout (lock) | 읽기 잠금이 지원하는 경우 읽기 잠금의 타임아웃(밀리초) 옵션이에요. 읽기 잠금을 얻지 못하고 타임아웃이 발생하면 Camel은 그 파일을 건너뛰고, 다음 폴링 때 다시 시도해서 이번엔 잠금을 얻을 수도 있어요. 0 이하 값은 영원히 기다린다는 뜻이에요. 현재 fileLock, changed, rename이 타임아웃을 지원해요. 참고: FTP의 기본 readLockTimeout은 10000이 아니라 20000이에요. readLockTimeout 값은 readLockCheckInterval보다 커야 하고, 대략 timeout이 check interval의 2배 이상이 되도록 잡는 게 경험칙이에요. 타임아웃에 걸리기 전에 읽기 잠금 과정이 잠금을 잡을 충분한 시간을 갖도록 하기 위해서예요. | 10000 | long | | backoffErrorThreshold (scheduler) | backoffMultiplier가 작동하기 전에 연속으로 몇 번의 오류 폴링(오류로 실패한 폴링)이 일어나야 하는지예요. | | int | | backoffIdleThreshold (scheduler) | backoffMultiplier가 작동하기 전에 연속으로 몇 번의 유휴(idle) 폴링이 일어나야 하는지예요. | | int | | backoffMultiplier (scheduler) | 연속으로 유휴/오류 폴링이 여러 번 일어나면 예약 폴링 consumer가 백오프하게 해줘요. 승수(multiplier)는 다음 실제 시도 전에 건너뛸 폴링 횟수예요. 이 옵션을 쓸 때는 backoffIdleThreshold와(또는) backoffErrorThreshold도 함께 설정해야 해요. | | int | | delay (scheduler) | 다음 폴링 전의 대기 시간(밀리초)이에요. | 500 | long | | greedy (scheduler) | greedy가 켜져 있으면 이전 실행이 1개 이상의 메시지를 폴링했을 때 ScheduledPollConsumer가 바로 다시 실행돼요. | false | boolean | | initialDelay (scheduler) | 첫 폴링이 시작되기 전의 대기 시간(밀리초)이에요. | 1000 | long | | repeatCount (scheduler) | 실행(fire) 횟수의 최대 한도를 지정해요. 1로 하면 스케줄러가 한 번만 실행되고, 5로 하면 다섯 번만 실행돼요. 0이나 음수는 영원히 실행한다는 뜻이에요. | 0 | long | | runLoggingLevel (scheduler) |

consumer가 폴링할 때 시작/완료 로그 한 줄을 남겨요. 이 옵션으로 그 로그의 레벨을 설정할 수 있어요.

Enum values:

TRACE
DEBUG
INFO
WARN
ERROR
OFF

initialDelay와 delay 옵션의 시간 단위예요.

Enum values:

NANOSECONDS
MICROSECONDS
MILLISECONDS
SECONDS
MINUTES
HOURS
DAYS

메시지 헤더 (Message Headers)

FTPS 컴포넌트가 지원하는 메시지 헤더(들)는 아래 나열된 것과 같아요:

Name	Description	Type
CamelFileLength (consumer) Constant: `FILE_LENGTH`	파일 크기를 담은 long 값이에요.	long
CamelFileLastModified (consumer) Constant: `FILE_LAST_MODIFIED`	파일의 마지막 수정 타임스탬프를 담은 Long 값이에요.	long
CamelFileNameOnly (consumer) Constant: `FILE_NAME_ONLY`	파일 이름만(선행 경로 없는 이름) 담아요.	String
CamelFileName (common) Constant: `FILE_NAME`	(producer) 쓸 파일의 이름을 지정해요(엔드포인트 디렉터리 기준 상대 경로). 이 이름은 String, 파일 또는 simple Language 표현식이 담긴 String, 또는 Expression 객체일 수 있어요. null이면 Camel이 메시지 고유 ID 기반으로 파일 이름을 자동 생성해요. (consumer) 엔드포인트에 설정된 시작 디렉터리를 기준으로 한 상대 파일 경로로 나타낸 소비 파일의 이름이에요.	String
CamelFileNameConsumed (consumer) Constant: `FILE_NAME_CONSUMED`	소비된 파일의 이름이에요.	String
CamelFileAbsolute (consumer) Constant: `FILE_ABSOLUTE`	소비한 파일이 절대 경로인지 나타내는 boolean 옵션이에요. 상대 경로라면 보통 false여야 해요. 절대 경로는 보통 쓰지 않지만, 파일을 절대 경로로 옮길 수 있게 move 옵션에 추가했어요. 다른 곳에서도 쓸 수 있어요.	Boolean
CamelFileAbsolutePath (consumer) Constant: `FILE_ABSOLUTE_PATH`	파일의 절대 경로예요. 상대 파일이라면 이 경로에는 대신 상대 경로가 들어가요.	String
CamelFilePath (consumer) Constant: `FILE_PATH`	파일 경로예요. 상대 파일이면 시작 디렉터리, 절대 파일이면 절대 경로예요.	String
CamelFileRelativePath (consumer) Constant: `FILE_RELATIVE_PATH`	상대 경로예요.	String
CamelFileParent (common) Constant: `FILE_PARENT`	부모 경로예요.	String
CamelFileNameProduced (producer) Constant: `FILE_NAME_PRODUCED`	쓰여진 출력 파일의 실제 절대 파일 경로(path name)예요. 이 헤더는 Camel이 설정하며, 쓰인 파일 이름을 최종 사용자에게 알려주는 게 목적이에요.	String
CamelOverruleFileName (producer) Constant: `OVERRULE_FILE_NAME`	CamelFileName 헤더를 덮어쓰고 그 값을 대신 쓰는 데 쓰여요(producer가 파일을 쓴 뒤 이 헤더를 제거하므로 한 번만 적용돼요). 값은 String만 가능해요. fileName 옵션이 설정돼 있어도 이 값은 여전히 평가된다는 점에 유의하세요.	Object
CamelFileLocalWorkPath (consumer) Constant: `FILE_LOCAL_WORK_PATH`	로컬 작업 디렉터리를 쓸 때 로컬 작업 파일의 경로예요.	String
CamelRemoteFileInputStream (consumer) Constant: `REMOTE_FILE_INPUT_STREAM`	원격 파일 입력 스트림이에요.	InputStream
CamelFileHost (consumer) Constant: `FILE_HOST`	원격 호스트 이름이에요.	String
CamelFtpReplyCode (common) Constant: `FTP_REPLY_CODE`	FTP 클라이언트 응답 코드예요.	int
CamelFtpReplyString (common) Constant: `FTP_REPLY_STRING`	FTP 클라이언트 응답 문자열이에요.	String

더 알아보기 (Learn more)

이 문서는 FTPS 컴포넌트 고유 옵션(보안 데이터 채널·SSL 컨텍스트 등)을 다뤄요. 공통 파일/FTP 동작(이동·잠금·필터링)의 상세는 위 본문에서 FTP 컴포넌트 링크를 참고하고, Camel 컴포넌트 전체 목록은 Camel 컴포넌트 문서에서 확인할 수 있어요.

FTPS 컴포넌트