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는 데이터 구조의 최상위에 위치하고 있으며, 데이터 이동과 데이터 송수신의 기본 단위로 사용되어집니다.

데이터 형식

X-API에서 지원하는 데이터의 형식(type)은 DataTypes에 정의되어 있습니다.

데이터의 형식은 nexacro platform과 X-API간의 약간의 차이가 존재하고, X-API가 약간 더 세분화되어 있습니다. 그러나, 기본적으로 nexacro platform과 X-API간의 통신중의 데이터 손실은 발생하지 않습니다.

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

Variable에 저장된 데이터는 getObject()과 getString()등의 필요한 데이터 형식에 따른 메소드를 이용하여 값을 참조할 수 있습니다.

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

VariableList에 저장된 Variable은 get(name) 메소드를 통해 참조하며, getObject(name)과 getString(name)등의 메소드를 통하여 직접 값을 참조할 수도 있습니다.

$r_title(단일 데이터(Variable) 참조)
PlatformData department = ...;

// VariableList 참조
VariableList varList = department.getVariableList();

// VariableList으로부터 값을 직접 참조
String name = varList.getString("name");

// Variable을 통한 값을 참조
Variable locationVar = department.getVariable("location");
String location = locationVar.getString();

// VariableList으로부터 int 형의 값을 직접 참조
int number = varList.getInt("number");

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");
	boolean 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);
  boolean manager = employees.getBoolean(i, 3);

  // ...
}

DataSet 생성

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

1. DataSet 생성

2. 열(column) 추가

3. 행(row) 추가

4. 데이터 설정

$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)에 대한 정보는 다음과 같습니다.

$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();
  boolean 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:
      boolean 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의 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");

  // ...
}

DataSet의 이벤트

DataSet은 구조가 변경되거나 데이터가 변경된 경우 DataSetEvent를 발생시킵니다. 만약에 DataSet 변경에 따른 특정 행동 또는 처리가 필요한 경우 DataSetListener를 구현하여 DataSet에 등록하여야 합니다.

이벤트가 호출되는 시점은 다음과 같이 4가지 경우입니다.

$r_title(DataSet에 DataSetListener 등록)
DataSet employees = new DataSet("employees");

// DataSet에 DataSetListener 등록
DataSetListener listener = new DataSetEventHandler();
employees.addDataSetListener(listener);

// 열(column) 추가, DataSetListener의 structureChanged 호출됨
employees.addColumn("name", DataTypes.STRING, 8);

// 행(row) 추가, DataSetListener의 rowInserted 호출됨
int row = employees.newRow();

// 데이터 설정, DataSetListener의 dataUpdated 호출됨
employees.set(row, "name", "John Jones");

// ...

$r_title(DataSetListener의 구현체)
class DataSetEventHandler implements DataSetListener {

  public void structureChanged(DataSetEvent e) {
    // 열(column)의 삭제등 구조가 변경된 경우
    DataSet ds = (DataSet) e.getSource();

    // ...
  }

  public void dataUpdated(DataSetEvent e) {
    // 데이터가 변경된 경우
    DataSet ds = (DataSet) e.getSource();
    int firstRow = e.getFirstRow();
    int lastRow = e.getLastRow();
    int column = e.getColumn();

    // ...
  }

  public void rowInserted(DataSetEvent e) {
    // 행(row)이 추가된 경우
    DataSet ds = (DataSet) e.getSource();
    int firstRow = e.getFirstRow();
    int lastRow = e.getLastRow();

    // ...
  }

  public void rowRemoved(DataSetEvent e) {
    // 행(row)이 삭제된 경우
    DataSet ds = (DataSet) e.getSource();
    int firstRow = e.getFirstRow();
    int lastRow = e.getLastRow();

    // ...
  }
}

DataSet의 선택사항

DataSet은 몇가지 선택사항을 가지고 있으며, 필요에 따라 선택사항의 값을 변경합니다. 다음은 DataSet의 선택사항들입니다.

데이터 설정 또는 반환시의 데이터 형식(type)과 데이터 변환

Variable과 DataSet은 데이터와 더불어 데이터의 형식(type)을 가지고 있습니다. 데이터의 형식(type)에 대한 자세한 내용은 데이터 형식을 참조해주세요. 만약에 설정된 데이터의 형식(type)과 다른 형식(type)의 데이터를 저장하거나, 저장된 데이터와 다른 형식(type)의 데이터로 반환을 요구하는 경우 데이터의 변환이 발생하게 됩니다.

예를 들어, Variable의 데이터 형식(type)은 String이지만, 숫자 123을 저장하는 경우 숫자 123은 문자열 "123"으로 변환되어 저장되어야 합니다. 또는 문자열 "123"을 저장하고 있는 상태에서 int 형식의 데이터를 요구하는 경우 문자열 "123"은 숫자 123으로 변환되어 반환되어야 합니다.

단, DataSet의 isConvertingToDataType가 false인 경우 데이터 설정시 위와 같은 변환은 이루어지지 않습니다.

Variable과 DataSet은 위와 같은 데이터 변환을 VariableDataConverter과 DataSetDataConverter에 위임합니다. Variable에 기본적으로 설정된 VariableDataConverter는 DefaultVariableDataConverter이며, DataSet에 기본적으로 설정된 DataSetDataConverter는 DefaultDataSetDataConverter입니다.

만약에 기본적으로 설정된 DataSet의 DataSetDataConverter를 이용하지 않고, 다른 방식의 변환을 원하는 경우 DataSetDataConverter를 직접 구현하거나, 또는 DefaultDataSetDataConverter를 상속받아 원하는 부분만 재정의하여 DataSet의 setDataConverter(DataSetDataConverter)을 호출하여 설정하면 됩니다. DataSet의 메소드와 그 내부에서 호출되는 DataSetDataConverter의 메소드와의 관계는 DataSetDataConverter를 참조해주세요. Variable도 DataSet과 동일한 방식으로 설정하면 됩니다.

$r_title(DataSet의 사용자 정의 DataSetDataConverter 등록)
DataSet ds = new DataSet("ds");
// "yyyy-MM-dd" 형식의 문자열도 Date로 변환해주는 DataSetDataConverter 설정
ds.setDataConverter(new UserDataConverter());

// 열(column)과 행(row) 추가
ds.addColumn("date", DataTypes.DATE_TIME, 256);
ds.newRow();

// "yyyy-MM-dd" 형식의 데이터 설정
ds.set(0, "date", "2008-12-25");

$r_title(사용자 정의 DataSetDataConverter)
class UserDataConverter extends DefaultDataSetDataConverter {

  public Object convert(DataSet ds, int row, int column, String value, int type) {
    return convert(ds, row, column, value, type, null);
  }

  public Object convert(DataSet ds, int row, int column, String value, int type, String charset) {
    // 데이터의 형식(type)이 DataTypes.DATE_TIME 형식인 경우
    // 기본적으로 지원하지 않는 "yyyy-MM-dd" 형식의 문자열도 Date로 변환
    if (type == DataTypes.DATE_TIME) {
      int len = (value == null) ? -1 : value.length();

      if (len == 10) {
        try {
          return new SimpleDateFormat("yyyy-MM-dd").parse(value);
        } catch (ParseException ex) {
          ;
        }
      }
    }

    return super.convert(ds, row, column, value, type, charset);
  }
}

데이터의 Debug 정보

개발시에는 데이터의 내용을 파악하기 위해 출력이 필요한 경우가 발생합니다. Debug를 위하여 데이터의 내용을 출력하기 위해서는 Debugger를 이용하여 출력합니다.

다음은 Debugger를 이용하여 데이터를 출력하는 예제와 출력 결과입니다.

$r_title(출력 결과 예)
PlatformData department = ...;

// Debugger 생성
Debugger debugger = new Debugger();

// Debug 정보 출력
log(debugger.detail(department));

variable=[
index=0 (name, string, "R&D Center")
, index=1 (location, string, "222 Jamsil-Dong, Songpa-Ku, Seoul")
, index=2 (number, int, "99")
]
---------- index=000 ----------
name=employees, alias=employees, columnCount=4, rowCount=2, charset=null, isStoreDataChanges=true
, column=[
index=0 (id, int, 4)
, index=1 (firstName, string, 16)
, index=2 (lastName, string, 8)
, index=3 (manager, bool, 2)
]
, row=[
index=0 inserted ("0", "John", "Jones", "false")
, index=1 inserted ("1", "Tom", "Glover", "true")
]