Using the STEP Tools® Software Java Libraries

Overview

STEP Tools^® software ships with pre-built Java libraries for the common information models. You can start programming immediately, just by adding the appropriate library to your classpath, and taking note of the details below or by using Java sample programs.

If we have not provided pre-built class library for the schema you are working with (or you want to change one of the preinstalled libraries) we have instructions for generating a class library from scratch.

Class Path

In order to run your application, you must provide the Java runtime with Jar files for the AP classes and the STEP Tools^® software base library. All Jar files are kept in the lib/java subdirectory under the STEP Tools^® software installation.

The STEP Tools^® software installer set the ROSE environment variable to the root of the installation, so you can specify the path as shown in the example below. The stdev.jar file has the definitions for the STEP Tools^® software base library. The name of the other Jar file is documented on the page for each schema, but follows the convention of ap201lib.jar, ap202lib.jar, etc.

# On Windows
> java -cp "%ROSE%"\lib\java\stdev.jar;"%ROSE%"\lib\java\ap203lib.jar prog

# On UNIX or MacOS 
> java -cp $ROSE/lib/java/stdev.jar;$ROSE/lib/java/ap203lib.jar prog

Imports

Your code will normally import all of the classes for a schema. The classes are under com.steptools.schemas, with separate packages for each schema. The specific path can be found on the page for each schema.

In addition, you will need to import definitions from the STEP Tools^® software base library. These are in com.steptools.stdev

/* example for AP203 */
import com.steptools.stdev.*;
import com.steptools.schemas.config_control_design.*;

Naming Conventions

The names for the generated definitions are all lowercase with the first letter in uppercase. So the interface for the "product" EXPRESS definition is Product, the interface for "cartesian_point" is Cartesian_point, and so on.

All definitions are under com.steptools.schemas.[schema-name], so any symbol conflicts with names like "Point" or "Curve" can be handled simply by qualifying the symbol.

Complete lists of all interfaces/classes for entities, aggregates, select types, and enumerations, can be found on the page for each schema.

Complex Entity Combinations

Complex entity combinations (sometimes called "AND/OR" instances) are instances with a set of types rather than a single type. This is just multiple inheritance, but the EXPRESS schema does not define an ENTITY for the combination.

The STEP Tools^® Java libraries do not have specific classes or interfaces for the combinations. Instead, they handle complex instances through late-bound calls on the EntityInstance interface.

In the Part 21 files, complex instances are written differently. Each supertype is called out in a parenthesized list along with the attributes defined by the super. The example below shows some complex instances used for unit definitions in STEP.

/* SI Units and Conversion-based units, complex instances */
#14= ( 	LENGTH_UNIT()
	NAMED_UNIT(*)
	SI_UNIT(.MILLI.,.METRE.)  );

#15= (	NAMED_UNIT(*)
	PLANE_ANGLE_UNIT()
	SI_UNIT($,.RADIAN.) );

#16= (	CONVERSION_BASED_UNIT('degree',#18)
	NAMED_UNIT(#17)
	PLANE_ANGLE_UNIT() );

/* some normal instances */
#17= DIMENSIONAL_EXPONENTS (0.,0.,0.,0.,0.,0.,0.);
#18= MEASURE_WITH_UNIT (PLANE_ANGLE_MEASURE(0.01745329252),#15);

If you look at the EXPRESS for named_unit, you will see that it has two groups of subtypes, some to describe the purpose of the unit (length_unit, plane_angle_unit, area_unit, etc) and some to describe the definition of the unit (si_unit, conversion_based_unit). STEP usage requires us to make a complex instance by picking one from each of these groups.

To create a complex instance, call the newInstance method of a Population, specifying all the supertypes of the complex instance. The following example constructs a complex instance of length_unit and si_unit and sets the fields to indicate a "millimeter" unit.

public EntityInstance create_millimeter_unit (Population pop) {
    /* Must be a SI_UNIT and LENGTH_UNIT combination */
    EntityDomain[] supers = {Length_unit.DOMAIN, Si_unit.DOMAIN};
    EntityInstance mm = pop.newInstance(supers);

    /* Set the SI_UNIT attributes */
    Si_unit mm_as_si_unit = (Si_unit) mm.castTo(Si_unit.DOMAIN);
    mm_as_si_unit.setPrefix (Si_prefix.MILLI);
    mm_as_si_unit.setName (Si_unit_name.METRE);

    return mm;
}

Building a New Java Library

If we have not provided pre-built class library for the schema you are working with (or you want to change one of the preinstalled libraries) you can generate your own Java classes using the EXPRESS to Java compiler. Given an EXPRESS schema, this tool will create Java source code in the java_classes subdirectory, which you can then compile and put into a Jar file.

# generate the Java classes
% express2java myschema.exp