X-API의 데이터 통신을 수행합니다.

넥사크로 또는 PlatformData를 이용하는 모든 클라이언트와 데이터 송수신을 수행합니다. 데이터 통신의 대부분의 경우 HTTP 상에서 수행되며, XML 등의 형식으로 변환된 후 송수신됩니다. 주요 클래스는 HttpPlatformRequest, HttpPlatformResponse 등입니다.

시작하기

다음은 X-API을 이용하여 데이터를 송수신하는 간단한 예제입니다.

$r_title(X-API를 이용한 예제)

using Com.Nexacro.Dotnet.Xapi.Data;
using Com.Nexacro.Dotnet.Xapi.Tx;
using System;
public partial class XAPI_TEST : System.Web.UI.Page
{
    protected void Page_Load(object sender, EventArgs e)
    {
        // HttpRequest를 이용하여 PlatformRequest 생성
        PlatformRequest req = new PlatformRequest(Request.InputStream);

        // 데이터 수신
        req.ReceiveData();

        // 수신받은 데이터 획득
        PlatformData reqData = req.GetData();
        VariableList reqVarList = reqData.GetVariableList();

        // 부서명 획득
        string name = reqVarList.GetString("name");

        // 송신할 데이터 생성
        PlatformData resData = new PlatformData();
        VariableList resVarList = resData.GetVariableList();

        // 부서별 인원을 저장할 DataSet 생성
        DataSet employees = new DataSet("employees");

        // DataSet에 열(column) 추가
        employees.AddColumn(new ColumnHeader("name", DataTypes.STRING, 8));
        employees.AddColumn(new ColumnHeader("jobTitle", DataTypes.STRING));
        employees.AddColumn(new ColumnHeader("number", DataTypes.INT));
        employees.AddColumn(new ColumnHeader("manager", DataTypes.BOOLEAN));

        // 부서별 인원 데이터 추가
        if ("R&D Center".Equals(name)) {
          // 행(row) 추가
          int row = employees.NewRow();
          // 추가된 행(row)의 데이터 설정
          employees.Set(row, "name", "John Jones");
          employees.Set(row, "jobTitle", "developer");
          employees.Set(row, "number", 1234);
          employees.Set(row, "manager", false);
          // ...
          // 정상 수행
          resData.AddDataSet(employees);
          resVarList.Add("ERROR_CODE", 200);
        } else if ("Quality Assurance".Equals(name)) {
          // 행(row) 추가
          int row = employees.NewRow();
          // 추가된 행(row)의 데이터 설정
          employees.Set(row, "name", "Tom Glover");
          employees.Set(row, "jobTitle", "manager");
          employees.Set(row, "number", 9876);
          employees.Set(row, "manager", true);
          // ...
          // 정상 수행
          resData.AddDataSet(employees);
          resVarList.Add("ERROR_CODE", 200);
        } else {
          // 오류 발생
          resVarList.Add("ERROR_CODE", 500);
        }
        // HttpServletResponse를 이용하여 PlatformResponse 생성
        PlatformResponse res = new PlatformResponse(Response.OutputStream);
        res.SetData(resData);
        // 데이터 송신
        res.SendData();
    }
}

데이터 송수신

넥사크로와의 데이터 통신은 대부분의 경우 HTTP 상에서 수행되며, 특정 형식으로 변환된 후 송수신됩니다.

송수신 형식(contentType)은 데이터가 송수신되기 위해 객체에서 특정 형식의 데이터(stream)으로 변환되는 것을 의미하며, 프로토콜 형식(protocolType)은 데이터의 압축, 암호화 등을 수행하는 것을 의미합니다.

송수신 형식(contentType)과 프로토콜 형식(protocolType) 등 데이터 변환에 대한 주요 인터페이스는 다음과 같습니다.

인터페이스명	설 명
DataSerializer	PlatformData를 특정 형식의 데이터(stream)으로 변환
DataDeserializer	특정 형식의 데이터(stream)를 PlatformData로 변환
ProtocolEncoder	데이터(stream)의 압축, 암호화 등을 수행
ProtocolDecoder	압축, 암호화 등이 적용된 데이터(stream)를 압축 해제, 복호화 등을 수행

데이터 송수신의 내부 흐름

데이터 송신 흐름

Server에서 데이터를 PlatformData에 저장한 후 송신함
DataSerializer에 의해 PlatformData가 특정 형식의 데이터(stream)로 변환됨
ProtocolEncoder에 의해 압축, 암호화 등이 적용됨
HTTP 상으로 데이터(stream)가 송신됨

데이터 수신 흐름

HTTP 상에서 압축, 암호화 등이 적용된 데이터(stream)를 수신받음
ProtocolDecoder에 의해 압축 해제, 복호화 등이 수행됨
DataDeserializer에 의해 특정 형식의 데이터(stream)가 PlatformData로 변환됨
Client에서 데이터가 저장된 PlatformData를 수신받음

Server 상의 HTTP 데이터 통신

넥사크로와 HTTP 상에서 데이터 통신을 하기 위해서는 PlatformRequest와 PlatformResponse를 이용하여 cs 파일을 작성합니다.

PlatformRequest와 PlatformResponse는 System.Web.HttpRequest와 System.Web.HttpResponse를 이용하여 HTTP 통신을 수행하며, PlatformRequest는 넥사크로로 데이터(stream)를 수신받은 후 PlatformData으로 변환하고, 그와는 반대로 PlatformResponse는 PlatformData를 데이터(stream)으로 변환한 후 넥사크로로 송신합니다.

$r_title(HttpServletRequest으로부터 데이터 수신)
// System.Web.HttpRequest를 이용하여 PlatformRequest 생성
PlatformRequest req = new PlatformRequest(Request.InputStream);
// 데이터 수신
req.ReceiveData();
PlatformData data = req.GetData();

$r_title(HttpServletResponse으로 데이터 송신)
PlatformData data = ...;
// System.Web.HttpResponse를 이용하여 PlatformResponse 생성
PlatformResponse res = new PlatformResponse(Response.OutputStream);
res.SetData(data);
// 데이터 송신
res.SendData();

$r_title(echo.cs 예제)

using Com.Nexacro.Dotnet.Xapi.Data;
using Com.Nexacro.Dotnet.Xapi.Tx;
using System;
public partial class XAPI_TEST : System.Web.UI.Page
{
    protected void Page_Load(object sender, EventArgs e)
    {
        PlatformRequest req = new PlatformRequest(Request.InputStream);
        req.ReceiveData();
        PlatformData reqData = req.GetData();
        PlatformResponse res = new PlatformResponse(Response.OutputStream);
        res.SetData(data);
        res.SendData();
    }
}

데이터 송수신 형식

송수신 형식은 데이터 송수신에서 언급되었듯이 데이터가 송수신되기 위해 객체에서 특정 형식의 데이터(stream)으로 변환되는 형식을 의미하며, 기 구현된 형식은 다음과 같습니다.

상수값	설 명
PlatformType.CONTENT_TYPE_XML	Platform에서 정의된 XML 형식
PlatformType.CONTENT_TYPE_BINARY	Platform에서 정의된 바이너리 형식
PlatformType.CONTENT_TYPE_SSV	Platform에서 정의된 SSV 형식

$r_title(XML 형식으로 데이터를 수신하고, Binary 형식으로 데이터를 송신하는 예제)
// XML 형식으로 데이터 수신
PlatformRequest req = new PlatformRequest(Request.InputStream, PlatformType.CONTENT_TYPE_XML);
req.ReceiveData();
PlatformData data = req.GetData();

// Binary 형식으로 데이터 송신
PlatformResponse res = new PlatformResponse(Response.OutputStream, PlatformType.CONTENT_TYPE_BINARY);
res.SetData(data);

res.SendData();

만약에 사용자에 의해 정의된 송수신 형식이 아닌 기 제공되는 송수신 형식인 경우에는 다음과 같이 PlatformRequest에 별도의 송수신 형식을 지정하지 않아도, 내부에서 자동으로 송수신 형식을 판단하여 처리합니다.

$r_title(송수신 형식을 자동으로 판단하여 데이터 수신)
// 송수신 형식을 자동으로 판단하여 데이터 수신
PlatformRequest req = new PlatformRequest(Request.InputStream);
req.ReceiveData();

PlatformData data = req.GetData();

데이터 프로토콜 형식

프로토콜 형식은 데이터 송수신에서 언급되었듯이 데이터의 압축, 암호화 등을 수행하는 것을 의미하며, 기 구현된 형식은 다음과 같습니다.

상수값	설 명
PlatformType.PROTOCOL_TYPE_ZLIB	ZLIB 방식으로 압축

$r_title(ZLIB 방식으로 압축하여 데이터 송신)
// 데이터 수신
PlatformRequest req = new PlatformRequest(Request.InputStream);
req.ReceiveData();
PlatformData data = req.GetData();

// ZLIB 방식으로 압축하여 데이터 송신
PlatformResponse res = new PlatformResponse(Response.OutputStream, PlatformType.CONTENT_TYPE_BINARY);
res.AddProtocolType(PlatformType.PROTOCOL_TYPE_ZLIB);
res.SetData(data);

res.SendData();

추가, 변경, 삭제된 데이터 송신

DataSet은 데이터가 추가, 변경, 삭제된 경우 변경된 상태와 변경 이전의 원본 데이터를 저장합니다. 자세한 정보는 DataSet의 원본 데이터와 변경된 데이터를 참조합니다.

PlatformResponse는 위와 같은 데이터를 저장 방식(saveType)에 따라 구분하여 전송합니다.

상수값	설 명
DataSet.SAVE_TYPE_NONE	미설정
DataSet.SAVE_TYPE_ALL	현재의 데이터와 추가, 변경, 삭제된 모든 데이터 저장 또는 전송
DataSet.SAVE_TYPE_NORMAL	현재의 데이터만 저장 또는 전송
DataSet.SAVE_TYPE_UPDATED	추가, 변경된 데이터만 저장 또는 전송
DataSet.SAVE_TYPE_DELETED	삭제된 데이터만 저장 또는 전송
DataSet.SAVE_TYPE_CHANGED	추가, 변경, 삭제된 데이터만 저장 또는 전송

저장 방식(saveType)은 PlatformData와 DataSet이 가지고 있으며, DataSet의 저장 방식이 우선으로 적용되고, DataSet의 저장 방식이 DataSet.SAVE_TYPE_NONE인 경우 PlatformData의 저장 방식이 적용됩니다.

만약에 PlatformData의 저장 방식도 DataSet.SAVE_TYPE_NONE인 경우 기본값 DataSet.SAVE_TYPE_NORMAL이 적용됩니다.