유틸 모듈 사용 가이드

개요

공통 Util은 자주 사용되는 공통적인 기능들을 제공한다. 캐모마일 프레임워크에서는 Json, XML, String, UUID, 프로퍼티 관련 공통 기능을 제공한다.

의존성 주입

dependency 등록(pom.xml)

<dependency>  
  <groupId>net.lotte.chamomile.module</groupId>  
  <artifactId>chamomile-util</artifactId>  
</dependency>

Json Util

마샬링은 객체의 메모리 구조를 저장이나 전송을 위해서 적당한 자료 형태로 변형하는 것을 의미한다.

마샬링은 통신을 위해 데이터가 이동되어야 할 경우 사용되며, 다른 컴퓨터나 다른 프로그램 간에 데이터를 전송해야 할 때 사용한다.

마샬링과 반대되는 의미로 언마샬링을 사용하며, 내용은 다르지만 유사한 의미로 직렬화(Serialization)와 역직렬화(Deserialization)가 있다.

동작방식

JsonUtil은 Jackson library 의 ObjectMapper를 기반으로 동작하며, 제공되는 기능은 마샬링, 언마샬링이 있다.

해당 기능은 static method를 직접 호출하여 결과를 얻을 수 있다. 자세한 사용방법은 테스트 코드를 통해 샘플을 제공한다.

사용법

마샬링

마샬링을 하기 위해 먼저 마샬링을 하기 위한 클래스를 만들어 둔다.

아래는 id, name, skills의 멤버 변수를 가진 클래스이다.

chmm.email.smtp.address=111.222.333.444
chmm.email.smtp.port=1234
chmm.email.smtp.id=lotte
chmm.email.smtp.pw=1234

직접 bean을 생성하고 싶다면 다음과 같이 생성하면 된다.

@JsonTypeName(value = "Employee")
@JsonTypeInfo(include = JsonTypeInfo.As.WRAPPER_OBJECT, use = JsonTypeInfo.Id.NAME)
public class Employee {
    private int id;
    private String name;
    private List<String> skills;

    public int getId() {
        return id;
    }
    public void setId(int id) {
        this.id = id;
    }
    public String getName() {
        return name;
    }
    public void setName(String name) {
        this.name = name;
    }
    public List<String> getSkills() {
        return skills;
    }
    public void setSkills(List<String> skills) {
        this.skills = skills;
    }
}

변환을 위해 해당 클래스에 위와 같은 Type annotation을 선언해야 한다. 명시적으로 선언하지 않으면 타입을 추정하여 변환을 하게 된다.

@JsonTypeName은 클래스가 가지는 논리명을 바인딩하기 위한 정보로 JsonTypeInfo를 설정하는데 사용된다.

@JsonTypeInfo는 Json의 직렬화 및 해제에 대한 형식 정보를 기술하며 실제 클래스에 대한 정보를 보존하는데 사용된다. 위 기술된 내용 중 상세 항목의 내역은 다음과 같다.

include 항목의 WRAPPER_OBJECT 는 실제 json의 유형 식별자 값을 포함한다는 설정이다. use의 NAME 항목은 논리 타입 이름이 타입 정보로 사용된다는 것을 의미한다. 여기서는 앞서 만든 클래스에서 선언한 @JsonTypeName항목을 참조하게 된다. 상세한 annotation의 설명은 ** Jackson-annotation javadoc 웹페이지 **에서 확인할 수 있다.

[예제]

아래 테스트 코드는 앞에서 만든 클래스의 객체를 생성한 뒤 마샬링을 통해 jsonString을 얻는 과정이다.

@Test
public void testJsonMarshaller() {
    Employee employee = new Employee();
    List<String> skills = new ArrayList<String>();
    skills.add("test1");
    skills.add("test2");
    employee.setId(101);
    employee.setName(“test_name");
    employee.setSkills(skills);
    try {
        System.out.println(JsonUtil.toJson(employee));
    } catch (JsonProcessingException e) {
        fail(e.getMessage());
    }
}

아래와 같이 객체를 생성하고 값을 설정한다.

Employee employee = new Employee();
List<String> skills = new ArrayList<String>();
skills.add("test1");
skills.add("test2");
employee.setId(101);
employee.setName(“test_name");
employee.setSkills(skills); 

생성한 객체를 아래와 같이 JsonUtil의 toJson 함수를 호출하여 마샬링을 수행한다.

try {
    System.out.println(JsonUtil.toJson(employee));
} catch (JsonProcessingException e) {

언마샬링

반대로 아래 테스트 코드는 앞에서 만든 클래스의 객체를 얻기 위해, jsonString을 언마샬링하여 객체를 얻는 과정이다.

@Test
public void testJsonUnMarshaller() {
    try {
        Employee employee = JsonUtil.fromJson(Employee.class, str);
    
        System.out.println("ID: " + employee.getId());
        System.out.println("Name: " + employee.getName());
        System.out.println("Skills: " +                 StringUtils.join(employee.getSkills(), ','));
    } catch (JsonParseException e) {
        fail(e.getMessage());
    } catch (JsonMappingException e) {
        fail(e.getMessage());
    } catch (IOException e) {
        fail(e.getMessage());
    }
}

아래 string은 객체 변환을 위해 만든 jsonString이다.

String str= 
    "{"+
    "    \"Employee\" : {"+
    "    \"id\" : 123,"+
    "    \"name\" : \"abcd\","+
    "    \"skills\" : [ \"test1\", \"test2\" ]"+
    "    }"+
    "}";

생성한 string을 아래와 같이 JsonUtil의 fromJson 함수를 호출하여 언마샬링을 수행한다.

try {
    Employee employee = JsonUtil.fromJson(Employee.class, str);

    System.out.println("ID: " + employee.getId());
    System.out.println("Name: " + employee.getName());
    System.out.println("Skills: " + StringUtils.join(employee.getSkills(), ','));
} catc

API

JsonUtil은 마샬링, 언마샬링을 위한 유틸로서 다음과 같은 static method로 구성되어 있다.

public static String toJson(Object target)
public static <T> T fromJson(Class<T> classpath, String target)

Object target : 마샬링 할 객체를 의미한다.

Class classpath : 언마샬링 대상이 되는 객체를 의미한다.

String target : 언마샬링 할 json String을 의미한다.

XML Util

XmlUtil은 Jackson library 의 XmlMapper를 기반으로 동작하며, 제공되는 기능은 3가지로, 마샬링, 언마샬링, Document 변환이 있다.

해당 기능은 static method를 직접 호출하여 결과를 얻을 수 있다. 자세한 사용방법은 테스트 코드를 통해 샘플을 제공한다.

사용법

마샬링

마샬링을 하기 위해 먼저 마샬링을 하기 위한 클래스를 만들어 둔다.

아래는 id, name, skills의 멤버 변수를 가진 클래스이다.

public class Employee {
    private int id;
    private String name;
    private List<String> skills;
 
    public int getId() {
        return id;
    }
    public void setId(int id) {
        this.id = id;
    }
    public String getName() {
        return name;
    }
    public void setName(String name) {
        this.name = name;
    }
    public List<String> getSkills() {
        return skills;
    }
    public void setSkills(List<String> skills) {
        this.skills = skills;
    }
}

변환을 위해 해당 클래스에 @XmlRootElement 등의 annotation을 선언해야 하나, 명시적으로 선언하지 않아도 타입을 추정하여 변환이 가능하다.

아래 테스트 코드는 앞에서 만든 클래스의 객체를 생성한 뒤 마샬링을 통해 xmlString을 얻는 과정이다.

@Test
public void testXmlMarshaller() {
    Employee employee = new Employee();
    List<String> skills = new ArrayList<String>();
    skills.add("test1");
    skills.add("test2");
    employee.setId(101);
    employee.setName(“test_name");
    employee.setSkills(skills);
    try {
        XmlUtil.toXml(employee);
    } catch (JsonProcessingException e) {
        fail(e.getMessage());
    }
}

아래와 같이 객체를 생성하고 값을 설정한다.

Employee employee = new Employee();
List<String> skills = new ArrayList<String>();
skills.add("test1");
skills.add("test2");
employee.setId(101);
employee.setName(“test_name");
employee.setSkills(skills);

생성한 객체를 아래와 같이 XmlUtil의 toXml 함수를 호출하여 마샬링을 수행한다.

try {
    System.out.println(XmlUtil.toXml(employee));
} catch (JsonProcessingException e) {

언마샬링

반대로 아래 테스트 코드는 앞에서 만든 클래스의 객체를 얻기 위해, xmlString을 언마샬링하여 객체를 얻는 과정이다.

@Test
public void testXmlUnMarshaller() {
    try {
        Employee employee = XmlUtil.fromXml(Employee.class, str);
    
        System.out.println("ID: " + employee.getId());
        System.out.println("Name: " + employee.getName());
        System.out.println("Skills: " + StringUtils.join(employee.getSkills(), ','));
    } catch (JsonParseException e) {
        fail(e.getMessage());
    } catch (JsonMappingException e) {
        fail(e.getMessage());
    } catch (IOException e) {
        fail(e.getMessage());
    }
}

아래 string은 객체 변환을 위해 만든 xmlString이다 .

String str = 
    "<Employee>\n" + 
    "   <id>101</id>\n" + 
    "   <name>test_name</name>\n" + 
    "   <skills>"+
    "       <skills>test1</skills>\n" + 
    "       <skills>test2</skills>\n" +
    "   </skills>"+
    "</Employee>";

생성한 string을 아래와 같이 XmlUtil의 fromXml 함수를 호출하여 언마샬링을 수행한다.

try {
    Employee employee = XmlUtil.fromXml(Employee.class, str);

    System.out.println("ID: " + employee.getId());
    System.out.println("Name: " + employee.getName());
    System.out.println("Skills: " + StringUtils.join(employee.getSkills(), ','));
} catch (JsonParseException e) {

Document 변환

아래 테스트 코드는 String 형태의 xml을 Document타입으로 변환하는 과정이다.

@Test
public void testXmltoDocument() {
    try {
        assertEquals("Employee", 
                     XmlUtil.toDocument(str).getDocumentElement().getNodeName());
    } catch (ParserConfigurationException e) {
        fail(e.getMessage());
    } catch (SAXException e) {
        fail(e.getMessage());
    } catch (IOException e) {
        fail(e.getMessage());
    }
}

API

XmlUtil은 마샬링, 언마샬링을 위한 유틸로서 다음과 같은 static method로 구성되어 있다.

public static String toXml(Object target)
public static <T> T fromXml(Class<T> classpath, String target)
public static Document toDocument(String xmlString)

Object target : 마샬링 할 객체를 의미한다.

Class classpath : 언마샬링 대상이 되는 객체를 의미한다.

String target : 언마샬링 할 xml String을 의미한다.

String xmlString : Document 변환을 할 xmlString을 의미한다.

String Util

StringUtil은 String 제어, XSS Encoding & Decoding 등의 기능을 수행한다.

API

메소드	파라미터	반환값	설명
allIndexOf	String source, String target	List\<Integer>	source의 substring 중 target과 일치하는 substring 의 index들을 반환
indexOf	String source, String target	int	source의 substring 중 target과 앞에서부터 처음 일치하는 index를 반환
ellipsis	String source, int MAXLEN	String	source의 길이가 MAXLEN을 넘어가는 경우 자름
ellipsis	String source, int MAXLEN, String limit	String	str의 길이가 MAXLEN 을 넘어가는 경우 limit 으로 치환
encodeXSS	String source	String	XSS Encoding (< 와 > 를 치환)
decodeXSS	String source	String	XSS Decoding(< 와 > 를 치환)
camelToUnderscore	String str	String	camel 양식의 문자열을 underscore(_) 양식으로 변환.
splitByLength	String str, int cutLength	List\<String>	주어진 문자열을 지정된 길이 만큼 잘라서 List로 반환한다.
appendToString	String… args	String	String들을 하나의 String으로 반환한다.
match	String src, String regex	boolean	정규식패턴과 일치하는지 판단한다.
ellipsisByByte	String src, int byteLen, String suffix	String	String을 원하는 크기(byte 단위)로 줄여 마지막 접미사를 붙여 반환한다. (접미사도 length에 포함) 한글의 경우 중간에 절단이 이루어 졌을경우 깨지는 것을 방지하기위해 완성형으로 제공한다.
abbreviate	String src, int maxWidth, String enc, String suffix	String	String을 원하는 길이(byte 단위)로 줄여 마지막 접미사를 붙여 반환한다. 접미사의 길이도 길이에 포함되며, 원하는 크기가 접미사의 길이보다 작으면 BaseRuntimeException 던진다. 주어진 인코딩 기준으로 byte[]를 얻은 후 이를 byte 단위로 나누며, 나누는 과정에 깨지는 문자는 버린다.
nvl	String src, String rep	String	주어진 input이 String이 null일 경우 지정값을 return
phoneFormat	String num	String	주어진 문자열을 전화번호 형식으로 변환
getCurrency	int money, Locale locale	String	국가별 화폐를 표시해준다.

UUID

UUID Util은 범용 고유 식별자를 의미하여 Java API 에서128bit로 구성되어있다.

주로 난수 생성이 필요할 때 사용하며, 입력값을 기준으로 UUID를 생성하게 되면 매번 동일한 UUID 가 생성된다.

API

메소드	파라미터	반환값	설명
getUuid		String	UUID 반환
getUuidOnlyString		String	UUID 반환(‘-‘제거)
getUuid	String input	String	input을 토대로 UUID 생성
getUuidOnlyString	String input	String	input을 토대로 UUID 생성 (‘-‘제거)

프로퍼티

.properties는 응용 프로그램의 구성 가능한 파라미터들을 저장하기 위해 사용하는 파일로, key=value 형식의 데이터를 저장한다.

DatabaseProperties는 파일로 관리되는 property를 DB기반으로 관리하기 위해 제공된다. Table에 key와 value 데이터를 입력 후 API 호출 시 key에 맞는 value를 반환하도록 구성되어 있다.

DatabasePropertyUtil은 Apache 에서 제공하는 Configuration을 사용하여 DB기반의 프로퍼티를 처리 한다. 또한 캐싱 처리를 위해 CacheManager의 설정이 필요하다.(캐시 가이드 참조)

설정

@Value("${chmm.property.table}")
private String propertyTable;
@Value("${chmm.property.key.column}")
private String propertyKeyColumn;
@Value("${chmm.property.value.column}")
private String propertyValueColumn;

@Bean
public DatabasePropertyUtil databasePropertyUtil(DatabaseProperties databaseProperties) {
    return new DatabasePropertyUtil(databaseProperties);
}

@Bean
public DatabaseProperties databaseProperties(DataSource dataSource) {
    DatabaseProperties databaseProperties = new DatabaseProperties();
    databaseProperties.setDataSource(dataSource);
    databaseProperties.setTable(propertyTable);
    databaseProperties.setKeyColumn(propertyKeyColumn);
    databaseProperties.setValueColumn(propertyValueColumn);
    databaseProperties.setCacheName("commonProperty");
    return databaseProperties;
}

DatabaseProperties 의 설정 항목은 다음과 같다.

dataSource : database 설정 빈을 주입 table : 프로퍼티 테이블 명을 지정 keyColumn : 프로퍼티 테이블의 key값을 저장할 컬럼을 지정 valueColumn : 프로퍼티 테이블의 value값을 저장할 컬럼을 지정 cacheManager : 캐시처리를 위한 cacheManager를 주입 cacheName : 구성된 캐시를 가져오기 위해 cacheName을 지정

예제

@Autowired
private DatabaseProperties databaseProperties;
...
databaseProprertyUtil.getProperty("test.property");

API

메소드	파라미터	반환값	설명
getProperty	String key	String	key에 해당하는 값을 가져온다.
addProperty	String key, String value		DB에 key/value를 추가한다.
setProperty	String key, String value		key에 해당 하는 값을 수정한다.
clearProperty	String key		key에 해당하는 값을 삭제한다.

Last modified: 10 1월 2025