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

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

시작하기

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

$r_title(데이터 참조)

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의 데이터를 생성하는 간단한 예제입니다.

$r_title(데이터 생성)
// 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차원 데이터로 구분합니다. 단일 데이터는 데이터를 구분할 수 있는 식별자(name)와 값(value)을 가지고 있으며, 이는 VariableList에 저장됩니다. 2차원 데이터를 저장하는 DataSet은 열(column)과 행(row)으로 구성되어 있으며, DataSetList를 통해 저장 또는 참조됩니다.

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

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) 메소드를 통하여 직접 값으로 추가할 수 있습니다.

$r_title(단일 데이터(Variable) 추가)
// 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);

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)등의 필요한 데이터 형식에 따른 메소드를 이용하여 값을 참조할 수 있습니다.

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

$r_title(식별자(name)를 이용한 DataSet의 데이터 참조)
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");
  // ...
}

$r_title(위치(index)를 이용한 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);
  // ...
}

DataSet 생성

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

DataSet 생성
열(column) 추가
행(row) 추가
데이터 설정

$r_title(DataSet 생성과 데이터 추가)
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);
// ...

ColumnHeader의 속성 참조

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

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

$r_title(ColumnHeader의 속성 참조)
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를 이용한 DataSet의 열(column) 추가

DataSet에 열(column)을 추가하는 방법은 AddColumn(name, dataType, dataSize)를 통하거나, 직접 ColumnHeader를 생성하여 추가할 수 있습니다.

$r_title(ColumnHeader를 이용한 DataSet의 열(column) 추가)
// 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의 데이터 참조

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

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

$r_title(ColumnHeader를 이용한 DataSet의 데이터 참조)
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;
    }
  }
}

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

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

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

$r_title(DataSet의 상수값을 가진 열(column) 추가)
// 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의 원본 데이터와 변경된 데이터

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을 생성하지 않고, 통신을 통해 전달받고, 이 시점을 기준 데이터로 본다면 굳이 호출하지 않아도 됩니다.

$r_title(추가, 변경, 삭제된 DataSet의 행(row))
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");
  // ...
}