2.1 Overview
The ST-Developer for Java library includes foundation classes that provide data management and serve as the base which is extended by the EXPRESS compiler. These classes provide the high-level data management, store metadata for the EXPRESS schema, and implement a late-bound API to the STEP data.
Unless otherwise indicated, all classes and interfaces are declared in the com.steptools.stdev namespace. Definitions in the schema namespace are generated by the EXPRESS compiler under com.steptools.schemas.< schname> , where schname is the name of the schema.
2.2 Models and Populations
STEP instances are organized into model and populations. A model coresponds to an entire a STEP Part 21 file, and a population corresponds to the HEADER or DATA section within the file. Most models will contain a header and a data population, but some might contain several data populations (the second edition of Part 21 allows more than one data section). Populations contain the STEP entity instances. Each population is associated with exactly one EXPRESS schema.
A model is represented by the Model class in com.steptools.stdev . A population is represented by a generated class named Population in the schema namespace. The Population class extends the PopulationBase class in com.steptools.stdev . There is no schema-specific model class, since a schema can contain instances from several schemas. Any method of Model that returns a population object is declared to return PopulationBase , which you may need to cast down to the intended type.
To create a Model with a Population , pass the schema to the constructor for the Model . The Population can then be obtained by calling getPopulation() on the Model . The following example shows how to create and populate a model. In this example, the schema is not imported in order to emphasize which definitions come from the ST-Developer class library, and which are EXPRESS compiler generated classes.
/* In this example, no schemas are imported.
* actual code is likely to be much less verbose.
*/
Model mod = new Model
(com.steptools.schemas.config_control_design.Schema.SCHEMA);
com.steptools.schemas.config_control_design.Population pop
= mod.getPopulation();
/* Create a instance */
com.steptools.schemas.config_control_design.Cartesian_point point
= pop.newCartesianPoint();
Generally, a Model will only contain a single Population of user instances. The Part 21 interface uses an additional Population to hold the STEP header information. It is possible, however, to create a Model with more than one Population . This can be used, to create a Part 21 file with multiple data sections. To create a Model with more than one Population , use the default, no argument, constructor for Model , and use the newPopulation method to create each Population in the model. Each Population must have an identifier, which is a java.lang.Object that is specified as a parameter to the newPopulation method. For models saved in Part 21 files, this identifier must be a string that gives the name of the data section in the Part 21 file.
To get a default Population from a Model , use one of the getPopulation methods. With no arguments, or with a null parameter getPopulation return the default Population of the Model . If you specify an argument it is interpreted as an identifier,and getPopulation returns the Population with the specified identifier, or null if no Population exists with that identifier.
2.3 Managing Entity Instances
STEP entity instances are represented by interfaces generated by the EXPRESS compiler. For every entity in a schema, the compiler creates a corresponding interface in the schema namespace. These generated interfaces extend the EntityInstance interface.
The schema-specific Population class contains a method to create entity instance in the schema. This method is named new<Entname> where Entname is the name of the entity, as mapped to Java (first letter is capitalized, all others lowercase).
To create an entity instance in a Population , call the appropriate new method on the Population .
To remove an entity instance from a Population call the removeInstance method. The instance is removed from the Population , but it will not get deleted from memory until the garbage collector notices that the instance is unreferenced.
2.4 Accessing Entity Instances by Type
The Population classes provides several methods to find instances by type. This is the most common way to access the data after loading a Model from a file on disk. The getExtent and getFolder methods each return an EntityExtent containing all the entity instances of a given type. The EntityExtent that the getExtent method returns also contain instances of all subtypes of the specified type. The EntityExtent class implements the java.util.Set interface, so you can obtain an Iterator , and traverse over the instances.
The following code traverses over all the product entity instances in a Population .
import com.steptools.schemas.config_control_design.*;
import com.steptools.stdev.*;
import java.util.*;
/* much further down - inside a class */
void processProducts(Population pop) {
EntityExtent prods = pop.getExtent(Product.DOMAIN);
Iterator itor = prods.iterator();
while (itor.hasNext()) {
Product prod = (Product) itor.next();
/* Now do something with the product */
}
}
2.5 Reading Part 21 Files
The Part21Parser class reads a Part 21 file into memory. To read a file, create an instance of Part21Parser , then call one of the parse methods to read the Model . For flexibility, the parse method is overloaded to take either a file name, a java.io.File object, or a java.io.Reader object. Whichever version is called, a Model is returned. The Part21Parser object may be reused to read multiple files.
The following code demonstrates how to read a Part 21 file, given the file name.
/* at the top of your code: */
import com.steptools.stdev.*;
import com.steptools.stdev.p21.*;
/* inside a class: */
Model read_file (String filename) throws STDevException, IOException {
Part21Parser parser = new Part21Parser();
return parser.parse(filename);
}
The Part 21 file header contains string that identifies the STEP schema. Normally the schema is found by loading the class named com.steptools.schemas.<schema-name>.Schema . You can override this behavior, by subclassing Part21Parser , and overriding the getSchema method. The following code demonstrates how to read every Part 21 file as if it were an AP203 file:
import com.steptools.stdev.p21.*;
class AP203Parser extends Part21Parser {
public SchemaBase getSchema(Stirng name) {
/* The schema object is in a static field of the Schema class */
return com.steptools.schemas.config_control_design.Schema.SCHEMA;
}
}
2.6 Writing Part 21 Files
The Part21Writer class is used to write a Model to secondary storage. To write a Part 21 file, create an instance of Part21Writer, and call one of the write methods. The write method is overloaded to take either a file name, a java.io.File object, or a java.io.Writer object for maximum flexibility. The same Part21Writer can be used to write multiple models to secondary storage.
The following example demonstrates how to write a Model to secondary storage:
/* at the top of your code: */
import com.steptools.stdev.*;
import com.steptools.stdev.p21.*;
/* inside a class: */
Model write_file (Model mod) throws STDevException, IOException {
Part21Writer writer = new Part21Writer();
return writer.write("test.stp", mod);
}
If you need to the control the name of the schema that gets written in the header of the file, you can subclass Part21Writer and override the getSchema method.
2.7 Entity Instance Identifiers
Every entity instance in a Part 21 file has an identifier. In the Part 21 file, the identifier is a "#" character followed by a number. ST-Developer includes the EntityIDTable to track the identifiers in a Model . The EntityIDTable is created when a Model is read from or written to a Part 21 file, or is can be created dynamically with the EntityIDTable.forModel static method. Identifiers in the EntityIDTable are of type java.math.BigInteger .
To find an EntityInstance by identifier, use the getInstance method of the EntityIDTable instance. The following example shows how to find an instance:
void EntityInstance findByID (Model mod, BigInteger id) {
/* Get the EntityIDTable for the model. This method will get the
* table associated with the model. This will create the table if it
* does not already exist.
*/
EntityIDTable tab = EntityIDTable.forModel(mod);
return tab.getInstance(id);
}
To get the identifier for an EntityInstance , use the getId method. This method takes a second parameter, with, if true, will assign an identifier to the instance otherwise, the method returns zero.
2.8 STEP Header
The HEADER section of a Part 21 file contains a timestamps, author, organization, and related information. In memory, the header is represented as a Population of the header_section_schema , which is defined in the Part 21 specification. While you can directory access to population, it is more convient to use the com.steptools.stdev.p21.Header class.
The Header class includes methods getFileName() and getFileDescription() that get the file_name and file_description instances, respecively, from the Part 21 header. If these instances do not exist, these methods will create them. In addition, a munber of attributes of these entities are declared as lists of strings. These methods insture that these lists exist by creating them is they are set to null.
This example shows how you could add a string to the description of a file:
import com.steptools.stdev.p21.*;
import com.steptools.stdev.*;
void addDescription (Model mod, String desc) {
Header head = Header.forModel(mod);
return head.getFileName().getFileDescription().getDescription()
.add(desc);
}
The following example returns the "originating system" attribute:
String getOrig (Model mod) {
Header head = Header.forModel(mod);
return head.getFileName().getOriginating_system();
}