General Java Porting Principles

The primary aim of this project is to port the prototype framework developed in the AOCS Framework Project from C++ to Java. This page describes the general principles that guided and constrained the porting process.

• Adherence to C++ Version
• Minor Changes
• Package Architecture
• Use of Templates
• Synchronization and Scheduling Issues
• Dynamic Binding Model
• Compliance with Real-Time Java Specifications
• Components as JavaBeans
• Framework Event Mechanism
• Management of Configuration Information
• Linking Data Flow Components
• Monitorable Properties
• Documentation Approach

• Back to Real-Time Java Project Home

Adherence to C++ Version

• a set of domain-specific design patterns,
• a set of abstract interfaces,
• a set of concrete components

• Design Patterns

Framework design patterns are maintained unchanged.
 
• Abstract Interfaces

Methods in abstract interfaces maintain the same name, the same number and types of methods with the only difference that C++ pointers are changed to Java references. Note that, in most cases, the C++ version of the AOCS framework passed non-primitive type by reference and not by value (the only exception are parameters of DataItem and ConfigurationState type both of which are considered below). This eliminates any problems due to the non-availability of  the parameter passing by value in Java.
 
• Components

Components’ interfaces are translated using the same rules as for the translation of abstract interfaces (see previous point). Their implementation is translated at a purely syntactical level preserving functionality unchanged. This type of ‘shallow’ translation is done with the assistance of the C2J++ application. C2J++ is a very simple public domain software that automatically translates C++ to syntactically equivalent Java code.

Back To Top, Back to Real-Time Java Project Home

Minor Changes

The non-localized minor changes are:

• The C++ version of the framework used include files in the /GeneralInclude directory to store general purpose constants such as class identifiers or event type identifiers as #define variables. In the Java frameworks these include files have been replaced by classes of the same name that define the constants as static final variables. Thus, for instance, the C++ include file ClassId.h becomes file ClassId.java.

• The C++ version of the framework used typedef's to make it easy to change basic framework type (for instance, the type of AOCS time, the type of class and instance identifiers, etc). This mechanism could not be translated to Java and all types choices are hardcoded

• In the C++ version of the framework, event repositories are often declared static and shared by all instances of a given class. In the Java version of the framework, this is never done except for the case of the event repositories used by class AocsObject. In the Java version of the framewok it thus becomes possible, for instance, for two recovery strategies to operate on two different failure event repositories. There is therefore greater flexibility but there is also a slightly greater memory usage.

• In the C++ version of the framework, bound checks were made on method arguments that represented array arguments. Their failure resulted in the generation of configuration errors. In the Java version, this is no longer done and the run-time system will generate an exception if the argument is out-of-bounds.

Package Architecture 

The top-level package for the framework classes is RtjAocsFramework. This package contains a number of subpackages that match the subdirectories of the Visual Studio project where the C++ version of the framework was developed.

Back To Top, Back to Real-Time Java Project Home

Use of Templates 

The C++ version of the framework used templates only to specialize the ObjectListTemplate class. The templatized classes were simply providing a type-safe wrapper for the ObjectList class. In the Java version of the framework, the template mechanism was replaced by the inheritance mechanism. The class ObjectList is functionally the same as in the C++ version of the framework. Type-safety is achieved by providing derived classes that expose type-safe methods to access the items in the object list. The names of the derived classes are as follows: <type-name>List is the wrapper that provides a type-safe list of objects of type <type-name>.

One awkward consequence of this approach is that methods like first in class ObjectList would now appear both in ObjectList and in its derived classes with different return types. This is forbidden by the Java compiler and therefore it was necessary to change the name of ObjectList.first to ObjectList.firstObject. Similar changes, and for the same reasons, were made to methods next and getObjectByPosition (see list of minor changes above).

Back To Top, Back to Real-Time Java Project Home

Synchronization and Scheduling Issues

• active components, namely components that implement interface ActiveObject
• passive components, namely components that do not implement interface ActiveObject

In a typical instantiation, to each active component, a dedicated thread is associated. How the threads are scheduled is an instantiation issue. The active components defined by the framework are written to be independent of how often they are activated and of the order in which they are activated. In a typical instantiation, all the active components are scheduled in accordance with a cyclical policy with the possible exception of the TelecommandLoader component that may be treated as a sporadic component to be awakened by the arrival of a new telecommand. Note however that this is not always the case. In some applications, the telecommand loader may be implemented to be activated cyclically to process raw telecommand data that are accumulated in a buffer by a lower level task (e.g. an interrupt processing routine).

Operation in a multithreading environment requires the implementation of mechanisms to preserve data integrity. This is done at three levels. At the first integrity level, it is necessary to ensure that objects are accessed in mutual exclusion. Consider the following method call:

    a.method(...);

The implementation of the method might change the internal state of object a and therefore this method call can only be guaranteed to be thread-safe if its execution is not interrupted by other threads that perform operations on object a. In the AOCS Framework, this objective is achieved by marking all methods that may be called during the operational phase synchronized. The only methods that are not subjected to this precaution are the configuration or initialization methods. These are methods that are intended to be called only during the application initialization phase when multi-threading operation has not yet begun. Typical configuration methods are: resetConfiguration and isConfigured. Other configuration methods are identified as such in the method documentation.

At the second integrity level,  it is necessary to ensure that data that are acquired from the same objects through separate operations are consistent. Consider the following situation:

    v2 = a.method2(...);

    . . .    // process v1 and v2

Suppose that there is a requirement that the two return values v1 and v2 are mutually consistent in the sense that, while they are acquired, the state of object a is not altered. There are two cases where this situation arises in the framework:

• Processing of framework events: events are stored in event repositories (instantiated from classes derived from EventRepository). The event repositories are implemented as FIFO queues where the arrival of a new event causes the oldest event in the queue to be over-written. Under such circumstances, there is no guarantee that the two succesive operations performed on the same event reference will result  in consistent return data. 
• Processing of object lists: the framework predefines classes that represent lists of objects (instantiated from classes derived from class ObjectList). These classes offer iterator methods that allow clients to retrieve all the objects in the list. The retrieval is typically done in a for loop. Inconsistencies may arise if, while a first thread performs the for loop, a second thread inserts or removes items from the list. 

In a non-real-time environment, the simplest way to cope with the above problem would be for the processing code to clone object a and thus create an internal copy that can be processed in the absence of interference from other threads (NB: this approach only works if the clone method is implemented as a synchronized method). However, creating internal clones requires performing a dynamic memory allocation which is not compatible with hard real-time constraints. Hence, the solution adopted in the framework is as follows:

    synchronized (a) {

           v1 = a.method1(...);

        v2 = a.method2(...);

    }

    . . .    // process v1 and v2

The acquisition operations are enclosed in a synchronized block that ensures that the state of the object from which the data are acquired is not altered by other threads. Thus, the solution to the two examples listed above is:

• Processing of framework events: the event data are copied out of the event object in a synchronized block (the synchronization is done on the event object)
• Processing of object lists: the processing of objects in a list is embedded in a synchronized block (the synchronization is done on the object list)

At the third integrity level,  it is necessary to ensure that data acquired from several sources are consistent. A typical example is the processing of sensor data by the controller. Consider for instance a situation where a controller processes data from two different sensors and produces data for two different actuators. Clearly, if the sensor acquisition task is interleaved with the control processing task and the latter is in turn interleaved with the actuator commanding task, a situation may arise where the controller takes as input data that have been acquired from the two sensors at different times or, similarly, a situation may arise where the actuators receive commands that have been computed in two different cycles. 

The framework takes the view that this kind of integrity issues must be dealt with at application design level. Normally, this would be done by defining a scheduling policy that ensures that the tasks that produce certain data have terminated their execution before the task that processes those data can begin. Thus, in the example situation outlined above, one would assign a release time for the controller task that is later than the deadline for the sensor acquisition task, and a release time for the actuator commanding task that is later than the deadline for the controller task. 

Back To Top, Back to Real-Time Java Project Home

Dynamic Binding Model

This difference made the following changes necessary in the Java version of the framework:

• The constructor of the AocsObject class no longer calls reset() and resetConfiguration(). The private methods localReset and localResetConfiguration have been defined with the same functionality and are called in their stead by the AocsObject constructor.

Compliance with Real-Time Java Specifications

Some of the code in a complete application is directly or indirectly inherited from the framework. This includes the components supplied by the framework, code that implements framework-supplied abstract interfaces, and code that supports framework-supplied design patterns. The framework is designed in such a manner that this code only uses standard Java constructs. This makes the framework compatible with different variants of real-time Java but also imposes the following restrictions on the design and implementation of the framework:

• Use of the new operator is only allowed in constructors and in initialization methods. These are methods that intended to be called only during the initialization phase of the application. They are marked as such in their JavaDoc comments.
• No use of exceptions
• All framework components are treated as potentially shared and their non-initialization methods are synchronized (see also discussion above)
• Only the Java.lang and Java.math packages are imported by framework classes. All other Java support classes are excluded as potentially unsafe (for instance, it may not be possible to guarantee that they do not perform any dynamic memory allocation)

Back To Top, Back to Real-Time Java Project Home

Components as Java Beans

• All classes were given a default constructor. Where in the C++ version of the framework there was a constructor with parameters, the Java version added a new parameterless constructor and transformed the former constructor parameters into settable bean properties. Additionally, method isConfigured was modified to ensure that a check is made to verify that the new properties have been set by the user. For an example see class ModeManager.

• All component attributes were explicitly treated as bean properties and greater use was therefore made of setter and getter methods. See the list of minor changes for details.

• The framework event model was modified to make it compatible with the event mode prescribed by the Java bean standard. This change is discussed below in a dedicated section.

The Framework Event Model

A second implication of the adherence to the Java beans event model is that class the AocsEvent class is implemented in the Java version of the framework as a subclass of EventObject. It is therefore the only framework class that does not inherit from RootObject. The constructor of class EventObject requires the event source as an argument and treats it as read-only parameters. This is not adequate for the framework that requires all event parameters to be settable since events cannot be created dynamically. Hence, the framework passes to the constructor of EventObject a dummy argument that is never used. The event source is stored as a parameter defined by class AocsEvent.

In the C++ version of the framework, events are generated to be stored in event repositories. In the Java version therefore the event repositories become event listeners. In one important difference with the C++ version of the framework, each event source could fire events to only one event repository. In the Java version, instead, event sources maintain an array of event listeners and can therefore potentially send their events to multiple repositories. Thus, for instance, it would be possible to have two failure event repositories.

Event adapters are not used in the Java framework. This is because it is assumed that event processing is "quick" and can therefore be done in the thread of the event source.

Back To Top, Back to Real-Time Java Project Home

Management of Configuration Information

Back To Top, Back to Real-Time Java Project Home

Linking Data Flow Components

The Java version of the framework introduces the concepts of data sink and data source. A a data sink is an object with a fixed number of inputs that participates in a data flow. Data sinks offer read-write access to their inputs. The inputs are always assumed to be of type 'double'. Data sinks are characterized by implementation of interface DataSink.

Similarly, a data source is an object with a fixed number of outputs that partipates in a data flow. Data sources offer read-only access to their outputs. The outputs are
always assumed to be of type 'double'. Data sinks are characterized by implementation of interface DataSource.

Data flow components see each other as instances of type DataSink and DataSource and, as far as the flow of cyclical data is concerned, are linked to each other through these two interfaces.

Back To Top, Back to Real-Time Java Project Home

Monitorable Properties

In the Java version of the framework, interface Monitorable is introduced to characterize monitorable objects. A monitorable object is an object that exposes properties that can be subjected to direct monitoring. It is therefore equivalent to a source of properties in the C++ version of the framework.

In the C++ version of the framework, some objects allow their properties to be subjected to monitoring according to the "monitoring through change notification" design pattern. This involves the monitor registering its interest in a certain property and specifying the type of change profile in which it is interested. The change profile is specified as an object of type ChangeObject. A violation of the change profile on the part of the monitored variable results in a change event being fired and in the propertyChange method of the monitoring object being invoked.

In JavaBeans application, the type of call-back action behind the monitoring through change notification design pattern should ideally be implemented using the event mechanism. Unfortunately, no satisfactory way was found to implement this design pattern using the Java event mechanism. Hence, the Java version of the framework replicates the implementation of the C++ version of the framework. The only properties upon which monitoring through change notification can be performed by default are the mode property exposed by mode managers and the manoeuvre state exposed by manoeuvre objects. In the C++ version of the framework, the reconfiguration status was exposed by configuration managers as a monitorable property. This is no longer the case in the Java version.

Monitoring through change notification in the Java version of the framework should be used only where absolutely necessary because its implementation deviates from the JavaBeans model.

Back To Top, Back to Real-Time Java Project Home

Documentation Approach

The documents describing the C++ version of the framework are:
 

The applicability status of these documents to the Java version of the framework is as follows:

Document 1 is applicable to both the C++ and Java versions of the framework since both are targeted at the same application domain.

Document 2 remains largely applicable. A section "Applicability to Java Version of the Framework" was added to identify parts that are specific to the C++ version of the framework.

Documents 3 remain partly applicable. The concept-level description of the framelets is the same for both the C++ and Java versions of the framework. In particular, both versions of the framework use the same design patterns. The architectural descriptions of the framelets however are only applicable to the C++ version of the framework. In the Java version of the framework, the architectural-level description is generated automatically by the JavaDoc tool. The Java source code is commented in accordance with the JavaDoc conventions and gives descriptions of all the class interfaces. Additonally, package overview documents in html are also provided and integrated in the custormary manner in the JavaDoc documentation.

Documents 4 to 6 cover the instantiation and testing of the framework and are superceded by the pages on this web site that document: the framework testing approach, the framework instantiation approach, and the prototype application instatiation.

Document 7 is specific to the C++ version of the framework and is not applicable to the Java version.

Document 8 was obsolete even with respect to the C++ version of the framework as it was not maintained through the project life. No update for the Java version is provided. Examples of implementation cases for the AOCS Framework can be found in the book "Software Frameworks and Embedded Control Systems" by A. Pasetti to be published in Dec. 2001 in the LNCS serie of Springer-Verlag.

Document 9 is superceded by the book "Software Frameworks and Embedded Control Systems" by A. Pasetti published as vol. 2231 in the LNCS series of Springer-Verlag.

Back To Top, Back to Real-Time Java Project Home