시스템헤더

BX Framework은 기본적으로 DefaultSystemHeader를 제공한다. Framework을 사용하게 될 사용자환경에 DefaultSystemHeader 필드를 적용할 수 없는 경우 시스템헤더를 사용자환경에 적합하게 커스터마이징할 수 있다.

시스템헤더를 커스터마이징할 때 아래 사항을 검토해야 한다.

사용하고자할 통신 프로토콜 및 전문포맷
시스템헤더의 항목

1. Default 시스템 헤더

DefaultSystemHeader(bxm.dft.context.DefaultSystemHeader)는 HTTP프로토콜을 사용하며 전문포맷으로 XML, FLD(Fixed Length Data), JSON을 사용하는 것을 지원한다.

에러메시지 및 정상메시지를 저장하는 메시지정보(bxm.dft.context.DefaultMessage)를 포함하고 있다.

DefaultSystemHeader의 항목
Type	이름	설명	길이	배열	비고
Long	msgLen	전문길이	8
String	guid	Global unique id	40
String	trxCd	거래코드	12
String	sysCd	시스템코드	3
String	chlType	채널유형	2
String	clientIp	클라이언트IP	15
String	msgReqDttm	전문요청시간	16
String	msgResDttm	전문응답시간	16
String	trxBranchNo	거래지점번호	4
String	trxTerminalNo	거래단말번호	4
String	userId	조작자ID	8
String	apprTrxYn	승인자거래여부	1
String	apprUserId	승인자ID	8
String	screenId	화면ID	10
String	langCd	언어코드	2		ISO 639-1(Alpha-2 code) 사용
String	resCd	응답코드	1		정상 : "0", 시스템에러 : "1", 사용자에러 : "2"
String	edayYn	마감여부	1
String	filler	filler	49
String	msgCd	메시지코드	9		에러발생시에만 에러메시지코드가 설정됨.
String	msgCnt	메시지갯수	5
DefaultMessage	msgs	메시지		msgCnt	msgCnt수만큼 반복됨.

DefaultMessage의 항목
Type	이름	설명	길이	배열	비고
String	errInfo	에러정보	200
String	basicMsg	기본메시지	200
Integer	detailMsgCnt	상세메시지갯수	5
String	detailMsgs	상세메시지	200	detailMsgCnt	detailMsgCnt수만큼 반복됨.

2. 전문 포맷

DefaultSystemHeader는 전문포맷으로 XML, FLD(Fixed Length Data), JSON을 지원한다.

2.1. XML

BX Framework는 XML전문을 사용할 때 다음과 같은 특징을 갖는다.

시스템헤더의 항목명을 xml eliment로 사용한다.
xml root element로 "bxm-message"를 사용한다.
시스템헤더를 나타내는 시작 element로 "header"를 사용한다.
업무서비스로 전달할 요청데이터를 시작하는 element로 업무서비스의 입력DTO이름을 사용한다.

DefaultSystemHeader를 사용하여 구성한 XML전문 예제는 아래와 같다.

…
<bxm-message>
    <header>
        <msgLen>0</msgLen>
        <guid>20161011jinman-VAIO331C006508653100</guid>
        <trxCd>SSMP1001A001</trxCd>
        <sysCd>DFT</sysCd>
        <chlType>A0</chlType>
        <clientIp>999.999.999.999</clientIp>
        <msgReqDttm>2016101118044653</msgReqDttm>
        <trxBranchNo>0001</trxBranchNo>
        <trxTerminalNo>0000</trxTerminalNo>
        <userId>88888888</userId>
        <apprTrxYn>N</apprTrxYn>
        <screenId>9999999999</screenId>
        <langCd>ko</langCd>
        <resCd>0</resCd>
        <msgCnt>0</msgCnt>
    </header>
    <SSMP1001A001InDto>
        <feduEmpNo>0</feduEmpNo>
    </SSMP1001A001InDto>
</bxm-message>

2.2. JSON

BX Framework는 JSON전문을 사용할 때 다음과 같은 특징을 갖는다.

시스템헤더는 name이 "header"인 pair에 value로 저장한다.
업무서비스로 전달할 요청데이터는 업무서비스의 입력DTO이름을 name으로 사용하는 pair에 value로 저장한다.
시스템헤더의 항목, 요청데이터의 항목은 json의 name/value형태로 저장한다.

DefaultSystemHeader를 사용하여 구성한 JSON전문 예제는 아래와 같다.

…
{"header" : {
  "msgLen" : 0,
  "guid" : "20161011jinman-VAIO331C006508642200",
  "trxCd" : "SSMP1001A001",
  "sysCd" : "DFT",
  "chlType" : "A0",
  "clientIp" : "999.999.999.999",
  "msgReqDttm" : "2016101118044642",
  "msgResDttm" : null,
  "trxBranchNo" : "0001",
  "trxTerminalNo" : "0000",
  "userId" : "88888888",
  "apprTrxYn" : "N",
  "apprUserId" : null,
  "screenId" : "9999999999",
  "langCd" : "ko",
  "resCd" : "0",
  "edayYn" : null,
  "filler" : null,
  "msgCd" : null,
  "msgCnt" : 0,
  "msgs" : [ ]
},
"SSMP1001A001InDto" : {
  "feduEmpNo" : 0
}
}

2.3. FLD(Fixed Length Data)

BX Framework는 FLD전문을 사용할 때 다음과 같은 특징을 갖는다.

전문의 첫부분은 전문 전체길이를 나타내는 길이필드를 갖는다.(전체길이에 길이필드는 포함안됨.)
시스템헤더의 항목, 요청데이터의 항목은 고정된 길이의 문자열로 저장한다.
항목이 여러번 반복되는 반복부의 경우 해당 항목 앞 항목으로 반복횟수 항목이 존재해야한다.

3. 시스템헤더 구현

System Header는 bxm.request.ContextHeader를 상속하며, 기본적으로 XML, FLD, JSON을 처리하기 위하려 bxm.omm.root.IOmmObject interface를 구현해야 한다.

…
public class DefaultSystemHeader extends ContextHeader implements IOmmObject {

3.1. IOmmObject 구현

OMM 에디터를 이용하여 시스템헤더의 항목을 OMM의 필드로 작성한다.

Figure 1. OMM 에디터를 이용한 시스템헤더 작성
OMM에 의해 생성된 Java 소스를 시스템헤더 클래스가 위치할 패키지로 복사한다.

시스템헤더의 Java 소스중 XmlRootElement부분을 아래와 같이 수정한다. (수정값 "header"는 BXM의 헤더 eliment 이름의 기본값이다.)

…
@XmlRootElement( name= "header")   // DefaultSystemHeader에서 header로 수정한다.
public class DefaultSystemHeader extends ContextHeader implements IOmmObject, Predictable, FieldInfo  {

OMM에 의해 생성된 Java 소스중 이름이 "isSet_항목명"인 필드, 해당필드의 getter, setter 메소드는 시스템헤더 사용시 사용하지 않으므로 삭제해도 동작에 이상이 없다.

다음은 msLen필드에 의해 자동생성된 소스중 삭제되어도 영향이 없는 부분에 대한 예제이다.
```
…
    @XmlTransient
    private boolean isSet_msgLen = false;

    protected boolean isSet_msgLen()
    {
        return this.isSet_msgLen;
    }

    protected void setIsSet_msgLen(boolean value)
    {
        this.isSet_msgLen = value;
    }
```

OMM 에디터에 의해 생성된 Java소스에서 추가구현된 Predictable, FieldInfo 인터페이스는 시스템헤더의 필수 인터페이스는 아니다.

3.2. ContextHeader 메소드 구현

ContextHeader를 상속받아서 구현할 때 성격에 따라 다음과 같이 나뉜다.

Framework 내부 사용 API
ContextHeader 필드 getter, setter메소드. ContextHeader에서는 구현되어 있지 않으므로 사용하는 시스템헤더의 비슷한 필드에 대한 getter, setter메소드로 구현한다.
메시지 API
Deprecated API(더 이상 사용되지 않는다.)

Framework 내부 사용 API
메소드	구현구분	설명
String getApplication()		요청서비스의 Application을 반환한다.
String getService()		요청서비스의 Service를 반환한다.
String getOperation()		요청서비스의 Operation을 반환한다.
String getTransactionCode()		요청서비스의 거래코드를 반환한다. 단, 거래코드를 사용하지 않는 경우 ""을 반환한다.
Map<Object, Object> getDataContainer()		DataContainer객체를 반환한다.
ContextHeader copy()		거래 연동시 헤더 복사를 위해 호출되는 API. side effect를 없애기 위해 deep copy형태로 복사해야함.

ContextHeader 필드 getter, setter API
메소드	구현구분	설명
String getUserId()		userId를 반환한다. 시스템헤더의 userId와 유사한 필드를 반환한다.
String getRemoteAddr()		remoteAddr을 반환/설정한다. client를 구분할 수 있는 IP를 설정한다.
void setRemoteAddr( String remoteAddr)		remoteAddr을 반환/설정한다. client를 구분할 수 있는 IP를 설정한다.
String getReturnCode()		결과코드를 반환/설정한다. 정상 : "0", 시스템에러 : "1", 사용자에러 : "2"
void setReturnCode( String code)		결과코드를 반환/설정한다. 정상 : "0", 시스템에러 : "1", 사용자에러 : "2"
String getMessageCode()		메시지코드를 반환/설정한다.
void setMessageCode( String messageCode)		메시지코드를 반환/설정한다.
String getUuid()		UUID(universally unique identifier)를 반환/설정한다. UUID를 사용하지 않는 경우 거래를 구분할 수 있는 key을 대체하여 사용한다.
void setUuid( String uuid)
String getSystemId()	옵션	System ID를 반환/설정한다. System ID를 사용하지 않는 경우 빈 문자열로 대체하여 사용한다. System은 동일한 Application을 사용하는 서버들의 그룹을 말한다.
void setSystemId( String systemId)	옵션

메시지 API
메소드	구현구분	설명
boolean addMessage(Message message)		메시지정보를 시스템헤더에 추가한다.
List<String> getMessages	옵션	시스템헤더의 메시지리스트를 반환한다.
List<String> getDetailMessages()	옵션	시스템헤더의 상세메시지리스트를 반환한다.
void clearMessages()	옵션	시스템헤더의 메시지리스트, 상세메시지리스트를 삭제한다.
void addMessage(String message)	비권장	메시지를 메시지리스트에 추가한다.
void setFirstMessage(String message)	비권장	메시지를 메시지리스트의 첫번째메시지로 저장한다.
void addDetailMessage(String message)	비권장	메시지를 상세메시지리스트에 추가한다.
void setFirstDetailMessage(String message)	비권장	메시지를 상세메시지리스트의 첫번째메시지로 저장한다.
String getTraceMessage()	비권장	시스템헤더에 저장된 Exception stack trace를 반환한다.
void setTraceMessage( String traceMessage)	비권장	시스템헤더에 Exception stack trace를 저장한다. 주의)시스템헤더에 Exception stack trace를 저장하는 경우 Client와의 통신시 외부에 exception stact trace가 노출되어 보안취약점이 될 수 있다.

Deprecated API
메소드	구현구분	설명
void setRequestTime( Date date)	deprecated	더 이상 사용하지 않는다.

3.3. getter메소드에 @XmlTransient, @JsonIgnore추가

전문출력대상이 아닌 ContextHeader의 getter메소드에 전문 출력 무시 옵션을 추가한다. 사용하는 전문포맷에 따라 XML인 경우 @XmlTransient, JSON인 경우 @JsonIgnore를 추가한다.

…
    @Override
    @XmlTransient
    @JsonIgnore
    public List<String> getDetailMessages() {
        return new ArrayList<String>();
    }