EUROCONTROL Development and Evaluation Platform Reference ... · EUROCONTROL Development and...

EUROCONTROL Development and Evaluation Platform Reference GL/DEP/DDD/1/2.0

6 Feb 2009

Page 1 of 117

eDEP Development Project

GSDK

DETAILED DESIGN DOCUMENT


6 Feb 2009

Page 2 of 117

Document Change Log

Release Author Date of the release

Description of the release

Modifications (sections affected and relevant

information)

1.5 Mike Vere 1.6 Tim Cooper Ensure consistent with code.

Removed redundant sections. 1.7 Graffica

(Aynsworth) 1

st April 2004. Added Discovery Monitor

section 5. Graffica (Vere) 16 Sept 2005 Change to timed updates. Added new section 3.2.10.1 1.8 Graffica

(Cooper) 17 Mar 2006 Updated description of

GSDK Swing Thread use. Section 3.1.5

1.9 Graffica (Vere) 14 Sept 2006 Added wheel mouse functionality. Added entity manager changes.

Section 3.4.6.3

1.10 Graffica (Vere) 16 Nov 2006 Added event monitor and subscription monitor decsriptions.

Sections 3.3.4 and 3.5.9

1.11 Graffica (Hargreaves)

21 Feb 2007 Updated description of the converter.

Added new section 3.4.2.2

1.12 Graffica (Vere) 21 Mar 2007 Added description of the AwsTextField widget..

Added new section 3.4.2.3

1.13 Graffica (Vere) 12 Apr 2007 Added section to cover time management.

Expanded original section 3.7

2.0 Graffica(Thom) 13th August

2007 Version number change to common Graffica standard. 2007 Q2 Release

N/A

2.1 Graffica (Hargreaves)

10th July 2008 Updated sections

describing layer setup and behaviour.

Sections 3.4.2, 3.4.3, 3.4.5, 3.4.6 and 3.4.7

2.2 Graffica( Stainton)

21st August

2008 Added gesture notes Sections 3.4.2.1.1

2.3 Graffica (Stainton)

3rd December

2008 Added notes on AwsEntityGraphicsManager

3.4.3

Acceptance and Reviewing Procedures

Name (s) Date of acceptance/ review Date of approval

Document distribution

to/cc Name Role


6 Feb 2009

Page 3 of 117

CONTENTS

1 INTRODUCTION............................................................................................................. 5

1.1 Document Purpose..................................................................................................... 5

1.2 Document Structure and Contents............................................................................. 5

1.3 Related Documents.................................................................................................... 6

2 Overview ........................................................................................................................... 7

2.1 ATC and GSDK Packages......................................................................................... 7

3 Toolkit Architecture ........................................................................................................ 16

3.1 The Application Framework.................................................................................... 16

3.2 Entity Model Management ...................................................................................... 21

3.3 Events Framework................................................................................................... 35

3.4 Graphics Framework ............................................................................................... 43

3.5 Middleware Framework .......................................................................................... 71

3.6 The Component Design Pattern............................................................................... 88

3.7 Time Management................................................................................................... 92

4 GSDK PACKAGES ........................................................................................................ 95

4.1 Application .............................................................................................................. 95

4.2 AWS........................................................................................................................ 95

4.3 AWTX..................................................................................................................... 95

4.4 Display..................................................................................................................... 95

4.5 Entity ....................................................................................................................... 95

4.6 Events ...................................................................................................................... 95

4.7 Format ..................................................................................................................... 96

4.8 Geometry................................................................................................................. 96

4.9 Graph ....................................................................................................................... 97

4.10 Labels ...................................................................................................................... 97

4.11 Map.......................................................................................................................... 97

4.12 Middleware.............................................................................................................. 97

4.13 Observer .................................................................................................................. 97

4.14 Process..................................................................................................................... 97

4.15 Reflect ..................................................................................................................... 97

4.16 Region ..................................................................................................................... 97

4.17 Resources................................................................................................................. 97

4.18 Route ..................................................................................................................... 102

4.19 Scenario ................................................................................................................. 102

4.20 STD ....................................................................................................................... 102


6 Feb 2009

Page 4 of 117

4.21 Tools...................................................................................................................... 102

4.22 Trajectory .............................................................................................................. 102

4.23 Utilities .................................................................................................................. 108

5 Discovery Monitor......................................................................................................... 112

5.1 Introduction ........................................................................................................... 112

5.2 Timings.................................................................................................................. 112

5.3 The TreePane Interface.......................................................................................... 112

5.4 The GraphPane Interface....................................................................................... 113

5.5 RUNNING THE MONITOR ................................................................................ 113

6 Launcher........................................................................................................................ 114

6.1 Introduction ........................................................................................................... 114

6.2 Launcher Creation Process .................................................................................... 114

6.3 Running from a Jar file.......................................................................................... 114

APPENDIX A - COLOUR MANAGEMENT FILES .......................................................... 116

Physical Colour Definition File......................................................................................... 116

Logical Colour Definition File .......................................................................................... 116

Font Definition File ........................................................................................................... 116


6 Feb 2009

Page 5 of 117

1 INTRODUCTION

This document provides the detailed design specification for the EUROCONTROL eDEP platform, being developed under EEC task TRS 221. The document describes the design of the underlying Graffica System Development Kit (GSDK), which forms the framework for the eDEP ATC software. This document covers the specification of each of the eDEP components, and describes the underlying design patterns used in the implementation of the components.

1.1 DOCUMENT PURPOSE

The purpose of this document is to provide a high level description of the internals of the GSDK Toolkit, forming an intermediate level of documentation between the eDEP Architecture document, describing the black box component view, and the detailed documentation provided by the Javadoc, embedded in the source code. The document is intended to take the developer from the interfaces identified in the Architecture document (the black box) through to the Javadoc (white box) description.

The summary lists below outline the structure of the document, highlighting the major areas of design detailed in this document.

1.2 DOCUMENT STRUCTURE AND CONTENTS

The document is structured with chapters describing the major design areas supporting the eDEP implementation, with details of the major design patterns, and descriptions of each of the major software components of the eDEP facility. The main chapters are:

• Toolkit Architecture

• GSDK Package Descriptions

1.2.1 Toolkit Architecture

This chapter focuses on the major frameworks provided by the Graffica System Development Kit, GSDK. These include:

• application framework

• model management

• parser framework

• events framework

• graphics framework

• middleware framework

A final section is provided to show how each of the patterns is combined to produce a complete component structure, identifying the major objects involved, the use of interfaces and the dynamics of the provided support facilities.

1.2.2 GSDK Utility Packages

This section provides an overview of the GSDK utility packages used to provide a range of facilities and algorithms available for use throughout the eDEP facility. igned using a relatively small number of easily repeatable design patterns to enable users and developers to master the design paradigms more rapidly than might otherwise be possible. The following design areas are described:


6 Feb 2009

Page 6 of 117

• aws

• format;

• geometry;

• graph;

• map;

• middleware;

• resources;

• std;

• tools;

• trajectory;

• utilities.

1.3 RELATED DOCUMENTS

This document provides the detailed design element for the GSDK toolkit underpining the eDEP facility. The eDEP ATC layer is described in the related design document (GL/DEP/DDD/1).

Additional documentation is provided to describe the overall architecture (GL/DEP/ADD/1) and inline Javadoc comments are provided through the source code, which are processed into the standard format Javadoc HTML files, which can be read using any HTML browser.


6 Feb 2009

Page 7 of 117

2 OVERVIEW

This section provides a brief overview of the eDEP facility. It provides an overall context diagram for the facility described in terms of its inputs and outputs. It also outlines the distinctions between the ATC classes and the underlying GSDK classes. The section also provides an introduction to some of the fundamental design concepts used in the platform. The eDEP facility is not restricted to the standard objects defined in the ATC packages described here. The platform provides flexibility to enable new variants of existing objects to be added to the platform, and indeed new types of object can be modelled without the need to re-code any of the framework modules. These capabilities are further described in the GSDK document [Ref. 2].

2.1 ATC AND GSDK PACKAGES

The delivered eDEP software comprises the Graffica System Development Kit (GSDK) layer, providing the framework classes to manage system facilities, such as data management, data distribution, graphics management, and event scheduling, subscription and notification management. In addition, there are software frameworks to support the parsing of text input data files and the creation and management of separate application components running within the same JVM.

The ATC software layer uses the abstract classes provided in the GSDK layer to derive tailored, system specific objects, which make use of the plug-in interfaces provided by the GSDK framework to add behaviour and user specific processing in response to system generated events.

This section provides a brief description of some of the key facilities provided by these software layers.

2.1.1 GSDK Overview

The GSDK packages provide an abstracted real time system framework from which domain and concept specific objects may be derived, and into which implementation specific behaviour may be applied. The GSDK makes extensive use of Java interfaces to hide the implementation details from a using object or component, and thus allow many implementations to satisfy a single interface requirement. This allows the developer to selectively change the behaviour and functionality of any derived system. Coupled with the use of the Java reflection tools, a developer can make use of object factories to create the chosen object class, provided that object conforms to the defined interface.

The GSDK will also provide the timing, event scheduling and event distribution mechanisms. These provide a number of methods to de-couple the behaviours associated with an object from its implementation, allowing reuse of basic objects, through attached event processing behaviour. These are described in more detail in the Toolkit Architecture described in section 3.

2.1.2 ATC Overview

The ATC packages define a layer of Java classes specific to the ATC domain, and as such define a baseline implementation for ATC object specifications and behaviours. The ATC objects described in this document are derived from and managed by the underlying abstract GSDK objects. Each object class in the ATC domain will be represented by a class derived from the GSDK Entity, and managed in an EntityManager. Each component in the eDEP platform will manage a database of entities, providing signals to create, update and destroy the objects. The following diagram shows the primary component actors of the platform.


6 Feb 2009

Page 8 of 117

Note that the airspace (ASP) and time service (TS) do not show all of their relationships, as they provide services to almost all other components and adding them would clutter the diagram.

Figure 2-1 The Primary Relationships Between eDEP Components

Each of the components and their associated relationships is briefly described in the following paragraphs.

2.1.2.1 Airspace ASP

Provides a central source of static airspace information. Airspace items can be loaded by item type, optionally filtered within an area. Alternatively the complete set of airspace items can be loaded in a single call. Components subscribing to airspace data include IFPL, FM, PM, CS, FPM and CWP.

2.1.2.2 Air Traffic Generator

Provides a source of secondary surveillance radar (SSR) tracks. These tracks define the latest detected position of a flight and are distributed to all subscribed components. This service will be used by the CWP to update the locations of the displayed aircraft, and by the FPM to track the aircraft along its agreed plan, and across sectors.

2.1.2.3 Coordination Service CS

The coordination service maintains the coordinated state of each flight as it transits each sector on its latest planned route. It processes requests to transfer control between units, and


6 Feb 2009

Page 9 of 117

to coordinate the boundary crossing conditions between negotiating units. Requests will be made by CWP components, and responses reported back to the subscribing CWPs.

2.1.2.4 Controller Working Position CWP

The controller working position (CWP) forms the principle graphical interface to the system based on a plan view display of the control sector. This configurable display is designed to provide a flexible set of components which can be plugged together either at compile time or at run time, to enable a broad range of display concepts to be developed.

2.1.2.5 Flight Manager FM

The flight manager (FM) component provides the main source of flight data in the system. It accepts initial flight plans from the IFPL server and processes them into trajectory objects by invoking the trajectory predictor, TP. This generates the trajectories from the constraints expanded from the initial plans. The FM will also post-process the trajectory to generate lists of significant points.

2.1.2.6 Flight Path Monitor FM

The flight path monitor (FPM) component uses the track data produced by the ATG to monitor the progress of the flight against its planned trajectory and its transit through the airspace.

2.1.2.7 Initial Flight Plan IFPL

The initial flight plan (IFPL) component reads a traffic sample from an input file, and generates an initial plan defining a set of route constraint points, and limited altitude information in the form of SIDs, STARs, and user defined control points. The FM and the PM will use the initial plan to generate trajectories, which can then be made available to the rest of the system.

2.1.2.8 Medium Term Conflict Prediction MTCD

The medium term conflict detector (MTCD) provides an algorithm to determine where predicted aircraft plans will infringe the minimum airspace separation criteria and raise conflicts. The MTCD will subscribe to trajectory data produced by the FM, and can produce synchronous probes for trajectories supplied by the user.

2.1.2.9 Time Service TS

The time service maintains the system wide simulation clock, and provides the central source of time updates throughout the platform. The rate of flow of time may be controlled through the console component. Users can also subscribe to wake-up events to post themselves an event at some future simulation time.

2.1.2.10 Trajectory Predictor TP

The trajectory predictor (TP) component provides a trajectory prediction algorithm, which uses a parametric aircraft performance model to predict the motion of the aircraft, and attempts to meet the given set of 4D constraint points. At present the TP only operates in 3D. More complex trajectory prediction algorithms may be substituted in future developments.

2.1.3 Design Concepts Overview

The eDEP facility attempts to provide the ATM experimenter an easy to use set of building blocks for the development of small to medium scale ATM simulations of arbitrary complexity, and unlimited concept scope. It endeavours to achieve this by creating a broad range of standard ATM components with conventional interfaces, but employs a set of consistent design patterns to provide the developer with a range of software features. These features will give the user a large degree of flexibility through the substitution of conformant


6 Feb 2009

Page 10 of 117

user developed software, and a number of standard inter-component and intra-component communication mechanisms.

The following paragraphs outline some of the key design patterns and features deployed in the system.

2.1.3.1 Application Model

The basic processing component in the eDEP facility is known as an application. The application model provides the developer with a flexible mechanism to run any combination of application objects within a single Java Virtual Machine (JVM) or distributed arbitrarily across a network of machines. The Application interface provided in the package gsdk.application, defines a set of initialisation methods provided for the application, which will be called in sequence from the GSDK kernel after the application has been registered with the GSDK. These methods allow the developer to implement the required initialisation and configuration procedures for the application, centring on standard patterns for data management (the Scenario), graphics (the AwsShellManager) and control of external access to the application (the ComponentController). The class diagram below shows the basic elements of a component application object.

Figure 2-2 Component Application Class Diagram

The information associated with an application is held within the GSDK in an ApplicationContext object, which will be passed into each of the initialisation calls made from the GSDK, and provides access to each of the application’s key objects.

2.1.3.2 eDEP Middleware

The middleware for the eDEP facility enables component applications to communicate either locally, passing messages between parallel threads running on the same JVM, or remotely, communicating over a local area network, or indeed across the internet (though performance


6 Feb 2009

Page 11 of 117

cannot be guaranteed in these circumstances). The middleware provides the communication medium through which the inter-component messages are channelled, first converting the server side objects into a serialised (machine independent) format, and then converting the data back into the required object structure on the client side.

The middleware is built on Sun’s Remote Method Invocation mechanism (RMI), and provides for both synchronous (blocking) calls and for asynchronous (non-blocking) calls. In addition, an asynchronous event distribution mechanism is provided on a publish/subscribe model. The event distribution mechanism will form the predominant information distribution mechanism, where the information is distributed in timely fashion from the server to its subscribers. The distributed events may be filtered on the event contents, by providing a filter on subscription.

The middleware operates through a look-up/discovery service, which distributes interfaces to the registered services to the consuming client components. Server components must register their interfaces with the Discovery mechanism, which enables client components to look-up the available services, and access the server component through the provided interface.

Figure 2-3 Middleware Example Showing Discovery of Remote Interfaces

The RMI stub object shown in the above diagram provides the machine dependent link between the object domain of the server and the object domain of the client, and is generated by the RMI compiler supplied with the Java Development Kit (JDK).

2.1.3.3 Entity Interfaces

The Entity interface and the associated manager classes define the fundamental data model elements of the system. The Entity provides the developer with a managed container object, which provides a range of functionality, defining the identity of the object, its characteristic attributes, and the modelled behaviour of the object. The toolkit provides a plug-in capability, whereby the application developer can define the actual implementation class required to satisfy a given interface at run time. This capability is achieved by defining an interface to the required implementation object (or objects), where all access is made through the interface, and the implementation is dynamically bound to that interface at run-time.

The following class diagram shows how the Flight interface used in the Flight Manager component of the eDEP can be substituted with an implementation other than the default FlightImpl provided in the package atc.fm.entity.

The Flight implementation objects are created using Java Reflection. Although the implementation classes were not previously known to the system, other than through the string containing the class path in the UserScenario, the client object can access the flight


6 Feb 2009

Page 12 of 117

methods of those classes through the provided Flight interface. As the objects implement the Flight interface, the client object is unaware of the nature of the implemented class hidden behind that interface, and may, indeed be dealing with more than one implementation when accessing a set of Flight objects.

Figure 2-4 Example Use of Flight Interface

2.1.3.4 Event Mechanisms

Objects within the eDEP environment can communicate with each other using a variety of event mechanisms, some of which require knowledge of the source of the event, while others can be notified of events from anonymous sources through a central event management facility. Also events are used to report messages from remote components to subscribed clients. The different event mechanisms defined are summarised below:

• Private events scheduled through the central event scheduler for some future time;

• Events notified to subscribed clients through the central event scheduler;

• Events notifying changes in entity objects;

• Events scheduled for immediate consumption;

• External events subscribed to on remote servers;

• Graphics events, signalled to invoke graphics behaviour.

In addition, notified events and external events may be filtered through an event filtering mechanism, so that only events with attributes matching the required criteria are forwarded to the registered client.

The central EventScheduler object is defined in the Scenario implementation class, and is available for use by all entity and graphical objects. It provides a strong mechanism to decouple the source of an event from the client objects, which react to the event, through an event notification mechanism. The EventScheduler mechanism can also be used to schedule events to be signalled at some future time, and to post events privately to perform some processing task when the event is signalled. Events scheduled on the event scheduler are derived from the EventObject base class, and interest can be registered in a particular event by associating an implementation of the EventListener interface with a given event class


6 Feb 2009

Page 13 of 117

name. This listener will be notified of the event whenever that event type is signalled, subject to an optional SubscriberFilter.

Events can be signalled with immediate effect by scheduling them on an immediate event queue, which will process the event at the earliest opportunity. The order of processing will be the same as the order that the events were added to the queue. As the event scheduler only maintains a partially ordered list of events, the precise order in which events are signalled for the same simulation time is not guaranteed. Adding events into the event scheduler is a synchronised process, which ensures that any events scheduled from another thread will be correctly inserted into the relevant queue. This provides a mechanism to decouple processing from RMI threads, supporting a remote request, from the main server processing by scheduling an event from the external thread and scheduling it for consumption on the internal server thread.

The diagram below shows the key elements of the central event mechanism. The event scheduler provides methods to schedule new events either for immediate consumption or to be signalled at some future time. The SubscriptionManager holds all the registrations of interest in particular events, and will be invoked by the event scheduler to distribute the event to all the registered clients by invoking the supplied EventListener object’s notify method.

Figure 2-5 The Central Event Class Diagram

Entities use a similar notification mechanism to the central event scheduler. However, the event is not scheduled centrally, but a list of subscribers is kept locally, and the event is only created if there is at least one subscriber. The client object creates an event listener, which is then registered, along with the name of the change of interest.


6 Feb 2009

Page 14 of 117

Figure 2-6 Entity Change Events

2.1.3.5 Parsing Framework

The GSDK defines a standard mechanism to read data files called the parser framework. This mechanism defines a standard syntax template for input files containing entity definitions, and defines the classes that need to be implemented in order to read the required scenario information. The parser framework constructs a parallel network of interfaces and classes with a similar pattern to the entity management structure itself. Each entity implementation class will define a corresponding parser class, with the same name as the Entity class, but terminated with the word “Parser”. Thus the parser interface supplied for the Entity interface is the EntityParser. The parser objects are collected together into a ParserManager, which in turn are placed in a ParserController.

The format of the scenario data files reflects the way that the scenario files are read by the parsers, with the attributes defining the base class being read first, and subsequent attributes in derived classes being read in class hierarchy order, super class first. The entity definitions are introduced with a keyword, corresponding to the name given to the EntityManager defined in the associated Scenario database object. Thus a SectorParser class derived from the RegionParser implementation class, which in turn was derived from the EntityParser, would first read the Entity attributes (simply defining the name of the sector instance), then the region definition information identifying the altitude range of the region and the latitude and longitude points defining its perimeter, and finally the sector ‘s coordination points, read by the SectorParser.

The details are associated with the Sector class by association with the sector’s entity manager name, called SECTOR. Thus when the keyword SECTOR is read, the sector entity manager is matched with the name, and the SectorParser class identified from the class information in the manager.

The parser framework provides a two-stage parsing strategy in order to resolve any forward references to undefined objects, by providing the resolveReferences method to operate after the details have been read.

The fragment of scenario listed below shows how an instance of the Sector entity class is described in a scenario file. The first line provides the Entity name attribute. Subsequent lines down to the first END describe the Region entity, the ATC describes the Zone type, and finally, the list of coordination points completes the description of the Sector.


6 Feb 2009

Page 15 of 117

SECTOR NATS_S10 REGION ALTITUDE 0 45000 52.03 0.55 52.10 0.02 52.21 -0.54 52.93 -1.01 53.54 -1.32 53.97 -1.46 54.08 -0.58 54.30 0.55 END ATC COORDINATION_POINT FAMBO COORDINATION_POINT UPTON COORDINATION_POINT SCORS END

2.1.3.6 Plug-in Capabilities

In addition to the substitutable entity objects, other interfaces are defined in the system, which allows the run-time replacement of implementation classes. This powerful feature allows the behaviour of the system to be radically altered without changing the system architecture, or indeed the need to recompile any software. However, this flexibility should be used with care, as the class loader can only make checks on the validity of a proposed plug-in class at run-time. The flight manager server provides an example of the use of a plug-in class, were the required constraint handling methods provide a well-defined interface, the ConstraintManager, which may be implemented using a number of different classes. The class diagram below shows how the plug-in can be substituted using an ObjectFactory mechanism, which constructs the new manager from a given class path string.

Figure 2-7 Constraint Manager Plug-in


6 Feb 2009

Page 16 of 117

3 TOOLKIT ARCHITECTURE

3.1 THE APPLICATION FRAMEWORK

3.1.1 Package Overview

The application framework, in the package gsdk.application, provides a set of classes to be used by an application developer to create a new component application. The following chapter describes the application framework facilities, divided into the following sections:

• adding applications into the GSDK class;

• application initialisation and execution dynamics;

• the application interface and adapter descriptions;

• threading issues when using Swing dynamics.

3.1.2 Adding GSDK Applications

The GSDK object manages a set of applications, running in parallel on distinct processing threads on a single Java Virtual Machine. The applications may be created and added into the GSDK, or they may be created by using an application factory mechanism within the GSDK object, creating the application instance by using Java reflection to create a new instance from a given class path. The given class must implement the application interface described in section 3.1.3 below. The GSDK will then invoke the initialisation methods of the interface, and finally

A typical structure for the main method is shown in the code fragment given below, where the required component classes are read from a resource named COMPONENTS, and each is added as component name and the required application class path name into the GSDK object. Once all of the required component applications have been created, the GSDK method startToolkit is invoked to perform the application initialisation sequence, and to start each application thread running.

public class ATCapplication { public static void main( String[] args ) { try { DiscoveryServer.main(null); GSDK gsdk = new GSDK( args ); ResourceIterator c = Resources.getIterator( "COMPONENTS" ); while ( !c.isEmpty() ) { ResourceIterator a = c.nextListElement(); String applicationClass = a.nextStringElement(); String applicationName = a.nextStringElement(); gsdk.addApplication( applicationClass, applicationName ); } // End while loading applications gsdk.startToolkit(); } catch ( Exception e ) { e.printStackTrace(); } } // End method main } // End class ATCapplication

The application framework provides a design pattern for users to introduce component applications running on distinct processing threads into the GSDK basic control loop, within a single JVM process. The user can bundle together an arbitrary number of application components, each of which implements the Application interface, and runs on an independent thread. The class diagram below shows the relationships between the classes. Each


6 Feb 2009

Page 17 of 117

application is derived either from the ApplicationAdapter class, or will implement the Application interface.

Figure 3-1 – Application Framework Class Diagram

3.1.3 Application Interface and Adapter Descriptions

The application interface defines the methods needed to perform the application initialisation processing, providing the required links via component discovery, and event subscriptions to connect this component application to the necessary sources of information and events. The interface defines the following methods:

public interface Application extends Runnable { public void create( ApplicationContext context ); public void register( ApplicationContext context ); public void initialise( ApplicationContext context ); public void start( ApplicationContext context ); public void readMapping( ApplicationContext context ); public Scenario createDatabase( ApplicationContext context ); public void createGraphics( ApplicationContext context ); public ComponentController createController( ApplicationContext context ); public void shutdown( ApplicationContext context ); } // End interface Application

The Application Adapter class provides an empty implementation of the Application interface, and is provided to simplify the creation of the application object, by providing the base class from which an application may be extended, overriding only those methods required for application start-up.

3.1.3.1 Create

Immediately after the application is created, the application Create method is called, and is passed the application context. This allows the component to perform any start-up processing before the application starts to connect to other running components. Create is usually left empty.


6 Feb 2009

Page 18 of 117

3.1.3.2 Read Mapping

If the component requires mapping information, the read Mapping method can read the mapping data into the Map Manager object supplied in the passed context object. If no mapping is required, this method is left empty.

3.1.3.3 Create Database

Each application is required to define its own entity database. An entity identifies a single instance of a simulated object and is placed within an entity manager, which holds a homogeneous set of objects of this class. The application database holds a set of entity managers, each defining a given class of entity object. An instance of the required database must be created in the create Database method, and returned to the calling method.

3.1.3.4 Create Graphics

If the component requires any permanently displayed graphical windows, the create Graphics method can create the required windows, registering any AWS based shells with the passed AWS Shell Manager object supplied in the passed context object. If no graphical objects are required, this method is left empty.

3.1.3.5 Create Controller

Component applications that need to communicate with other components must define a Component Controller object, which defines the interface the application presents for other components. The Component Controller is responsible for registering the application with the middleware, to make subscriptions to other components, and to set the application thread running, accepting remote requests, and distributing application generated messages to subscribed components. The created controller is returned by this method. If no inter-component communication is required, this method may be left empty.

3.1.3.6 Register

Immediately after the application is registered (performed by invoking the application’s Component Controller register method) with the GSDK middleware, the application Register method is called, and is passed the application context. This method allows the component to perform any processing before the application makes any subscriptions to other running components. The register is usually left empty.

3.1.3.7 Initialise

Immediately after the application is initialised with the GSDK middleware (performed by invoking the application’s Component Controller initialise method), the application register method is called, and is passed the application context. This method allows the component to perform any processing before the application makes any subscriptions to other running components. The initialise method is usually left empty.

3.1.3.8 Start

Immediately after the application has been started, the application Start method is called (performed by invoking the application’s Component Controller start method), and is passed the application context. This method allows the component to perform any processing before the application enters its main processing loop. The start method is usually left empty.

3.1.3.9 Shutdown

The shutdown method is invoked from the GSDK after a signal has been received to end the execution of the components on the platform. Each application shutdown method is called in turn to perform any required component shutdown processing.


6 Feb 2009

Page 19 of 117

3.1.4 Application Initialisation and Execution Dynamics

The following sequence diagram shows the processing required when creating and initialising a new application. First, the application is created using Java Reflection implemented in the ObjectFactory class from the gsdk.utilities package. Then an application context object is created to hold the details of each application. The GSDK class then performs an initialisation sequence by calling the createMapping, createDatabase, createGraphics and createController methods in turn to create and initialise the corresponding objects within the application. The processing requirements for each method are discussed in section 3.1.3 above.

Figure 3-2 Application Initialisation Dynamics

3.1.5 Threading Issues Using Swing Dynamics

The description above applies to an application, which either requires no graphical support, or which uses the AWT graphics model. The Swing implementation of the main execution loop will run both the graphics and the application on a common thread, defined within the Swing environment. Applications using Swing graphics must update through the Swing Utilities Thread in order for the display to update correctly.

The Swing Utilities Thread is assigned to the application context by the executing a runnable class on the thread. Figure 3-4 below shows how this assignment is achieved.


6 Feb 2009

Page 20 of 117

Figure 3-4 Assigning Swing Graphics Thread

The GSDK Graphics Thread is responsible for managing the update of registered graphical applications. The Application Runner is executed on the Swing Utilities Thread and triggers the update of each application. This enables all swing graphics application updates to execute on the Swing Thread. The sleep method attempts to calculate a sleep time for the thread that will result in a standard frame-rate. The frame-rate is defined in the resources. If the frame-rate cannot be met, or if the calculated sleep time is larger than a pre-determined maximum time, then an update occurs immediately. Figure 3-5 below shows the Graphics Thread update cycle.


6 Feb 2009

Page 21 of 117

Figure 3-5 Updating Swing Graphics Applications

3.2 ENTITY MODEL MANAGEMENT

3.2.1 Overview

An entity represents a basic modelling unit within the GSDK architecture. An entity can represent any real world object, or an abstract concept. An entity may define an airspace point, an aircraft, or an air traffic control centre. Equally it may define a letter of agreement or a standard route through the airspace. An entity is an object which carries a set of attributes describing itself, is identified by name, and may define internal behaviour, which client objects can register interest in.


6 Feb 2009

Page 22 of 117

The diagram in Figure 3-3 shows the relationships between the entity interfaces and classes and shows how entities reference the key scenario objects, which an be referenced through the entity context object. It also shows how entities are arranged into sets of entities of the same type, in entity manager objects, which in turn are collected together under an entity controller object, held in the scenario.

Figure 3-3 Entity Data Model

3.2.2 The Entity Manager

The entity manager object manages sets of entities of the same class and type. Each manager has a unique type name, which is used to introduce new entity descriptions in a scenario file, read by the parser framework described below. The manager is also passed a string defining the class path of the type of entity that this manager is required to manage. This entity class name is used to generate new instances of the managed entity type, and to create the required entity parser, and the creation and destruction event types. If these entity specific classes are to be used, they must adhere to the following naming conventions for them to be picked up automatically by Java Reflection:

Entity class path: package.sub.entity.UserEntity

Parser class path: package.sub.entity.UserEntityParser

Creation event class path: package.sub.entity.UserEntityCreationEvent

Destruction event class path: package.sub.entity.UserEntityDestructionEvent


6 Feb 2009

Page 23 of 117

The parser class is used to read the entity details from a tokenised input stream, and forms a part of the Parser Framework, described in section . The creation and destruction events are raised automatically when an entity is created and destroyed respectively. If either of the event classes do not exist, the entity manager will use the default classes defined in the entity package, EntityCreationEvent and EntityDestructionEvent. A typical entity life cycle is shown in the flowing sequence diagram:

Figure 3-4 Entity Life Cycle

An EntityManager object can be created from a set of parameters defining the name of the entity type the manager represents and its parent controller, along with the Class generator classes for entity objects of the required type, and the corresponding creation and destruction event classes. The constructor also defines the update time period for the entities held in this manager; a value of zero would indicate that this manager does not update its entities on a regular update cycle. An optional state transition diagram, STD (or Finite State Machine FSM) can also be provided. Other forms of the constructor create a manager from a simple name string, or an existing manager and a controller. Further parameters are supplied with invocations of the setManagerAttributes method.

Specialist entity managers may be created, by extending the generic EntityManager and adding any additional functionality specific to the entity type. These entity managers should provide parameterless constructors that set the required TYPE_ID and generator classes. The manager is then added using the addEntityMananger method that takes the manager object instance as a parameter. Note that this method can raise an IllegalCreationException may be thrown, if the entity manager cannot resolve all its generator classes.


6 Feb 2009

Page 24 of 117

3.2.3 Entity Creation

Entities are most often created using Java Reflection to create new instances of an object from the class generator object held in the EntityManager. They can also be created from entity description objects, which represent a serialised form of an entity. The EntityDescription class hierarchy provides a parallel set of classes to the entities themselves, and which allows transmission of the entity details in a distributed system, or to store the entity in a file. The entity description contains sufficient identification and state information to recreate the entity, with the correct contextual references in a different thread, or in a separate process on a remote Virtual Machine.

3.2.4 The Entity Interface

The GSDK defines three primitive entity types; they are an abstract entity, a positioned entity and a mobile entity, and define a set of interfaces in parallel to the entity class implementations. The abstract class defines the basic management functions, the positioned entity class defines additional static position functions, and the mobile entity class defines additional dynamic position functions. These interfaces are described in the paragraphs below.

3.2.4.1 Abstract Entity

The abstract Entity object provides the basic entity management functionality. This includes identifying the name and manager of the entity, and its role in the user model hierarchy, defined by the parent/subordinate relationship, and the carries and carried by relationship. Note that most ATC applications are unlikely to use the parent/subordinate facility, and these references will be left set to null. The abstract entity defines interfaces to create or update the entity’s attributes from an EntityDescription object and to start, update and destroy the entity, and to access the key scenario objects through the entity context.

Associations provide a mechanism to link the life cycle of an entity with the set of widgets that are used to provide a graphical representation of that entity on the associated graphics displays. The association allows all associated widgets to be updated or destroyed from a single reference point.

Figure 3-5 Entity Widget Association

A localUpdate flag is provided to indicate that the entity is to be updated according to its internal model, rather than being updated through external ‘set’ methods. If the entity defines either a trajectory defining its route plan, or an implementation of the EntityMotion model, it will produce its own position updates if this flag is set. Only the ATG component uses this mechanism in the ATC software.


6 Feb 2009

Page 25 of 117

3.2.4.2 Registering For Entity Change Events

A client of the entity object can register interest in any EntityChangeEvent generated locally by this entity. The entity client object supplies a listener object derived from the event listener interface. This is then registered with a SubscriptionManager object held within the entity, which will signal the event to all subscribed listeners when any change event is signalled by this entity. The entity change event is not inserted on the central event scheduler by this mechanism. The client can specify that all events generated by the entity are notified, or the events required can be qualified by identifying the name of the required event. The entity can then signal the event by invoking the notify method on its SubsriptionManager.

The sequence diagram below shows how a client object registers for an event, and is subsequently notified when the event is signalled.

Figure 3-6 Registering For Entity Change Events

3.2.5 Entity Context

The EntityContext class provides an object to encapsulate the GSDK environment, in which the entity is running, and may be extended by the developer to hold entity specific information. The entity context identifies the component level objects with which the entity will interact. In particular this includes the following objects:

• entity manager;

• entity controller;

• scenario object;

• event scheduler;

• time manager;

The entity context object will define the environment for all entities in all managers, but may be specialised for specific entity classes. Thus separate context objects are stored with each


6 Feb 2009

Page 26 of 117

entity manager, though the default object will carry references to the same information for all managers. The entity manager class will define additional interfaces to set a specialised context, and will set the entity’s context reference when the entity is managed.

3.2.6 The Positioned Entity

The PositionedEntity interface is derived from the Entity interface defines an entity object with a fixed position (that is, the entity’s position does not evolve with time. The positioned entity implementation class inherits from the abstract entity implementation, and provides additional position functionality. Including ‘set’ and ‘get’ methods for attributes of its position object, or the position object itself. It also defines range methods.

3.2.7 Mobile Entity

The MobileEntity defines an entity interface for objects with a continually changing position (that is a position that evolves with time). The entity object inherits from the PositionedEntity and provides additional motion functionality. The entity can move either along a predefined pathway (defined by a trajectory object), or its motion can be defined by an implementation of the EntityMotion object, which will define the rules by which the entity moves. It also provides rates of change methods, and mechanisms to carry other entity objects, or be carried by another entity, to enable position to be resolved through the parent carrier. The carries mechanism is unlikely to be used in the ATM environment.

The class diagram below shows the complete set of relationships between the entity objects, their managers, and scenario objects, and associated context objects.

Figure 3-7 Entity Object Management


6 Feb 2009

Page 27 of 117

3.2.8 State Transition Diagrams

State Transition Diagrams (STD, and also known as Finite State Machines, FSM) provide a mechanism to create complex state machines, with large numbers of states and state transitions. They are defined by identifying the set of transitions of the form:

STATE A changes under TRANSITION T1 to STATE B

The STD stores these transitions, mapping the named states and transitions onto the corresponding state names identified in a derived STD object, and the transition names from an associated event class derived from the event class StateTransitionEvent.

The following simple example shows a five state system, with states START, INITIALISED, RUNNING, STOPPED and END. The START and END states are default states marking the first and the last states in the system.

Figure 3-8 Simple State Transition Example

3.2.8.1 The Derived STD Class

This example STD would be mapped onto a derived state transition event class, which provides methods to map between the transition names and the transition numbers, and defines an abstract method to return the set of transition names created in the derived state transition class. This class would be implemented with the following set of transition names and associated transition numbers:

public class ExampleStateTransitionEvent extends StateTransitionEvent { public static final int INITIALISE = 0; public static final int START = 0; public static final int RESTART = 0; public static final int STOP = 0; public static final int SHUTDOWN = 0; public static final String[] transitionNames = { “INITIALISE”, “START”,


6 Feb 2009

Page 28 of 117

“RESTART”, “STOP”, “SHUTDOWN” }; pubic static String[] getTransitionNames() { return transitionNames; } // End method getTransitionNames } // End class ExampleStateTransitionEvent

3.2.8.2 The Derived State Transition Event

The state transitions themselves can be loaded from a resource file, which can provide a resource value in the form of a list containing the initial state of the system, and a set of valid state transitions. The name of the property defining the STD can be passed into the STD constructor, which will then build an STD with all the valid transitions. Each state is mapped into a number by searching through the list of states in the derived STD object, and similarly, the transitions are mapped into a number by searching through the list of transitions in the class derived from the StateTransitionEvent. The associated ExampleSTD class is defined below:

public class ExampleSTD extends STD { public static final int START = 0; public static final int INITIALISED = 1; public static final int RUNNING = 2; public static final int STOPPED = 3; public static final int END = 4; public static final String[] stateNames = { “START”, “INITIALISED”, “RUNNING”, “STOPPED”, “END” }; pubic static String[] getStateNames() { return stateNames; } // End method getStateNames } // End class ExampleSTD

3.2.8.3 Defining An STD From a Resource

The resource property is defined as a list of items, the first value identifying the name of the initial state, and subsequent values identifying the transitions as a state name, followed by a transition name, and then the new state. The resource definition for the STD in the above example is given below.

STD.EXAMPLE ( START, ( START, INITIALISE, INITIALISED ), ( INITIALISED, START, RUNNING ), ( RUNNING, STOP, STOPPED ), ( STOPPED, RESTART, RUNNING ), ( STOPPED, SHUTDOWN, END ) )

For a given current state, and a given transition, the STD will return the value of the next state in the method getNextState.

3.2.9 The Parser Framework

The parser framework provided by the GSDK factors out all the scenario reading functionality from the entity framework, and into a replaceable set of classes. These classes


6 Feb 2009

Page 29 of 117

define a read method, which parses the attributes of the corresponding entity syntax, and a symbol resolution method to resolve any forward references to entity objects, which had not yet been read from the scenario stream. This two-stage resolution enables items to be referenced in the scenario file before they are defined.

The parser framework follows a parallel object framework to the entity framework, comprising a parser controller, and a set of parser manager objects, each of which references a set of entity parser objects of a specific type, which will hold a reference to the corresponding created entity, and maintain the text data items defining unresolved attributes. The entity parser objects provide a read method to parse the text syntax of the defining text, and a

resolveReferences method, which attempts to resolve any textual references to other

entities defined within the parent scenario. These two methods replace the existing Read

method in the entity class.

3.2.9.1 Class Structure

The following diagram shows the relationships between the classes forming the parser framework. This includes the relationships between the parser framework and the GSDK scenario, and main application loop classes.

The parser controller object generates a set of parser manager objects, which mirror the entity managers of the scenario database. Each parser manager will contain a set of entity parser objects, which will read the tokens with a grammar defining the required type of entity. Each entity parser defines a one-to-one mapping with the corresponding entity object. The entity parser object will form a temporary data buffer to maintain any unresolved details of the entity in a primitive data format (typically comprising strings and Java primitives). These data references are resolved by invoking the resolveReferences method. This method returns

a flag to indicate whether all the references have been resolved for the entity parser object or whether some references remain unresolved. It is called immediately after the data has been read from the given stream, and (if the data is still unresolved) again after the parser has reached the end of the token stream.

Scenario"Reader Impl

Parser"Controller

Entity"Controller

Entity "Manager

Scenario "Reader

Entity"Parser

Application"Loop

Application"Scenario

BasicLoop

Parser"Manager

Scenario

Entity

1..*

1

1..*1

1

1..*1..*1


6 Feb 2009

Page 30 of 117

Figure 3-9 - Entity Parser Framework Class Structure

3.2.9.2 Parsing Tokens From A File

When an application reads a scenario file, first a ScenarioReader object must be installed in the application. The Scenario class installs a default reader automatically. This default reader accepts tokens from the file, and attempts to match the given token against the names of the entity managers in its scenario database. If an entity manager name matches the token found in the file, then an EntityParser object is created using an object factory to create the entity parser specific to the type of entity managed in the parent entity manager. The name pattern used for the parser class is derived from the entity name, and is of the form <entityName>Parser. The parser object is managed in the corresponding ParserManager object. Parser managers are, in turn managed within a ParserController object. The parser will also create an empty instance of the corresponding entity object, which will be populated with attribute values read from the tokens in the file.

The following sequence diagram shows the interactions between the objects forming the parser framework.


6 Feb 2009

Page 31 of 117

Figure 3-10 - Entity Parsing Mechanism Sequence Diagram

The required EntityParser instance will then read tokens from the scenario file according to the implementation of the class specific passer, each inherited read operation reading its set of tokens from file. Thus an object derived from the PositionedEntityParser, such as a Beacon, will read the Entity attributes first, followed by the PositionedEntity attributes and finally the Beacon specific attributes. The token values are read and either applied into the entity object, or if they need to be resolved to establish a reference to another entity object, which has yet to be created (a forward reference), they are stored for future resolution.

Once the tokens have been read the resolveReferences method is invoked to attempt to resolve any of the unresolved objects referenced from the entity. If the resolution is completed, a flag is set to indicate that the parsed entity is ready to be managed in its entity manager. If unable to resolve all the references, the parsing will continue until the end of the file is reached. At this point, all the unresolved parsers will once again have their resolveReferences methods called to attempt to resolve the remaining references. This final attempt should find all remaining objects, as the file must resolve all its own references to be self-consistent. Failure to resolve the references at this point will exclude the unresolved entities from the database, and they will play no part in the simulation.

The resolution of undefined entity objects is supported by the Reference class, which defines a reference in terms of a manager name string (identifying the corresponding entity manager) and the entity name string (identifying the specific instance of the entity). The Reference class also defines a method to resolve itself into an entity, given a scenario object or an entity controller object.

3.2.10 Entity Dynamics

This section describes the dynamics of an Entity object. This covers the scenario update mechanism, the use of events to signal changes of state, and the use of the Association structure, which provides a link between the entity object and its display symbols on one or more windows in the application.

3.2.10.1 Time Updates

The entities held in the component databases in a GSDK platform may be updated at regular intervals to bring their internal state up to date with the simulation time. The simulation time may be updated from a variety of sources, but in the eDEP platform the central source of simulation time updates is the time-server, TS.

The scenario update must be performed prior to any timed events being processed. Thus the scenario update is performed in each component simultaneously with the time tick update. When the TimeService processes the time tick, it invokes the setTime method on the scenario object, which then performs an update on each entity manager that has requested update for its managed entity objects. Any subsequent events scheduled for the new simulation time are processed after the entities have been updated.

The TimeService implementation invokes the method setTime() on the scenario object. The local time manager is updated from the scenario setTime() method, which then calls its update method with the new simulation time.

Where an update is required, an explicit non-zero time step value is set in the manager as it is added to the database, using the method addEntityManager (), and the entity manager’s local update flag is set automatically from this value, to indicate that a regular update is required. By default, an entity manager will not perform a regular update of its entities, setting the time step value to zero.


6 Feb 2009

Page 32 of 117

3.2.10.2 Scenario Update Mechanism

Entities maybe signalled on a regular basis to update themselves according to the dynamics identified in their EntityMotion model, or by simply being moved to the next predicted position along the given planned route, defined by a Trajectory object. This update is internal to the Scenario, and provides a way of modelling a time evolving state according to some physical model. Entities can be marked for the internal update by setting the localUpdate flag either in each individual entity, or in the EntityManager, which will automatically set the flag in the Entity objects held within it. These update mechanism could be used, for example, to provide a thrust and drag model for an aircraft by implementing an EntityMotion object. Specific model parameters may be given for a particular aircraft type; the Entity provides an interface to set a collection of model specific characteristic parameters in a class derived from the EntityType object.

The interval between updates is set by the update interval defined in the EntityManager. This value is expressed as a multiple of the basic time step stored in the Scenario object, and is supplied to the manager when the manager is created and added into the derived Scenario class constructor. The EntityManager time step value is optional, and if not present a default value of zero is assumed, which will turn off the regular update signal, and the entity manager will not call the Entity update method.

The sequence diagram below shows how the updates might be managed for a time evolving entity, Track, and for an entity that is positioned according to messages coming from some external source, Aircraft.

Figure 3-11 Entity Update Mechanism

3.2.10.3 Entity Change Event Notification

The entity provides an asynchronous event notification mechanism, where a client object can register interest in changes of state occurring within an entity object. The client supplies an EventListener object, with an optional SubscriberFilter, which matches a particular type of change of state event, by comparing the name of the raised event with the supplied filter name. The listener and associated filter is stored in a SubscriptionManager object contained within the entity implementation. The listener object is notified of any state changes matching


6 Feb 2009

Page 33 of 117

the given filter. If a client wishes to process a change event raised by any of the entities managed within a given EntityManager, the client can register interest in all such events through the manager, rather than through the entity itself.

When the entity signals a change of state, and there is at least one subscriber interested in that change of state, the entity will create an EntityChangeEvent. This event can then be distributed through the SubscriptionManager to all registered clients, by invoking the notify methods of the registered event listeners.

Each derived entity object class may define a set of changes of state, which are published for subscribers to register interest. These change types are identified by a simple name string, and the events referenced using these name Strings, as demonstrated by the following code fragments from the MobileEntity object. Interest may be registered in the change of a ROUTE_PLAN in the entity object, by invoking the method registerForChangeEvent with the name of the required change type, “ROUTE_PLAN”. When the new route plan is set, the entity can call the method notifyChangeEvent to distribute the signal of the change to all subscribed client objects. The following code fragments from the MobileEntity show how these calls are made. Note that the route plan event name is qualified with the entity name “ROUTE_PLAN/<name>”, to allow it to be distinguished from similar events raised from other mobile entity objects.

public interface MobileEntity extends PositionedEntity { public static final String ROUTE_PLAN = "ROUTE_PLAN";

public void SetRoutePlan( Trajectory NewRoute ) { RoutePlan = NewRoute; notifyChangeEvent( ROUTE_PLAN+"/"+getName() ); } // End method SetRoutePlan

A client can also register for changes occurring to all entities within a given manager object by registering for the event through the EntityManager. The following sequence diagram shows how the entity, entity manager and subscription manager interact with a client of the change event.


6 Feb 2009

Page 34 of 117

Figure 3-12 Signalling An Entity Change Event

3.2.10.4 Adding Events To The Central Event Scheduler

All entities have access to the central event scheduling mechanism, provided by the EventScheduler created in the Scenario implementation class. This allows entities to register interest in user defined events signalled by other entities, and to generate its own events, which can in turn by signalled to any object that has registered interest in any of the events. In addition, the GSDK event scheduling provides two mechanisms to allow an entity object to schedule events for its own consumption.

The first method requires the developer to create a new event class derived from the EventObject class, and makes use of the unimplemented method process() in the EventObject. This parameterless method is called when the event is signalled. This method can be overridden in the derived event class, to implement some user defined processing, which can make use of any parameters added into the derived event class. This event can be scheduled on the EventScheduler either for immediate consumption (by calling the scheduleNow method), or for consumption at some future time, using either the schedule method (where the time is set in the event) or the scheduleAfter method (where a time interval is added to the current time and then set in the event).

The second mechanism allows the developer to create a periodic UpdateEvent. This event defines its own process method, which reschedules itself to be signalled after an interval given in the event constructor. The updated object must implement the UpdateInterface, which defines a single method, update called with the current simulation time. This method returns a Boolean flag to indicate whether the next periodic event should be scheduled. If it returns true the next event is scheduled, false and the update event chain terminates.


6 Feb 2009

Page 35 of 117

Figure 3-13 Scheduling Events Using Central Event Scheduler

3.3 EVENTS FRAMEWORK

3.3.1 Overview

The event framework provided within the GSDK allows objects to communicate with each other using a rich set of event mechanisms. These mechanisms allow the notification of events through a central event queue, with events stored either for immediate consumption or to be signalled at a pre-determined future simulation time. Events can also be scheduled to fire in real-time, and events provide the primary mechanism to carry information between running applications either within the same JVM or remotely across a network, using RMI based middleware, as described in section 3.5.

3.3.2 Event Scheduler Interface

The EventScheduler provides a central mechanism to schedule and coordinate the distribution of events to interested objects within a single component application. It can be used to pass information anonymously from one object to another through a notification mechanism, or it can be used to allow an object to schedule future events to itself. The EventScheduler also provides a mechanism to decouple processing tasks, as the scheduling of new events and the retrieval of current events is performed through synchronised methods. This provides a mechanism to schedule external messages retrieved from an RMI thread, and to place them onto the internal application thread.

3.3.2.1 Event Object and Event Listener Classes

All the events, scheduled using the central event scheduling mechanism, are derived from the abstract event class EventObject. This simply defines the time at which the event is due to be signalled, and in the provided GSDK implementation inherits from a HeapObject, which enables the event to be sorted on a Heap queue. The Heap has the property that the object at the top of the heap is the next ordered object in the sequence, and the reordering of an object can be performed in log2N time, where N is the size of the heap. This makes the heap an extremely efficient mechanism to sort large numbers of rapidly changing events.

The EventObject defines an empty implementation of the parameter less method process. This method can be overridden in derived classes to provide a mechanism to perform some private processing when the event is signalled. For example, a client object may wish to be woken-up


6 Feb 2009

Page 36 of 117

at some future simulation time, and will schedule itself a derived event class object, which in the event’s process method implementation will invoke the required methods in the client object to signal the wake-up call. A typical example of this is provided in the UpdateEvent described in section 3.3.3.3 below.

3.3.2.2 Event Scheduling and Cancellation

This section provides brief descriptions of the available event scheduling methods and the event cancellation methods. The EventScheduler provides the following scheduling methods:

• schedule – schedule the event to occur at the simulation time defined within the event. Event order for events occurring at identical simulation times is not guaranteed;

• schedule now – schedule the event to occur at the next event processing opportunity. Events will be retrieved in the same order they were placed on the queue;

• schedule after – schedule an event to occur after a given simulation time interval. Event order for events occurring at identical simulation times is not guaranteed;

• schedule real-time – creates a real-time event on a Java Timer object, to occur a given number of milli-seconds of real-time into the future. The real time event can optionally be made periodic.

Figure 3-14 Event Processing Order

Events may be cancelled using the cancel method. Events can only be cancelled if they have been scheduled for some future simulation time, or if they have been scheduled as real-time events. Events scheduled for immediate consumption, on the immediate event queue, cannot be cancelled. Note that the scheduler of the event must keep a local reference to that event to be able to cancel it.

3.3.3 Event Processing

The GSDK provides different event usage design patterns, available for use in a system implementation. An object may use events privately to provide a wake-up signal at some future time, or an object can register to be notified of an event when a particular event type is signalled through the event scheduler. Events may also be used to report messages from


6 Feb 2009

Page 37 of 117

remote components to subscribed client component services. The different event mechanisms defined are summarised below:

• time scheduled events defining a private process method;

• events notified to registered clients;

• events notifying changes in entity objects;

• events scheduled for immediate consumption;

• subscriptions to messages from remote servers;

• graphics events, signalled from active widgets.

In addition, notified events and remote message events may be filtered through an event filtering mechanism, so that only events with attributes matching the required criteria are forwarded to a registered client.

3.3.3.1 Private Event Processing

The following sequence diagram demonstrates the simple use of a private event to stimulate processing in the FlightEntity object each time that object flies across a sector boundary. In the example, the flight entity retrieves a list of boundary crossing points from the flight service, and the first crossing point in the list is used to create and schedule a NextCrossingEvent on the event scheduler. The event time will be set to the first sector crossing time.

The NextCrossingEvent is an extension of the EventObject, and provides an implementation of the process method that will invoke the crossing processing in the FlightEntity, which in turn will cause a new NextCrossingEvent to be created and scheduled for the next crossing time. This will continue until the last crossing is negotiated.

Figure 3-15 Using Private Timed Events and the Process Method

3.3.3.2 Event Notification Mechanism

The consumer of an event may be unaware of the source of an event, and likewise the source of an event may be unaware of the event’s consumers. The GSDK provides a very loosely coupled mechanism using the EventScheduler as the intermediary between the producing and consuming objects.


6 Feb 2009

Page 38 of 117

The mechanism follows a simple subscription paradigm, where the consumer registers interest in an event type, by invoking the registerFor method in the EventScheduler, passing the event class path name together with an object implementing the EventListener interface. The event class path will match the required event’s class name, given by a call to eventClass.getClass().getName(). The EventListener interface defines a single method, notify, which is invoked from the EventScheduler, if an event is signalled whose class name matches the registered name, the supplied EventListener’s notify method is invoked to signal the event to the consuming object.

When registering for an event, the consuming object can provide an additional optional parameter defining a SubscriberFilter object. The SubscriberFilter enables the consumer to filter on the attributes of the required event class, so that only those events that pass the filter will be notified. The consumer can only filter on information contained within the event, which is passed as an EventObject into the method matches. This method returns true if the consumer wishes to be notified.

It should be noted that no check is made that the supplied event class name defines a valid event class, and similarly no check can be made that an event raised by a producing object will be notified to its intended consumers.

Figure 3-16 Event Notification Class Diagram

The following sequence diagram shows how a consumer registers interest in an event, through the event scheduler, and how a produced event is signalled to the consumer through the supplied event listener:


6 Feb 2009

Page 39 of 117

Figure 3-17 Event Notification Processing Sequence

3.3.3.3 Entity Change Event Notification

The Entity class defines an entity specific event notification mechanism, which is design for performance, and is made available to local consumers, with knowledge of the producing entity. A SubscriptionManager performs the subscription management within the entity object. This manager is only created if at least one subscriber registers interest in an EntityChangeEvent. Each EntityChangeEvent carries a reference to the entity object raising the change event, and a string identifying the topic that this event refers to. The topic attribute might identify the type of change, and be further qualified with details of the change. This topic string can then be used to qualify the registration of interest in the event, by adding a topic field to match with the topic string set in the event. The class diagram below shows the relationships between the entity and the event notification classes.


6 Feb 2009

Page 40 of 117

Figure 3-18 Entity Change Events

The following sequence diagram shows how a client object can register for interest in an EntityChangeEvent, and get notified when a change matching the notification criteria occurs in the entity:

Figure 3-19 Entity Change Notification Mechanism

3.3.3.4 The Concept Of Topic

The notion of an event topic provides a mechanism to supply events to specific objects, without that event being made widely available. The event itself can define a string in which the topic is defined. The format of the topic string follows the URL syntax, with topic headings. The following topic name example might be used to re-post a private event back to an event listener provided by the object, which originally received the event, identified by its hash code 348590. As this topic name in the event would be set, and would only be known to the re-posting object, the event would not therefore be widely available for notification.

gsdk:classname/private/repost@348590

The complete subscription URL string (class name and topic) describes a directory like structure, which is mirrored in the subscription manager. A subscriber will receive all events that match the URL and all the URL patterns that start with the subscriber URL. For example, if an entity change event were raised which identified a PEL change, and a specific aircraft callsign, it might be subscribed to with a topic of “PEL/AFR123”. A subscription identifying just PEL (that is “gsdk:gsdk.entity.EntityChangeEvent/PEL”) would also return the event, as this subscription pattern would match all URLs of the form “gsdk:gsdk.entity.EntityChangeEvent/PEL/…”. A null topic will match all events raised against a subscription to just the class name.

The subscription manager makes use of the topic mechanism, using a hash table look-up each sub-topic element of the topic string, forming a search tree. Each branch in the tree defines a vector of subscribers to that branch (and implicitly all sub-branches), and the sub-branches are mapped with another hash table, as shown in the diagram in Figure 3-20 below.


6 Feb 2009

Page 41 of 117

Figure 3-20 Using Topic Names To Filter Event Notifications

3.3.3.5 Immediate Events

The immediate event scheduling mechanism allows users to schedule events, which will be processed at the earliest possible opportunity. The events are scheduled on the ImmediateEventQueue and are processed in the same order that they are added into the queue. The events are of the same type, namely the EventObject, as those scheduled on the Heap queue in the EventScheduler, but are scheduled using the method scheduleNow.

3.3.3.6 Real-Time Events

The real time event scheduling mechanism allows users to schedule events, which will be processed after the given interval of real time has elapsed. The events are scheduled on the RealTimeEventQueue and are processed in the same order that they are added into the queue. The events are of the same type, namely the EventObject, as those scheduled on the Heap queue in the EventScheduler, but are scheduled using the method scheduleRealTime. The events can be rescheduled automatically be specifying a repeat period. The real-time timing mechanism is achieved through the use of the Java utility Timer class, which fires after a given delay in milliseconds. When the timer fires, an EventObject is scheduled asynchronously on the ImmediateEventQueue, for processing at the earliest opportunity.


6 Feb 2009

Page 42 of 117

Figure 3-21 Scheduling a Real-Time Event

3.3.4 Monitored Events

Some simulation events, scheduled in the timed event heap, are routinely cancelled before they fire, and to ensure that all references to the event and any associated information are cleaned up, a mechanism is provided to monitor the progress of an event while it is scheduled within the event heap.

The MonitoredEvent class offers listener functionality that allows the client to be notified when the event is cancelled, enabling out of date references to be updated or removed. The user should create an event derived from this class rather than the standard EventObject, from which it is derived. The listener is an implementation of the interface MonitoredEventListener, which provides notification immediately after event cancellation, event process and event notification. The event monitor listener is added to the event by calling the setMonitor method.

The listener interface is defined below.

public interface MonitoredEventListener { public void eventProcessed( MonitoredEvent e ); public void eventNotified( MonitoredEvent e ); public void eventCancelled( MonitoredEvent e ); } // End interface MonitoredEventListener

3.3.5 Example Event Classes

3.3.5.1 Update Event


6 Feb 2009

Page 43 of 117

3.3.5.2 Entity Change Event

Entities use a similar notification mechanism to the central event scheduler. However, the event is not scheduled centrally, but a list of subscribers is kept locally, and the event is only created if there is at least one subscriber. The client object creates an event listener, which is then registered, along with the name of the change of interest.

3.4 GRAPHICS FRAMEWORK

3.4.1 Introduction

The GSDK AWS package provides a range of graphical features and hierarchically organised widget types, which may be used to build specialised, geographically oriented windows such as the plan view display (PVD) window of a controller working position (CWP). The acronym AWS stands for Abstract Widget Set, and is designed to provide classical push button style and functionality, but applied to objects of arbitrary shape, employing features to provide real time widget management, and associations between a display widget and its underlying data source (usually an Entity object). The graphics framework supports the drawing of background maps and overlaid transparent effects, as well as providing a set of widgets, which may be configured into distinct layers, keeping the widgets allocated to a given layer, always appearing above or below widgets allocated into a different layer. This section will provide a guide to the key design patterns to be used when developing graphics applications from the package gsdk.aws.

3.4.2 Graphics Management Class Structure

The AWS graphics facility provides a number of manager classes to support the initialisation, and update of the graphical items under its control. The AwsPanel provides an interface to the basic container, in which the AWS objects are drawn, and through which the AWS behaviour facilities operate. The panels are hosted in an AwsShell object, which inherits from the Java swing JFrame object.

The AwsPanel has access to a number of key GSDK objects, including the Scenario, the EventScheduler and the TimeManager. It also defines a Converter object, which provides automatic position and scale functionality to map objects defined in the world coordinate frame of reference onto the panel window frame of reference.

The drawing mechanism divides the display into a series of layers. The AwsLayerManager object held by the AwsPanel manages these layers. This layer manager holds an arbitrary number of widget managers although usually three suffice, providing a manager to define mapping information, then transparent overlays and the top manager defining the widget layers. In addition, the basic behavioural responses to mouse and key input events can be configured using default behaviour, which processes the events using the internal event dispatching mechanisms, or the user can provide application specific behaviour by replacing the default listeners with user defined listeners. The following class diagram shows the relationships between these key manager objects.


6 Feb 2009

Page 44 of 117

Figure 3-22 Panel Management Classes

3.4.2.1 The AWS Panel and Associated Classes

When an AWS based display is required, the developer will usually start by extending the AwsPanel to form a specific display object, configured to meet the given display requirements. The AwsPanel creates an AwsLayerManager, which maintains each of the drawn layers on the AwsPanel, the developer will then add the widget managers that are required and the layers required in each manager. The implementation class AwsPanelImpl implements the interface AwsPanel and extends the Swing component class JPanel, and may be used interchangeably with other Swing components. The panel is drawn by providing implementations of the standard component painting methods paint(Graphics g), paintComponent(Graphics g) and repaint(). When any graphical item needs to be re-drawn, it makes a request to the layer manager, which determines the optimal way to perform the required draw operations. The implementation of the paint method simply sets a flag to indicate that the first draw has been completed. The paintComponent method activates the AWS drawing algorithm, determining which layers need to be redrawn, and rendering the panel image a layer at a time. First the background is filled with the default background colour then the contents of the widget managers are then drawn in order. After each widget manager has been drawn the resulting image is stored so that the process does not have to start from the lowest manager each time but can start from the lowest layer in the lowest manager that has any redraw requests. The drawing requests, and the order in which graphical items are drawn are controlled by the AwsLayerManager, which is described in more detail in section 3.4.4.

keyboard button presses, which are passed into the currently active widget on the display.


6 Feb 2009

Page 45 of 117

Figure 3-23 Panel Layer Management

3.4.2.1.1 AwsPanel Mouse and Key Event Handling

The AwsPanel receives Java AWT graphics events through standard AWT listeners registered in the panel. These listeners detect all mouse motion and button press events over the panel, and distribute these events to interested parties..

Currently GSDK supports mouse adapters that follow the Swing framework pattern – taking mouse button presses, releases and clicks, wheel movements and coding specific handlers for these activities. This works well when the interactions are simple, where a certain event should always trigger a certain action (for example, a mouse button press over an AwsButton should activate the button highlighting). Such situations are encountered when handling mouse events for a small non-complex widget.

However when the widget or panel is complex, for example, where the handling of the event has some dependence on the state of the widget/pane/layer or panel under the mouse pointer, the event handler must implement a more complex chain of logic in order to select the appropriate course of action. Furthermore, the operations that are required on receipt of an event tend to be embedded in the logic of the mouse event handler itself, making the handler less open to configuration, sub-classing or reuse.

Looking at a particular example of this, in the case of the base class implementation of the AwsPanel, the panel supported many possible operations. These were zoom in, zoom out, rotate, drag – pan , zoom in/out of a selectable area, map centering amongst others. Furthermore the panel also displays individual widgets in their layers and these widgets may also respond to mouse events.

These actions had been coded in one pretty much giant piece of logic where the buttons, events and their enabling flags were inspected and the operations were activated. Implementers of sub-classes had a hard time overriding small parts of this behaviour. Some downstream projects simply re-implemented with their own panel mouse event handlers, after removing the base mouse handler.

This tangle of logic and behaviour was not the most satisfactory situation and the AwsGesture and related classes were introduced aiming to rectify these problems and provide a framework


6 Feb 2009

Page 46 of 117

for dealing with such complex contextual mouse/key events. The nomenclature adopted is that we create triggers which subsequently cause activation of an action relevant to these triggers i.e the on-screen gesture that the mouse/key enacts.

With these concepts in mind, the main function of the gesture framework is to intercept conventional Swing or Java based mouse events and delegate their processing to a series of triggers and gestures, ultimately (or maybe as a matter of priority) pushing unconsumed events through to the individual widget handlers.

Another issue with adding custom mouse handlers is that there is no way to prioritise one event handler over another. Normally events are processed in some order related to the listener addition order. The gesture framework provides the means to prioritise handling of particular operations over others. One of the other requirements for the API therefore is that some gestures should have higher priority gestures than others. Consider the case in which a user is dragging the mouse. If the mouse drag starts over a widget, this context may dictate that we wish to drag the widget. If however the mouse drag occurs over anything other than a widget than we may wish this to correspond to a pan around the airspace. We can say that the pan around the airspace is a low priority gesture, and that we should try to detect the mouse drag on the widget as a priority. In this scenario we would configure the drag – pan gesture with low priority. Similarly we may wish that when we are in map centering mode that a mouse button click should always centre the map without regard to the presence of a widget under the cross hair cursor. In this case we would say that the map centre action has priority over the widget

The gesture framework also aims to make triggers and gestures configurable at runtime and to allow gestures to be mapped to one or more triggers. This is especially advantageous as the use of one or more triggers for a gesture allows one to add keyboard accessibility for certain activities that previously may have only been possible through mouse activity.

3.4.2.1.1.1 Framework Details.

The framework provides a gesture manager implementation to support registration of gestures, their triggers and the processing with respect to incoming mouse events. To use the manager we must delegate processing from the conventional Swing mouse listeners to this manager.

One useful thing to record about a delegated event is which mouse handler delegated the event -whether a mouse was pressed, clicked or released or a mouse wheel moved may have some importance in the activation of a particular gesture. We find then that the panel gesture manager is hooked into the panels Swing/GSDK mouse listener as follows:

private class AwsMouseAndKeyActionHandler extends AwsDefaultMouseActionHandler implements KeyListener

{

public AwsMouseAndKeyActionHandler()


6 Feb 2009

Page 47 of 117

{

super( AwsPanelImpl.this, buttonMask );

} // End constructor AwsMouseAndKeyActionHandler

/**

* Delegate through gesture manager

*

* @param e the mouse event triggering the call.

*/

public void mousePressed( MouseEvent e )

{

gestureManager.processGestures( null , e, AwsGesture.MOUSE_PRESSED );

} // End method mouse Pressed

… other handlers omitted …

/**

* Delegate through gesture manager

*

* @see java.awt.event.KeyListener#keyPressed(java.awt.event.KeyEvent)

*/

public void keyPressed(KeyEvent e)

{

gestureManager.processGestures( e, null , AwsGesture.KEY_PRESSED );

}//end method keyPressed

}

Thereafter all panel mouse events are processed by an AwsGestureManager implementation.

The AwsPanel implementation should provide a suitable gestureManager.

3.4.2.1.1.2 Classes, Roles and responsibilities.


6 Feb 2009

Page 48 of 117

AwsGesture

AwsGestureManager

AwsGestureManagerImpl

AwsGesturePriority AwsGestureTrigger

NullGesture

Figure 24 Gesture framework key classes

AwsGestureManager – interface, supports registration and removal of gestures, gesture priority update and gesture processing in priority order on receipt of a mouse event.

AwsGestureManagerImpl – The AwsGestureManagerImpl is a concrete class that provides basic support for registration, retrieval, processing and removal of gestures. It implements AwsGestureManager using ArrayList and associated semantics to enable gesture addition and removal. Uses simple sort on addition strategy to implement priority ordering of gesture processing.

AwsGesture – abstract class - The principle stages of a mouse or key gesture in any context are initiation, update and completion. To achieve the execution of these distinct stages the base AwsGesture class supports addition and retrieval of one or more trigger instances that may or may not indicate these stages are in progress. Meanwhile concrete AwsGesture sub-classes provide implementations of the onStart, onUpdate and onCompletion methods.

AwsGestureTrigger - The start, update and completion conditions are implemented in sub-classes of the abstract base class AwsGestureTrigger. This base class also supports configuration of a trigger button to provide the convenience of run-time button configuration if so desired.

AwsGesturePriority - Gestures are processed in priority order, with the priority typically being one of the pre-determined priority constants held in AwsGesturePriority (HIGHEST, DEFAULT, LOWEST). All gestures support the setting and getting of their priority. However care should be taken to use the gesture manager to update a gesture priority, as this will re-sort the gestures before any further processing occurs.


6 Feb 2009

Page 49 of 117

3.4.2.1.1.3 Implementation details.

With these implementations and roles in mind the basic pseudo-code that describes the reception and processing of a mouse/key event by the gesture manager is as follows:

Receive mouse / key event ;

Process gestures in order of priority

until terminating gesture is received

Notice that to implement this strategy we need to determine whether a gesture is a terminating gesture. This is something that the implementor of a particular gesture must decide upon because if a gesture is marked as terminal, no further processing will occur until another mouse event/key event is received. It is similar to setting a mouse event as having been consumed.

In the abstract operation class AwsGesture, the methods onStart, onUpdate, onCompletion provide a boolean return type to indicate whether the gesture should be considered terminal. The base AwsGesture class provides a terminal flag that is reset and set during the gesture processing cycle based on the flag returned from these methods. In this way the main processing loop can determine whether or not to terminate after handling an event, or continuing to apply the event to other lower priority gestures.

The main application of AwsGesture and associated classes can be found in gsdk.aws.panel.gesture, which specialises the gesture classes to operate in collaboration with an AwsPanel implementation.

In AwsPanelImpl the panel's mouse listener delegates event handling to an AwsPanelGestureManager instance (AwsPanelGestureManager simply inherits from AwsGestureManagerImpl to add and work with an AwsPanel reference).

The collaboration with the AwsPanel is shown below:


6 Feb 2009

Page 50 of 117

AwsPanelGesture

AwsPanelGestureManager

AwsPanelGestureTrigger

PanelEventDispatcher PanelEventDispatchTrigger

AwsPanel

AwsGestureManagerImpl

ScaleRubberBandGesture

ScaleRubberBandTrigger

Figure 25 AwsPanel and PanelGesture collaborations

The AwsPanelGestureManager configures itself to handle the default AwsPanel actions - One of these is the scale rubber band gesture, which activates the appearance of a draggable, rectangular frame. And, as we always wish to dispatch events to widgets within the panel and to assign this action with a priority relative to other gestures, we will make this dispatch process a special gesture case for the panel that is always triggered. This is wrapped in the PanelEventDispatcher specialisation of the abstract AwsPanelGesture.

All gesture managers can use the public registerGestures method to invoke initialisation of particular gestures. The AwsPanelGestureManager installs the panel event dispatcher gesture (shown in ) and the scale rubber band gesture by default.

Another special case of gesture manager used within eDEP is the PVDGestureManager which adds registration of the standard plan view operations of rotation, zoom, panning and centreing.

3.4.2.2 The Converter Class

The converter provides the functionality to convert between world coordinates and screen coordinates. The converter object contains two scale objects which provide the basic conversion mechanism, maintaining its own scale factor. The converter will always contain the two scale objects however they are only used independently of each other when the


6 Feb 2009

Page 51 of 117

converter is being used inside a graph where two scales are required otherwise when used with a standard map the scale factor on the y axis is kept the same as that on the x axis. The converter also contains a viewport object which holds a reference to the AwsPanelImpl this converter is a part of and allows the converter to respond to any resize events which will result in the converter being updated. The converter interface requires that when converting to or from world coordinates both an x and y coordinate are provided. This provides the converter with the information to be able to rotate the point that has been provided around the centre.

Figure 3-24 The Converter


6 Feb 2009

Page 52 of 117

3.4.2.3 The Widget Hierarchy

The AWS defines a range of widget classes to support specialist geographically based applications, but also to support more conventional widget structures, based around the rectangular push button. AWS widgets are provided to form the building blocks for more complex widget structures, and only implement a small set of container/manager widget classes. Some of the key features of the geographical widget set are listed below:

• arbitrary button shapes - AwsGenericButton;

• configurable trail history and heading vector - AwsPathDetails

• automatic positioning at the world coordinate location - AwsWindow;

• widget drag functionality - AwsGenericButton;

• label – AwsLabel and leader line – AwsLeaderLine structure;

• complex, configurable interactive labels - AwsLabel;

• containers for column menus – AwsColumnMenu and lists - AwsList;

• compound widgets – AwsSlider.

The root of the widget hierarchy is the AwsManagedObject, which provides the basic widget management functions. The derived class AwsWindow then provides position and size functionality. Finally the AwsWidget class provides the behaviour functionality, implemented using a set of AwsListener types. The widget hierarchy is summarised in the following class diagram in Error! Reference source not found..

Figure 3-25 The AWS Widget Hierarchy


6 Feb 2009

Page 53 of 117

The function of each derived widget is described briefly in the following paragraphs. The detailed description is provided in the hyperlink reference to the HTML Javadoc, given with each description.

• AwsGenericButton – provides the super class for all the derived button widgets. Defines basic push button functionality, as well as drag motion functionality.

• AwsButton – provides a classical push button widget in a rectangular region, with optional shadow, and in-filled background.

• AwsMarker – provides a widget with similar functionality to AwsButton, but defines a circular button, with circular shadow.

• AwsPolygonButton - provides a widget with similar functionality to AwsButton, but defines a button with an arbitrary shape defined by a Java AWT polygon.

• AwsEllipse – derived from the button widget, displays a button label within an ellipse.

• AwsPane – provides a primitive container class. The pane object defines a rectangular region, which can be in-filled with colour or left transparent. It defines an offset coordinate frame from its parent widget.

• AwsFrame – provides a basic rectangular framed widget containing optional header bar and close button across the top, and frame border enclosing an AwsPane container widget.

• AwsThumbnail – convenience widget to display an image within a frame. Can load GIF or JPEG format images from named image files.

• AwsColumn – defines a simple column container for AwsButton widgets.

• AwsPopupHeader - provides a simple widget defining the header name for a pop-up menu. Used in combination with the AwsColumn widget to form an AwsColumnMenu widget.

• AwsColumnMenu – used to create a pop-up menu, with a header identifying the name of the menu, and a column of buttons defining its input values.

• AwsLabel – a compound widget made up from a column of AwsRow objects, with each row defining a series of buttons, packed into a minimum space. Provides functionality to allow label drag, and to link the label to another widget through a AwsLeaderLine widget.

• AwsRow – a container widget holding a row of button widgets of uniform height. The widgets can either be packed into a row, or laid out at pre-determined horizontal positions by using an AwsRowLayout object.

• AwsSlider – a compound widget derived from the AwsPane widget, with a drag-enabled AwsButton constrained to move in a slider trough.

• AwsList – a container widget derived from the AwsPane object, it holds a column of AwsRow objects, and grows or shrinks so that it just contains all of the objects. It signals any resize actions, so a parent widget can adjust its size accordingly.

• AwsPolyline – a complex widget defining a sequence of line segments, with an optional handle displayed at each vertex, to allow the poly line to be modified by dragging the handle, or by inserting new handles, or deleting existing ones. The handles are created from AwsMarker widgets.

• AwsPolygon – a widget derived from the AwsPolyline widget, which defines an enclosed polygon loop, with the same modification functionality as provided by the AwsPolyline widget.


6 Feb 2009

Page 54 of 117

• AwsRangeSlider – a complex widget providing a double slider that can be used to define a linear range between limiting maximum and minimum values. Available in horizontal and vertical configurations.

• AwsLink – a widget that provides a link line, that can be anchored to the two widgets being linked together, or can be used to provide elastic vector functionality.

• AwsTextField – a widget that provides a basic mechanism to input text from the keyboard. The text input is formatted from left to right.

3.4.2.4 Widget Creation

Widgets are created using a two-stage process. The first stage creates a widget using a parameterless constructor. In the second stage the widget is added to the AwsWidgetManager or its parent widget. The widget’s validate method is then called by the AWS framework to complete the initialisation. The two-stage creation process is required to support the parameterless construction of widget through the GSDK object factory utility that makes use of the java reflection framework.

The parameterless constructor for a widget can only set basic attributes for the widget, as the widget is not yet managed by the AWS framework and cannot access its manager objects. Any operation that require interaction with other widgets, managers, entity objects, etc. should be performed in the validate method, which has a specific implementation for each widget type.

The validate method is called automatically for a widget when it is added to either another widget, or to the AwsWidgetManager object and should not be called directly outside of this structure. When the widget is added in this way associated information is set, such as the parent object, that allows the widget to interact correctly with the rest of the AWS framework. New widgets that define a validate method must call the super-implementation to preserve the previous settings and functionality, unless specifically required not to.

3.4.3 Panel Widget Entity interaction

The panel supports registrations of a manager interface called the AwsEntityGraphicsManager. This has particular convenience when widgets have a one to one relationship with an entity. Using an implementation of this class one can tie the widgets lifecycle to the lifecycle of an entity. In the implementation one references the class of entities to consider ( using the TYPE_ID constant for the entity) and this causes the manager to subscribe for all lifecycle events within that entity class. When an entity is created, the manager creates a widget; when that entity is destroyed the manager destroys it.

Optionally one may also subscribe for update topics and use notification of entity updates to update a managed widgets appearance.

3.4.4 The AwsEntityGraphicsManager also maintains a list of its managed widgets

that are currently on screen – this can be convenient when searching for

widgets.Layering Model

3.4.4.1 Overview

The AWS provides a layer model, which defines the order in which the different classes of graphical element are drawn (generally maps, transparent overlays and interactive widgets), and decides which parts of a display need to be redrawn. It also provides a layer management mechanism for the widgets themselves to ensure that particular widget types always appear above or below other widgets types. For example a flight level menu should always be


6 Feb 2009

Page 55 of 117

presented above all the other displayed widgets in the PVD, and beacons should be displayed below all other widgets. The AwsLayerManager object manages the layers, and is responsible for drawing the elements of each layer and for dispatching graphics events into the relevant consuming widgets.

The layers are arranged into groups, with the bottom layer group comprising a set of maps, the middle layer group comprising the transparency layers, and the top layer group defining the logical widget layers. Each layer group defines one or more physical images on which the content of the layers is drawn. Additional images may be added to the layer groups by associating the image with a given layer to enhance the performance of the redraw operation.

3.4.4.2 Redrawing Mechanism

The display is partially redrawn when a request is made from a widget, or a complete layer, to be redrawn. When a request for a redraw is received, once the next update slot is scheduled, the layer manager estimates the most efficient mechanism to achieve the redraw. If the request comes from the widget layer group, then only the requesting widget and any overlapping widgets need to be redrawn in the widget layers above and below the requesting layer. If a given widget layer below the requesting layer defines a pixmap image, then this layer defines the limit of the downward search for overlapping widgets.

Figure 3-26 AWS Layer Management

By using a redraw request mechanism, if a large number of requests are queued either for the same widget, or for a large number of widgets, only the latest requests will be processed, and if the numbers of widgets making requests exceeds a threshold value, then the processing can be simplified by forcing a complete redraw of the affected widget layers.

If requests to redraw are received from the overlay layers, then the background map image is copied onto the transparent layer image, and the transparent overlays are completely redrawn to their layer. Similarly if a request to redraw the map is received then the map image will be cleared and redrawn, as will the overlay transparencies and the widget layers above. Redrawing the overlays and the map are the most computationally expensive drawing processes. They may be optimised to give real time feedback when, for example, scaling or re-centring the map, by drawing transparent overlay objects in solid outline colour.

3.4.4.3 The Widget Layer Mechanism

The widget layer mechanism provided in the AWS allows any number of logical layers to be defined within an AwsWidgeManager object. This holds a set of layers each of which contains a list of widgets allocated to that layer. The widgets in the layer are drawn in the order they

BAW821

KLM112

map layers

transparent

layers

bottom

widget layer

top widget layer{widget

images

{mapping

images


6 Feb 2009

Page 56 of 117

are held within the layer, and the layers are drawn from the lowest layer first to the top layer last.

The class diagram shown below describes the layer model. The AwsLayerManager controls access to the sets of graphical layers in the AwsWidgetManagers. The parent AwsPanel is made available to all widgets through the AwsManagedObject interface.

Figure 3-27 Managing Individual Layers

3.4.4.4 Event Dispatching

Events are dispatched into widgets by cascading the graphical AwsEvent through the widget layers, until the bounds of a widget on a given layer coincide with the Cartesian location at which the event was signalled. The widget then becomes a candidate to consume the event. But first, the widget checks whether any of its children can consume the event, by cascading the event through the child widget hierarchy, until the lowest level child contains the event. If the consuming widget is an instance of the container widget AwsPane, and is transparent, the event will not be consumed, but can fall through to a widget lower down in the layer, or on a lower layer. While the event has not been consumed by any widget it will continue to be dispatched until there are no more widgets to offer it to. Widgets define three special states that changes the default way that events are dispatched:

• Widgets that are defined as modal will accept all input irrespective of the location of the cursor. A modal widget provides the default focus for events. Typically, a modal widget might be used to represent a pop-up menu that requires an input to be made before any other interaction can take place.

• An active widget represents a widget that is in the process of being activated, but has yet to complete the activation. An example of this might be the completion of a mouse click event over a push button. The button press event is made over the button to initiate the activation (so the button is designated active). However, a click event will only occur if the corresponding mouse button release also occurs over the widget. If the mouse has moved, so that the cursor no longer lies over the button, then the click event will not be raised. The active widget effectively becomes a modal widget while the mouse button is pressed, so that the release event can be captured and associated with the button.


6 Feb 2009

Page 57 of 117

• A focused widget is also defined, this is set with the active widget and remains set until the active widget is re-set. The focused widget is supplied with all keyboard events, provided there is no modal widget set. This allows widgets such as the AwsTextField to receive keyboard events without the need for it to be modal.

The following sequence diagram shows the event dispatch processing involved:

Figure 3-28 Event Dispatching Through The Widget Layers

3.4.4.5 Widget Layer Redraw Algorithm

Widgets are only redrawn if a request has been made to redraw a given widget, or if redrawing one widget requires another widget to be redrawn, because one widget overlaps another. Redraw requests are recorded through the AwsWidgetManager, in a list of rectangular areas that need to be updated. Each widget defines a rectangular bounding area, and this is used to mark the extent of the redraw request. The requests for update from individual widgets from any layer will arrive asynchronously at the AwsWidgetManager where they are stored in a temporary candidate patch list managed by the class AwsPatchList. If the list gets to a given threshold size, a complete widget redraw (redrawAll) may be actioned, as this will be deemed a faster action than attempting to recalculate the areas that need to be redrawn.


6 Feb 2009

Page 58 of 117

Figure 3-29 Amalgamation of Widget Redraw Patches

If separate patches are to be used in the redraw, then the widgets’ patch rectangles are merged to form contiguous redraw areas, termed patches. If any two rectangles overlap, they are merged to form a rectangle that just encloses the pair of overlapping rectangles. This process continues until only distinct (non-overlapping) patches remain.

Once the patches to be redrawn have been identified, the redraw process must identify which layer holds the last unmodified background image (each widget layer may be allocated a background image, or there may only be a single image for all the widget layers). This image will form the background from which rectangular regions of the image will be copied into the patch areas, to obscure the drawn widgets in the layers above this image.

The merged patches in the patch list identify the areas of widgets that need to be redrawn through the layer structure, drawing any widgets that overlap a given patch rectangle from the bottom layer upwards. As each layer is redrawn, the area that the patch of redrawn widgets occupies will remain constant up to the lowest layer that defined the original patch, but above this layer, the patch area may grow, as the redraw process steps upwards through the higher layers, taking in new overlapping areas. The updated patch rectangle is returned by each subsequent call to redraw, to form the redraw area of the next layer up. Once the top-most layer has been redrawn, the area of the expanded patch defined on the current widget image is copied forwards onto the screen window. If there are intermediate images between the background image and the display window, then a succession of rectangular patch copies will be made from one image to the next, repeating the overlapping widget redraw algorithm until the final copy to the display window.

Patch1

Patch2

Patch3


6 Feb 2009

Page 59 of 117

Figure 3-30 Determining the Widgets to Redraw

The widget redraw processing is described in the following sequence diagram. The algorithm follows the redraw from the request to redraw a given widget in a given layer, though the redraw signal from the layer manager, and shows how the determination of the elements to redraw is made.

Update

requested

on widget

Overlapping

request widgets

on different

layers

Widget

Layer Image Previous

Layer Image

copy image

area

Expanding patch

redraw area


6 Feb 2009

Page 60 of 117

Figure 3-31 Processing Sequence for the Redraw Algorithm

3.4.4.6 Graphics Update Loop

Each redraw is triggered from within the GSDK. A graphics thread is started upon construction of a GSDK object which reguraly updates the applications within itself. This thread takes standard update times from Resources to control the time between updates. When an update is triggered each application listed in the GSDK will be updated causing the events to be processed and the graphics to be updated.

There are two time values used to control the update loop, a standard update rate and a priority update rate. The standard update rate provides the maximum length of time between two redraws, once the graphics thread has slept for the standard time delay an update must take place across all of the applications. The priority update time can be set to a smaller time than the standard update time. This results in the graphics thread waking up more frequently to perform a priority update. The priority update, rather than updating all of the applications, updates applications that have priority update requests, these are generated from redraw requests which are the result of user interaction such as a mouse or keyboard event. If a priority update is found within the list of applications then the update is recorded and the time until a standard update is performed is reset to the full standard delay.

The priority update time is set, as default, to match the standard update time resulting in priority updates being treated the same as standard updates. However it does allow for the standard update time to be set significantly higher than normal, reducing the CPU load of a busy display, but by keeping a low priority update time allows the system to remain responsive when interacted with.


6 Feb 2009

Page 61 of 117

3.4.5 Widget Structure

This section describes the structure of a widget object, and the breakdown of the widget into its constituent classes. The AwsWidget class is extended from the class AwsWindow, which provides the basic position and size functionality associated with a displayed object. This in turn is extended from the base class AwsManagedObject, which provides the widget management functionality, arranging widgets into hierarchies and providing access to parent objects. Any widget requiring push-button functionality extends the AwsGenericButton class, which is derived from the AwsWidget class.

3.4.6 Widget Dynamics and Behaviour

3.4.6.1 Overview

The widgets provide a range of standard dynamics and user provided behaviour options. These options are divided between intrinsic characteristics of the widget itself, and the user provided behaviour in the form of listeners and related objects. The key dynamics and behaviour features are summarised below.

• intrinsic widget behaviour;

• user provided listener behaviour;

• widget updater and format methods;

• colour functions;

• symbol and label construct;

• label dynamics;

• widget motion constraint;

• widget change events.

3.4.6.2 Intrinsic Widget Behaviour

The intrinsic widget behaviour defines the appearance that widgets present when the behaviour is left unmodified by user provided listeners. By default, widgets define three display states.


6 Feb 2009

Page 62 of 117

• a normal state, showing an optional shadow with lighting from the top left corner, showing any button-like appearance to be “popped-out”.

• a highlighted state, where the widget background is drawn in a lighter colour, but retaining the shadow for lighting from the top left. This behaviour is exhibited when the setHighlightOnEntry method is set to true.

• an active state, where the widget appears “pressed-in”, with the lighting still from the top left, but the shadow colours are flipped over, and the button background colour set to a darker shade. This state is entered if a mouse button is pressed over the widget.

The intrinsic behaviour (and appearance) of a widget is controlled through the detection and distribution of standard AWT mouse and keyboard events to the widget’s handleEvent method. This method is responsible for setting the widget parameters to describe the current intrinsic state of the widget. It will also activate and user defined behaviours added to the widget as listeners. The drawComponent method will then use these state parameters to determine how the widget is to be drawn to reflect these intrinsic properties.

3.4.6.3 Standard Widget Listeners

The AwsWidget class defines a standard set of behaviour types, which can be supplied through user implementations of the corresponding listener interfaces and adapter classes. These listeners are activated in response to detected AWT events, from the handleEvent method in the widget. The standard types of listener provided are listed below:

• AwsButtonListener – detects mouse button press and release events over the widget. Press and release methods are provided for each of up to three buttons.

• AwsActionListener – detects a button click event over the widget. A click is a combined press and release event. Action methods are provided for each of up to three buttons.

• AwsMotionListener – detects mouse motion over the widget, including widget entry, widget exit and drag motion (a mouse button pressed down whilst the cursor is being moved over the widget).

• AwsChangeListener – detects changes in the nature of the widget, including change to an icon, resize, motion or a value change.

• AwsKeyboardListener – detects input from the keyboard in the form of a key press, a key release or a combined key action.

• AwsAutoRepeatListener – provided to capture automatically repeated mouse presses on a widget where a mouse button held in a pressed position needs to feed press events continuously into the widget to cause repeated updates of the widget state. A typical example would be a slider. Pressing down in the trough should stimulate the slider to move a “page” at a time towards the mouse cursor.

• AwsDestructionListener – this listener is called from the widget destroy method, and provides a mechanism to perform additional user processing as the widget is destroyed.

• AwsWheelListener – detects movement of the wheel on a wheel mouse when the cursor is over a given widget. The listener method wheelRotated is invoked with the magnitude of the rotation. The sign of the value indicates whether the wheel was rotated forwards or backwards.


6 Feb 2009

Page 63 of 117

3.4.6.4 Colour Functions

The AWS provides two classes to support a programmed approach to setting a widget’s colour. The AwsColourFunction class allows the user to select the colour of a widget according to the some user defined rules or algorithm. Typically, the colour of a widget may be determined from the state of an underlying entity object. For example, an aircraft label might be drawn in a colour that reflects the control state of the aircraft in the given CWP. The AwsColourFunction defines methods to return the normal colour of the widget, the highlight colour and the active colour. These colours will be selected from the widget draw method, which will set the appropriate colour type according to the current state of the widget.

Figure 3-32 Use of the Colour Function When Highlighting a Widget

The example use of a colour function above shows the determination of colour for a widget with its highlightOnEntry flag set to true. When a mouse motion event is detected over the widget, an entry event is signalled for the widget, and a request to redraw the widget is posted the widget draw method will access the background highlight colour. A similar mechanism will apply when the mouse motion takes the cursor out of the widget, generating an exit event and the widget will access the normal background colour from the colour function. By default, the colour function will use the Java methods darker on the normal colour for the widget activation colour, and brighter for the widget highlight colour.

A second class, the AwsColourCycle class, is provided to allow a limited degree of colour animation. It creates a “trajectory” through three-dimensional RGB colour space, defining a set of colour “waypoints”. As time proceeds, the widget is displayed using the colours returned from the colour cycle at the RGB position defined by the given distance moved along the cycle’s trajectory. The precise RGB at any point along the trajectory is determined by interpolating between the colours to produce the required RGB value. If the RGB values at


6 Feb 2009

Page 64 of 117

successive waypoints are defined as (R0, G0, B0) and (R1, G1, B1), then the interpolated RGB at a fraction f along the line linking the two colours, will be given by:

11

11

01

)1(

)1(

)1(

BffBB

GffGG

RffRR

−+=

−+=

−+=

Figure 3-33 Example Use of the Colour Cycle Class

Figure 3-34 Widget Updater Mechanism

3.4.6.5 Symbol and Label Construct

A key feature provided by the GSDK AWS package is the ability to link together a symbolic representation of an Entity, provided by an arbitrary AwsWidget, and an interactive text based label of arbitrary complexity, provided by the AwsLabel widget, showing attribute details from the entity, and connected via a leader line. The drawing below shows an example of the display of an aircraft symbol, identified by an associated text label, showing the key attributes of the underlying Entity object. In addition, the symbol may be annotated with its trail history and a heading vector defining the anticipated direction that the aircraft will follow for an arbitrary time into the future.

The trail history points and the heading vector are both maintained in the AwsPathDetails class, which can be assigned to any AwsGenericButton object. This can be configured to show a trail history of arbitrary length, and to set colour, style and shape characteristics for the trail dots. Similarly, the heading vector can be configured to display a heading vector of arbitrary length, and is used to indicate where the aircraft might fly to a given time interval into the future.

The label is shown in the diagram is in the transparent form on the left and in its opaque (solid) form on the right. Each field in a row is packed into the left hand end of each row, and empty rows are discarded to pack the label into the minimum space. The label defines the following key functionality:

• entity state dependent colours for the whole label, using an AwsColourFunction to set the overall label colour;

Interpolated

colour between

the colour waypoints.

R G

B


6 Feb 2009

Page 65 of 117

• entity state dependent colours for an individual field in the label, using an AwsColourFunction to set the individual field colour, otherwise inheriting the default label colour for the field;

• entity state dependent display of a field in a label, using an AwsFieldDisplayer to determine whether the field should be displayed;

• display of a field dependent on label opaque status, using an AwsFieldDisplayer;

• automatic label infill on cursor entry;

• automatic symbol highlight on label entry;

• opaque label can be dragged from any point, to preferred offset from symbol.

Figure 3-35 Exemplar of the Aircraft Symbol and Label Construct

3.4.6.6 Label Field Dynamics

The AwsLabel widget defines a complex interactive object that can be configured with arbitrary behaviour to change which fields are displayed, modify colours and change the appearance of the label between the opaque and the solid form. The label comprises one or more rows of button fields, contained in the AwsRow widget. The displayed fields are automatically configured into the minimum space, removing undisplayed fields and packing the remaining fields to the left hand end of the row, and removing undisplayed rows, and packing the remaining rows into minimum space.

The class diagram shown in Figure 3-36 shows the classes involved in constructing a complex label object.

3.4.6.7 Widget Change Events

A widget can be implemented to provide similar change event functionality to the EntityChangeEvent implemented in the Entity object model. A given widget can offer a number of change events, identified by event name defined as public static final String in the derived widget class. Each method that causes the corresponding change event to occur can then raise the event by invoking the notifyChangeEvent method in the AwsWidget interface. The user of the widget can then register interest in the event by making a call to

EHAM

CLN 390220

KLM2049

Solid

Label

Heading

Vector

State

Dependent

Colours

Symbol

Highlight

EHAM

CLN 390220

KLM2049

Symbol

Leader

Transparent

Label

Trail History


6 Feb 2009

Page 66 of 117

registerEvent, supplying the name of the required change, and an EventListener object to be invoked when the event is signalled.

The AwsWidgetChangeEvent class carries the change information in the form of a reference to the widget that has undergone the change, and the topic name identifying the change. The change event is supplied to event listener notify method in the conventional way, as described in section 3.3.3.3.

Figure 3-36 Label Dynamics Class Diagram

3.4.7 Map Layers

The GSDK can display an optional set of background mapping detail, comprising one or more separate maps. These maps are read from files using the Map class, which assumes generic map syntax. The mapping data is stored in the component scenario database, and may be used for display purposes, or to perform user defined geographical algorithms, such as determination of spot height, or the estimation of radar coverage. The map provides an arbitrary number of features, derived from the generic features COASTLINE, CONTOUR, AREA, LINEAR and POINT features. The Coastline and Contour features, although they define particular instances of area features, are treated separately. The AreaFeature may be used to define items such as lakes, urban areas and forest. A LinearFeature might define boarders, railways and rivers. A PointFeature might define spot heights, a bridge or a mast. The example data used in the GSDK is derived from the Digital Chart of the World mapping data (VMAP Level 0), and is stored in a readable latitude/longitude text format. In addition to the point feature, a RASTER feature is defined to allow an AWT Image object to be overlaid onto the map, and is provided by the class RasterFeature.

The map data is drawn using an AwsWidgetLayer object. The AwsWidgetLayer object will draw coastline, contours and area items as polygons, linear items as lines and point items as symbolic motifs, or as a raster image. These map widgets are created by the MapWidgetManager and added to appropriate layers when the maps are read in. The required colour for each item is applied using the colours selected in the palette in the associated AwsPalette object. The layer object forms a layer in AwsWidgetManager class, which in turn forms the set of layers describing the mapping display in the AwsLayerManager, which is held in the AwsPanel implementation class.


6 Feb 2009

Page 67 of 117

The following class diagram shows the relationships between the mapping classes and the MapWidgetManager class, which creates the layers and widgets to define how the map is drawn.

Figure 3-37 Map Management and Drawing Classes

3.4.7.1 Map Scale and Centre

All the features on the map are described in latitude and longitude coordinates, with height coordinates for contours and optional heights for features requiring height values. When read into the application, the map data is projected onto a Cartesian coordinate frame, with an arbitrary origin and scale. This coordinate frame is then transformed onto the required display window by processing the map data through a Converter object from the package gsdk.geometry. This class translates the centre, and transforms the scale of one Cartesian frame into another. The conversion between Cartesian frames is performed each time the map is drawn.

3.4.7.2 Map Grid Class

The map can be overlaid with a grid showing the selected coordinate frame of reference. It will take a colour from the given map colour palette, and can display the following types of reference grid:

• projection Cartesian grid;

• spherical latitude/longitude grid;

• concentric circles.

This grid may be shown as the projected Cartesian coordinate frame, using a set of lines spanning the x coordinate range and the y coordinate range of the given window with between two and twenty equally spaced lines of constant x, or constant y. The separation between each line is given in units starting from 1 metre and increasing logarithmically as the scale increases, 10m, 100m, 1km, 10km etc, always keeping between 2 and 20 lines parallel to each axis drawn on the window, regardless of scale.

A spherical grid is provided, which draws line of latitude and longitude at intervals of 1 degree. It uses the projection used to convert the map latitude and longitude values along each line of constant latitude and constant longitude to produce the curvilinear lines of the spherical grid.


6 Feb 2009

Page 68 of 117

A grid based on concentric circles can be drawn, centred on the centre of the window. The separation between each circle is given in units starting from 1 metre and increasing logarithmically as the scale increases, 10m, 100m, 1km, 10km etc, always keeping between 2 and 20 concentric circles drawn on the window, regardless of scale.

3.4.7.3 Map Filter

The map filter class is constructed from the classes of map item and the types of map item within each class, to provide display options for each item type stored in a given map. Each class of item has the ability to toggle the display of the related widgets, this is done by setting the visibility of the layer. The map item classes defined in the map filter are:

• Coastline

• Contours

• Area Features

• Linear Features

• Point Features

The feature types are identified by name, so linear features may be sub-typed into roads, railways, rivers etc. These names will form the key to select items of the desired type.

3.4.7.4 Map Format

The map data is read, before the scenario database is created, using the Map class. The map details are stored in a single file, which defines the bounding latitude/longitude of the area from the South West corner to the North East corner. It then defines a sequence of coastline and contour polygons, with vertices given in floating point latitude/longitude co-ordinates. All positions are quoted in degrees.

The syntax of the map file allows a wide range of two-dimensional objects to be defined, by providing a generic syntax for area, linear and point features. Each item in the map is classed as AREA, LINEAR or POINT feature. By default, the feature is an AREA. Each item can define a height above its local environment, which is either sea level (the default value) or the height of the contour the item is placed in. The items can also define an optional name field. The perimeter of the AREA and LINEAR features is defined by a list of (latitude, longitude) co-ordinates, terminated by an END keyword. The POINT features are positioned with a single (latitude, longitude) co-ordinate.

The file has the following format:

BOUNDS -7.75 49.75 2.0 61.0 COASTLINE 0.537056 51.517582 0.526694 51.516777 … END CONTOUR HEIGHT 76 -2.661771 52.332763 -2.661827 52.322707 … END RAILWAY LINEAR -2.6125 54.43211 -2.612417 54.431946 … END LAKE -5.627639 57.639027 -5.630944 57.637833 …


6 Feb 2009

Page 69 of 117

END POPULATION -1.331889 52.848251 -1.331306 52.845974 -1.336417 52.836945 … END

As the map data is read from the file, it is automatically converted from latitude/longitude co-ordinates to an appropriate projection to give Cartesian co-ordinates. By default, the toolkit uses a Lambert projection, but any projection algorithm satisfying the Projector interface, from the geometry package, can be used.

public interface Projector { public void toProjection( double Lat, double Long, Vector2D XYpoint ); public void toLatLong( double x, double y, Vector2D LLpoint ); } // End interface Projector

3.4.7.5 Map File Storage

Although GSDK map data is defined using a generic text format, the files in which the mapping data is stored may be compressed in order to save disk space and loading time, particularly across a network or over the internet.

The GSDK supports three map file storage formats:

a) plain text file;

b) compressed file using the GNU GZIP format;

c) compressed file using the standard ZIP format.

The GSDK differentiates between the format of the stored data by checking the file extension name. If the extension is .zip then the file is opened as a ZIP compressed file, and each entry in the ZIP archive will be opened and extracted as a plain text file. If the extension ends with a z then the file is opened as a GZIP compressed file, and extracted as a plain text file. All other files are treated as plain text. Note that there is no Java capability to open a ZIP file from within an Applet, as the Java ZIP protocol requires file access, which is forbidden under Java security rules.

.

3.4.8 Transparent Overlays

One of the key features provided by the GSDK AWS is the ability to produce transparency effects. The transparent objects are normally managed by a widget manager object between the map manager and widget manager although they are not restricted only to that position. The following paragraphs describe the process of creating transparent colours, and how new transparent objects are created and managed.

3.4.8.1 Creating a Transparent Colour Palette

To display the overlay features in a transparent colour, the colour must be defined in the resource list PHYSICAL_COLOURS.

PHYSICAL_COLOURS( ( Black, 0, 0, 0 ), ( Concerned, 128, 0, 0 ),


6 Feb 2009

Page 70 of 117

( tATCColour, 120, 120, 110, 90 ), ( tAirlaneColour, 175, 175, 175, 90 ) )

Standard opaque colours can be defined using RGB values, transparent colours must include an additional Alpha value which defines the level of transparency in the colour. An alpha value of 0 will result in a completely transparent colour where as a value of 255 will result in a colour that is completely opaque.

The defined physical colour must then be mapped to a logical colour.

LOGICAL_COLOURS( ( SIL_HEADER_TEXT, Black ), ( AC_LABEL_CONCERNED, Concerned ), ( T2, tATCColour ), ( T5, tAirlaneColour ) )

To use a palette colour, the colour needed to draw a particular map base or transparent object can be extracted using the colour name tag to search for the required colour in that palette by invoking the AwsPalette class method, getColour.

The map feature colours are automatically allocated by defining the list resource PALETTE.MAPFEATURES. This defines a set of relationships between the map feature class and feature type, and associates this with the required pallete base colour, referenced by the base colour name. An example is given in the following fragment from a GSDK resource file.

PALETTE.MAPFEATURES ( ( COASTLINE COASTLINE B2 ) ( TERRAIN CONTOUR_76 B4 ) ( TERRAIN CONTOUR_152 B5 ) ( TERRAIN CONTOUR_305 B6 ) ( TERRAIN CONTOUR_457 B7 ) ( TERRAIN CONTOUR_610 B8 ) ( TERRAIN CONTOUR_914 B9 ) ( TERRAIN CONTOUR_1219 B10 ) ( POINT MAST B15 ) ( POINT BRIDGE B15 ) ( LINEAR RAILWAY B11 ) ( LINEAR RIVER B12 ) ( LINEAR ROAD B13 ) ( LINEAR BOUNDARY B15 ) ( LINEAR GRID B16 ) ( AREA LAKE B12 ) ( AREA POPULATION B14 ) )

3.4.8.2 Creating and Managing Transparent Objects

Having set up the required colour palette for the background map and the transparent overlays, the programmer can now create the managed transparency objects.

The AwsAreaDisplay and AwsNetworkDisplay are widgets specifically designed for displaying transparent areas. The AwsAreaDisplay can be provided with an arbitrary number of polygons, this will merge any overlapping polygons into a single area of solid colour. The AwsNetworkDisplay takes an arbitrary number of lines defined as Point2D arrays these lines are merged into a single path to provide a single area of colour.

To allow for improved performance when transparency is not necessary the AwsAreaDisplay has methods allowing the fill area and an outline to be switched on or off. This allows for an outline to be drawn in a standard opaque colour and the transparent fill to be turned allowing


6 Feb 2009

Page 71 of 117

for much faster drawing. The AwsNetworkDisplay also allows for the network and a centre line to be switched on or off. This allows a single opaque network line to be drawn rather than the transparent network.

While these widgets have been created specifically for use when drawing transparent overlays any widget can be drawn with a transparent colour and be added either to an overlay widget manager or a map or top level widget manager.

3.4.9 Underlying Swing/AWT Toolkits

3.5 MIDDLEWARE FRAMEWORK

3.5.1 Overview

The eDEP platform is delivered with a light-weight middleware infrastructure, based on RMI, enabling application components to be distributed across different Virtual Machines (VM).

The following chapter shall describe this infrastructure, and is divided down into the following sections,

• RMI Overview this section outlines the major characteristics of RMI and their impact upon the overall eDEP software architecture

• Package overview

• General Component Pattern A general overview of the design patterns employed within distributed components

• GSDK Middleware Threading Pattern A general overview of the threading patterns applied within the middleware

• Event Distribution

• Remote Calls to Components

• Discovery

3.5.2 RMI Overview

3.5.2.1 Introduction

RMI is the Sun defined standard for Java Remote Method Invocation. This section shall provide an overview of key RMI characteristics which have an important design impact upon the eDEP software architecture. This should provide important insights into why the eDEP team have developed the gsdk.middleware package.

This section assumes the reader is familiar with RMI programming and distributed computing concepts. The reader is invited to consult the following tutorials for more information,

• Standard Sun Tutorial http://java.sun.com/docs/books/tutorial/rmi/index.html

• Standard SDK RMI feature guide http://java.sun.com/j2se/1.3/docs/guide/rmi/index.html


6 Feb 2009

Page 72 of 117

RMI is similar to most RPC1 technologies such as CORBA. In other words the basic behaviour is as follows,

• The client calls what appears to be a normal interface operation (lets say String reply = MyInterface.operation1 (“Hi there”);)

• In fact what happens is the following,

• The operation parameters are marshalled (e.g. serialised) and a network call made to the server VM process

• The server processes the calls the relevant MyInterface object. This then returns a result

• This result is marshalled and sent back to the client

• The client demarshalls the result and unblocks the client thread.

3.5.2.2 Dynamic Behaviour

In fact, examining RMI dynamics in detail, we note the following characteristics,

• RMI clients will always block until the distant call reaches the server, is

processed by the application layer (i.e. the object implementing the remote

interface) and the result returned.

• RMI servers, if ‘busy’, upon receiving a new incoming message, will create a new

thread to dispatch the call to the application layer (i.e. the object implementing

the remote interface)

These points have an important effect upon an application’s performance, dynamics and threading model.

Concerning the server-side ‘callee’ issue, an application object implementing a remote interface may be called within the context of several threads, and potentially in parallel. Hence, remote objects must be aware of these threading issues, and take steps to ensure they are thread-safe.

Concerning the client-side ‘caller’ point, its implications are mainly throughput related. This become evident when discussing events. Most event listeners are of the form

interface EventListener extends Remote { void notify (EventObject o) throws RemoteException; }

Such interfaces have operations with only ‘in’ parameters and no return values. Unlike

CORBA which offers oneway semantics for such operations, RMI will block the calling

RMI client until the message reaches the server, and the application code implementing ‘notify’ is executed.

In event-based applications where event reception tends to lead to .. event production, this sort of behaviour can be disastrous.

For example, imagine a component A which pushes an event to B. B within its ‘notify’ implementation performs some processing, which includes calling the component C and then pushing of an event to D. In this catastrophic design example, the original call from A will

block until all of this code in B,C and D executes.

Hence, the gsdk middleware to be presented in the following sections, has been designed to handle these RMI imposed issues

1 Remote Procedure Call


6 Feb 2009

Page 73 of 117

• Ensuring server-side (callee) code is always executed within the context of a single thread

• Ensuring client-side RMI calls may be non-blocking.

• Ensuring event-distribution is efficient (and as non-blocking as possible)

3.5.2.3 Performance Related Issues

RMI has equally a number of performance related issues which require consideration

• RMI is expensive - the major cost being object serialisation

• RMI offers no optimisation for 2 communicating remote objects that are actually in

the same VM

The Object Serialisation overhead within RMI has been well-documented (see IBM Developer works). This becomes especially true when we consider event-based systems. In such systems, a server generated event is normally pushed to several remote clients. With RMI each push to each client would cause serialisation to occur.

RMI, unlike CORBA, offers no optimisation for 2 communicating remote objects that are actually within the same VM (the term used is collocation). That is, two such collocated objects when communicating will still make use of RMI (stubs, skeletons and object serialisation).

The gsdk middleware provides a number of optimisations to overcome these issues.

3.5.3 Package Overview

The gsdk middleware is divided down into the following packages

• Gsdk.middleware.client classes specific to client-side issues (i.e. making distant calls to remote objects)

• Gsdk.middleware.server classes specific to server-side issues (i.e. processing incoming calls to objects)

• Gsdk.middleware.event classes specific to the issues of distributed event dispatching

• Gsdk.middleware.util

• Gsdk.middleware.discovery classes specific to the eDEP discovery mechanism

• Gsdk.middleware.discovery.client

• Gsdk.middleware.discovery.server

There remain a number of other gsdk.middleware packages which are currently not used.

The gsdk.middleware packages have close ties with the following other packages

• Gsdk.events

• Gsdk.util.threads

3.5.4 General Component Pattern

The use of the eDEP middleware imposes a certain pattern upon the application developer’s code, at both the client and server side. This section outlines the middleware issues concerning this standard component pattern.

The basic pattern is outlined in the following diagram.


6 Feb 2009

Page 74 of 117

Component

C

Component

A

Component

B

Private remote

communications

A VM1

VM2

VM3

B

Components are distributed across various Java Virtual Machines, and consist of two distinct parts –

• The back-end component which contains the vast majority of the component’s functionality (called the Controller)

• A front-end part which resides within the client VM (called the client service)

The role of the front-end part is to provide a convenient, easy to use interface to the client, which hides completely the distribution issues. The client component can only communicate with a distant component via the client-side interface.

Hence, the distributed communication between the front-end and back-end parts is completely private.

The component design pattern described in sections 2.1.3.1 and 2.1.3.2 provides a broader view of this pattern, concentrating upon the application issues.

The following UML class diagram summarises the overall component pattern:

ComponentServiceImpl

(from client)

discovery

(from middleware)

ComponentController

(from server)

ComponentControllerImpl

(from server)

FMControllerImpl

(from server)

FMController

(from server)

publishes Controllerlooks up Controller

FlightService

FlightServiceImpl

(from client)CWPcontroller

(from serv...

invokes operations

registers for events

register for events

invoke operations

FlightManager

server side code

FlightManager

client side code

Real Client code

push events push events

ComponentService

(from client)

An eDEP distribution-enabled component, in this case FM, is represented by two distinct interfaces – one present on the server and one present in the. Considering the example of the Flight Management component we have,


6 Feb 2009

Page 75 of 117

• Atc.fm.server.FMController The server-side RMI remote interface offering the Flight Management service

• Atc.fm.client.FlightService The client-side interface providing access to the distant FMController

The discovery mechanism (see section 3.5.8) is used to connect the client-side interface to the server-side interface.

The real client itself (in this case the CWP) has its own code, which interacts with the client-side FM interface, FlightService.

The various actors include

• Real Client Code (CWP) The client code interacts with the FlightService. Typically, the client will invoke operations and register for events. When registering for events the client passes the reference to the EventListener implementation which should receive these events at some later point.

• Client Side Component interface (FlightService) The client-side interface FlightService provides a convenient abstraction, hiding the distant RMI interface from the developer. Equally, a number of difficult distribution related issues are hidden behind this client-side interface within the implementation FlightServiceImpl (see section 3.5.7). The client side equally contains EventListener implementations (e.g. TrajectoryReceiver) which subscribe to the remote server events. These distant events upon reception are processed, transformed and then passed on to the real client application.

• Server Side Component interface (FMController) The server-side interface FMController provides the remote flight management functionality. This interface inherits from ComponentController, which defines the common supervision interface (and corresponding state machine).This FMController interface is implemented by the class FMControllerImpl which in turn inherits from ComponentControllerImpl which provides server-side functionality present to all components.

3.5.5 GSDK Middleware threading model

An important part of the gsdk middleware is concerned with solving the threading problems resulting from the use of RMI. The basic issue is that RMI allows incoming calls to remote objects to execute on multiple threads in parallel. Hence, the problem of thread-safe code is the responsibility of the application developer.

Writing complex applications that accept parallel threads of execution is far from trivial. The testing and debugging tasks are extremely complex. Hence, the gsdk middleware solves the problem for the developer by introducing patterns which allow these multi-threaded incoming RMI calls to be diverted onto a single thread.

This pattern is used in various forms for the different types of communication present in the GSDK (event-driven, synchronous RPC, asynchronous RPC). Hence, it shall be briefly described within this section.

The basic pattern is simple –

• All components have their own internal thread

• This thread should be the only thread allowed to access a component’s internals


6 Feb 2009

Page 76 of 117

• This thread equally controls the component’s EventScheduler

• incoming RMI requests, running within some unknown thread, are diverted onto the component’s thread

• this is done by scheduling an event to the component’s EventScheduler

• this event will be fired at some later point in time, within the context of the component’s thread

• this event will cause code to be run which implements the logic of the RMI request

The following diagram illustrates the principle,

Remote

Controller

Event

Scheduler

Eventnew

schedule

process

Component

Internals

Access, updates

Possiblesynchronisation

The red coloured blocks and the dotted interaction lines illustrate processing that is occurring in some foreign thread. This processing is considered to be potentially ‘dangerous’ – hence it is limited to

• Initial processing that does not address the component internals

• Creation of an event

• Scheduling of the event (note : the EventScheduler is thread-safe!)

At some later point in time, this event shall be scheduled for execution. This execution will occur within the context of the component’s own thread (blue coloured blocks and solid lines). The related event processing is free to address the component internals.

In some cases, once the processing has terminated, the RMI object may be informed, so that post-processing results can be returned to the distant caller.

This call-redirection is handled by the following classes,

• Gsdk.middleware.server.ProcessingRequest This class provides the initial abstraction of a processing request (i.e. status of request)

• Gsdk.middleware.server.ComponentControllerProxy Builds upon ProceessingRequest to include the Object and Method to invoke. This class relies heavily on Dynamic Proxies, a powerful java abstraction which relies heavily upon reflection.


6 Feb 2009

Page 77 of 117

3.5.6 Event Distribution

3.5.6.1 Overview

The gsdk middleware event subsystem is concerned with the issues of efficient and scalable distributed event distribution. That is, the implementation is designed to handle situations of high fan-out (a large number of subscribers for a single event).

The majority of the event functionality is provided by the gsdk.middleware.events package, which builds upon the foundations of gsdk.events.

3.5.6.2 Component-Centric Class Overview

The following UML diagram defines the event subsystem, where the classes are divided into 3 broad groups –

• Server-side gsdk event code (yellow classes) Classes concerned with the issues of event subscription management and event dispatching

• Client-side gsdk event code (bright yellow classes) Interfaces / classes concerned with the issues of remote event reception and processing

• Component code (orange classes) Specific component provided code that (a) decides when events are actually generated (b) decides what action to take when events are received

Component Controller(from server)

Component Contro llerI mpl(from server)

RemoteSubscriptionManager(from even...

-subscribers

ThreadPool

numThreads : int

(from threads)-threadPool

FM ControllerI mpl(from serv...

DelegateRemoteListener(from events)

RemoteLis tenerAdapter(from events)

RemoteSubscription(from RemoteSubscriptionManager)

EventListener(from events)

Subscription

Subscription()notify()

(from SubscriptionManager)

+action

SubscriptionManager(from events)

0..n0..n

Runnable(from lang)

FMController(from server)

GroundTrajectoryReceiver

notify()

(from FlightServiceIm...

f orwar ds-calls

FlightServiceImpl

GroundTrajReceiver : GroundTrajector yReceiverAircraftTrajReceiver : Airc raft Trajector yReceiver

(from clie...FlightManagement

AircraftTrajectoryReceiver

AircraftTrajectoryReceiver()internalNotify()

(from FlightServiceIm...

3.5.6.2.1 FM Controller / FM Controller Implementation

The component provided interface and implementation that actually performs the business logic and event generation.


6 Feb 2009

Page 78 of 117

3.5.6.2.2 Component Controller Implementation

The ComponentControllerImpl class implements functionality common to all server-side components. This class manages the RemoteSubscriptionManager.

3.5.6.2.3 RemoteSubscriptionManager / RemoteSubscription

This RemoteSubscriptionManager class implements the core logic for efficient and scalable event distribution. It builds upon the SubscriptionManager class found in gsdk.events.

The class manages RemoteSubscritpion objects (an inner class) which represent each remote EventListener subscription.

The class makes use of ThreadPool, a thread worker pool utility class, which provides much of the required logic for multi-threaded event distribution.

3.5.6.2.4 EventListener

The gsdk.events interface that defines the platform standard interface for event reception.

3.5.6.2.5 DelegateRemoteListener / RemoteListenerAdapter

These two GSDK provided classes perform exactly the same role – perform initial client-side processing upon receiving remote events, hiding a number of distribution-related issues from the component developer.

The two classes differ in one respect – how they are used by the application developer. The DelegateRemoteListener is used via aggregation, whilst the RemoteListenerAdapter must be extended by the developer.

3.5.6.2.6 Trajectory Receiver / AircraftTrajectoryReceiver

The FlightService created event listener implementations, that provide the real event reception logic. These classes contain the real logic of what the client-side FlightService intends to do with the server generated events.

Very often, these classes perform a small amount of processing, and then raise client-side events (see below).

3.5.6.3 Event-Centric Class Overview

The following diagram illustrates the event class structure,


6 Feb 2009

Page 79 of 117

EventListener (from events)

ForwardEvent (from events)

ExternalEvent (from events)

EventObject (from events)

-event

MarshalledEvent (from events)

-originalEvent

TrajectoryMessage (from server)

TrajectoryEvent (from client)

TrajectoryReceiver (from FlightServiceImpl)

receives instanciates

FMController (from server)

FlightService (from client)

FlightServiceImpl (from clie...

FMControllerImpl (from server)

instanciates

RemoteSubscriptionManager (from events)

3.5.6.3.1 MarshalledEvent

A gsdk middleware class which provides a serialisation optimisation. The MarshalledEvent encodes within itself the real event in a pre-serialized form. This MarshalledEvent can then be passed to many clients with a very low serialiazation overhead.

This class is used by RemoteSubscriptionManager.

3.5.6.3.2 ForwardEvent

A gsdk.events class which provides an event forwarding capability. That is, an event can be re-scheduled to be sent to a specific EventListener

3.5.6.3.3 External Event

Conceptually, it is supposed to provide a common super-class to all remote server-generated events.

3.5.6.3.4 Server Side Message: Trajectory Message

All remote (server-side) generated events are termed ‘Messages’.

Very often these messages contain simple data structures (e.g. Strings).

3.5.6.3.5 Client-side Event: Trajectory Event

At the client-side, the remote server messages are received, processed and then local events are generated. These events are intended for the client’s consumption, and tend to be rich (e.g. reference Entities)

3.5.6.4 Event Subscription

Is it really worth detailing this, or is it obvious?


6 Feb 2009

Page 80 of 117

3.5.6.5 Event Publication

The RemoteSubscriptionManager handles the server-side event publication. The following sequence diagram illustrates the nominal case, whereby a single server event is dispatched to two subscribing EventListeners.

: RemoteSubscriptionManager

: RemoteSubscription : EventListener


: FMControllerImpl

notify(EventObject)

notify(EventObject)

notify(EventObject)

dispatchEvent(EventObject)

notify(EventObject)


notify(EventObject)

As the sequence diagram illustrates, the time taken to publish a server event is linear with respect to the number of subscriptions. This will become a performance bottleneck as the number of subscriptions grow. Hence, the RemoteSubscriptionManager class implements a number of important optimisations,

• Marshalling Optimisation

• Multi-threaded event dispatching

3.5.6.5.1 Marshalling Optimisations

As previous mentioned ‘N’ subscriptions for an event ‘E’ will lead to ‘N’ calls to EventListener.notify (E), which in turn will cause ’E’ to be re-serialised ‘N’ times.

For large events and large values of N, this will consume important amounts of CPU time.

Therefore, the gsdk middleware includes the class gsdk.middleware.events.MarshalledEvent. This class allows an event ‘E’ to be marshalled before it is transmitted. Hence, ‘N’ subscriptions will only require 1 serialisation.

This MarshalledEvent class is not used directly by the developer. Rather the RemoteSubscriptionManager makes use of it.

This marshalling optimisation is controlled via the resource

GSDK.MIDDLEWARE.OPTIMISE_EVENT_MARSHALLING [TRUE|FALSE]

3.5.6.5.2 Multi-threaded Event Dispatching

The RemoteSubscriptionManager contains an important optimisation which allows an event E to be dispatched to N subscribers in parallel

2, via the use of a thread pool. The following sequence diagram illustrates the principle

2 it remains to be seen how much parallelism is achieved – given that ultimately each thread must compete for the same network card resource


6 Feb 2009

Page 81 of 117

: FMControllerImpl

: RemoteSubscriptionManager


: RemoteSubscription

: ThreadPool : EventListener

notify(EventObject )notify(EventObject) performTask(Runnable)

run( )


notify(EventObject)

notify(EventObject) performTask(Runnable)

run( )


notify(EventObject)

The call to RemoteSubscriptionManager.notify returns as soon as the ThreadPool is informed of the work to perform. The actual dispatching of the events is then done later on a separate set of threads.

Note : the parallelism only applies to the dispatching of a single event to ‘n’ clients. If the FMController has a second event requiring dispatching, then the RemoteSubscriptionManager must wait until the first event is fully dispatched. This is to ensure that partial ordering semantics are maintained3.

The multi-threading is controlled via the following resources

GSDK.MIDDLEWARE.MULTITHREAD_EVENT_DISPATCHING [TRUE | FALSE] GSDK.MIDDLEWARE.EVENT_DISPATCHING_THREADPOOL_SIZE [integer]

3.5.6.6 Event Reception

The client-side remote event reception is handled by either the class DelegateRemoteListener or RemoteListenerAdapter. Both classes offer similar functionality, except they are used in different ways by the developer,

• RemoteListenerAdapter is an abstract class requiring that the developer extend and implement the method internalNotify

• DelegateRemoteListener uses an aggregation pattern – the developer must implement the EventListener inteface and provide it as a parameter to the DelegateRemoteListener.

Both classes solve the following problems for component developers,

• Reception of MarsalledEvents (RemoteSubscriptionManager optimisation) such events are automatically demarshalled and passed on to the developer code.

• Threading issues incoming calls to the EventListener may occur on an arbitrary RMI-created thread. These classes immediately re-post the event on the internal EventScheduler, ensuring that all events shall be processed within the same thread (i.e. the component’s own thread)

Note : the event re-posting functionality is provided by the utility class gsdk.events.ForwardEvent

The following diagram illustrates the process with DelegateRemoteListener

3 events E1, E2 dispatched in this order from a single server, should arrive at a particular client in the order E1,E2


6 Feb 2009

Page 82 of 117

: FMControllerImpl GTM :GroundTrajectoryMessage

:RemoteSubscript...

ME :MarshalledEvent

: DelegateRemoteListener FE : ForwardEvent : EventScheduler

GTR :GroundTrajectoryReceiver

GTE :GroundTrajectoryEvent

: Flight

new

notify(GTM) MarshalledEvent(GTM)

notify(ME)

decodeEvent( )ForwardEvent(GTM, GTR)

scheduleNow(FE)

process( )

notify(GTM)

new

scheduleNow(GTE)

Server Side Processing client side processing

processEvents( )

SetTrajectory(Trajectory, String)

The following points should be noted –

• Stage 1 – FM server-side event dispatching In this example the RemoteSubscriptionManager performs marshalling optimisations. Hence, the original event GTM, is placed within a MarshalledEvent

• Stage 2 – initial FM client-side event reception (shown in red) The DelegateEventListener receives the incoming MarshalledEvent, within the context of some unknown ‘foreign’ thread. The listener will unpack the marshalled event, and schedule it for later processing (using ForwardEvent)

• Stage 3 – FM client-side event processing (shown in blue) The EventScheduler, within the correct component thread, shall schedule the ForwardEvent, which in turn calls the GroundTrajectoryReceiver listener. This class may now interact with local Flight entities and raise any necessary intra-component events.

• Stage 4 – real client processing (not shown on diagram) The final client application (e.g. CWP) may now process the locally created GroundTrajectoryEvent.

3.5.7 Remote calls to components

3.5.7.1 Overview

Remote calls to a component’s Controller interface introduce a number of issues at both the client (caller) and server (callee) ends.

For the client, making a distant RMI call causes the client thread to be suspended until a result is returned. This presents a problem to graphically oriented client applications, where such thread suspending may cause the HMI to freeze.

The GSDK middleware incorporates the concept of asynchronous call to solve this issue.


6 Feb 2009

Page 83 of 117

For the server, the problem is the usual one – multiple RMI threads addressing the remote object in parallel). The GSDK middleware incorporates the concept of ProcessingRequest to solve this problem.

3.5.7.2 Class Diagram

The following UML class diagram outlines the major classes,

EventObject

(from events)

RemoteCallResult

getOriginalCall()getRaisedException()getReturnedValue()

(from client)

ThreadPool

numThreads : int

(from threa...

ComponentServiceImpl

getName()dispatchCall()

(from client)

-asynchCallDispatcher

EventListener

(from even...

AsynchronousRemoteCall

(from client)

makeRemoteCall()run()

-remoteCall

-listener

executes

FlightServiceImpl

(from client)

GetInitialTrajectory(Callsign : String) : TrajectoryGetInitialTrajectory(Callsign : String, el : EventListener) : void

GetInitialTrajectoryCall

makeRemoteCall()

(from FlightServiceImpl)

ComponentService

3.5.7.2.1 ComponentService

This ComponentService inteface and its implementing class ComponentServiceImpl contains common functionality present to all client side services. This includes the ability to dispatch asynchronous calls (through the use of the associated ThreadPool).

3.5.7.2.2 FlightService / FlightServiceImpl

The concrete client-side classes representing the FM. It should be noted that there exist two versions for each flight service operation – a synchronous and asynchronous one.

Typically the asynchronous one is ideal to the synchronous one except for,

• An extra EventListener parameter The listener to be asynchronously informed when the distant call is complete

• No return parameters since the call is asynchronous, having return parameters has no sense.

3.5.7.2.3 AsynchronousRemoteCall

The AsynchronousRemoteCall abstract class contains the essential functionality for making distant RMI calls.

The developer must supply an EventListener which is asynchronously informed when the remote call has finished. The EventListener is passed an event of type RemoteCallResult.

3.5.7.2.4 SetDirectToCall / GetInitialTrajectoryCall

The concrete classes which extend AysnchronousRemoteCall, implementing the method makeRemoteCall. These implementations add the real application logic (i.e. defining what operation is called on the remote interface).


6 Feb 2009

Page 84 of 117

The makeRemoteCall method is called from a threadpool thread. Hence, the implementation of this method should not access local data which is not thread-safe.

3.5.7.3 Client side calling

The following sequence diagram illustrates an asynchronous remote call in progress, with the red portions indicating those calls being executed outside the component’s own thread.

: EventListener :

CWPcontroller :

FlightServiceImpl : ThreadPool GITC :

GetInitialTrajectoryCallRCR :

RemoteCallResult : FMController :

EventSchedul er

GetInitialTrajectory(String, EventListener) new

dispatchCall(GITC)

performTask(GITC)

run( )

makeRemoteCall( )

GetGroundTrajectory(String)

new

scheduleNow(GITC)

processEvents( )

notify(GITC)

3.5.7.4 Server side processing

The following diagram illustrates a server-side use of ProcessingRequest.


6 Feb 2009

Page 85 of 117

:

Flight Serv iceImpl

:

FMControllerImpl

GGTPR :

GetGrdTrajProcessingRequest :

Ev entScheduler

: Flight

GetGroundTrajectory (String) new

scheduleN ow(GGTPR )

process( )

GetGroundTrajectory ( )

perf ormProcessing( )

getResult( )

processEvents( )

3.5.8 Discovery

3.5.8.1 Overview

The eDEP platform is supplied with a simple discovery mechanism, which allows components (or rather Component Descriptions) to be published and looked-up. The following UML diagram defines the discovery mechanism


6 Feb 2009

Page 86 of 117

ComponentDescriptionList

(from d iscovery)

DiscoveryServer

ma in ()

(from server)

ComponentDescription

(from d iscovery)

0..n0..n

DiscoveryImpl

(from server)

Remote

(from rmi)

Discovery

(from server)

DiscoveryService

(from client)

-$discoveryServer

Registry

(from registry)

instanciateslooks-up DiscoveryServer

The discovery mechanism, like any component, consists of two parts,

• Server-side component (DiscoveryServer) containing the actual remote service gsdk.middleware.discovery.server.Discovery and its implementation

• Client-side interface (DiscoveryService) convenience class for accessing the distant service

The following sequence diagram illustrates the service in action

3.5.8.2 Discovery Server

The discovery mechanism offers a number of interesting functions,


6 Feb 2009

Page 87 of 117

• Qualified component registration published components are described by a ComponentDescription which may include an arbitrary property list.

• Timed lookup mechanism lookup calls may include a timeout parameter. This allows clients to wait an ‘acceptable’ amount of time, before deciding that a component is not present. This solves the classic system start-up problem of component inter-dependencies (i.e. component A must be started before component B)

• Filtered lookup mechanism The lookup operations accept a DiscoveryFilter parameter. This allows for client-side filtering code to be transported to the discovery server. This filtering code usually acts upon the property list present in the ComponentDescription.

• Event driven lookup mechanism NOT IMPLEMENTED

3.5.8.3 Client Side : DiscoveryService

The client-side class DiscoveryService provides a convenient access to the remote discovery server. Moreover, this class offers an important (yet slightly dangerous) optimisation feature – collocation.

The DiscoveryService provides such an optimisation, using a simple technique – local client-side caching. Within a single VM, the DiscoveryService maintains a hashtable of all components published through it. Hence, if a lookup is performed, within the same VM, for a collocated component, the DiscoveryService returns the value stored within the local hashtable.

Such a behaviour has an important side-effect : no RMI stubs are actually generated. Hence calls between the 2 collocated objects are reduced to simple procedure calls – no object serialisation occurs.

This has another important side-effect applications are packaged up with the JavaWebStart technology. Such applications are invariably run within a single VM, and hence this collocation optimisation allows them to run without the need for privildged security policies (i.e. the application can run within the classical sandbox).

This feature may be controlled via the resource

GSDK.MIDDLEWARE.OPTIMISE_COLLOCATION [TRUE|FALSE]

3.5.8.4 Bootstrap problem

There exists an initial bootstrap problem – how does the client-side DiscoveryService locate the distant DiscoveryServer?

In order to solve this problem, the Discovery Server instanciates an RMI registry and publishes itself within.

The client-side class DiscoveryService at start-up shall bind to the Registry in order to locate the Discovery server.

Note : due to the inadequacies of the RMI Registry, the client must know the host-name running the registry. This needs to be specified in the resources file

GSDK.DISCOVERY_HOST <hostname>

If this parameter is not specified then the default value is <localhost>.


6 Feb 2009

Page 88 of 117

3.5.9 Subscription Monitor

The SubscriptionMonitor class is a utility class that allows component application developers to keep track of subscriptions made from the client to a particular message type, identified by event name, to ensure that only one subscription is made and only one message is delivered to the client. Generally, the client will only ever make one subscription to the server, but in more complicated cases, the client may make several subscriptions for the same message.

As each subscription is made the client adds a reference to that subscription to the subscription monitor. Before the subscription is made, the monitor will test whether the subscription is already accounted for and not re-subscribed. Any subscriptions using the message filter mechanism will provide an additional filter key string to the subscription monitor. The key is set to UNIVERSAL by default to ensure delivery of all messages, unfiltered.

3.6 THE COMPONENT DESIGN PATTERN

This section discusses how the features described in the sections above can be put together to form the overall architecture that implements a complete system based on the described GSDK design patterns. The section will discuss the key structural elements of a generalised GSDK application component. It will cover the following areas of the design:

• component package structure;

• overall structure;

• client/server patterns;

• inter-component dynamics.

3.6.1 Component Package Structure

The Java source code for eDEP is arranged into a standard package arrangement, with the major packages identifying the GSDK library packages, the derived ATC library packages, specialist packages for concept specific options, a test package and an application specific package. The directory structure looks as follows:

Directory Java Package Description

<home>/src/atc atc The ATC library package. This defines ATC specific classes and the definitions of the components themselves.

<home>/src/atcapp atcapp The ATC application package. This defines any application specific classes, and will include the main program class. It also holds the scenario text files for Resources, scenario files, and application specific images.

<home>/src/eatmp eatmp EATMP specific package containing classes specific to the EATMP CWP.

<home>/src/graffica n/a Additional binary files supporting the GSDK. Provides logos and icon images.

<home>/src/gsdk gsdk The GSDK library package.

<home>/src/test test Any software developed to support the testing of GSDK items and the ATC components.


6 Feb 2009

Page 89 of 117

The atc package structure is broken down into separate packages for individual components, and these in turn define packages for the client side and the server side classes, the entities and the supporting classes defined by the component, and an optional graphics package. The component class is defined in the component package itself. The following table shows the package structure for the FM component. It does not define any graphical elements, so it has no atc.fm.graphics package.

Directory Java

Package

Description

<home>/src/atc/fm atc.fm The FM package, containing the client, server and entity sub-packages and the FM component class.

<home>/src/atc/fm/client atc.fm.client Client-side package defining the FM service interface and the service implementation. This presents an object model defining functional interface of the FM component to the client. Also provides events raised on the client-side, to notify the client of incoming messages from the FM.

<home>/src/atc/fm/entity atc.fm.entity The entity package defining the FM entity objects. These are implementations of interfaces derived from the Entity interface provided in the package gsdk.entity. The entities define the object model that represents the corresponding real-world objects. They define both data and behaviour, and each entity object defines a unique identity, but although presenting a common interface, or type, they may be implemented in different forms on each component that hosts entities of a given type.

<home>/src/atc/fm/server atc.fm.server Server-side package defining the FM Controller interface and controller implementation. This defines the server functionality, accessed through the client-side service object, which will invoke methods through the serialized controller interface and GSDK middleware layer. The controller implementation defines the core functionality of a component.

3.6.2 Component Structure

Having identified the major packages that make up a particular component, this section describes how these elements combine to define the component behaviour. The following class diagram shows the major classes involved in the structure of the Flight Manager, FM, component.


6 Feb 2009

Page 90 of 117

Figure 3-38 Flight Manager Example Component Class Diagram

3.6.2.1 Initialisation

Components move through a multi-stage initialisation process, before being started. This initialisation process constructs the component application, comprising registration with the system middleware, and creation of the scenario database, the component controller (FMController) and any graphical elements. The FMController then receives an initialise signal, at which point it can set up the access to other component services it requires. These services will create the required subscriptions to the remote component servers, and generate the local FM events to signal the arrival of information from these servers. Once the services have been created, the FMController receives a signal to start the FM component running, which includes starting the database and loading the airspace details prior to entering the main processing loop.

Figure 3-39 Flight Manager Initialisation Sequence


6 Feb 2009

Page 91 of 117

3.6.2.2 Processing Loop

Once started the component will enter an infinite loop, waiting for internally scheduled events, or asynchronous messages from external components.

3.6.3 Client Server Design Patterns

3.6.3.1 Client Service Object Model

3.6.3.2 Server Message Based Interface

3.6.3.3 Messages And Events

3.6.4 Component Dynamics

3.6.5 Example Sector Inbound List Subscribing To PEL Changes

The interaction diagram shown in figure 2.3 shows the interactions which define the processing involved in registering interest in all PEL updates for the sector inbound list, which might display a list of aircraft details, including the planned entry level, PEL. The subscribing object (the inbound list) registers interest in all PEL Changes, by invoking the generic EntityManager method notifyEntityChange with a listener object and a string containing the value “PEL”. When a new PEL value is signalled through the ‘setPEL’ method in the entity, first the entity subscription manager will be invoked to distribute the event to any registered objects, and then the event manager’s subscription manager is invoked to distribute the event. In this case it will find the inbound list listener has been registered, and its notify method will be called.

Note that in this instance, the PEL display widget could have registered interest in the PEL change for the given aircraft itself rather than registering for all aircraft, but the example shows how the mechanism is used to deliver all such events.

Figure 2.3 – Registering Interest in and Notification of a PEL Change

The subscription manager class will provide a method to parse the topic, separating each branch of the tree by locating the ‘/’ delimiters in the topic string, and extracting the next field name. The registerFor method will be modified to parse the topic string to create and

define the required node branches defining the full subscription path. The ‘notify‘ method

will also be modified to match topic names recursively as the tree is descended. This can be achieved by adding a notify method to the internal class defining the tree nodes, this will recursively call itself on the nodes returned in the branches hash table:


6 Feb 2009

Page 92 of 117

3.6.6 Modifications To The Event Object

The event object will now define a source identifier (a simple name in a Java string object), and a set of targets, defined by the topic identifier (also defined by a String object). The topic name defines a set of notifiable objects each implementing the event listener interface, and stored in the subscription manager, referenced from the event scheduler object. The topic name is added to the event either through a constructor or through the setTopic method.

The default constructor will create a group for a single identified target. Alternatively, adding targets into the growing target group object can create the required set. The array could be implemented as a Vector with an initial capacity of 1 item (as most targeted events are likely to have only one target). Events that do not define a topic will set the topic reference to null.

3.6.7 Provision Of A Re-post Event Method

Events received from an external source, and delivered to service providing classes will need to reschedule the event on the local event queue, to de-couple the event processing between the competing threads. A method is provided in the event scheduler to re-post an event on the immediate event queue. It is passed the remote event, and a the topic key, which identifies this event is being for notification only to those aware of the topic key, allowing the re-posted event to be directed to the selected subscriber(s) as a private event.

The diagram in figure 2.4 shows the interactions required to re-post an event delivered from a server object to a client object, using the private topic notification mechanism. The client object registers interest in the remotely supplied event, creating a unique notification topic key, making the event notification private to this object. The event can then be re-scheduled on the immediate event queue, and notified in the conventional way.

Figure 2.4 – Re-posting an Event from a Server Using a Private Subscription Topic

3.7 TIME MANAGEMENT

3.7.1 Overview

Time is managed locally in each component in the TimeManager object. This object is managed within the component’s entity database, which is notified by the TimeService when a time tick is received, and updates its local reference to the current time. The time reported from an entity, a widget or any actor object will all refer to the time stored in the local TimeManager.

3.7.2 Time Methods Provided

The TimeManager provides methods to access the current simulation time and the simulation start date/time. The simulation time is measured in elapsed seconds from the simulation start time and accounts for pause and fast time execution. The current simulation date/time is determined by adding the elapsed simulation time to the simulation start date/time.

The time manager also provides methods to create time strings either from the current simulation time, or using the simulation date/time. The strings are formatted according to a client supplied standard Java SimpleDateFormat string. By default the manager returns a simple string format of HH:mm:ss. Note that the simple date format uses capital HH for hours and lower case mm for minutes and ss for seconds.

3.7.3 Subscription To Time Changes

The time manager provides TimeChangeEvents when either the simulation start time is set, or when the current time value changes. Clients can subscribe to START_DATE and TIME_UPDATE event types. The start date event is signalled when the start date in the time


6 Feb 2009

Page 93 of 117

manager is changed. This is usually only at the start of the simulation. The time update event is signalled on each time update made through a call to setCurrentSimTime or setElapsedTime. Subscriptions are provided through the standard event registration pattern:

public SubscriptionID registerForTimeChangeEvent( String topic, EventListener action, SubscriptionFilter filter ); public SubscriptionID registerForTimeChangeEvent( String topic, EventListener action );

When a time change event is raised, the time manager will notify all the subscribers registered in its local subscription manager, subject to the given event topic and filter.


6 Feb 2009

Page 94 of 117


6 Feb 2009

Page 95 of 117

4 GSDK PACKAGES

4.1 APPLICATION

4.2 AWS

4.3 AWTX

4.4 DISPLAY

4.5 ENTITY

4.6 EVENTS

4.6.1 gsdk.events.Heap

The events thart are registered with the EventScheduler are stored in a min-heap structure in order to minimize sorting when events are added to the heap. The principles behind this min-heap are illustrated in the following diagram (for the opposite max-heap structure). Basically when sorted as a min-heap the first event is always guranteed to be the next event (in time order), and after that the guarantee is that each node is before its two children.


6 Feb 2009

Page 96 of 117

4.7 FORMAT

4.8 GEOMETRY

4.8.1 Overview

A number of geometric facilities are provided, to support the graphics and simulation functions of the GSDK and to provide some utility functions for application developers. These are defined in the package gsdk.geometry. The following facilities are provided:

• Double precision rectangle and polygon functions;

• Translation and Scaling between Cartesian coordinate frames;

• Spherical to Cartesian conversion using an arbitrary projection algorithm;

• Calculations on a line segment;

• Point and Position definitions;

• Polyline;

• Quadratic roots;


6 Feb 2009

Page 97 of 117

• Range object;

• Vector in a plane;

• Representation of a volume.

4.9 GRAPH

4.10 LABELS

4.11 MAP

4.12 MIDDLEWARE

4.13 OBSERVER

4.14 PROCESS

4.15 REFLECT

4.16 REGION

4.17 RESOURCES

4.17.1 Overview

The GSDK provides a central mechanism to provide named resource values to participating applications. These resources are similar to Unix shell variables, or Java properties. The Resources class provides a set of static methods to access the required resource items. These items can define the primitive values Boolean, real, integer or String. In addition, arbitrary lists of objects can be created, and can be laid out in the file using free format text. Resource names must start with an alphabetic character and may contain any alphanumeric or underscore ‘_’ or dollar ‘$’ or period ‘.’ characters. By convention, resource names can be given structured names by using the period character to create more meaningful names.

HOME "c:/users/GSDK/" DEBUG true WARNING false MESSAGE true GSDK.MIDDLEWARE.MULTITHREAD_EVENT_DISPATCHING FALSE


6 Feb 2009

Page 98 of 117

GSDK.MIDDLEWARE.OPTIMISE_COLLOCATION TRUE GSDK.MIDDLEWARE.OPTIMISE_EVENT_MARSHALLING FALSE PROJECTION.CENTRE.LATITUDE 53.5 PROJECTION.CENTRE.LONGITUDE -0.5 CLOCK.STARTTIME "07:15:32" TRAJECTORY.CLASS "gsdk.trajectory.TrajectoryImpl" WAYPOINT.CLASS "gsdk.trajectory.WaypointImpl" CONSTRAINT.CLASS "gsdk.trajectory.ConstraintPointImpl" IMAGES $HOME & "atcapp/images/" MAP $HOME & "gsdk/dat/ukcoast.maz" TRANSPARENCY TRUE DEBUG.ATG TRUE DEBUG.CWP1 TRUE COMPONENTS ( ( atc.ts.TS, TS ), ( atc.console.Console, Console ), ( atc.airspace.ASP, ASP ), ( atc.ifpl.IFPL, IFPL ), ( atc.fm.FM, FM ), ( atc.tp.TP, TP ), ( atc.track.ATG, ATG ), ( atc.cwp.CWP, CWP1 ), ( atc.cwp.CWP, CWP2 ) ) ASP.SCENARIO $HOME & "atcapp/airspace.dat" IFPL.SCENARIO $HOME & "atcapp/traffic4.dat" CWP1.SCENARIO $HOME & "atcapp/cwp.dat" CWP2.SCENARIO $HOME & "atcapp/cwp.dat" #LOAD $HOME & "atcapp/physicalColours.gsdk" #LOAD $HOME & "atcapp/logicalColours.gsdk" #LOAD $HOME & "atcapp/fonts.gsdk"

4.17.2 Resources Implementation

The following code fragment shows the set of static methods defined by the Resources class to initialise and to provide access to its resources database. It is followed by a set of descriptions outlining the function of each method.

public class Resources { public static void initialise() public static void initialise( String resourcesFileName ) public static void addProperty( Property property ) public static void addProperty( Property property, String fileName ) public static void addProperty( String name, String value ) public static void addProperty( String name, int value ) public static void addProperty( String name, double value ) public static void addProperty( String name, boolean value ) public static boolean getBoolean( String keyName ) public static boolean getBoolean( String keyName, boolean defaultValue ) public static int getInteger( String keyName ) public static int getInteger( String keyName, int defaultValue ) public static double getReal( String keyName )


6 Feb 2009

Page 99 of 117

public static double getReal( String keyName, double defaultValue ) public static String getString( String keyName ) public static String getString( String keyName, String defaultValue ) public static Color getLogicalColour( String requiredLogicalColour ) public static Font getFont( String requiredFont ) public static ResourceIterator getIterator( String keyName ) public static void read( String resourcesFileName ) } // End class Resources

4.17.2.1 Initialise

Initialises the resources database. The method without any parameters is invoked at GSDK start-up to attempt to load the default resources file called resources.gsdk, from the current directory. The method with a file name parameter will attempt to load resources from the given resources file.

4.17.2.2 Add Property (overloaded)

Adds a new property to the resources database. The property type can be one of integer, real, Boolean or String, and is associated with the given key name. Also, a pre-defined property object can be added directly to the database.

4.17.2.3 Get String (overloaded)

Evaluates the property identified by the key name, returning the result of the valuation as a string. If the property is not found, and a default parameter is given, then the given default value is returned.

4.17.2.4 Get Boolean (overloaded)

Evaluates the property identified by the key name, returning the result of the valuation as a Boolean. If the property is not found, and a default parameter is given, then the given default value is returned.

4.17.2.5 Get Integer (overloaded)

Evaluates the property identified by the key name, returning the result of the valuation as an integer. If the property is not found, and a default parameter is given, then the given default value is returned as an Integer. If the property is not found, and a default parameter is given, then the given default value is returned.

4.17.2.6 Get Real (overloaded)

Evaluates the property identified by the key name, returning the result of the valuation as a double precision number. If the property is not found, and a default parameter is given, then the given default value is returned.

4.17.2.7 Get Logical Colour

A convenience method to convert the given resource name identifying a logical colour into the corresponding Java AWT Color class defining an RGB value.

4.17.2.8 Get Font

A convenience method to convert the given resource name identifying a font into the corresponding Java AWT Font class defining the required text font.


6 Feb 2009

Page 100 of 117

4.17.2.9 Get Iterator

Returns an iterator, which is used to access each element of a resource list property, corresponding to the given resource name. If the named resource does not exist, then the method returns an empty iterator.

4.17.2.10 Read

Reads the resources definitions defined in the given resources file name into the Resources database. The resources will be added to those already held in the database. If an existing resource is redefined it will override the resource value already held in the database.

4.17.3 Resource Iterator Object

The ResourceIterator object is used to iterate through a resources list property. The GetIterator method described in section 4.17.2.9 above returns the iterator. The following code fragment describes the resource iterator class interface.

public class ResourceIterator { public String nextStringElement() public int nextIntegerElement() public double nextDoubleElement() public boolean nextBooleanElement() public ResourceIterator nextListElement() public boolean isStringNext() public boolean isIntegerNext() public boolean isDoubleNext() public boolean isBooleanNext() public boolean isListNext() public boolean isEmpty() } // End class ResourceIterator

4.17.3.1 Next String Element

Retrieves the next string element from the iterator object, moving the iterator on to the next item in the list.

4.17.3.2 Next Integer Element

Retrieves the next integer element from the iterator object, moving the iterator on to the next item in the list.

4.17.3.3 Next Double Element

Retrieves the next double precision element from the iterator object, moving the iterator on to the next item in the list.

4.17.3.4 Next Boolean Element

Retrieves the next Boolean element from the iterator object, moving the iterator on to the next item in the list.

4.17.3.5 Next List Element

Retrieves the next list element iterator from the iterator object, moving the iterator on to the next item in the list.


6 Feb 2009

Page 101 of 117

4.17.3.6 Is String Next

Returns true if the next item in the list is a string.

4.17.3.7 Is Integer Next

Returns true if the next item in the list is an integer.

4.17.3.8 Is Double Next

Returns true if the next item in the list is a double precision number.

4.17.3.9 Is Boolean Next

Returns true if the next item in the list is a Boolean.

4.17.3.10 Is List Next

Returns true if the next item in the list is another list.

4.17.3.11 IsEmpty

Returns true if the list iterator has no more items to extract.

4.17.4 Resource Operators

4.17.4.1 Overview

The resources module provides a set of operators introduced with the @ symbol to manipulate existing resource property definitions. The operators can be used to APPEND, JOIN and MERGE lists, and to REMOVE elements from a list. A LOAD operator can be used to read a new set of resources, overwriting any existing definitions.

4.17.4.2 LOAD

The @LOAD operator loads a new file containing resource definitions into the resources set. The load operation resolves the File or URL path and reads the contents. Any existing properties with the same name are overwritten with the new content. The @LOAD operator can be nested to an arbitrary depth.

@LOAD “atcapp/resources/defaults.gsdk”

4.17.4.3 APPEND

The @APPEND operator appends an item to an existing list. The item can be any primitive or an arbitrary list of items. The item is always added to the end of the existing list. If the append property does not exist, an error is reported.

LIST (A B C)

@APPEND LIST Z

LIST contains (A B C Z)

COMPONENTS ((package.A A) (package.B B))

@APPEND COMPONENTS (package.Z Z)

COMPONENTS contains ((package.A A) (package.B B) (package.Z Z))

4.17.4.4 JOIN

The @JOIN operator is similar to the append operation, but it joins the contents of a list item to an existing list, extending the number of entries in the combined list by the number of entries in the joined list. The resource property can be any arbitrary list, as must the joined


6 Feb 2009

Page 102 of 117

item. The item is always joined to the end of the existing list. If the join property does not exist, an error is reported.

LIST (A B C)

@JOIN LIST (D E F)

LIST contains (A B C D E F)

4.17.4.5 MERGE

The @MERGE operator is similar to the join operation, but it merges the contents of a list item to an existing list, extending the number of entries in the combined list by the number of entries having distinct keys in the joined list. The match can be made with a literal key or a wild card introduced with an “*” character. The resource property can be any arbitrary list, as must the merged item. If the merge property already exists then the previous value is deleted. The new property value is merged to the end of the list.

LIST (A B C)

@MERGE LIST (C D E)

LIST contains (A B C D E)

4.17.4.6 REMOVE

The @REMOVE operator searches its given list property for an item matching the given keyed list item, and if a matching item is found, removes the element from the list. The match can be made with a literal key or a wild card introduced with an “*” character. The resource property can be any arbitrary list, and the removed item may be a primitive item or an arbitrary list including wildcards. The first matching item is removed from the existing list. If the remove property does not exist, an error is reported. LIST (A B C)

@REMOVE LIST B

LIST contains (A C)

4.18 ROUTE

4.19 SCENARIO

4.20 STD

4.21 TOOLS

4.22 TRAJECTORY

4.22.1 Overview

The GSDK provides a set of interfaces defining the methods provided by trajectory, waypoint and constraint object implementations. It also provides a set of default implementations for these interfaces. The trajectory object defines a list of waypoint objects, each of which may optionally reference a constraint point object. The trajectory implementation and the


6 Feb 2009

Page 103 of 117

constraint list define ObjectFactory objects, which are used to create the required instances of derived classes.

The diagram in Figure 4-1 below shows the relationships between the interfaces and the implementation classes defining the trajectory framework.

Figure 4-1 Trajectory Framework

4.22.2 Trajectory Interface

The trajectory interface defines the methods that must be provided by any class implementing a trajectory object. The trajectory class stores a sequence of waypoint objects to represent the 3D positional path taken by an entity, together with time, heading and speed at any point. The trajectory defines the time at which the path starts, and the state of the entity at all subsequent points on the path.

The units used for the trajectory object are not explicitly defined, but must be consistent with the constraint point and waypoint objects, also defined in this section. The units used in ATC applications are metres for the projected (x, y) coordinates, feet for the altitude, and seconds for the time.

The interface is defined by the Java interface definition given below:

4.22.3 Waypoint Interface

The waypoint interface provides a set of access methods for waypoint implementations. A waypoint consists of a position object defining the Cartesian location of the waypoint, the passing time at the waypoint, and the instantaneous heading, climb rate and speed at this point. The accumulated distance along the parent trajectory route is also stored with the waypoint.


6 Feb 2009

Page 104 of 117

The units used for the waypoint object are not explicitly defined, but must be consistent with the waypoint and constraint point objects, also defined in this section. The units used in ATC applications are metres for the projected (x, y) coordinates, feet for the altitude, and seconds for the time.

The following code defines the interface to the waypoint implementation classes, and is followed by a brief explanation of each method.

4.22.3.1 Clear Attributes

This method clears al the waypoint characterisation attributes. The clear method sets all the bits to zero, indicating that the waypoint defines no characteristic attributes.

These attributes define whether this waypoint marks the start or end of a manoeuvre, and may be combined as each attribute mask value marks a single bit in the characterisation attribute field. The list of valid attributes is given in the table below:

Attribute

Name

Value

Mask

Description

BOC 1 Bottom of climb

TOC 2 Top of climb

BOD 4 Bottom of descent

TOD 8 Top of descent

SOT 16 Start of turn

EOT 32 End of turn

SOA 64 Start of acceleration

EOA 128 End of acceleration

SOD 256 Start of deceleration

EOD 512 End of deceleration

OVERFLY 1024 Over fly waypoint

CROSS 2048 Cross (abeam) waypoint

CCR 4096 Change cruise speed in cruise

CCL 8192 Change climb level in climb

CDL 16384 Change descent level in descent

4.22.3.2 Set Attribute

Sets one or more waypoint characterisation attributes. The attributes may be combined with the ‘or’ operator (or simple addition) to form a combination of attribute types. The example below would mark the waypoint as a top of descent and a start of deceleration point:

...

w.setAttribute( Waypoint.TOD | Waypoint.SOD );

...


6 Feb 2009

Page 105 of 117

4.22.3.3 Unset Attribute

This method removes one or more waypoint characterisation attributes from the waypoint attribute set. The attributes may be combined using the ‘or’ operator (or by addition) to form a combination of attribute types.

4.22.3.4 Is Attribute

This method is used to test whether one or more waypoint characterisation attributes has been set for this waypoint. The attributes may be combined by addition to form a combination of attribute types. The method returns true if and only if all the attributes tested are matched in the waypoint.

4.22.4 Constraint Point Interface

The constraint point interface provides a set of access methods for constraint point implementations. A constraint point consists of a central 4D location (x, y plan position, altitude and time), and a 4D box defining a window of allowed values for each coordinate. This identifies the acceptable tolerance limits about the central location that any trajectory generated from a set of constraints must meet. In addition, a constraint list will define an accumulated plan distance stored at each successive constraint point in the list, providing an estimate of the overall route distance.

The units used for the constraint object are not explicitly defined, but must be consistent with the Trajectory and Waypoint objects, also defined in this section. The units used in ATC applications are metres for the projected (x, y) coordinates, feet for the altitude, and seconds for the time.

The following code defines the interface to the constraint point implementation classes, and is followed by a brief explanation of each method.

4.22.4.1 Set Attributes

The setAttributes methods provide equivalent functions to the constructors defined in the

implementation classes of this interface. These methods are required to initialise the constraint point object created with a default parameterless constructor, when using a user specified implementation of the class. The following overloaded methods are defined:

a) Parameterless method sets all attributes to null or to default values.

b) Set (x, y) attributes set in the constraint point. Other attributes set to null.

c) Set (x, y) and altitude attributes in the constraint point. Other attributes set to null.

d) Set (x, y), altitude and time attributes in the constraint point. Other attributes set to null.

e) Set (x, y) attributes from Point 2D

f) Set (x, y) and altitude attributes from Point 3D

g) Set (x, y), altitude and time attributes from Point 4D

h) Set the constraint name and (x, y)

i) Set the constraint name and (x, y) and altitude

j) Set the constraint name and (x, y), altitude and time

k) Set the constraint attributes from another constraint


6 Feb 2009

Page 106 of 117

4.22.4.2 Set Altitude Window

This method sets the altitude constraint error margin above and below the nominal constraint point altitude centred on the Z attribute.

4.22.4.3 Set Plan Window

Sets the planar error defining the plan constraint error margin about the nominal constraint point location at (x, y). It is assumed that this error will be isotropic.

4.22.4.4 Set Time Window

Sets the time constraint error margin in terms of time before and time after the nominal constraint point passing time.

4.22.4.5 Get Name

Retrieves the name of the constraint point. If the constraint defines no name, a null is returned. This name will identify an airspace beacon or a defined point in space.

4.22.4.6 Get Position

Retrieves the 2D location of the constraint point as a 2D point object.

4.22.4.7 Get X, Get Y

Retrieve the x location and the y location of the constraint point respectively.

4.22.4.8 Get Point 4D

Retrieves the 4D location of the constraint point as a 4D point object. This defines the (x, y) planar location and the altitude and time constraint values. If the point does not define a constraint for a given coordinate, a value of zero is returned in the 4D point.

4.22.4.9 Get Altitude Constraint

Retrieves the altitude of this constraint point. If no constraint is defined, it returns zero. This method should be used in conjunction with the method IsAltitudeConstraint method,

described in section Error! Reference source not found., which tests whether this constraint defines an altitude component.

4.22.4.10 Get Time Constraint

Retrieves the time at this constraint point. If no constraint is defined, it returns zero. This method should be used in conjunction with the method IsTimeConstraint, which tests

whether this constraint defines a time constraint.

4.22.4.11 Get Plan Distance

This method returns the accumulated plan distance along the constraint list. This approximates to the distance along the generated trajectory route.

4.22.4.12 Get Altitude Window

Returns the range of allowed altitudes, which meet this constraint. It defines the upper and lower altitude bounds for this constraint.

4.22.4.13 Get Plan Window

Returns the plan error distance about the central plan position defined for this constraint.

4.22.4.14 Get Time Window

Returns the range of allowed times, which meet this constraint. It defines the early and late time bounds for this constraint.


6 Feb 2009

Page 107 of 117

4.22.4.15 Is Altitude Constraint

Returns true if this constraint defines an altitude constraint component.

4.22.4.16 Is Time Constraint

Returns true if this constraint defines a time constraint component.

4.22.4.17 Set Name

Sets the name of the constraint point to the string given.

4.22.4.18 Set Position (Overloaded)

Sets the planar (x, y) position of the constraint point to the coordinates given in either a 2D point object or from the given x and y coordinates.

4.22.4.19 Set Altitude Constraint

Sets the altitude constraint value to the given altitude. This method automatically sets the constraint to be an altitude constraint.

4.22.4.20 Unset Altitude Constraint

Unsets the altitude constraint, removing the altitude component of the constraint.

4.22.4.21 Set Time Constraint

Sets the time constraint value to the given time. This method automatically sets the constraint to be a time constraint.

4.22.4.22 Unset Time Constraint

Unsets the time constraint, removing the altitude component of the constraint.

4.22.4.23 Set Plan Distance

Sets the accumulated plan distance (2D range) along the constraint list. This distance serves as an estimate of the route distance in the generated trajectory. By keeping constraints in distance order, it allows the constraints to be mapped onto equivalent locations on direct to or set heading manoeuvres.

4.22.4.24 Get Range 2D Squared (Overloaded)

Calculates the square of the planar range between this constraint and the given position information. There are two forms of this function. One takes position information from a Position object, and the second from a Point2D object.

4.22.4.25 Get Range 2D (Overloaded)

Calculates the planar range between this constraint and the given position information. There are three forms of this function. One takes position information from a Position object, the

second takes the position from a constraint point, and the third from a Point2D object.

4.22.5 Using The Object Factory in Trajectory Implementation

In order to create an application specific instance of a particular user defined object class, the identity of this class must first be introduced into the application, and then an instance of this object class is created using an instance of the object factory class. The following code fragment shows how a Trajectory class might reference a user specific implementation of a

Waypoint class.


6 Feb 2009

Page 108 of 117

4.23 UTILITIES

4.23.1 Overview

The package gsdk.utilities provides a selection of system wide utility objects to support

4.23.2 Object Factory

4.23.2.1 Factory Overview

The object factory class provides a convenience object to convert a given string parameter, containing a class path, into an instance of the corresponding class. This allows the developer to define the actual object class to use at run time, supplying the path name of the required class as a string, and dynamically loading the class from the class file corresponding to this path into the Java Virtual Machine. The given class must conform to the expected interface, but otherwise can be linked into the system while it is running. Generally, the classes will be supplied through the Resources mechanism, which allows a given class path to be referenced using a resource parameter. The object factory provides an additional mechanism to load class names directly from a resource name. Thus if a specific trajectory class were required, a resource named TRAJECTORY.CLASS could be set in a resource file, and de-referenced by the

object factory, before conversion into an instance of that class.

TRAJECTORY.CLASS “atc.trajectory.TrajectoryImpl” WAYPOINT.CLASS “atc.trajectory.WaypointImpl” CONSTRAINT.CLASS “atc.trajectory.ConstraintImpl”

The object factory uses the Java Reflection mechanism to generate an instance from the path, using the forName method in the Class class. The only constraint on the use of this mechanism to create new objects is that the object must provide an empty constructor, as the object factory provides no mechanism to supply parameters into the constructor using the newInstance method.

4.23.2.2 Object Factory Implementation

An object factory can be created either by using the empty constructor, and then using the setClass method to identify the required object generator class, or by passing the class name directly into the constructor. A third mechanism allows the class to be extracted from a resource name, with an optional default class name provided if the resource was not found.

The ObjectFactory class returns the newly created objects through the createObject method as an instance of the default class java.lang.Object, which must then be cast to the required object type. The object factory may be specialised to provide typed interfaces, which perform the cast internally.

public class ObjectFactory { private Class generator; public ObjectFactory() {} public ObjectFactory( String className ) {} public ObjectFactory( String resourceName, String defaultClassName ) {} public ObjectFactory( Class generator ) {} public void setClass( String className ); public void setClass( Class generator ); public Object createObject(); public boolean isValid(); public Class getGenerator(); public String getGeneratorName(); } // End class ObjectFactory


6 Feb 2009

Page 109 of 117

4.23.2.3 Object Factory Constructors

The constructors of the object factory create new factory objects, which can be used to generate the required type of object instances from the corresponding generator class. The default constructor, with no parameters, sets the generator class to null. Two other versions of the constructor take a class path name string, and a resource name followed by a default class path name string. The final version takes an existing Class object parameter as the object generator class.

4.23.2.4 Set Class

The setClass method sets the object class generator for the client object. This overloaded method can take the name string of an object generating class path, from which the generator class is determined, or the actual class generator Class object.

4.23.2.5 Create Object

The createObject method creates a new instance of the generator class, and returns this instance cast as a java.lang.Object type. The object is created using the Class method newInstance. The class constructor must have a form without any parameters, as no parameters may be passed into this implementation of object factory.

4.23.2.6 Is Valid

This method checks that a valid generator object exists, and checks that the object factory currently defines a generator class that is not null. It returns a simple Boolean if the factory is valid.

4.23.2.7 Get Generator

This method simply returns the Class object defining the generator class object.

4.23.2.8 Get Generator Name

This method simply returns the name string of the path of the currently defined generator class object.

4.23.3 Error Reporting and Debug Facilities

4.23.3.1 Overview Of Error Handling Patterns

The GSDK provides an error reporting mechanism in the form of the static utility class Reporter in the package gsdk.utilities. This class provides a set of methods to output messages to the standard output or to a file. The developer can substitute a new ReportHandler object rather than the default objected provided in the Reporter class.

The Reporter defines methods to output information messages, ordinary text, debug messages, warning messages, and error messages. The error messages can be output with associated information carried in an exception, or an error occurring on a token stream giving token and line number information. The debug output can be controlled by selecting a debug level, or by identifying the thread name on which debug output is required. The following interface code defines the facilities available in the Reporter object.

4.23.3.2 Reporter Design

This section details the design of the Reporter class, describing each of the static methods provided by the class.


6 Feb 2009

Page 110 of 117

public class Reporter { public static void SetReporter( ReportHandler NewReporter ); public static void Error( String errorStr ); public static void Error( String errorStr, Exception exception ); public static void Warning( String warningStr ); public static void Message( String messageStr ); public static void Print( String textStr ); public static void PrintLine( String textStr ); public static void Debug( String DebugStr ); public static void Debug( String DebugStr, int Level ); public static void TokenError( StreamTokenizer tokenStream, String scenarioFileName ); public static void SetWarning( boolean Warning ); public static void SetMessage( boolean Message ); public static void SetDebug( boolean Debug ); public static void SetDebug( boolean Debug, int Level ); public static void SetDebugLevel( int Level ); public static void addApplication( String name, boolean outputDebug ); } // End class Reporter

• Set Reporter Sets a new implementation of the ReportHandler interface for this Reporter to use. This object will format the output of the messages according to the needs of the developer.

• Error Reports a formatted error message with an ERROR prefix, and a stack trace showing the point at which the reporter was called.

• Exception Reports a formatted error message with an ERROR prefix, the exception details, and a stack trace showing the point at which the exception occurred.

• Warning Reports a formatted warning message with a WARNING prefix.

• Message Reports a formatted message with a MESSAGE prefix.

• Print(Line) Outputs a simple text string. Print line will terminate the string with a carriage return and line feed.

• Debug Reports a formatted debug message with a DEBUG prefix.

• Debug(Level) Reports a formatted debug message with a DEBUG prefix. The message is only output if the given level is above the current debug threshold level.

• Token Error Reports an error arising from reading the given token stream from a given file name. It outputs the line number and the offending token in a standard message format.

• Set Warning Sets a flag to output warning messages.

• Set Message Sets a flag to output information messages.


6 Feb 2009

Page 111 of 117

• SetDebug Sets a flag to output debug information. If the optional level parameter is given, only debug calls with an indicated level above the given value will be output.

• SetDebugLevel Sets the default debug level threshold, above which debug messages will be output.

• Add Application Adds an application to the list of debug sources, setting a flag to indicate whether debug is required from this source. The application is identified by name, which is matched against the name of the current thread to determine if output is required.


6 Feb 2009

Page 112 of 117

5 DISCOVERY MONITOR

5.1 INTRODUCTION

The monitor is a GSDK application, built to display interactions between components. It connects to each other component via the discovery service. Once connected, it queries the methods, fields and interfaces, and prints these out in the tree pane. Additionally, whenever a component sends an event, this tabulates the number of components which receive the event – and prints the results in a graph. A console is included in the monitor, so that the user may control the time server.

5.2 TIMINGS

5.2.1 Initialisation:

When the monitor is loaded, it does three things:

• Initialises the graphics

• Queries Discovery for pre-registered components, and processes them

• Registers a listener with Discovery, to process other component registrations.

5.2.2 Processing Components:

The monitor does the exact same things whenever it finds a component – either by querying Discovery or via the RegistrationListener:

• Finds out if it has a ‘subscribe’ method (in which case, this is a server).

• If it does, it:

o Creates a MonitorListener for that component, and adds it to the component

o Adds it to the tree model, under “servers”

• Otherwise, it adds it to the tree model, under “clients”

5.2.3 Purpose of MonitorListener

A MonitorListener is used to listen to all outgoing messages from a component. Each component has a registerMonitor method, which saves the MonitorListener online. Whenever the server-component sends out an event, the component keeps a note of how many client-components listened to it, then tells the MonitorListener. The monitor categorises these messages according to the class of event, and keeps a value according to how often that event is called. This value decays over time, so will tend towards the true frequency of the component. The MonitorListener also keeps a generic frequency for the entire component – summing all events generated by the component.

5.3 THE TREEPANE INTERFACE

The TreePane has two major subdivisions – Servers and Clients. The Servers part contains all components that have public methods beginning with “subscribe”. The Clients part contains all the rest of the components. Each component can be queried for its Methods, Fields and Interfaces (using reflection). Additionally, a right-click on a Server component allows you to filter the graphpane, so it shows all events from a specific component, instead of generic results from all components. This can be reversed with a right-click on “Servers”


6 Feb 2009

Page 113 of 117

5.4 THE GRAPHPANE INTERFACE

As soon as events start firing, they get added to the Graph pane. Initially, there are no events listed on the pane – even if it has registered with components. This is because the monitor revolves around listening to events, not just things that happen to correspond to a particular

subscribe-message. As such, the monitor has no way of knowing what the events are called before they fire.

Whenever a new event fires, the component is noted in the graph pane. Each component will have its own generic result that is initially displayed; after filtering, each component will have a list of all events that the Monitor has seen.

The graph bars decay regularly; this is so that over time they should normalise towards an approximation of the frequency they fire. The scale of the graph is also logarithmic; hopefully the shrinking scale reflects this. When an event fires, the bar does not increment uniformly; the size of the bar is not simply a measure of how often the event fires, rather the bar increments according to the number of non-monitor components which were notified of the event. So if no components have registered an interest in that event, the bar will not increment at all.

5.5 RUNNING THE MONITOR

In order to run the Performance Monitor it is only necessary to insert the monitor in the list of components, i.e. the following line should be inserted in the COMPONENTS list:

( gsdk.middleware.monitor.Monitor, Monitor ).

Several example applications have been created. These are:

• componenttests/monitor/standalonemonitor.gsdk

• componenttests/monitor/monitor.gsdk.


6 Feb 2009

Page 114 of 117

6 LAUNCHER

6.1 INTRODUCTION

GSDK.Launcher is an abstract class that can be used, in conjunction with the abstract GSDK.LauncherPanel class, to construct an Application Launcher. The Launcher consists of a window containing a tab-pane that has user-configurable options for the application. These options translate to Resource settings.

6.2 LAUNCHER CREATION PROCESS

In order to construct a new Launcher the following steps should be taken:

For each Panel required:

• Create a class that extends gsdk.LauncherPanel.

• Create the graphical components in the constructor method.

• Implement the defaultValues method to return all options to their defaults.

To construct the launcher:

• Create a new Launcher class, that extends gsdk.Launcher.

• Declare Listener methods for all graphical options that have an effect on other options. For example ticking a checkbox may lead to other options being disabled or set to a default value.

• Implement the initGraphics method. This method should instantiate the Listener methods and Construct the Panel Classes and call tabPane.addTab("<Name of panel>",<panelObject>) for each panel.

• Implement the launchCWP and launchPVT methods. These should set up all resources, according to the user selected options and then launch the application in a separate thread.

A good example of this can be found in ATCApp.Launcher, LauncherPanelMain and LauncherPanelAWS.

6.3 RUNNING FROM A JAR FILE

When running the Launcher from a Jar file, because it is not possible to scan directories from within a Jar file, it is required that you provide a parameter with a file that lists all of the scenario files that are required. An example of such a file is shown below.

atcapp/resources/acceptancetests/validation2002/resources/standaloneCWP.gsdk atcapp/resources/acceptancetests/validation2002/resources/standaloneCWP_PWP.gsdk atcapp/resources/componenttests/ccs/ccs.gsdk atcapp/resources/componenttests/cs/announced.gsdk atcapp/resources/componenttests/cs/force_act.gsdk atcapp/resources/componenttests/cs/rentrant.gsdk

This file can be found in atcapp/componenttests.dat and is launched with the following command line:


6 Feb 2009

Page 115 of 117

java -Djava.security.policy=java.policy -Xms2m -Xmx200m -cp ../eDEP.jar;products/classes atcapp.Launcher atcapp/componentTests.dat


6 Feb 2009

Page 116 of 117

APPENDIX A - COLOUR MANAGEMENT FILES

PHYSICAL COLOUR DEFINITION FILE

PHYSICAL_COLOURS ( ( Black, 0, 0, 0 ),

( Assumed, 0, 0, 0 ),

( Coordination, 255, 255, 255 ),

( White 255, 255, 255 ),

( HandleDark, 178, 127, 127 ),

( Act_In, 0, 0, 130 ),

( DarkBlue, 0, 0, 130 ),

( Selected, 117, 224, 79 ),

( Green, 117, 224, 79 ),

( Beacon, 166, 166, 166 ),

( Concerned 128, 0, 0 ),

( Red_Brown 128, 0, 0 ),

( Not_Concerned, 128, 128, 128 ),

( WBlue, 112, 140, 168 ),

( WBlue_Highlight, 163, 191, 219 ),

( WBlue_Depressed, 69, 81, 138 ),

( CRD_Background, 122, 115, 115 ),

( CRD_Highlight, 191, 191, 191 ),

( Advanced, 235, 173, 173 ) )

LOGICAL COLOUR DEFINITION FILE

LOGICAL_COLOURS ( ( SIL_HEADER, Green ),

( SIL_HEADER_TEXT, Black ),

( SIL_BACKGROUND, CRD_Background ),

( SIL_ADVANCED, Advanced ),

( MW_HEADER, WBlue ),

( MW_HEADER_TEXT, Black ),

( MW_BACKGROUND, CRD_Background ),

( MW_TEXT, Black ),

( MW_PROPOSED_BG White ) )

FONT DEFINITION FILE

FONTS ( ( SIL_TITLE, Arial-BOLD-18 ),


6 Feb 2009

Page 117 of 117

( SIL_LIST, Arial-BOLD-14 ),

( MW_TITLE, Courier-BOLD-16 ),

( MW_LIST, Arial-BOLD-14 ),

( HAM_FONT, Courier-BOLD-14 ) )

Date post:	06-May-2018
Category:	Documents
Upload:	truonganh
View:	214 times
Download:	0 times