AP233 Software Development Support

1 Introduction

This document provides software-related artifacts, including AP233 application programming interface (API) libraries, that are useful for developing AP233-based software. The main purpose of these artifacts and APIs is to enable quicker implementation of AP233 by hiding some of the details of AP233 and the related AP233 XML schema from implementors.

It is useful to keep in mind that AP233 is infrastructure - the specification of a data pipeline for the purpose of integrating Architecture Framework, Systems Engineering and other applications.

AP233 Data Pipeline
Note
For STEP/EXPRESS experts, these artifacts are generated from the AP233 ARM which is the recommended implementation method enabling direct interoperability with the OASIS/STEP Product Life Cycle Support (PLCS) standard. This does mean that a mapping is necessary to achieve interoperability with traditional STEP standards.

Two kinds of AP233 APIs are discussed:

  1. High Level APIs : An API specified at a higher level of abstraction than AP233 itself and that reads and writes the required XML documents using a layered approach as described below.
  2. AP233 Level APIs : An API specified at the same level of abstraction as AP233 but specified in languages that are more accessible and easy to use (e.g. scripting languages like Ruby). This should also make AP233 data more accessible to users who are not professional software developers.
Note
A Ruby proof-of-concept API is available in the current version of this Web site.

A very simple example usage by a software developer is shown in the following figure. The software developer uses an API provided with the Systems Engineering application to read/write data from the SE application database. The software developer uses the AP233 High Level API to read/write AP233 XML files. The AP233 Processor might be a data importer or data exporter.

High Level API Usage

A Systems Engineer might invoke the AP233 Processor delivered as part of the SE application to export data into an AP233 file for transfer to a second SE application system. This usage of a data exchange export feeding into the AP233 data pipeline is shown in the following figure.

High Level API Usage

Additionally, AP233 data can be exchanged using multiple file formats (e.g. clear text ISO 10303-21 files, ISO 10303-28 Edition 1 DTD-based XML documents). The use of a High Level API allows the application software to be written without regard to different file formats as the API libraries take care of those details.

2 Design Concepts

2.1 Architecture

The AP233 High Level API architecture is designed to separate the API for use by clients from the details of the persistence mechanism, including XML. The implementation supported by this AP233 High Level API is based on the AP233 XML Schema model used in conjunction with External classes. Other persistence mechanisms can be added as required (e.g. RDBMS or STEP Part 21 files). The basic architecture is shown in the following figure.

High Level API Usage

Note that this architecture also allows developers to use the lower level APIs upon which the High Level API is built should that be required. This, for example, allows using DOM and XPATH on the XML Infoset.

2.2 What does higher level of abstraction mean?

The AP233 High Level API architecture is designed to allow more efficient manipulation of the AP233-driven data than if it was manipulated based on the concepts defined in the AP233 schema/model itself. In general, the classes in the High Level API are at a higher level of abstraction and group objects together that are created/destroyed simultaneously.

A second consideration for the development of a High Level API is the set of Business Objects in the domain supported by that API. AP233 addresses the Systems Engineering (SE) domain, so SE concepts should be visible in the API. This allows a more direct mapping from the concepts SEs use to the software developed for their support.

A third consideration for the development of a High Level API is the possibility of providing Web Services that are based on the concepts it defines. This takes a view that is more interested in the services/functions in a domain than in its data objects. In fact, those services might be built upon underlying data structures that are quite different from AP233 but which support the AP233 concepts as part of its definition or as an import/export capability.

Each of these design considerations (efficient access, Business Objects and Web Services) are important for the SE domain. However, for this initial AP233 High Level API work, the main focus has been on enabling more efficient access. The following figure shows a simple example of what this might mean. The State class has an operation defined called createSubstate which creates a new State of the specified kind, which is an enumeration of kinds of states, and links it as a substate of the current State. The Transition class has an operation defined called connectStates which sets the source State and target State for the Transition. The API defines interfaces for key operations on these business objects that are exposed by implementations. Conformant implementations will ensure that the integrity of the business objects are maintained as these operations are carred out. In this example, a call to connectStates should ensure that there is one source and one target object, and that both objects are States.

Simple Example of More Efficient Substate Creation

Even though the initial work focuses on enabling more efficient access, the architecture supporting the specification and development of the High Level API should enable additional requirements (and perhaps even additional APIs) to be addressed in the future. This is shown in the following possible future scenario where business level services are implemented using the current AP233 High Level API in the Server and the WSDL defines the interface for clients. The AP233 XML structures may also be used as the payload in the SOA envelop.

AP233 Usage in SOA and Web Services

2.3 What does more accessible mean?

A second approach to enabling simpler AP233 implementation via APIs is to provide them in more accessible languages. In this case, more accessible means using languages that do not require the use of professional software development tools. Note that development at this level does require knowledge of the concepts, attributes and relationships defined in AP233 itself.

AP233 Scripting Language Usage

The Ruby programming language is an example of a scripting language which is based on an interpreter (i.e. a piece of software that interactively executes a program). A second aspect of these languages is that the syntax is fairly easily understood so that people who are not professional software developers using Integrated Development Environments (IDEs) can still do something useful. Scripting languages like Ruby (see Ruby Home Page) are good for proof-of-concept implementations as the overhead involved in getting started is quite low.

An example of the use of the AP233 Ruby API showing just how easy it really can be.

## Create a model container for the data instances. Always use the ap233 namespace.
## A model equates to an XML file when output.
## Use the model_elements list to hold pointers to the instances included in the model.
## myData is the pointer to the container.
myData = AP233::Model___data.new
myData.namespace = "ap233"
##
## Create a Requirement.
## myReq is the pointer to the new Requirement instance.
myReq = AP233::Requirement.new
##
## Set the name attribute for instance number 1
myReq.name = "Requirement 1"
##
## Put the Requirement instance number 1 in the model container using the model_elements list.
myData.model_elements = [myReq]
 

3 AP233 Ruby API

This section describes Draft 0.3 of the AP233 Ruby API. It is specified as a mapping (or binding) from the AP233 model to the Ruby language.

Note
As more AP233 Ruby implementation experience is gained with Draft 0.3, future drafts of this API may change.

The AP233 Ruby API was generated directly from the AP233 ARM EXPRESS schema as shown in the following diagram.

AP233 Ruby API Generation

The following rules explain the result of the code generation process.

  1. All AP233 Ruby declarations are created in a Ruby module named AP233
  2. A container for AP233 Ruby instance data is available as the AP233::Model___data class.
  3. The AP233::Model___data has an associated "writeP28e2" method which writes the entire contents of the model into an XML document using the Ruby REXML capability. It also has a "readP28e2" method which reads an AP233 XML file defined to Ruby REXML into the model. The following shows writing the instances in a model referernced by the variable "m" into a file named "data.xml" in the local directory/folder.
    ##
    ## Set up the XML file and write all data in the model container to the file. Only change the File name.
    datafile = File.new("data.xml","w")
    p28file = REXML::Document.new
    m.writeP28e2 p28file
    datafile.puts p28file
    datafile.close	
    
  4. For each concept in the AP233 model, a Ruby class is defined. That class has the same name as these concept with the first letter upper case and all following letters in lower case.
  5. Inheritance, including support for multiple inheritance, is handled using a Ruby mixin (i.e. there is a Ruby module for each declared concept in AP233 defining accessors for locally defined attributes). The following Ruby class results from the AP233 Requirement concept that is a kind of AP233 Product.
    class Requirement
      include Product___module
      include Requirement___module
    end
    
  6. For each attribute, of any type and including all inherited attributes, a read and write accessor is created that has the same name as the attribute all in lower case. The following Ruby module results from the AP233 Organization concept that has an "id" and a "name" attribute.
    module Organization___module
      attr_accessor :id
      attr_accessor :name
    end
    
  7. For each attribute that is a set, bag, list or array the normal Ruby Array class methods are available (see Ruby Core API Reference - Array class methods").
  8. As Ruby is not a strongly typed language, the AP233 Ruby ARM API is very flexible, does no validity checking and so will allow the creation of invalid AP233 data (and even invalid AP233 XML files).

An HTML documentation capability called RDoc is built into Ruby 1.8.2 and later. The HTML generated from the AP233 Ruby API results in 15MB of data and so it is not distributed here - users can an use Rdoc to generate it themselves. However, screen shots showing what it looks like follow.

Note
With Ruby installed and at the Ruby prompt: rdoc AP233_ARM_LF.rb will generate the HTML.

The following screen shot shows the AP233 Behaviour class. It has no interesting methods defined on the class other than the new method. The accessors, which allow getting and setting attribute values, are all defined in the Ruby module that is generated for each concept in AP233. Inheritance is supported using these Ruby modules and the Ruby concept of mixins..

AP233 Behaviour RDoc example

The following screen shot shows the accessors defined against the AP233 Product concept, that get inherited by the AP233 Behaviour concept and all other subclasses of Product.

AP233 Product RDoc example

In order to manage the instances of AP233, a container class named AP233::Model__data is used. The following figure shows the methods and accessors defined for that class. The model_elements array contains the list of instances in the model.

AP233 Model data RDoc

4 Software artifacts

This section contains links to AP233 software artifacts that are useful for developers.

Warning
The software made available on this site is proof-of-concept only.
Warning
This software is provided on an 'as-is, where-is' basis with no warranties, guarantees or representations of any kind, whether express or implied, including any warranty of merchantability or fitness for a particular purpose or for the performance, use or operation of the software in any manner. This software is expressly not guaranteed to be error or interruption free. The US DOD and Eurostep shall have no liability for any damages, including, but not limited to, direct, indirect, consequential, incidental, special, exemplary, punitive, and/or incidental damages arising out of or relating to the performance, use, or operation of the software, even if US DOD and/or Eurostep have been advised of the possibility of such damages."

The artifacts available here were, for the most part, generated directly from the AP233 schema using exff software as depicted in the following diagram. The one exception is that the AP233 UML 2 model was created by reading a UML 1.5 model into MagicDraw which converted the model to UML 2. These UML models are the basis for the diagrams in the AP233 documentation itself.

AP233 Code Generators
AP233 Software Artefact Links
Artefact Web address
AP233 UML 1.5 XML Metadata Interchange File xmi.zip
AP233 MagicDraw 11 UML 2 File (import of UML 1.5 XMI file) mdzip
AP233 XML Schema (based on ISO 10303-28 Edition 2) xsd.zip and related exp.xsd
AP233 EXPRESS exp.zip and as STEPMod DTD XML xml.zip
AP233 ARM Ruby API AP233_ARM_LF.rb.zip
Examples using Ruby API http://www.exff.org/ap233/ap233_arm_write_example.rb
http://www.exff.org/ap233/ap233_arm_read_example.rb