JSDAI Introduction

Example Write Application

In the previous chapter we did read and analyze a part21 file.
This chapter is on creating part21 files like this:

ISO-10303-21;
HEADER;
FILE_DESCRIPTION(('Examp1e program to generate a very basic AP203 p21 file'),'2;1');
FILE_NAME('&repository1','2000-02-09 T10:58:28',('Lothar Klein'),('LKSoftWare GmbH'),
'NO VERSION','J-SDAI MULTIPLE level: Version 2.0 (Build 173, 2000-02-07)','Lothar Klein');
FILE_SCHEMA(('CONFIG_CONTROL_DESIGN'));
ENDSEC;
DATA;
#1=APPLICATION_CONTEXT('CONFIGURATION MANAGEMENT');
#2=APPLICATION_PROTOCOL_DEFINITION('INTERNATIONAL STANDARD','CONFIG_CONTROL_DESIGN',
1994,#1);
#3=MECHANICAL_CONTEXT('CONFIGURATION CONTROL DESIGN',#1,'MECHANICAL');
#4=PRODUCT('TestId','TestName','TestDescription',(#3));
ENDSEC;
END-ISO-10303-21;

This is about the smallest possible AP203 example. It does not fit to several global rules of AP203 but it is valid according to the EXPRESS structural definitions.

Step by Step

SDAI-Session and SDAI-transaction

Like in the previous example the session is started at the beginning and closed at the end. This application is creating/modifying data, so a Read/Write transaction is started. But because the data is not intended to be persistent the transaction is aborted at the end.

public static final void main(String argv[]) throws SdaiException {
SdaiSession.setLogWriter(new PrintWriter(System.out, true));
SdaiSession session = SdaiSession.openSession();
SdaiTransaction transaction = session.startTransactionReadWriteAccess();
...
transaction.endTransactionAccessAbort();
...
session.closeSession();
}

SDAI-Repository

Having the session and the R/W transaction createRepository() gives us new empty repository. The first parameter specifies the repository-name. Giving an empty String "" assigns JSDAI to create a temporarily repository which exist only during this session. The second parameter is the location of the repository, e.g. a remote location. A null value assign jsdai to use the default repositories directory.

A new part21 file is created with exportClearTextEncoding. The whole contents and all the header information of the repository is written out. The only one parameter specifies where to place the part21 file. In this case the first command line argument is used. At the end the repository is closed and deleted. Because the repository is created as a temporarily, this is not really needed - it is only given here for completeness.

SdaiRepository repo = session.createRepository("", null);
repo.openRepository();
...
repo.exportClearTextEncoding(argv[0]);
...
repo.closeRepository();
repo.deleteRepository();

Please note that creation and deletion of repositories is not covered by the transaction mechanism.

Repository / Part21 Header information

The header information of a part21 file is also available for an SdaiRepository. When creating the repository these fields are pre-set with default values if needed or left empty otherwise. It is up to the application to fill them. Some of the header fields (description, author, organization) are aggregates of strings. The aggregates itself do always exist - the user only need to add his values to these aggregates. Other header fields (originatingSystem, authorization) are simple strings which can be directly set.

A_string descriptions = repo.getDescription();
descriptions.addByIndex(1, "Examp1e program to generate a very basic AP203 p21 file");
A_string authors = repo.getAuthor();
authors.addByIndex(1, "Lothar Klein");
A_string organizations = repo.getOrganization();
organizations.addByIndex(1, "LKSoftWare GmbH");
repo.setOriginatingSystem(session.getSdaiImplementation().getName() + " " +
session.getSdaiImplementation().getLevel() );
repo.setAuthorization("Lothar Klein");

SDAI-Model

We need one SDAI-model where we can create the entity instances later on. The main attributes of SDAI model are name and underlying_schema. In this example the name is "Model1" and the underlying_schema is AP203. Here we use the early binding version of createSdaiModel where the schema is specified through a special Java class SXxx in package jsdai.SXxx. For AP203 we have to replace Xxx with Config_control_design. The operator ".class" gives us a Class object (capital C) representing this Java class. A read-write access is started on this model allowing to create entity instances.

Usually the read-write access on the model is ended when no longer needed. But after some changes these changes first need to be either accepted or rejected through the transaction operation commit and abort. Here we abort and end the transaction in one operation. Ending the transaction results also in ending all read-only or read-write access to models.

SdaiModel model = repo.createSdaiModel("Model1", jsdai.SConfig_control_design.SConfig_control_design.class);
model.startReadWriteAccess();
...
transaction.endTransactionAccessAbort();

Creating Entity-Instances

An SdaiModel is based on an underlying express schema. It can contain only entity instances available for this schema. Again we use the early binding version of createEntityInstance where the entity type is specified by the Java class representing this entity. Please note that applications usually use the Java interfaces EXxx representing the entity. Only for creation and a few other purposes we use the Java classes representing the exact complex entity data type CXxx. The creation of an entity instance looks like this:

EXxx instance = (EXxx) model.createEntityInstance(CXxx.class);

In this example application we need instances of the types application_context, application_protocol_definition, mechanical_contextand product. Here they are:

EApplication_context app_context = (EApplication_context)
model.createEntityInstance(CApplication_context.class);
EApplication_protocol_definition app_protocol = (EApplication_protocol_definition)
model.createEntityInstance(CApplication_protocol_definition.class);
EMechanical_context mechanical = (EMechanical_context)
model.createEntityInstance(CMechanical_context.class);
EProduct product = (EProduct) model.createEntityInstance(CProduct.class);

Setting the Attributes

After creating entity instances all attributes are unset - even if EXPRESS defines them to be mandatory. So the last step to do is to provide values for the attribute. If the values are of a non-aggregate type the set methods are used. For early binding the name of the attribute is combined with the prefix "set". Depending on the type of the attribute the set methods accept String, int, an specialized entity EXxx or the generic entity EEntity, etc. Here are some examples:

app_context.setApplication(null, "CONFIGURATION MANAGEMENT");
app_protocol.setApplication_protocol_year(null, 1994);
mechanical.setFrame_of_reference(null, app_context);

Attributes of an aggregate type can't be set. The aggregate instance can only be created in place. For early binding the method name is a combination of the prefix "create" with the attribute name. After the aggregate is created members can be added to it.

AProduct_context contexts = product.createFrame_of_reference(null);
contexts.addUnordered(mechanical);

It is also possible to create a instance of e.g. AProduct_context with the new operator. But this would create only a non-persistent list. Such an aggregate instance can't be set to an attribute of an entity-instance - or in the case of nested aggregates to a member of the enclosing aggregate.

Complete Example

// Simple SDAI application program.
// Generates a very basic ap203 population and
// writes it out into a p21 file.

import java.io.*;
import jsdai.lang.*;
import jsdai.SConfig_control_design.*;
import jsdai.SApplication_context_schema.*;
import jsdai.SProduct_definition_schema.*;

public class Example11 {
public static final void main(String argv[]) throws SdaiException {

if (argv == null || argv.length != 1) {
System.out.println("usage:");
System.out.println(" Example11 output_file");
return;
}
// redirect the J-SDAI system log to System.out
SdaiSession.setLogWriter(new PrintWriter(System.out, true));
// first open a session and specify the desired AP
SdaiSession session = SdaiSession.openSession();
// start a read/write transaction to allow importClearTextEncoding
SdaiTransaction transaction = session.startTransactionReadWriteAccess();
SdaiRepository repo = session.createRepository("", null);
repo.openRepository();
A_string descriptions = repo.getDescription();
descriptions.addByIndex(1, "Examp1e program to generate a very basic AP203 p21 file");
A_string authors = repo.getAuthor();
authors.addByIndex(1, "Lothar Klein");
A_string organizations = repo.getOrganization();
organizations.addByIndex(1, "LKSoftWare GmbH");
repo.setOriginatingSystem(session.getSdaiImplementation().getName() + " " +
session.getSdaiImplementation().getLevel() );
repo.setAuthorization("Lothar Klein");
SdaiModel model = repo.createSdaiModel("Model1", jsdai.SConfig_control_design.SConfig_control_design.class);
model.startReadWriteAccess();
EApplication_context app_context = (EApplication_context) model.createEntityInstance(CApplication_context.class);
app_context.setApplication(null, "CONFIGURATION MANAGEMENT");
EApplication_protocol_definition app_protocol = (EApplication_protocol_definition) model.createEntityInstance(CApplication_protocol_definition.class);
app_protocol.setStatus(null, "INTERNATIONAL STANDARD");
app_protocol.setApplication_interpreted_model_schema_name(null, "CONFIG_CONTROL_DESIGN");
app_protocol.setApplication_protocol_year(null, 1994);
app_protocol.setApplication(null, app_context);
EMechanical_context mechanical = (EMechanical_context)
model.createEntityInstance(CMechanical_context.class);
mechanical.setName(null, "CONFIGURATION CONTROL DESIGN");
mechanical.setFrame_of_reference(null, app_context);
mechanical.setDiscipline_type(null, "MECHANICAL");
EProduct product = (EProduct) model.createEntityInstance(CProduct.class);
product.setId(null, "TestId");
product.setName(null, "TestName");
product.setDescription(null, "TestDescription");
AProduct_context contexts = product.createFrame_of_reference(null);
contexts.addUnordered(mechanical);
repo.exportClearTextEncoding(argv[0]);
transaction.endTransactionAccessAbort();
repo.closeRepository();
repo.deleteRepository();
System.out.println();
System.out.println("Done");
session.closeSession();

}
}

Running the program

C:\examples>javac Example11.java

C:\examples>java Example11 t.stp
--- time for getting values=0sec
--- Writing time=0sec
Done

The resulting file "t.stp" is given above.

Download Example11.java