nexacro17 X-API for C#  1.0
Manual
nexacro17 X-API

X-API는 nexacro platform 클라이언트와의 통신을 위한 API이다.

com.nexacro17.xapi.data : X-API의 데이터 구조를 정의한다.

com.nexacro17.xapi.tx : X-API의 데이터 통신을 수행한다.

1. 소개

X-API의 주목적은 nexacro platform 클라이언트와의 통신을 제공하고, 데이타 송수신, 또는 송수신된 데이타의 조작을 단순화함으로써, 개발자는 비지니스 개발에 초점을 맞추도록 하는 것이다.

클라이언트와 서버간에 송수신하는 데이터는 key-value으로 구성된 단일 데이터도 존재하고, DB의 Table과 유사한 2차원 데이터도 존재한다. 이러한 데이터를 조작 또는 송수신하기 위한 것이다.

X-API의 주요 기능은 com.nexacro17.xapi.data와 com.nexacro17.xapi.tx을 참조한다.

2. 설치

X-API는 설치는 간단하게 임의의 위치에 dll들을 위치 시키고 웹 프로젝트에 참조로 dll을 추가 시킨다.

다음은 X-API의 dll 파일들이다.

파일명 설 명 필수여부
Nexacro17XAPILib.dll X-API yes

X-API는 .NET Framwork 4.5 이상을 요구하고 있으며, X-API를 사용하기 위한 외부 컴퍼넌트는 다음과 같다.

컴퍼넌트명 설 명 필수여부
NLog.dll X-API 내부 로깅 yes
ICSharpCode.SharpZipLib.dll X-API Zip library yes

3. NLog config

1) Web.config에 직접 설정

  <configSections>
    <section name="nlog" type="NLog.Config.ConfigSectionHandler, NLog">
  </configSections>
  <nlog throwConfigExceptions="true" xmlns="http://www.nlog-project.org/schemas/NLog.xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <targets>
      <target name="LogFile"
        xsi:type="File"
        layout="${longdate} [${uppercase:${level:padding=-5}}] ${message} ${exception:format=tostring}"
        fileName="${basedir}Logs\${var:runtime}\${date:format=yyyyMMdd}.log"
        encoding="UTF-8"
        archiveFileName="${basedir:processDir=true}Logs\archives\${var:runtime}\archive.{#}.log"
        archiveEvery="Day"
        archiveNumbering="Rolling"
        maxArchiveFiles="7"
        header="[Start Logging]"
        footer="[End Logging]${newline}">
    </targets>
    <rules>
      <logger name="*" minlevel="Info" writeTo="LogFile">
    </rules>
  </nlog>

2) 상세 설명

가) App.config나 web.config 파일에 nlog를 embedded 할 경우 section을 지정

<configSections>
    <section name="nlog" type="NLog.Config.ConfigSectionHandler, NLog">
</configSections>

나) 로그 생성 중 예외가 발생했을 경우 출력 옵션

<nlog throwConfigExceptions="true" …………… >

다) 변수 설정

<variable name=”logDir” value=”${basedir}/logs/”>>

라) target 지정 시 출력 layout을 CSV, JSON, XML 혹은 File 형태로 지정 가능 

<targets>
<target name="LogFile" 
xsi:type="File" 
        layout="${longdate} [${uppercase:${level:padding=-5}}] ${message} ${exception:format=tostring}" 
        fileName="${basedir}Logs\${var:runtime}\${date:format=yyyyMMdd}.log" 
        encoding="UTF-8"               
        archiveFileName="${basedir:processDir=true}Logs\archives\${var:runtime}\archive.{#}.log" 
        archiveEvery="Day" 
        archiveNumbering="Rolling" 
        maxArchiveFiles="7" 
        header="[Start Logging]" 
        footer="[End Logging]${newline}">
</targets>

마) Rule 설정

<rules>
    <logger name="*" minlevel="Info" writeTo="LogFile">
<logger name="nexacro17.xapi.tx.*" minlevel="Info" writeTo="LogFile">
</rules>

바) Layout 환경 변수
https://nlog-project.org/config/?tab=layout-renderers

사) XML 설정
https://github.com/nlog/NLog/wiki/Configuration-file#variables

4. 라이센스

X-API의 라이센스 파일명은 "nexacro17_server_license.xml" 이며, XML 형식으로 구성되어 있다.
라이센스 발급은 필수이며 라이센스가 없을 경우 정상 작동하지 않는다. 라이센스 발급은 고객지원센터를 통해 발급하여 사용할 수 있다.

라이센스 파일은 Nexacro17XAPILib.dll 파일과 동일한 디렉토리에 위치 시키면 된다.

5. com.nexacro17.xapi.data Description

X-API의 데이터 구조를 정의한다.

클라이언트와 서버간의 송수신하는 데이터는 단일 데이터도 존재하고, DB의 Table과 유사한 2차원적인 데이터도 존재한다.
이러한 데이터를 송수신 또는 조작하기 위한 데이터 구조를 정의한다. 주요 클래스는 PlatformData, DataSet와 Variable 등이다.

  1. 시작하기
  2. 데이터 구조
  3. Variable의 단일 데이터 조작
  4. DataSet의 2차원 데이터 참조
  5. DataSet 생성
  6. ColumnHeader의 속성 참조
  7. ColumnHeader를 이용한 DataSet의 열(column) 추가
  8. ColumnHeader를 이용한 DataSet의 데이터 참조
  9. ConstantColumnHeader가 가지는 열(column)의 상수값
  10. DataSet의 원본 데이터와 변경된 데이터

1) 시작하기

다음은 X-API의 데이터를 참조하는 간단한 예제이다.

PlatformData department = ...;
// VariableList 참조
VariableList varList = department.GetVariableList();
// VariableList으로부터 값 참조
String name = varList.GetString("name");
String location = varList.GetString("location");
int number = varList.GetInt("number");
// ...
// DataSet 참조
DataSet employees = department.GetDataSet("employees");
// DataSet의 행(row)수만큼 순환
for (int i = 0; i < employees.GetRowCount(); i++) {
    // DataSet의 데이터 참조
    int id = employees.GetInt(i, "id");
    String firstName = employees.GetString(i, "firstName");
    String lastName = employees.GetString(i, "lastName");
    boolean manager = employees.GetBoolean(i, "manager");
    // ...
}

데이터 참조

다음은 X-API의 데이터를 생성하는 간단한 예제이다.

    
// PlatformData 생성
PlatformData department = new PlatformData();
// VariableList 참조
VariableList varList = department.GetVariableList();
// VariableList에 값 추가
varList.Add("name", "R&D Center");
varList.Add("location", "222 Jamsil-Dong, Songpa-Ku, Seoul");
varList.Add("number", 99);
// DataSet 생성
DataSet employees = new DataSet("employees");
// 열(column) 추가
employees.AddColumn("id", DataTypes.INT);
employees.AddColumn("firstName", DataTypes.STRING, 16);
employees.AddColumn("lastName", DataTypes.STRING, 8);
employees.AddColumn("manager", DataTypes.BOOLEAN);
// 행(row) 추가
int row = employees.NewRow();
// 추가된 행(row)의 데이터 설정
employees.Set(row, "id", 0);
employees.Set(row, "firstName", "John");
employees.Set(row, "lastName", "Jones");
employees.Set(row, "manager", false);
// 행(row) 추가
row = employees.NewRow();
// 추가된 행(row)의 데이터 설정
employees.Set(row, "id", 1);
employees.Set(row, "firstName", "Tom");
employees.Set(row, "lastName", "Glover");
employees.Set(row, "manager", true);
// DataSet을 PlatformData에 추가
department.AddDataSet(employees);

데이터 생성

2) 데이터 구조

데이터는 크게 단일 데이터와 2차원 데이터로 구분한다. 단일 데이터는 데이터를 구분할 수 있는 식별자(name)와 값(value)을 가지고 있으며,
이는 VariableList에 저장된다. 2차원 데이터를 저장하는 DataSet은 열(column)과 행(row)으로 구성되어 있으며, DataSetList를 통해 저장 또는 참조된다.

VariableList와 DatasetList를 가지고 있는 PlatformData는 데이터 구조의 최상위에 위치하고 있으며, 데이터 이동과 데이터 송수신의 기본 단위로 사용되어 진다.

3) Variable의 단일 데이터 조작

Variable은 데이터를 저장하는 변수를 의미하며, 이는 식별자(name)와 값(value)으로 구성된다. 값(value)은 데이터의 형식(type)에 따라 변환된 후 저장된다.

Variable 생성과 데이터 설정은 3가지 방식으로 가능하다.

  • Variable(name, type, value)의 생성자 호출
  • Variable(name) 또는 Variable(name, type)의 생성자 호출 후 set(value) 메소드 호출
  • Variable.createVariable(name, value)의 정적 메소드 호출을 통한 생성

VariableList의 Variable 추가는 Variable 생성 후 add(var) 메소드를 통하여 추가한다. 또한, Variable을 생성하지 않고 add(name, value) 메소드를 통하여 직접 값으로 추가할 수도 있다.


// PlatformData 생성
PlatformData department = new PlatformData();
// VariableList 참조
VariableList varList = department.GetVariableList();
// VariableList에 값을 직접 추가
varList.Add("name", "R&D Center");
// Variable을 생성한 후 VariableList에 값을 추가
Variable location = new Variable("location");
location.Set("222 Jamsil-Dong, Songpa-Ku, Seoul");
varList.Add(location);
// VariableList에 int 형의 값을 직접 추가
varList.Add("number", 99);

단일 데이터(Variable) 추가

4) DataSet의 2차원 데이터 참조

DataSet은 열(column)과 행(row)으로 구성되며, 2차원 데이터를 저장한다. 구조는 DB의 Table과 유사하며, 열(column)에 대한 정보는 ColumnHeader에 의해 저장되고, 데이터는 내부 클래스인 DataRow에 의해 행(row) 단위로 저장된다.

DataSet에 저장된 데이터는 행(row)의 위치(index)와 열(column)의 이름(name) 또는 위치(index)로 참조하며, Variable과 동일한 방식으로 getObject(rowIndex, columnIndex)과 getString(rowIndex, columnIndex)등의 필요한 데이터 형식에 따른 메소드를 이용하여 값을 참조할 수 있다.

마찬가지로 주의할 점은 원 데이터의 형식과 다른 데이터 형식으로 반환을 요청한 경우 데이터의 변형이 발생할 수 있다.


PlatformData department = ...;
// DataSet을 식별자(name)를 이용하여 참조
DataSet employees = department.GetDataSet("employees");
// DataSet의 행(row)수만큼 순환
for (int i = 0; i < employees.GetRowCount(); i++) {
  // DataSet의 데이터를 식별자(name)를 통하여 참조
  object name = employees.GetObject(i, "name");
  string jobTitle = employees.GetString(i, "jobTitle");
  int number = employees.GetInt(i, "number");
  bool manager = employees.GetBoolean(i, "manager");
  // ...
}

식별자(name)를 이용한 DataSet의 데이터 참조



PlatformData department = ...;
// DataSet을 위치(index)를 이용하여 참조
DataSet employees = department.GetDataSet(0);
// DataSet의 행(row)수만큼 순환
for (int i = 0; i < employees.GetRowCount(); i++) {
  // DataSet의 데이터를 열(column)의 위치(index)를 통하여 참조
  object name = employees.GetObject(i, 0);
  string jobTitle = employees.GetString(i, 1);
  int number = employees.GetInt(i, 2);
  bool manager = employees.GetBoolean(i, 3);
  // ...
}

위치(index)를 이용한 DataSet의 데이터 참조

5) DataSet 생성

DataSet 생성은 다음과 같은 과정으로 이루어 진다.

  1. DataSet 생성
  2. 열(column) 추가
  3. 행(row) 추가
  4. 데이터 설정 
PlatformData department = new PlatformData();
// DataSet 생성
DataSet employees = new DataSet("employees");
// 열(column) 추가
employees.AddColumn("name", DataTypes.STRING, 8);
employees.AddColumn("jobTitle", DataTypes.STRING, 16);
employees.AddColumn("number", DataTypes.INT);
employees.AddColumn("manager", DataTypes.BOOLEAN);
// 행(row) 추가
int row = employees.NewRow();
// 데이터 설정
employees.Set(row, "name", "John Jones");
employees.Set(row, "jobTitle", "developer");
employees.Set(row, "number", 1234);
employees.Set(row, "manager", false);
// 행(row) 추가
row = employees.NewRow();
// 데이터 설정
employees.Set(row, "name", "Tom Glover");
employees.Set(row, "jobTitle", "manager");
employees.Set(row, "number", 9876);
employees.Set(row, "manager", true);
// DataSet을 PlatformData에 추가
department.AddDataSet(employees);
// ...

DataSet 생성과 데이터 추가

6) ColumnHeader의 속성 참조

DataSet의 열(column)에 대한 정보는 ColumnHeader에 의해 저장되며, 열(column)에 대한 정보는 다음과 같다.

속성명 변수명 데이터 형식 유효한 값
식별자 name String null과 ""를 제외한 DataSet 내에서 유일한 문자열
열(column)의 형식 type int 일반적인 열(TYPE_NORMAL)과 상수값을 가진 열(TYPE_CONSTANT)
데이터 형식 dataType int DataTypes에 정의된 상수 참조
데이터 크기 dataSize int 정수값
값 value Object ConstantColumnHeader 내에서만 유효 


PlatformData department = ...;
// DataSet 참조
DataSet employees = department.GetDataSet("employees");
// DataSet의 열(column)수만큼 순환
for (int i = 0; i < employees.GetColumnCount(); i++) {
  // DataSet으로부터 ColumnHeader 참조
  ColumnHeader columnHeader = employees.GetColumn(i);
  // 열(column)의 속성 참조
  string name = columnHeader.GetName();
  int type = columnHeader.GetType();
  int dataType = columnHeader.GetDataType();
  int dataSize = columnHeader.GetDataSize();
  bool isConstant = columnHeader.IsConstant();
  // 상수값을 가진 ColumnHeader인 경우
  object value = null;
  if (isConstant) {
    value = ((ConstantColumnHeader) columnHeader).GetValue();
  }
  // ...
}

ColumnHeader의 속성 참조

7) ColumnHeader를 이용한 DataSet의 열(column) 추가

DataSet에 열(column)을 추가하는 방법은 AddColumn(name, dataType, dataSize)를 통해 가능하기도 하고, 직접 ColumnHeader를 생성하여 추가하여도 된다.

// DataSet 생성
DataSet employees = new DataSet("employees");
// DataSet에 열(column) 추가
employees.AddColumn(new ColumnHeader("name", DataTypes.STRING, 8));
employees.AddColumn(new ColumnHeader("jobTitle", DataTypes.STRING, 16));
employees.AddColumn(new ColumnHeader("number", DataTypes.INT));
employees.AddColumn(new ColumnHeader("manager", DataTypes.BOOLEAN));
// 행(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);
// 행(row) 추가
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);

ColumnHeader를 이용한 DataSet의 열(column) 추가

8) ColumnHeader를 이용한 DataSet의 데이터 참조

때로는 DataSet의 열(column)에 대한 정보를 참조해야 하는 경우도 있다. 예를 들어, 각각의 열(column)에 대한 정보를 알지 못하는 경우나, DataSet의 데이터를 공통적으로 처리하여야 하는 경우일 것이다.

DataSet의 getColumn(index)를 호출하여 열(column)의 갯수만큼 ColumnHeader를 참조하고, ColumnHeader으로부터 식별자(name), 데이터 형식(dataType), 데이터 크기(dataSize) 등을 참조하여, 이에 따라 원하는 동작을 수행하면 될 것이다.

PlatformData department = ...;
// DataSet을 식별자(id)를 이용하여 참조
DataSet employees = department.GetDataSet("employees");
// DataSet의 행(row)수만큼 순환
for (int i = 0; i < employees.GetRowCount(); i++) {
  // DataSet의 열(column)수만큼 순환
  for (int j = 0; j < employees.GetColumnCount(); j++) {
    // DataSet으로부터 ColumnHeader 참조
    ColumnHeader columnHeader = employees.GetColumn(j);
    // 열(column)의 식별자(name) 참조
    string name = columnHeader.GetName();
    // 데이터의 형식(dataType)에 따른 구분
    switch (columnHeader.GetDataType()) {
    case DataTypes.STRING:
      string str = employees.GetString(i, name);
      // ...
      break;
    case DataTypes.INT:
      int n = employees.GetInt(i, name);
      // ...
      break;
    case DataTypes.BOOLEAN:
      bool bool = employees.GetBoolean(i, name);
      // ...
      break;
    default:
      object obj = employees.GetObject(i, name);
      // ...
      break;
    }
  }
}

ColumnHeader를 이용한 DataSet의 데이터 참조

9) ConstantColumnHeader가 가지는 열(column)의 상수값

ConstantColumnHeader는 상수값을 가진 열(column)을 의미한다.

즉, DataSet에 addConstantColumn(name, value)을 호출하여 열(column)을 추가하거나, ConstantColumnHeader를 생성하여 추가한다면, 해당 열(column)의 값은 행(row)의 위치(index)와 관계없이 일정한 상수값을 가지게 된다.

// DataSet 생성
DataSet employees = new DataSet("employees");
// DataSet에 일반 열(column) 추가
employees.AddColumn("name", DataTypes.STRING, 8);
employees.AddColumn("jobTitle", DataTypes.STRING, 16);
// DataSet에 상수값을 가진 열(column) 추가
employees.AddConstantColumn("city", "Seoul");
employees.AddColumn(new ConstantColumnHeader("company", "Tobesoft"));

DataSet의 상수값을 가진 열(column) 추가

10) DataSet의 원본 데이터와 변경된 데이터

DataSet은 데이터가 추가, 변경, 삭제된 경우 변경된 상태와 변경 이전의 원본 데이터를 저장한다. 데이터가 변경되는 경우에는 원본 데이터를 별도로 저장하고, 현재 데이터를 변경하며, 삭제되는 경우에는 현재 데이터에서는 삭제되지만,
별도의 삭제된 데이터에 저장된다. 변경된 상태는 행(row) 단위로 저장되며, DataSet의 getRowType(index)를 호출하여 현재의 상태를 확인할 수 있다.

상수값 설 명
DataSet.ROW_TYPE_NORMAL 일반적인 행(row)
DataSet.ROW_TYPE_INSERTED 추가된 행(row)
DataSet.ROW_TYPE_UPDATED 변경된 행(row), 원본 데이터 존재할 수 있음
DataSet.ROW_TYPE_DELETED 삭제된 행(row), 다른 데이터와는 별도로 저장됨

저장 여부는 DataSet의 startStoreDataChanges()를 호출하여 활성화시키고, stopStoreDataChanges()를 통하여 저장을 중지하며, startStoreDataChanges()를 호출하는 시점의 데이터를 기준 데이터로 설정된다.

startStoreDataChanges()가 호출되면 이전에 저장된 원본 또는 삭제된 데이터는 삭제되므로, 데이터 유지가 필요한 경우 startStoreDataChanges(true)를 호출하여야 한다.
반대로 stopStoreDataChanges()가 호출되면 이전에 저장된 원본 또는 삭제된 데이터는 보존되므로, 보존을 원하지 않는 경우 stopStoreDataChanges(false)를 호출한다.

또한, 각각의 상태에 따른 데이터는 다음 메소드를 통하여 참조할 수 있다.

  • 현재 데이터 : getObject(rowIndex, columnIndex) 등
  • 변경 이전의 원본 데이터 : getSavedData(rowIndex, columnIndex) 등
  • 삭제된 데이터 : getRemovedData(rowIndex, columnIndex) 등

주의할 점은 DataSet의 기본 설정은 변경되는 상태와 데이터를 저장하는 것이다. 즉, DataSet의 생성과 동시에 startStoreDataChanges()가 자동적으로 호출되어 있는 것이다.

이것이 의미하는 것은 사용자가 startStoreDataChanges()를 별도로 호출되지 않는 이상 DataSet에 저장되는 모든 데이터의 상태는 ROW_TYPE_INSERTED일 것이다.
예를 들어, DataSet을 생성한 후에 데이터를 추가하고, 추가된 데이터를 다시 변경하더라도 데이터의 상태는 여전히 ROW_TYPE_INSERTED이다. 이유는 DataSet의 기준 데이터는 생성한 직후가 되기 때문에,
즉 데이터가 없는 상태를 기준으로 본다면 데이터는 여전히 추가된 상태인 것이다. 마찬가지로, 데이터를 추가한 후에 삭제하더라도 데이터의 상태는 ROW_TYPE_DELETED가 아니고, 데이터가 없는 상태를 기준으로 본다면 어떤 변경도 없었던 것이다.

따라서, DataSet의 추가, 변경, 삭제된 상태와 데이터가 필요한 경우 적절한 시점에 startStoreDataChanges()가 호출되어야 한다. 물론 DataSet을 생성하지 않고, 통신을 통해 전달받고, 이 시점을 기준 데이터로 본다면 굳이 호출하지 않아도 된다.

PlatformData department = ...;
// DataSet을 식별자(id)를 이용하여 참조
DataSet employees = department.GetDataSet("employees");
// 변경 정보 저장 시작
employees.StartStoreDataChanges();
// DataSet의 데이터 추가, 변경, 삭제 수행
...
// 변경 정보 저장 중지
employees.StopStoreDataChanges();
// DataSet의 행(row)수만큼 순환
for (int i = 0; i < employees.GetRowCount(); i++) {
  // 행(row)의 상태 참조
  int rowType = employees.GetRowType(i);
  if (rowType == DataSet.ROW_TYPE_NORMAL) {
    // 일반적인 행(row)인 경우
    object name = employees.GetObject(i, "name");
    // ...
  } else if (rowType == DataSet.ROW_TYPE_INSERTED) {
    // 추가된 행(row)인 경우
    object name = employees.GetObject(i, "name");
    // ...
  } else if (rowType == DataSet.ROW_TYPE_UPDATED) {
    // 변경된 행(row)인 경우
    object name = employees.GetObject(i, "name");
    object savedName = employees.GetSavedData(i, "name");
    // ...
  } else {
    // 발생 않음
  }
}
for (int i = 0; i < employees.GetRemovedRowCount(); i++) {
  // 삭제된 형(row)인 경우
  object removedName = employees.GetRemovedData(i, "name");
  // ...
}

추가, 변경, 삭제된 DataSet의 행(row)

6. com.nexacro17.xapi.tx Description

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

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


  1. 시작하기
  2. 데이터 송수신
  3. 데이터 송수신의 내부 흐름
  4. Server 상의 HTTP 데이터 통신
  5. 데이터 송수신 형식
  6. 데이터 프로토콜 형식
  7. 추가, 변경, 삭제된 데이터 송신

1) 시작하기

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

using Nexacro17.Xapi.Data;
using Nexacro17.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();
    }
}

X-API를 이용한 예제

2) 데이터 송수신

nexacro platform과의 데이터 통신은 대부분의 경우 HTTP 상에서 수행되며, 특정 형식으로 변환된 후 송수신된다.

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

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

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

3) 데이터 송수신의 내부 흐름

데이터 송신 흐름

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

데이터 수신 흐름

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

4) Server 상의 HTTP 데이터 통신

nexacro platform과 HTTP 상에서 데이터 통신을 하기 위해서는 PlatformRequest와 PlatformResponse를 이용하여 cs 파일을 작성한다.

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

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

HttpRequest으로부터 데이터 수신

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

HttpResponse으로 데이터 송신

using Nexacro17.Xapi.Data;
using Nexacro17.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();
    }
}

echo.cs 예제

5) 데이터 송수신 형식

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

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


// 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();

XML 형식으로 데이터를 수신하고, Binary 형식으로 데이터를 송신하는 예제

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

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




 
6) 데이터 프로토콜 형식


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





상수값 설 명  



PlatformType.PROTOCOL_TYPE_ZLIB 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();    

   




ZLIB 방식으로 압축하여 데이터 송신


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


DataSet은 데이터가 추가, 변경, 삭제된 경우 변경된 상태와 변경 이전의 원본 데이터를 저장한다. 자세한 정보는 10) 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이 적용된다.