스크립팅 개요

개요

Fess에서는 다양한 장면에서 스크립트를 사용하여 커스텀 로직을 구현할 수 있습니다. 스크립트를 활용하면 크롤링 시 데이터 가공, URL 변환, 스케줄 작업 실행 등을 유연하게 제어할 수 있습니다.

지원 스크립트 언어

Fess는 다음 스크립트 언어를 지원합니다:

언어 식별자 설명
JavaScript javascript（별칭: js , sai ）

Fess에 기본으로 내장된 스크립트 언어이자 기본 스크립트 언어 （ Constants.DEFAULT_SCRIPT ）입니다. Fess가 DI XML 식 판정에도 사용하고 있는 CodeLibs의 Nashorn 포크인 Sai 위에서 동작하며, 스크립트는 ECMAScript 6로 실행됩니다.
Groovy groovy

fess-script-groovy 플러그인으로 제공됩니다. 플러그인은 배포물에 동봉되지 않으므로 관리 화면 또는 bin/fess-setup install plugin fess-script-groovy 로 설치해야 합니다.

참고

스크립트 설정에 스크립트 타입이 기록되어 있지 않은 경우, 해당 스크립트는 Groovy로 취급됩니다. 이는 일시적인 이행 조치가 아니라 영구적인 사양입니다. 15.9 이전에 작성된 설정은 Groovy 구문의 스크립트를 유지한 채 스크립트 타입이 기록되어 있지 않으므로, 이 기본값 덕분에 업그레이드 후에도 그대로 동작합니다. 15.9 이후에 새로 작성되는 설정에는 스크립트 타입으로 javascript가 명시적으로 기록됩니다.

이 문서의 스크립트 예제는 특별한 언급이 없는 한 JavaScript 구문으로 작성되어 있습니다. Groovy 구문에 대해서는 Groovy 스크립트 가이드를 참조하세요.

스크립트 사용 장면

데이터 스토어 설정

데이터 스토어 커넥터에서는 가져온 데이터를 인덱스 필드에 매핑하기 위해 스크립트를 사용합니다. 설정은 필드명=식 형식으로 한 줄씩 기술하며, 각 줄은 독립된 하나의 스크립트 식으로 평가됩니다（기본값은 JavaScript）.

url=site_url
title=name
content=description
last_modified=updated_at

데이터 스토어 스크립트에서 참조할 수 있는 변수명은 커넥터 종류에 따라 다릅니다. 예를 들어 CSV 데이터 스토어나 JSON 데이터 스토어에서는 각 컬럼명·필드명을 그대로 변수로 사용할 수 있습니다（ data 와 같은 공통 접두사는 붙지 않습니다）. 파일 계열 커넥터（Box, Google Drive, OneDrive 등）에서는 file.*, Slack에서는 message.* 등 커넥터마다 접두사가 다릅니다. 사용 가능한 변수의 자세한 내용은 각 데이터 스토어 커넥터 문서를 참조하세요.

참고

데이터 스토어의 각 줄은 하나의 식으로 평가되기 때문에, 여러 줄에 걸친 if 블록이나 let / const에 의한 변수 선언문은 사용할 수 없습니다. 조건에 따라 값을 변경할 경우에는 필드마다 삼항 연산자를 사용하세요 （예: title=enabled === "true" ? name : null ）. 클래스를 참조할 경우에는 완전 한정 이름（FQCN）을 인라인으로 기술합니다.

경로 매핑

경로 매핑은 크롤링 대상 URL을 정규화·변환하기 위한 기능입니다. 기본적으로는 「정규 표현식」과 「치환 문자열」의 쌍으로 설정하며, 스크립트가 아닙니다. 예를 들어 정규 표현식에 http://, 치환 문자열에 https://를 지정하면 URL의 스킴을 교체할 수 있습니다.

치환 문자열이 （엔진명）:형식으로 시작하는 경우, 콜론 앞부분이 실행할 스크립트 엔진의 이름으로 해석되며, 등록된 엔진명과 일치하면 콜론 이후의 문자열이 해당 엔진의 스크립트로 평가됩니다. 예를 들어 groovy:는 Groovy 엔진（ fess-script-groovy 플러그인 필요）을 선택하고, javascript:（별칭 js: , sai: ）은 JavaScript 엔진을 선택합니다. 콜론 앞부분이 등록된 스크립트 엔진명과 일치하지 않는 경우（예: 일반 치환 문자열에서 콜론 앞이 https처럼 URL 스킴명인 경우 등）에는 스크립트로 취급되지 않고, 문자열 전체가 그대로 정규 표현식의 치환 문자열로 사용됩니다. 스크립트로 평가되는 경우, 그 스크립트 내에서는 변환 대상 URL 문자열을 나타내는 url과, 정규 표현식의 java.util.regex.Matcher를 나타내는 matcher를 사용할 수 있습니다.

javascript:url.replace(/http:\/\//g, "https://")

스케줄 작업

스케줄 작업에서는 커스텀 처리 로직을 스크립트로 작성할 수 있습니다. 스크립트 전체가 하나의 스크립트로 평가되기 때문에, 여러 줄 기술이나（JavaScript의 경우）``let`` / const에 의한 변수 선언, 조건 분기 등도 사용할 수 있습니다.

return container.getComponent("crawlJob").logLevel("info").gcLogging().execute(executor);

JavaScript에서는 일반적으로 최상위 레벨의 return 문은 구문 오류가 되지만, Fess의 스크립트 엔진은 스크립트를 먼저 식으로 해석하려고 시도하고, 그것이 실패한 경우에만 문（스테이트먼트）블록으로 다시 해석합니다. 위 예제는 식으로는 해석할 수 없으므로 문 블록으로 처리되어 그대로 동작합니다. 자세한 내용은 JavaScript 스크립트 가이드를 참조하세요.

logLevel("info") 등의 메서드는 작업 클래스（ ExecJob 및 그 서브클래스）의 메서드이며, 메서드 체인으로 기술할 수 있습니다. executor 변수에 대해서는 「실행 컨텍스트와 사용 가능한 객체」를 참조하세요.

기본 구문

다음은 JavaScript의 기본 구문 예제입니다. 주석은 //（줄 주석）또는 /* */（블록 주석）을 사용합니다. #으로 시작하는 주석은 JavaScript에서도 사용할 수 없다는 점에 주의하세요.

변수 접근

// 데이터 스토어의 필드（CSV/JSON에서는 컬럼명·필드명으로 접근）
title

// DI 컨테이너에서 컴포넌트 취득
container.getComponent("systemHelper")

문자열 조작

// 연결
title + " - " + category

// 치환（정규 표현식 사용. ECMAScript 6에는 String#replaceAll이 없습니다）
content.replace(/old/g, "new")

// 분할
tags.split(",")

조건 분기

// 삼항 연산자
status === "active" ? "유효" : "무효"

// 기본값（논리 OR 연산자. JavaScript에는 Elvis 연산자가 없습니다）
description || "설명 없음"

날짜 조작

// 현재 날짜/시간
new Date()

// 포맷（Java 상호운용은 Groovy와 동일한 표기법을 사용）
new java.text.SimpleDateFormat("yyyy-MM-dd").format(updated_at)

실행 컨텍스트와 사용 가능한 객체

스크립트 내에서 사용할 수 있는 객체는 스크립트를 실행하는 컨텍스트에 따라 다릅니다. container만이 모든 컨텍스트에서 사용 가능합니다.

실행 컨텍스트 사용 가능한 객체 설명
모든 컨텍스트 container

DI 컨테이너. container.getComponent("systemHelper") 나 container.getComponent("fessConfig") 로 각 컴포넌트에 접근 가능
데이터 스토어 스크립트 커넥터 고유의 필드 변수

데이터 스토어에서 가져온 각 필드가 변수로 사용 가능 （변수명·접두사는 커넥터에 따라 다름. CSV/JSON은 필드명이 그대로 변수가 됨）
경로 매핑 url matcher

변환 대상 URL 문자열과 정규 표현식의 Matcher（치환 문자열이 （엔진명）: 형식일 때만. 앞에 붙은 엔진명（ groovy , javascript 등）이 실행 언어를 결정）
스케줄 작업 executor 작업 실행 인스턴스（ JobExecutor ）. 작업의 셧다운 제어에 사용

참고

container 이외의 객체는 특정 컨텍스트에서만 주입됩니다. 예를 들어 executor는 스케줄 작업에서만 사용 가능하며, 데이터 스토어 스크립트나 경로 매핑에서는 사용할 수 없습니다.

보안

경고

스크립트는 강력한 기능을 갖기 때문에 신뢰할 수 있는 소스에서만 사용하세요.

  • 스크립트는 서버에서 실행됩니다

  • 파일 시스템이나 네트워크에 접근할 수 있습니다

  • 관리자 권한을 가진 사용자만 스크립트를 편집할 수 있도록 하세요

  • 스크립트 실행은 감사 로그（ audit.log ）에 기록됩니다. 기록 여부는 script.audit.log.enabled로 제어하며 기본값은 true입니다. 기록되는 스크립트 문자열의 최대 길이는 script.audit.log.max.length로 제어하며 기본값은 100자입니다.

성능

스크립트 성능을 최적화하기 위한 팁:

  1. 복잡한 처리 피하기: 데이터 스토어 스크립트는 문서마다 실행됩니다

  2. 외부 리소스 접근 최소화: 네트워크 호출은 지연의 원인이 됩니다

  3. 캐시 활용: 반복적으로 사용하는 값은 캐시를 검토

디버그

스케줄 작업의 스크립트에서는 스크립트 전체가 하나의 스크립트로 평가되기 때문에 로그 출력을 활용하여 디버깅할 수 있습니다. （데이터 스토어 스크립트는 한 줄이 하나의 식으로 평가되기 때문에 여러 줄의 처리는 사용할 수 없습니다.）

const logger = org.apache.logging.log4j.LogManager.getLogger("fess.script");
logger.info("executor = {}", executor);

위 예제에서는 fess.script라는 이름의 로거를 사용합니다. 이 로그를 출력하려면 app/WEB-INF/classes/log4j2.xml에 해당 로거 설정을 추가합니다.

<Logger name="fess.script" level="DEBUG"/>

또한 스크립트 엔진 자체의 디버그 로그를 활성화하려면 org.codelibs.fess.script 패키지의 로그 레벨을 DEBUG로 설정합니다.

<Logger name="org.codelibs.fess.script" level="DEBUG"/>

참고 정보