Generic Framework – version 1.0 Guidelines for Components …publicaties.minienm.nl/download-bijlage/9681/2001-128x.pdf · Report Project SRW2000 Version 1.1 Registration number

Project SRW2000 Generic Framework – version 1.0 Guidelines for Components version 1.1

Blanc page.

Project SRW2000

Generic Framework – version 1.0 Guidelines for Components version 1.1

Project team SRW2000 By commission of STOWA, ALTERRA, RIVM, RIZA September 2000 Bibliography: Tacke, J.H.P.M. (MX.Systems BV), Brinkman, R. (WL | Delft Hydraulics),

Frieswijk, E. (EDS International BV), Levelt, D. (WL | Delft Hydraulics), Otjens, A.J. (W!SL-Alterra), 2001, Generic Framework – versie 1.0, Guidelines for Components, ISBN 90-5773-145-2, Foundation for Applied Water Research (STOWA), Utrecht, report 2001-W-09, Directorate-General for Public Works and Water Management, Institute of Inland Water Management and Waste Water Treatment (RIZA), Lelystad, report 2001.128X, 52p.

Blanc page.

Report Project SRW2000

Version 1.1

Registration number P4118-R-3

Foreword The ‘Generic Framework – Realisation version 1.0’ project was commissioned by STOWA (Foundation of Applied Water Research) and was co-financed by RWS-RIZA, RIVM, NITG TNO and Alterra. The project was carried out by a consortium of IT organisations who actively develop applications for integrated water management in the Netherlands, namely W!SL/Alterra, MX.Systems, Geodan IT, NITG TNO and WL | Delft Hydraulics. The following persons were involved in the execution of the ‘Generic Framework– Realisation version 1.0’ project: Steering committee: Jacques Leenen

(chairman) STOWA

Jan Anne Boswinkel NITG TNO Anton van der Giessen RIVM Miep van Gijsen Alterra Gaele Rodenhuis WL | Delft Hydraulics Theo van Stijn RIKZ Frans van de Ven RIZA Supervisory committee: Jandirk Bulens (chairman) Alterra Henk Alkemade RIZA Aldrik Bakema RIVM Michiel Blind RIZA Piet Groenendijk Alterra Jan Noort Sepra (for STOWA) Ludolph Wentholt STOWA Rick Wortelboer RIVM Concept Control Team: Bas van Adrichem MX.Systems Jan Jellema NITG TNO Joost Maus Geodan IT Jaco Stout WL | Delft Hydraulics Tamme van der Wal W!SL / Alterra Project team: Johan Tacke (project

manager) MX.Systems

Rob Brinkman WL | Delft Hydraulics Michiel Dijkman Geodan IT Edwin Frieswijk EDS International BV Joris Sierman Geodan IT Tonny Otjens W!SL / Alterra The supervisory committee monitored the progress of the project on behalf of the Realisation of Generic Framework steering committee and assessed the contents of (interim) products. The Concept Control Team has been responsible for contextual steering of the project team and for internal reviews of the (interim) products, on behalf of the consortium of clients.

I


Version 1.1


CONTENTS Foreword...................................................Fout! Bladwijzer niet gedefinieerd. 1 Introduction................................................................................................ 1

1.1 Background ........................................................................................ 1 1.2 Target group....................................................................................... 1 1.3 Reader’s guide ................................................................................... 1

2 GF architecture.......................................................................................... 2 2.1 Introduction......................................................................................... 2 2.2 Framework and framework components ............................................ 2 2.3 Implementation................................................................................... 4

3 GF Library.................................................................................................. 6 3.1 Introduction......................................................................................... 6 3.2 Building the library.............................................................................. 6 3.3 Collections and Iterators..................................................................... 7 3.4 eXtensible Markup Language............................................................. 9 3.5 Events .............................................................................................. 11

4 Development of framework components ................................................. 13 4.1 Introduction....................................................................................... 13 4.2 Which requirements must each framework component meet? ........ 13 4.3 Tips for developing framework components..................................... 16

5 Development of model applications......................................................... 17 5.1 Introduction....................................................................................... 17 5.2 Phased planning............................................................................... 17 5.3 Realisation of a model application.................................................... 18

5.3.1 Phase 1: Definition of project source ........................................ 18 5.3.2 Phase 2: Implementation of project source............................... 18 5.3.3 Phase 3: Implementation of model elements and connectors .. 22 5.3.4 Phase 4: ModelApplication implementation operations ............ 25 5.3.5 Phase 5: Link with computational unit....................................... 28 5.3.6 Phase 6: Testing ....................................................................... 28

6 Development of generic tools .................................................................. 29 6.1 Introduction....................................................................................... 29 6.2 Phased planning............................................................................... 29 6.3 Realisation of a presentation component ......................................... 30

6.3.1 Phase 1: Definition of project source ........................................ 30 6.3.2 Phase 2: Implementation of project source............................... 30

II


Version 1.1


6.3.3 Phase 3: Implementation of BuildingFC operations .................. 31 6.3.4 Phase 4: Implementation of GenericTool operations ................ 32 6.3.5 Phase 5: Implementation of PresentationComponent operations................................................................................................ 33 6.3.6 Phase 6: Testing ....................................................................... 34

7 Using data definitions .............................................................................. 34 7.1 Introduction....................................................................................... 34 7.2 Reading and writing of data.............................................................. 35

7.2.1 DataDefinition............................................................................ 35 7.2.2 SRWDataObject........................................................................ 36 7.2.3 Scope of a DataDefinition ......................................................... 38

7.3 Data definitions for model applications............................................. 38 7.4 Data definitions for generic tools ...................................................... 42

8 Standards and name conventions ........................................................... 42 8.1 Introduction....................................................................................... 42 8.2 Use of XML....................................................................................... 42 8.3 Name conventions............................................................................ 43

9 References .............................................................................................. 44 Appendix A: Contents of SRWLib................................................................... 45 Appendix B: Delphi Settings ........................................................................... 47 Appendix C: Commonly asked questions ....................................................... 51

III


Version 1.1


Blanc page.

IV


Version 1.1


1 Introduction

1.1 Background This document is one of the reports on the realisation phase of the ‘Generic Framework– Realisation version 1.0’ project. Roughly speaking, this phase consists of the following elements:

• Construction framework and framework components;

• Implementation/testing of national and regional cases;

• Adjustment of Technical Design (TD);

• Supplement to Guidelines for component builders. This document is the modified version of the Guidelines for component builders. These modifications and supplements are based on the experiences gathered during the construction of framework and framework components.

1.2 Target group This document provides a phased planning which can be used as a guideline for the development of model applications and generic tools. It is therefore primarily written for system developers. Implementation choices made during the realisation of the Generic Framework (GF) influence these guidelines and consequently the required knowledge of system developers who will built the GF components. It is assumed that the reader has sufficient knowledge of Object Orientation (OO), Unified Modeling Language (UML), Delphi syntax (Object Pascal) and eXtensible Markup Language (XML).

1.3 Reader’s guide This document does not contain all information needed to build GF components. The Technical Design for Generic Framework [GF-TD] and to a lesser extent the Functional Design for Generic Framework [GF-FD] are required for reference as well. As an introduction, Chapter 2 provides a summary of the most important GF architecture concepts. During the realisation of the framework and framework components, a library was developed with all types of functionalities which can be put to use in the entire framework and any framework component. This library - SRWLib1 -is available as a set of Delphi units. The components of SRWLib are described in Chapter 3. Each framework component must fulfil certain general specifications. Adhering to these specifications during a component's development will 1 The Dutch name of the Generic Framework is SR. It used to be SRW (W: water). Since the name was changed during the project in some cases you will find SRW. For example this projects formal registration is SRW2000, and one specific tool is implemented and named SRW-Editor.

1


Version 1.1


ensure its compatibility. The specifications and additional hints are included in Chapter 4. In Chapter 5, the framework component specifications are covered in further detail for the purpose of developing model applications. This model application development is illustrated in the form of phased planning. Analogue to this, a phased planning for the development of generic tools is described in Chapter 6. Using the DataEngine, the framework has the flexibility to deal with different data structures and formats. Chapter 7 illustrates how this works. In addition to all specifications needed to guarantee the framework's correct functioning, development of framework components can be simplified by means of a number of standards and conventions. The standards and conventions applied are described in Chapter 8.

2 GF architecture

2.1 Introduction The design developed for GF version 1 was based on the Architecture for the Generic Framework [GF-A] and the GF functional analysis [GF-FD]. This design defines the services to be provided by the framework and its various components, and the manner in which these services are offered.

2.2 Framework and framework components The framework is the basis for any GF application and has general functions to cater for this:

• Management of registered framework components;

• Initiation of framework components;

• Receiving and sending of so-called framework component ‘events’. Applications based on this framework include a number of framework components. Some of the components must be available in order to compose and carry out cases. These components are:

• ProcessManager The ProcessManager provides the ‘Composer’ which is used to compose a case and co-ordinate a simulation (starting, pausing, stopping, determining computational sequence).

• DataEngine The DataEngine is responsible for the (mutual) exchange of data between model applications and generic tools and the management of this data. The DataEngine is able to manage the total input and output of model applications or just the references to data locations. It is therefore not a central database for all model applications.

• SRW-Editor

2


Version 1.1


The SRW-Editor creates connections between the connecting points (schematisations) of model applications based on user selections. In other words, the SRW-Editor records the data which must be transferred from one model application or generic tool to another.

• CaseManager The CaseManager provides a list of previously studied cases and allows the user to select an existing case or create a new one upon initiation of an GF application.

• (Optional) MessageServer The MessageServer can be used to send messages to the user in the form of a dialogue box. This server automatically saves all messages sent by framework components.

Only one registered copy of the above mentioned components can be used (if a second ProcessManager is registered, the framework will ignore this second version). Within the GF architecture, these components are referred to as BasicFrameworkComponents (or BasicFCs).

Framework

ProcessManager

DataEngine CaseManager

SWFEditor MessageServer

Figure 2.1 – Basic configuration for an GF application

Among the flexible possibilities that GF has to offer, addition and removal of framework components will be particularly utilised due to the development of new model applications or, for example, new presentation components. These are also the framework components which have various 'types' that can be used adjacent to one another. Within the GF architecture, these components are referred to as BuildingFrameworkComponents (or BuildingFCs). BuildingFCs are the components which are used as part of a case.

Framework

ProcessManager

DataEngine CaseManager

SRWEditor MessageServer

Graph Tool SwapModel

SobekModel

DuflowModel

BasicFrameworkComponents

BuildingFrameworkComponents

Figure 2.3 – Basic configuration for an GF application, supplemented with Building Framework Components.

3


Version 1.1


The above structure derives from the class diagram below, which illustrates the relationship between the framework, BasicFCs and BuildingFCs.

Framework FrameworkComponent**

BasicFrameworkComponent

BuildingFrameworkComponent ProcessManager DataEngine

ModelApplication GenericTool

SRWeditor

Figure 2.2 – Class diagram of framework and framework components

2.3 Implementation For the development of an GF component, the following is required :

• Borland Delphi 5 development environment, including Service Pack 1.

Borland supplies three versions of Delphi 5: Standard, Professional and Enterprise. All versions are applicable because Internet, Database and COM components are not used within the framework or the BasicFCs.

The required Service Pack can be downloaded from Borland at: http://www.borland.com/devsupport/delphi/downloads/index.html

• XML parser A parser is required for reading and writing XML (eXtensible Markup Language). Microsoft® supplies the necessary parsers in the form of a COM DLL, under the name of MSXML. Version 2.5 of this parser is required for the development of GF components. This parser is automatically present if your PC is installed with MS Internet Explorer 5.0. Individual parser installation is also possible, refer to: http://msdn.microsoft.com/xml/default.asp

• Delphi source code or compiled units of framework and BasicFCs The basic source code is required in order to develop a new framework component. Using this basic code, a private code can be compiled and debugged. The figure below, shows the directory structure on the basis of which the framework and framework components for version 1 have been

4


Version 1.1


developed. In order to develop (compile) specific framework components, it is essential that this structure is retained to ensure the correctness of (relative) search paths to this code.

Figure 2.3 – Directory structure of GF source code.

In addition to the described tools and source code, knowledge of certain technologies is required in order to develop GF components.

• Delphi development environment and Object Pascal syntax. Apart from knowledge of syntax, experience of the Delphi environment (compiler, debugger, etc) is also required.

• XML The XML Document Object Model (in which COM interfaces are applied as DOMDocument, XMLDOMNode, etc) is assumed to be known by the user. Additional information is available at: http://www.msdn.microsoft.com/xml/default.asp

• Development of Delphi DLLs An GF component is developed as a Dynamic Link Library (DLL). Knowledge on the development of DLLs and so-called class DLLs (DLLs which make a class available instead of a set of functions) is required.

5


Version 1.1


3 GF Library

3.1 Introduction For the development of framework and framework components, a number of agreements have been made concerning the implementation of commonly used program elements. For these program elements, certain standard solutions have therefore been made which can be applied to each framework component. These standard solutions are incorporated in a library - the GF Library (SRWLib). A number of classes which are part of SRWLib are GF interfaces and are described in the technical design. These interfaces are included in SRWLib because they are applied to various framework components. Use of these interfaces is therefore necessary to ensure optimal functioning of the GF application. In addition to these ‘compulsory’ elements, a number of standard solutions are included which are not part of GF specifications, but which are only offered as tools. It is therefore possible to decline any standard solutions, even though it would not make sense to choose an internal XML parser, with SRWLib containing an extensively tested version.

3.2 Building the library SRWLib is available in the form of a Delphi project. This project includes sixty source files (Pascal files) in which the standard solutions are implemented. Although the SRWLib project can be compiled into a DLL, it is not the intended method of use. This DLL should involve an inconvenient and complicated interface. Use of SRWLib is therefore only possible when referring to the relevant source files in this library. Within Delphi this means that the so-called ‘uses clause’ is expanded with units from SRWLib. Generally speaking, SRWLib consists of the following elements: 1. GF classes

All interfaces described in the GF Technical Design and (which can be) applied in the framework components are included in SRWLib.

2. Collection/Iterator Design Pattern Iterator Design Pattern [GAMMA, 1995] has been developed in order to be able to use and process object collections.

3. Event Model So-called ‘events’ are used for sending messages between framework components and the framework (and vice versa), such as status modifications or error messages. Events are always sent to the framework (the Publisher). The framework signals which framework components ‘are interested’ in these events and forwards them on the basis of this information. In order to use this concept, a number of standard classes are offered in SRWLib.

4. Basic constants and types In addition to standard classes/interfaces, standard types and constants are also included in GF. These basic and enumeration types ensure a

6


Version 1.1


minimum dependency of specific Delphi (Object Pascal) language concepts. Examples include individual types for strings and date/time.

5. XML and GML classes (Meta)information of framework components and cases is exchanged in XML format. Model schematisations are presented in a specific implementation of this, a GML. In order to use this format, various Delphi classes have been developed which avoid direct use of the MSXML parser.

Appendix A gives a complete summary of all SRWLib units. Searching a unit in SRWLib is simplified because the name of a unit is always the same as its class, preceded by the prefix ‘u’ (i.e., the unit ‘uPosition’ contains the class ‘Position’).

3.3 Collections and Iterators Object collections are updated at various locations in an component. An object collection itself is also an object which has operations to manipulate this collection. For this purpose, SRWLib offers the Collection interface. This interface provides the following operations: • Add(aObject: TRootObject)

Adds the object aObject to the collection.

• Remove(aObject: TRootObject)

Removes the aObject object from the collection.

• Size()

Indicates the size of the list.

• Includes(aObject: TRootObject)

Gives True as the result if aObject object is the element of the collection, otherwise False.

• CreateIterator()

Creates an object with which the object collection can be browsed.

• ValidateElement(aObject: TRootObject)

Checks whether the aObject object may be added to the list.

• SetElementConstraint(aPredicate: TPredicate)

Sets the predicate as precondition for objects in the collection.

Classes which use/implement this interface are:

• IndexedCollection – This class ensures that the objects are kept in a fixed, indexed order. Operations such as getFirstIndex, getLastIndex and getItem are therefore provided as well. This class is abstract, which means no instances may be created from it.

• AssociationList – This IndexedCollection subclass maintains an object collection with the list not being the ‘owner’ of the objects in the list. If this list is removed, the objects contained in it are retained.

• FastAssociationList – This class is identical to AssociationList, but is specifically designed for very large collections (more than several dozens of objects).

7


Version 1.1


• TempAssociationList – this is a specialisation of AssociationList and is

identical to it, with the exception of its corresponding Iterator which is also responsible for removal of this list.

• AggregationList – This class is identical to AssociationList, with the exception that the list is now the owner of objects in the list. If this list is removed, the objects in the list are also removed.

• FastAggregationList – This class is identical to AggregationList, but is specifically designed for very large collections (more than several dozens of objects).

• ManagedAggregationList – This specialisation of AggregationList is used to set the maximum size of a list. The ‘oldest’ objects will be removed when the maximum size is exceeded.

When a collection is used, it is either updated (objects are added/removed) or the list is browsed (for searching an object, for example). The collection has an Iterator in order to browse objects. This Iterator provides operations for browsing the list. As a result, the physical structure of the collection is concealed. The interface Iterator provides the following operations: • NextElement()

Restores the next element of the collection.

• Done()

Gives True as result if end of list has been reached This operation must always be requested prior to initiating NextElement().

• First()

Repositions the Iterator at the beginning of the collection.

• Last()

Repositions the Iterator at the end of the collection.

• Count()

Gives the number of elements which has been included in the corresponding collection.

The following classes implement the Iterator interface:

• EmptyIterator – If an iterator from an empty/non-existent list is requested, an instance of EmptyIterator can be given.

• SingletonIterator –If a collection comprises just one element, an instance of SingletonIterator can be given.

• CombinedIterator – In order to browse two consecutive collections, a CombinedIterator can be used to combine this process.

• IndexedCollectionIterator – This iterator is intended for browsing IndexedCollections.

• TempIndexedCollectionIterator – This ensures that if an iterator is removed, the corresponding collection will also be removed.

The design of the combination of collections and iterators is shown in the class diagrams below:

8


Version 1.1


Collection

IndexedCollection

AssociationList

FastAssoc iat ionList TempAssociationList

AggregationList

FastAggregationList ManagedAggregationLis t

Figure 3.1 – Collections

TempIndexedCollectionIterator

Iterator

EmptyIterator CombinedIteratorSingletonIterator IndexedCollectionIterator

Figure 3.2 – Iterator design pattern

3.4 eXtensible Markup Language XML is a language designed for describing data. The language makes use of so-called XML Elements, which comprises data that is preceded and closed by a ‘tag’, similar to HTML. An example of an XML Element is

<framework>SRW</framework>

The “Framework ”element above has an “SRW” value. The Framework element describes the SRW value.

9


Version 1.1


So-called XML Documents are used for collections of these elements. An XML Document is an XML Element that can contain subelements. An example of this:

<application>

<framework>SRW</framework>

<component>ProcessManager</component>

</application>

The above example shows an XML Document “Application” which contains the elements “framework” and “component”. For utilisation of XML Elements and Documents, an object model is created. This object model is a collection of objects which can be used to manipulate XML Elements/Documents. The elements in an XML Document in this object model are regarded as ‘Nodes’ and describe the properties of these Nodes and the operations which can be performed on them. Microsoft® supplies a parser which is able to read/write XML. The XML object model (XMLDOM) is worked out in a number of COM interfaces. SRWLib has ‘wrapped’ the most important elements in two Delphi classes. As a result, Delphi COM interface usage is concealed from GF component developers. The Delphi classes are:

• XMLDocument – the wrapper of COM interface, IXMLDOMDocument;

• XMLNode – the wrapper of COM interface, IXMLDomNode. The structure is derived directly from the XML object model.

RootObject(from Framework package)

XMLDocument

XMLNode

**

Figure 3.3 – Class diagram XMLwrappers for Delphi

Delphi classes generally offer the following possibilities:

• Reading of an XML file An existing XML file can be opened using:

XMLDocument.Load(aURL)

where aURL is the XML file name. An XML file can saved (or changed) using:

XMLDocument.Save(aURL)

• Writing in an XML file 10


Version 1.1


Nodes can be added when writing in an XML file. A ‘ParentNode’ must be allocated, so that all subnodes can be positioned when added. To add a node, use the following:

XMLNode.CreateChild(aTag)

where aTag is the name of the new node. To set the value of a node, use the following:

XMLNode.SetValue(aString)

where aString represents the value.

• Searching nodes and corresponding values in an XML file The nodes in an XML file have a tree structure. The principle node or ‘Parent’ can be requested, as well as the collection of subnodes, the ‘Child’. To search for a node by name, use the following:

XMLNode.SelectNode(aPattern)

where aPattern contains the node name (or names) to be searched. In GF, only a small part of the XML options are applied and described here. The large number of additional options such as StyleSheets, DTDs, etc are not applicable to version 1 of GF. Many help files are available for the XML object model. The XMLSDK25.CHM tool, which can be obtained from Microsoft®, provides a complete summary of the options.

3.5 Events Exchange of information is required between the framework components (mutually) and the framework. The interdependency of these components is considerably reduced due to information (such as status transitions, error messages and case changes) being sent as so-called ‘event’ instead of direct communication between components. This concept is derived from the Observer Design Pattern and is also referred to as the Publish-Subscribe mechanism. Framework components have the ability to both send and receive events. An event sent by a framework component, is always received by the Publisher of the framework itself. A framework component can ‘subscribe’ to specific event types in the framework, such as events which indicate status changes in a case. The Publisher knows which framework components are subscribed to which event types. The Publisher then forwards the received events to these subscribers.

11


Version 1.1


FrameworkComponent 1

Framework

Publisher



Event

Event

Event

Figure 3.4 – Publish – Subscribe mechanism

Each framework component always has a reference to the framework. As a result, each framework component can send events to the Publisher (which is part of the framework). Each event object in GF is derived from the class DistributedEvent. This object contains standard information about the event sender and event specifications. These specifications are incorporated in an object of the Subject type. Depending on the nature of the event, a subclass can be created from DistributedEvent. Specific information or behaviour can be included in the subclass. The following event types are included in SRWLib standardly:

• ConfirmEvent – Event used to confirm a question.

• StatusEvent – Event used to transfer status changes in a case.

• ProgressEvent – Event used to report the progress of a simulation. The structure of events and subjects is shown in the class diagram below.

DistributedEvent Subject11

StatusEvent ProgressEvent ConfirmEvent

Figure 3.5 – Events in GF

Apply the code below to subscribe framework components to a specific event type.

FFramework.Subscribe(aSubcriber, aEventType, aNotifyProcedure)

This contains the following definitions:

• aSubscriber: an object of the Subscriber type which allows the subscriber to actually receive the events.

12


Version 1.1


• aEventType: the event type which is being subscribed to - here, the

CaseChanged event type.

• aNotifyProcedure: a reference to the procedure which has to be requested by the Publisher when sending an event. This procedure must comply with the following specification: TDistributedEventProc = procedure(aDistributedEvent : TDistributedEvent) of object

This notification can be used during the instantiation of a framework component, for example. This notification must be cancelled before a framework component is removed (otherwise the Publisher will continue to send events to non-existent components). The framework therefore provides the operation UnSubscribe. Apply the code below when sending events to the Publisher.

FFramework.Notify(aSubjectname, aSubjectValue)

This contains the following definitions:

• aSubjectName: the name of the subject that is being sent.

• aSubjectValue: the information (such as text or a value) which is sent together with the event.

4 Development of framework components

4.1 Introduction The development of a framework component often involves model application or generic tool development, the so-called BuildingFCs. The replacement of a ProcessManager or DataEngine will be less frequently than the addition of a model application to the framework application.

4.2 Which requirements must each framework component meet? The standard functionalities that each framework component must have, can be derived from the class hierarchy on which it is based. This hierarchy is shown in the figure below.

Framework FrameworkComponent**


Figure 4.1 – Class diagram of framework components

13


Version 1.1


This class diagram shows that the Framework contains a collection of FrameworkComponents. Each framework component is a subclass of BasicFrameworkComponent. This means that a framework component always has to implement two interfaces - FrameworkComponent and BasicFrameworkComponent. A framework component therefore offers a minimal set of operations. The developer must implement these operations, if the implementation default is insufficient. This involves the following operations.

FrameworkComponent

function GetComponentDescription(): TComponentDescriptor;

Provides a reference to the ComponentDescriptor-object which describes the framework component. The standard implementation does not have to be overwritten.

function GetComponentReference(): TComponentReference;

Provides a reference to the ComponentReference-object which belongs to this framework component. The standard implementation does not have to be overwritten.

function GetProvidedServices: TIterator;

Provides a reference to the collection of services provided by the framework component. The collection is read from the ComponentDescriptor. The standard implementation does not have to be overwritten.

function GetRequiredServices: TIterator;

Refers to the collection of services required by the framework component. The collection is read from the ComponentDescriptor. The standard implementation does not have to be overwritten.

function GetSubscriber : TSubscriber;

Refers to the Subscriber-object which belongs to this framework component. The standard implementation does not have to be overwritten.

function MultipleInstance : Boolean;

The result of this function indicates whether more instances of this framework component are allowed. This is standardly possible. Implementation must be overwritten for components where only one instance is allowed.


function GetFramework: TIFramework;

Refers to the framework. The implementation cannot be overwritten in specific framework components.

function GetComponentType: TComponentType; override;

Indicates the component type. BasicFrameworkComponent is standardly given as the type (ctBasic). This implementation must be overwritten in specific framework component if it concerns a model application or generic tool (ctBuilding).

Each framework component is compiled as Delphi DLL. These DLLs have a simple interface containing two operations. In addition to the possible overwriting of standard implementations of the framework component operations, standard DLL functions must be entered:

• InitFrameworkComponent This function gives the framework component concerned as the result. The DLL is the instantiation entry of a framework component. The function uses the following signature:

14


Version 1.1


function(aFramework: TIFramework; aComponentReference: ComponentReference):

TFrameworkComponent;

• GetXMLString This function provides the ComponentDescriptor of the framework component in XML format. The function uses the following signature:

function: String

As an example, DLL functions are presented in the same way as in the graph tool. Modification of framework components is a simple process, because only class names and the ComponentDescriptor need to be changed.

function InitGraphTool(aFramework: TIFramework; aComponentReference:

TComponentReference): TPresentationComponent; export; stdcall;

begin

try

// create frameworkcomponent

Result := TGraphTool.Create(aFramework, aComponentReference);

except

Result := nil;

end;

end;

function GetGraphToolXML: String;

begin

Result :=

'<SRWXML>' +

'<HEADER>' +

'<VERSION>0.1</VERSION>' +

'<ACCESS>atReadOnly</ACCESS>' +

'</HEADER>' +

'<CONTENTS>' + '

<COMPONENTDESCRIPTOR>' +

'<NAME>' +

'<TDESCRIPTION>GraphTool</TDESCRIPTION>' +

'</NAME>' +

'<VERSION>1.0</VERSION>' +

'<SIZE>50</SIZE>' +

….

'</COMPONENTDESCRIPTOR>' +

'<SERVICES>' +

…

‘</SERVICES>’

'</CONTENTS>' +

'</SRWXML>';

end;

15


Version 1.1


For exact details on filling in DLL functions, refer to the phased planning for model application development (Chapter 5) and generic tools (Chapter 6).

4.3 Tips for developing framework components In addition to all standard specifications, there are a number of tips which can help speed up the development process of a framework component.

• Do not use hints with buttons and other visual controls.

• Do not send events to the Publisher in the destructor of a framework component.

• Check that Delphi does not contain any Garbage Collection functionalities. Each object must explicitly be released again. A ‘destroy’ task must be included with each ‘create’ task.

• An object may only be created by a framework component if the framework component in question is responsible for destroying the object and that no other framework component references exist for this object.

• Avoid the use of an exception from a different framework component in a try-except construction.

• Always send exceptions to the Publisher.

• Use the Messaging component instead of displaying dialogue screens.

• When making changes to SRWLib, recompile all components.

• Never use text in source code, refer instead to a resource string from a unit with constants.

• Only use SRWLib in a Delphi project search path. Do not use directories from other framework components.

• If a framework component uses other files (data, dll, etc), include these in the ‘Additional files’ section of a ComponentDescriptor.

• Use of ‘as’ for typecasting is not possible if an object has been created in a different framework component. In this case, use C-style typecasting (hard typecasting, ConcreteClass(AbstractClass).getName, for example).

• Create a documentation header for each class and operation.

• Use the standard name conventions (see Chapter 8).

• Only use external (Delphi or ActiveX) components if the source code is available. An run time creation of components which do not form part of Delphi VCL ensures that installation of that component is not required for all other developers.

16


Version 1.1


5 Development of model applications

5.1 Introduction Within the GF architecture, a model application is part of BuildingFramework Components (BuildingFCs). A model application can therefore also be used as building blocks of a case. A model application differentiates from other BuildingFCs because it can offer a collection of connecting points. Each connecting point can demand and/or supply properties. The model application contains a wrapped computational unit. The model application must make it possible for this computational unit to be requested on the basis of time steps. To allow for data exchange between other model applications or generic tools, the specific model schematisation in the wrapper must be translated to the generic form of connecting points (model components) and properties (model attributes).

5.2 Phased planning Despite the diversity of models that can be included in GF, the migration process of these models to GF involves a large number of standard activities. When developing an GF model application, it is possible to base the development process on a number of source code units (in Delphi) whereby further developments can be applied from within the actual model application. This source code can be viewed as a set of functions (grouped in classes) containing default implementations. A number of default implementations must be overwritten to allow specific functions, although a majority of these functions are general and require no modification therefore. The implementation of a model application can be divided into the following phases (each phase is explained in further detail in the next section): 1. Definition of project source 2. Implementation of project source 3. Implementation of model elements and connectors 4. Implementation of ModelApplication operations

a. Modification of class names in interface and implementation b. Development of SchematisationCreator c. Development of PropertyEditor d. Implementation of Init operation e. Implementation of Start operation f. Implementation of Finalize operation g. Implementation of Check operation h. Implementation of Load operation i. Implementation of Save operation

17


Version 1.1


5. Link with calculation unit a. Communication b. Error processing c. Memory control

6. Testing a. Registration in the framework b. Composing a case c. Property editor d. Simulation e. Memory use

5.3 Realisation of a model application Realisation of a model application can be achieved using the phased planning shown in the previous section. There is a default Delphi project available from which the development starts, called DefaultModelApplication.dpr, and can be read in Delphi 5.

5.3.1 Phase 1: Definition of project source After reading the DefaultModelApplication.dpr project in Delphi, both the project and the units included be saved under a different name. In a standard situation, the term ‘default’ will be replaced by a more suitable term (such as Modflow). Following this phase, the files DefaultModelApplication.dpr, fDefaultPropertyEditor.pas, fDefaultPropertyEditor.dfm, uDefaultModelApplication.pas and uDefaultSchematisation.pas will be renamed, for example, ModflowModelApplication.dpr, fModflowPropertyEditor, etc. The project standardly contains correctly set search paths so that all SRWLib units can be found, for example. This can be checked by comparing the display which is shown after the Project|Option menu option with the screen dumps of Appendix B.

5.3.2 Phase 2: Implementation of project source The source code of DefaultModelapplication.dpr project file contains standard implementations of the operations:

InitModelApplication

GetModelApplicationXML

These operations must be modified in order to assign individual behaviour to the model application2.

a) InitModelApplication

2 Tip: search the term ‘default’ in the project file and replace it by a specific model name, such as SOBEK or DUFLOW.

18


Version 1.1


This operation is used during the instantiation of a model application. An object of the type TDefaultModelApplication is created in the default implementation. This type must be replaced with the class in which the specific model application is implemented (for example, TSwapModelApplication). function InitModelApplication(aFramework: TIFramework; aComponentReference: TComponentReference):

TIModelApplication; export;stdcall;

begin

try


Result := TDefaultModelApplication.Create(aFramework,

aComponentReference);

except

Result := nil;

end;

end;

b) GetModelApplicationXML

This operation includes all required meta-information of the model application in XML format. This information is used during the registration of a component. The XML string must be modified so that the framework can check which component it concerns. The XML structure consists of two elements: <header> and <contents>. The <header> does not have to be modified, whereas a number of changes will have to be made to the <contents>. XML comprises a number of so-called tags (similar to those used in HTML), which contain a value or a new tag. GF anticipates tags in certain places (according to a set hierarchy). It is therefore important not to change this hierarchy. The XML string standardly comprises the following tags and values (the line numbers have been added for text reference). 01 <SRWXML> 02 <HEADER> 03 <VERSION>1.0</VERSION> 04 <ACCESS>atReadOnly</ACCESS> 05 </HEADER> 06 <CONTENTS> 07 <COMPONENTDESCRIPTOR> 08 <NAME> 09 <TDESCRIPTION>DefaultModelapplication</TDESCRIPTION> 10 </NAME> 11 <VERSION>1.0</VERSION> 12 <SIZE>50</SIZE> 13 <CREATOR> 14 <TOWNER> 15 <COMPANY> 16 <TDESCRIPTION>Default Company</TDESCRIPTION> 17 </COMPANY> 18 <AUTHOR> 19 <TDESCRIPTION>Default SoftwareEngineer</TDESCRIPTION> 20 </AUTHOR>

19


Version 1.1


21 </TOWNER> 22 </CREATOR> 23 <DATE>01/01/2000</DATE> 24 <TYPE>ctBuilding</TYPE> 25 <ACCES>atNormal</ACCES> 26 <ICON> 27 <TURL>Default.ico</TURL> 28 </ICON> 29 <ADDITIONALFILES> 30 </ADDITIONALFILES> 31 <CREATEOPTION>coManual</CREATEOPTION> 32 <COMPONENTMODEL>cmDLL</COMPONENTMODEL> 33 </COMPONENTDESCRIPTOR> 34 <SERVICES> 35 <SERVICEDESCRIPTOR> 36 <NAME> 37 <TDESCRIPTION>snModelApplication</TDESCRIPTION> 38 </NAME> 39 <TYPE>stData</TYPE> 40 <PART>spProvide</PART> 41 </SERVICEDESCRIPTOR> 42 <SERVICEDESCRIPTOR> 43 <NAME> 44 <TDESCRIPTION>snProcessManager</TDESCRIPTION> 45 </NAME>' 46 <TYPE>stEvent</TYPE> 47 <PART>spNeed</PART> 48 </SERVICEDESCRIPTOR> 49 </SERVICES> 50 </CONTENTS> 51 </SRWXML>

The following details must be entered in the XML string:

• Component name Line 9 of XML structure. The name “DefaultModelApplication” can be replaced by a new name within the TDescription-tag. Spaces may be applied, unlike the characters “<” and “>”.

• Version Line 11 of XML structure. The version number can be entered between the Version tags.

• File size Line 12 of XML structure. The DLL size can be entered. This version does not use Size tags. Entry/modification is not required therefore.

• Manager/owner/contact Company and contact names can be entered for software managers of a component.

<TOWNER> <COMPANY> <TDESCRIPTION>Default Company</TDESCRIPTION> </COMPANY> <AUTHOR> <TDESCRIPTION>Default Software Engineer</TDESCRIPTION> </AUTHOR>

20


Version 1.1


</TOWNER>

These details can be entered in the TDescription tags (see line 16 and 19 in XML structure).

• Date Line 23 of XML structure. The DLL compilation date can be entered in the Date tags. The same date format but must be used as the existing one (dd/mm/yyyy). GF’s internal process always uses this format, regardless of specific PC settings.

• Component type The component type indicates which FrameworkComponent subclasses are implemented in the DLL: BasicFrameworkComponent (BasicFC) or BuildingFrameworkComponent (BuildingFC). A model application always derives from a BuildingFC. For this reason, its standard details may not be overwritten.

• Access type An access type records whether a component is physically restricted to one location or whether it is allowed to be copied. Version 1.0 only uses the ”atNormal” type and therefore it does not have to be modified.

• Icon name An icon of 32x32 pixels can be incorporated in the model application which can be used in the framework and the ProcessManager, for example. The name of this icon (*.ico) can be entered in the Icon tag.( line 27).

<ICON> <TURL>Default.ico</TURL> </ICON>

The XML structure uses relative paths, based on the DLL location. If no path is given, as is the case with the default icon name, it is assumed that the icon is from the same directory as the DLL.

• Names of possible additionally required files Additional files can be used in the DLL (for example, a DLL functioning as a computational unit). These dependencies must be included in the XML structure (line 29/30).

'<ADDITIONALFILES>' '</ADDITIONALFILES>'

Standardly, no additional files are included. If this is required, the file name(s) must be entered in the Additional Files tag. A file name in GF is regarded as a TURL type. If the files “Rekenkern.DLL” (computational unit) and “Database.DBF” are required, the Additional Files tag will appear as follows:

<ADDITIONALFILES> <TURL>Rekenkern.DLL</TURL> </ADDITIONALFILES> <ADDITIONALFILES> <TURL>Database.DBF</TURL> </ADDITIONALFILES>

• CreateOption

21


Version 1.1


Line 31 of XML structure. The so-called CreateOption can be defined. The “coManual” and “coAuto” types are available. A component of the coAuto type is automatically instantiated when activating the framework “Design mode” (the mode in which a case can be composed). A model application may only be instantiated during the initialisation of a simulation. For this reason, the coManual type cannot be modified.

• Component model At present, only DLLs in the framework are registered, indicated by the component model type cmDLL. This is a standard type used in version 1.0 of GF, and should therefore not be modified.

• Required and provided services Each framework component provides at least one service. A model application provides the “model application” service. Internally, the “snModelApplication” type is used for this purpose. In addition, it is possible that a component only functions if another component can provide a certain service. For example, a model application cannot function without the ‘ProcessManager’ service. Internally, this service is typified as ‘snProcessManager’. These dependencies must be recorded in the XML structure. The default dependencies of a model application are shown in the XML structure (lines 34 to 49). Additional services that are required or supplied can be added here. All different services are included in the uConsts.pas code unit of SRWLib.

<SERVICES> <SERVICEDESCRIPTOR> <NAME> <TDESCRIPTION>snModelApplication</TDESCRIPTION> </NAME> <TYPE>stData</TYPE> <PART>spProvide</PART> </SERVICEDESCRIPTOR> <SERVICEDESCRIPTOR> <NAME> <TDESCRIPTION>snProcessManager</TDESCRIPTION> </NAME>' <TYPE>stEvent</TYPE> <PART>spNeed</PART> </SERVICEDESCRIPTOR> </SERVICES>

5.3.3 Phase 3: Implementation of model elements and connectors In GF, a schematisation of a model application is viewed as a network of connected model components. Firstly, a distinction is made between nodes and connections between nodes: Model elements and Connectors Secondly, the possibility of aggregations is also a distinguishing feature. A model component which contains model components itself is a composed model component. Such a composed variant exists for both a Model element and a Connector: the CompositeModelelement and the CompositeConnector. If a model component does not contain any

22


Version 1.1


elements, its form is considered to be singular and the applicable options are the SingleModelelement and the SingleConnector. When developing a model application, model elements and connectors must be designed for it. This means a distinction must be made between the different types. Each type is a subclass of CompositeModelelement, CompositeConnector, SingleModelelement or SingleConnector. Examples of such an element are a pump, a soil layer, the atmosphere and a surface water sector. For each distinguished type, the following must be established:

• Which superclass applies to the type?

• If this is a composed element: which types of elements can be part of the type?

• Which attributes are contained in the type? Each model component can contain attributes. For example, a surface water sector may contain attributes such as water height, length and slope angle. Each attribute is implemented as a subclass of the ModelAttribute type. After designing all model component types and corresponding attribute types, these types must be implemented as classes in Delphi. The uDefaultSchematisation unit is the standard unit in the DefaultModelApplication project. A number of example model components and attributes are included in this unit. This code has no function in the implementation of a specific model application, of course. The code can therefore be removed or modified in comments, so that it can serve as an aid when implementing specific classes. The implementation of model components and attributes can be carried out in the following phases: a) Specification of ModelComponent

During model component specification, it must be determined which superclass will be applied. In the example below, the “TTestCompositeModelElement” model component is derived from the CompositeModelElement class.

TTestCompositeModelElement = class(TCompositeModelElement) private FSinus, FConstant: TModelAttribute; public constructor Create(aID: LongInt; aGeometry: TGeometry; aBuildingFC : TBuildingFrameworkComponent); destructor Destroy; override; function GetDescription: TDescription; override; function GetAttributes: TIterator; override; end;

A list of attribute names can then be specified in the “private-part” of the class definition. In the above example, the attributes “FSinus” and “FConstant” are specified.Following class specification, its implementation must then be carried out. In the class

23


Version 1.1


“TestCompositeModelelement” shown in the example above, the following implementation is applied (line numbers have been added for specific code reference):

01 { TTestCompositeModelElement } 02 03 constructor TTestCompositeModelElement.Create(aID:LongInt; 04 aGeometry:Tgeometry; aBuildingFC :

TBuildingFrameworkComponent); 05 begin 06 inherited Create(aID, aGeometry, aBuildingFC); 07 FSinus:= TSinusAttribute.Create(self, 'SinusAttribute'); 08 FConstant := TConstantAttribute.Create(self, 'ConstantAttribute'); 09 end; 10 11 destructor TTestCompositeModelElement.Destroy; 12 begin 13 FSinus.Destroy; 14 FConstant.Destroy; 15 inherited; 16 end; 17 18 function TTestCompositeModelElement.GetAttributes: TIterator; 19 begin 20 Result := TSingletonIterator.Create(FSinus); 21 Result := TCombinedIterator.Create(Result, 22 TSingletonIterator.Create(FConstant)); 23 end; 24

25 function TTestComposModelElement.GetDescription: TDescription; 26 begin 27 Result := 'TestCompositeModelelement' + IntToStr(GetID); 28 end; 29

The attribute objects must be created in the constructor. An example of attribute creation is shown in lines 7 and 8. As validation, the attribute name is supplied. Objects created in the constructor must be removed again in the destructor. This also applies to attribute objects. An example of attribute destruction is shown in lines 13 and 14. A list of all attributes can be requested for each model component. The GetAttributes operation is applied for this purpose. An Iterator object is given as the result of this function. The attribute list is therefore not displayed, but an object used to browse the list. This Iterator object must be completed during the implementation of this operation. An example of this implementation is shown in lines 20 and 21. If a model component does not contain any attributes, the operation implementation is as follows:

Result := TemptyIterator.Create;

The name of a model component can be requested using the GetDescription operation. Line 27 of the above implementation shows the result of this. The name “TestCompositeModelcomponent” must be replaced by a specific name. Two types of attributes can be distinguished within the framework: An attribute object can either supply values or require/use values.

24


Version 1.1


Consequently, the lists of ‘supplying’ and ‘receiving’ attributes are subsets of the total attribute list. The GetProvidedAttributes and GetRequiredAttributes operations must provide these subsets as a result, in the form of an Iterator object. Default implementations for these operations are included in the ModelComponent class. These implementations provide a list of supplying or requesting attributes as a result. Specification of ModelAttribute

Each attribute allocated to a ModelComponent type must be implemented as a subclass of ModelAttribute. An example attribute is specified in the following code fragment: TSinusAttribute = class(TModelAttribute) public function CanProvide: Boolean; override; function GetValue(aTime: TSrwTime): Double; override; function GetValue(aTime: TSrwTime; aValue: Double): TOperationResult; override; function GetType(): TAttributeType; override; function GetSource(): TSourceType; override; function GetUnitOfMeasurement : TunitOfMeasurement; override; end;

The general ModelAttribute class, offers a default implementation for a number of functions. These functions only have to be overwritten if another implementation applies for this attribute. In the above example, the default implementation is used for the following functions (and are therefore not included in the interface):

function GetName: TDescription; function IsRequired: Boolean; virtual; function CanUse: Boolean; virtual; function HasExchangeItems: Boolean; function AddExchangeItem(aExchangeItem: TExchangeItem): TOperationResult; function GetProvidingExchangeItems: TIterator;

The default implementations are included in the ‘uModelAttribute.pas’ unit of SRWLib. Functions which do not contain implementations in this class (abstract operations) or require another implementation, must be included in the relevant subclass. In the example of TsinusAttribute, this is applied to seven functions.

5.3.4 Phase 4: ModelApplication implementation operations The object that uses the connecting points with corresponding attributes and is responsible for controlling the computational unit, is an instance of (a subclass of) ModelApplication. This DefaultModelApplication class is included in the default project and received a new name in a previous phase.

01 TDefaultModelApplication = class(TModelApplication) 02 private 03 04 FEndTime, FStartTime: TSrwTime; 05 protected 06 procedure CreateSchematisation;

25


Version 1.1


07 function CheckAttributes(aModelComp:TModelComponent):Boolean; 08 public 09 constructor Create(aFramework: TIFramework; 10 aComponentReference: TComponentReference); 11 destructor Destroy; override; 12 { BuildingFrameworkComponent } 13 function HasPropertyEditor: Boolean; override; 14 function Edit: TOperationResult; override; 15 function Save(aSRWDataObject : TISRWDataObject) : TISRWDataObject; override; function Save(aSRWDataObject : TISRWDataObject) : TOperationResult; override; 16 function Check: Boolean; override; 17 function Init: TOperationResult; override; 18 function Start(aStartTime,aEndTime:TSrwTime;aTraceID:LongInt): 19 TOperationResult; override; 20 function GetStartTime : TSrwTime; override; 21 function GetEndTime : TSrwTime; override; 22 { ModelApplication } 24 function GetNextTime: TSRWTime; override; 25 function Finalize: TOperationResult; override; 26 end;

The above example shows the default class, which must be successively modified in the following locations: a) SchematisationCreator

This CreateSchematisation operation (line 6 of above code fragment) is used to create all connecting points with corresponding attributes. All connecting points must be available following the creation of the model application, which means the CreateSchematisation operation is used in the constructor of this class. The development of the schematisation consists of the following stages: • Create the connecting points and connectors;

• If logical, link the connecting points using the connectors;

• Add all connecting points and connectors to the “FComponents” collection. This collection is part of each model application.

The geometry of connecting points and connectors must be known for the creation of these components. This geometry is required as argument in the constructor of both model components and connectors. Objects of the TGeometry type are used for the geometry. These objects comply with OpenGis specifications and contain the additional function of GML string formulation.

b) Property Editor If an editor is available, the HasPropertyEditor operation must be overwritten with the implementation (line 13):

Result := True;

The editor can be requested using the Edit operation. This operation creates and displays the corresponding form, as well as removing the form. The following code can be applied for this: var lPropertyEditor: TfrmDefaultPropertyEditor;

26


Version 1.1


try lPropertyEditor := TFrmPropertyEditor.Create(Application); try lPropertyEditor.ShowModal; if lPropertyEditor.ModalResult = mrOK then begin { only result success if the user didn't cancel} Result := orSuccessful; end; finally lPropertyEditor.Free; end; //finally except Result := orFailed; end;

c) Init function The initialisation of the computational unit takes places using this operation (see line 17 of the example code fragment). During this process, a link is made with the computational unit. The exact execution depends on the computational unit. Following this operation, the model application should acquire the status “Initialized”. The ‘csInitialized’ type is applied in GF for this purpose. This state is standardly allocated in the default implementation of Init operation and can be used in specific model applications by adding the following statement to specific implementation of the Init operation:

Inherited Init;

d) Start function The execution of computational time steps is initialised with this function (line 18 in the example code fragment). The implementation delegates the computational unit concerned. In addition to controlling the computational unit, it is important that the correct status is allocated to the model application. Analogous to the Init operation, this is guaranteed if in the implementation the operation of the same name is requested from the superclass according to:

Inherited Start(aStartTime, aEndTime, aTraceID);

e) Finalize function The finalize operation is used to save the actual state of the model application and corresponding computational unit, so that a new initialisation can be carried out (line 25 of the example code fragment). An equivalent of this must therefore be available in the computational unit. In addition to this functionality, it is important that the new “NotInitialized” state is allocated eventually. This is available in the ModelApplication default implementation.

f) Checking current settings Prior to model application initialisation, the ProcessManager ensures that all model applications and connections in the case are checked. This means, for example, that each model application is checked to see whether all attributes which require a value for each time step also actually have a supplier (a different attribute). This check is implemented by the Check operation (line 16 of the previous code 27


Version 1.1


fragment). The verification of attributes is executed in the default implementation which uses the “protected” operation CheckAttributes.

g) Saving current settings A case can be saved using the DataEngine. A case is a set of model applications, generic tools and connections. By saving a case, the entire configuration is saved. Each model application is responsible for saving specific settings (for example, saving in the property editor). This functionality is achieved using the Save operation (line 15 of previous code fragment). The implementation has to be filled in per model application, which means no default implementation is available.

5.3.5 Phase 5: Link with computational unit The link between a model application (in the form of a DLL) and the computational unit can be achieved in a number of ways. The options directly depend on the form in which the computational unit is presented. The most obvious forms are an executable, a DLL or a COM server. A number of aspects are important here and can or must be arranged. a) Communication

The model application will have to start the computational unit in the INIT( ) operation and exit the computational unit in the FINALIZE( ) operation.

b) Error processing If the start and exit functions of a computational unit do not operate correctly, efficient error processing is vital. The computational unit must therefore be able to report to the model application to what extent a task has been successfully completed. It is important that the computational unit or model application do not sent error messages to the display or generate exceptions. The framework must be notified of possible errors and the standard event solution should be selected for this therefore (see Chapter 0).

c) Memory control Memory capacity allocated by a computational unit cannot be released by the framework. It is therefore important that space is released for loaded DLLs and interim results during the running of the FINALIZE operation.

5.3.6 Phase 6: Testing Needless to say, testing of a developed model application starts with the successful compilation of Delphi project without ‘hints’ and ‘warnings’. Testing the compiled DLL consists of:

a) Registering of the DLL in the framework Registering of the DLL in the framework application must occur without errors or warnings.

b) The addition of the model application to a case The addition of the DLL to the Composer of the ProcessManager must occur without errors or warnings.

28


Version 1.1


c) Using the Property editor If you have created a specific editor, the editor must be started using the ‘Component | Properties’ option and subsequently the Internal editor’ option.

d) Execution of a simulation If a case check (check option) does not present error messages, the model application must be able to execute the computational stages faultlessly during the interval specified.

e) Model application memory use Memory used by the model application for loading libraries or saving interim results during a simulation, must be released again in the Finalize operation. The frequent and consecutive execution of the same case may not cause an increase in the application’s memory use.

6 Development of generic tools

6.1 Introduction In addition to a model application, a generic tool is a specialisation of BuildingFrameworkComponent (BuildingFC). A generic tool differentiates from a model application, because this tool does not provide connecting points with attributes (a generic tool does not have a model schematisation). Examples of generic tools are a graph tool, a GIS viewer and an analysis tool. A generic tool performs one or a number of general tasks in a case.

6.2 Phased planning Compared to a model application, less straightforward phased planning can be provided for a generic tool. For example, the presentation of results in a graph requires a different implementation than the validation of results based on measurements. This is depicted in the phased planning below since details are applied to a lesser extent versus the planning for model applications. 1. Definition of project source 2. Implementation of project source 3. Implementation of BuildingFrameworkComponent operations

a. Creation of GenericTool subclass

b. Development of PropertyEditor

c. Implementation of Check operation

d. Implementation of Init operation

e. Implementation of Start operation

f. Implementation of Finalize operation

g. Implementation of Load operation

29


Version 1.1


h. Implementation of Save operation

4. Implementation of GenericTool operations a. Implementation of Get/Set Starttime operation b. Implementation of Get/Set Endtime operation c. Implementation of GetModelComponentByID operation

5. If relevant: Implementation of PresentationComponent operations

a. Implementation of AddAttribute operation

b. Implementation of RemoveAttribute operation

c. Implementation of GetAttributes operation

d. Implementation of GetModelComponents operation 6. Testing

6.3 Realisation of a presentation component The realisation of a generic tool can be achieved using the phased planning shown in the previous section. As with the model application, there is a default Delphi project available from which the development starts. During the development of a presentation component, the GraphTool project can also be used as an example.

6.3.1 Phase 1: Definition of project source This phase is identical to phase one of a model application development. The required Delphi project files must be created and saved under unique names. The easiest way to achieve this is to adapt the project file of the graph tool: Graphtool.dpr. If no presentation component is developed, the DefaultModelApplication project can be applied, which allows the units fDefaultPropertyEditor.pas, fDefaultPropertyEditor.dfm, uDefaultModelApplication.pas and uDefaultSchematisation.pas. to be removed. The project standardly contains search paths with correct settings in order to be able to trace all SRWLib units, for example. This can be checked by comparing the display which is shown after the Project | Option menu option with the screen dumps of Appendix B.

6.3.2 Phase 2: Implementation of project source The source code of the Graphtool.dpr project file contains standard implementations of the operations:

InitGraphtool

GetGraphtoolXML

30


Version 1.1


These operations must be modified in order to assign individual behaviour to the model application3. Operation names can be changed into more relevant names. From now on, the names InitGenericTool and GetGenericToolXML will be used.

a) InitGenericTool This operation is used during the instantiation of a generic tool. When Graphtool is implemented, an object of the TGraphtool type is created. This type must be replaced by the class in which the specific generic tool is implemented (for example, TGISViewer). function InitGenericTool(aFramework: TIFramework; aComponentReference: TComponentReference):

TGenericTool; export;stdcall;

begin

try


Result := TGenericTool.Create(aFramework,

aComponentReference);

except

Result := nil;

end;

end;

b) GetGenericToolXML

This operation is used to acquire all meta-information about the generic tool in XML format. This information is used during the registration of a component. The XML string must be modified so that the framework can check which component it involves. The XML structure consists of two elements: <header> and <contents>. The <header> does not need to be modified, whereas a number of changes will have to be made to the <contents>. The elements are identical to the XML description of a model application, which is illustrated in development phase two of a model application and can be applied for this.

6.3.3 Phase 3: Implementation of BuildingFC operations The generic tool which is developed must be a subclass of TGenericTool or TPresentationComponent. With this hierarchy, a number of standard operations must be applied in order to allow for specific functions. The first set of applicable operations are determined by BuildingFC interface.

a) Creation of GenericTool subclass The development starts by determining a new subclass. The name of this class must be similar to the name entered in phase 1a of the Delphi project file. If a presentation component is developed, the

3 Tip: search the term ‘default’ in the project file and replace it by a specific model name, such as SOBEK or DUFLOW.

31


Version 1.1


uGraphTool unit can be modified for the specific component. If no presentation component is developed, a new unit must be added to the project in which the class is recorded.

b) Development of Property editor If the generic tool uses a specific display, this is added as the so-called Property editor to the component. The hasPropertyEditor operation must be added to the specific class using the following implementation:

Result := True;

The user display can be added to the project as Delphi TForm. c) Implementation of Check operation

The Check operation must be applied via the relevant class. This operation is initiated by the ProcessManager, prior to a case being started. All necessary user settings entered, must be checked in this operation.

d) Implementation of Init operation The start of a simulation begins with the Init operation requesting each model application and generic tool in the case. Starting a tool or loading a database/file are typical elements that are carried out using the Init operation.

e) Implementation of Start operation The Start operation is requested by the ProcessManager during a simulation, to allow the component to execute a computational time step. Functionalities required during the simulation must be carried out in this operation. The results of linked models are read and added to line strings in the graph tool.

f) Implementation of Finalize operation After exiting a case, it is important that loaded files, allocated memory and initialised help files are released. This activity must be executed in the Finalize operation. In a graph tool, for instance, all read in results are removed from the graph.

g) Implementation of Load operation All settings that are specific to the component, but must be used again when opening a previously created case, must be saved and read by the component itself. The DataEngine functionalities can be used for this. The most simple solution is to modify the Load operation of the graph tool. How to use the DataEngine is described in detail in Chapter 7.

h) Implementation of Save operation As with reading specific component settings, the settings must be saved by requesting the Save operation. Use of the graph tool implementation as an example is recommended for this.

6.3.4 Phase 4: Implementation of GenericTool operations Based on the class hierarchy, the GenericTool operations must be carried out following BuildingFC operations.

32


Version 1.1


a) Implementation of Get/Set Starttime operations Using these operations, the start time can be requested and specified. Each specified time is standardly set without being checked. If the specific component does require checking however (because a component can only be used during a certain time interval) this monitoring function can be implemented in the Set operation.

b) Implementation of Get/Set Endtime operations Using these operations, the end time can be requested and specified. Each specified time is standardly set without being checked. If the specific component does require checking however (because a component can only be used during a certain time interval, for example) this monitoring function can be implemented in the Set operation.

c) Implementation of GetModelComponentByID operation In the case of a model application, connecting points can be requested based on an ID. In a generic tool, there are no schematisation connecting points. The Check operation must be implemented in the relevant class anyway. It is possible to give ‘nil’ as the result. A presentation component allows a special connection point as the result: a PresentationModelComponent.

6.3.5 Phase 5: Implementation of PresentationComponent operations If a presentation component is developed, the specific class is not directly derived from GenericTool, but from the subclass PresentationComponent. This subclass allows model application attributes to be introduced or removed (for inclusion in a graph, for example). The operations listed below must be carried out in this case:

a) Implementation of AddAttribute operation This operation is used to report a connecting point feature to a presentation component. In this case, a graph tool creates a line string for the attribute.

b) Implementation of RemoveAttribute operation This operation is used to cancel the reporting of an attribute. In the case of a graph tool, the corresponding line string will be removed again.

c) Implementation of GetAttributes operation A complete list of all component attributes reported to the presentation component must be given as the result in this operation. This result must be given as an Iterator object.

d) Implementation of GetModelComponents operation Needless to say, a presentation component does not have a model schematisation. However, this type of component gives a special connecting point, to which the reported attributes are linked: a PresentationModelComponent. This presentation connecting point allows links to be made between a model application and a

33


Version 1.1


presentation component using the SRW-Editor. When implementing this operation, the presentation model component must be given as the result (as Singleton iterator object, see SRWLib).

6.3.6 Phase 6: Testing Testing a developed generic tool starts, of course, with the successful compilation of Delphi project without ‘hints’ and ‘warnings’. Testing the compiled DLL consists of:

a) Registration of the DLL in the framework DLL registration must occur without errors or warnings in the framework application.

b) Addition of the model application to a case The addition of the DLL to the Composer of the ProcessManager must occur without errors or warnings.

c) Using the Property editor If a specific editor is created, it must be started using the ‘Component | Properties’ option and then ‘Internal editor’.

d) Execution of a simulation If a case check (check option) does not present any error messages, the generic tool must be able to execute the functionalities during the interval specified.

e) Generic tool memory use Memory used by the generic tool for loading libraries or saving interim results during a simulation, must be released again during the Finalize operation. The frequent and consecutive execution of the same case may not cause an increase in the application’s memory use.

7 Using data definitions

7.1 Introduction The DataEngine can be used to save (locations of) framework components data. The part of the DataEngine responsible for this, is the DataStore. In order to save data, the DataStore must have information about:

• Storage medium – Determines where data is stored, for example, in a file or a relational database. In GF, this storage medium is referred to as Device. XML Device is available in version 1 of GF. In other words, creation of data in XML files is supported.

• Storage structure – Before a Device can be used, it must be clear what data can be written in the Device and where it can be stored. In GF, this description is referred to as a DataDefinition. These DataDefinitions are written in XML.

The structure of Devices and DataDefinitions in the DataStore are shown in the figure below.

34


Version 1.1


DataEngine

DataStore

XML Device

SQL Device

Swap DataDef.

Duflow DataDef.

Figure 7.1 – Devices and DataDefinitions

7.2 Reading and writing of data Reading and writing data from and to the DataEngine is executed using a standard procedure. When writing data, an object is ‘filled’ with data and offered to the DataEngine. When reading data, an object ‘filled’ with data’ is received by the enquirer. This object is an instance of the SRWDataObject class. It contains the data to be read or written, and also includes the DataDefinition.

Model application

SRWDataObject

DataEngine

DataDefinition

DataList

Figure 7.2 – Reading and writing data with an SRWDataObject

7.2.1 DataDefinition A DataDefinition comprises a header and a definition part. The XML structure below illustrates the basis of each DataDefinition.

<SRWXML>

<HEADER>

<NAMEID>unique datadefinition name</NAMEID>

<TDESCRIPTION>description</TDESCRIPTION >

<VERSION>datadefinition version</VERSION>

<DEVICE>device name</DEVICE>

<SCOPE>datadefinition validity</SCOPE>

<OWNER>

<COMPANY>company name</COMPANY>

<AUTHOR>responsible body</AUTHOR>

35


Version 1.1


</OWNER>

</HEADER>

<SRWDEFINITION>

….

</SRWDEFINITION>

</SRWXML>

The data structure is entered in the SRWDEFINITION tags. This structure can be defined in two ways:

• Defined as Data structure A data structure, indicated as SRWSTRUCTURE, can contain singular data, such as a string, integer or floating point value. To save multiple strings or numbers, several SRWStructures can be included in one DataDefinition. The structure of SRWStructure is as follows:

<SRWSTRUCTURE>

<NAMEID>unique name</NAMEID>

<TYPE>data type (string, integer, double, datetime or boolean)</TYPE>

</SRWSTRUCTURE>

Optionally, LENGTH and PRECISION tags can be added. This can be important when applying a SQL device, for example.

• Defined as Data list In addition to singular values, list of values can also be used. So-called DataLists are used for this purpose. A DataList of a DataDefinition is a reference to another DataDefinition. A list of objects can be saved in the DataDefinition for this reference. The XML structure below is applied for this:

<SRWLIST>

<NAMEID>unique name of data definition that is being referred to</NAMEID>

</SRWLIST>

7.2.2 SRWDataObject Exchange of data using a DataEngine is executed using a generic object: an SRWDataObject. In order to retrieve data, a framework component must offer the DataEngine with an ‘empty’ SRWDataObject. The Data Engine subsequently ‘fills’ the object with the required data. This process runs in reverse when saving data. A framework component never directly approaches the DataEngine, because a framework component never has a reference to the DataEngine. It therefore requests a service from the framework - the ‘DataDefinition’, in this case. The DataEngine will be located for this service by the framework in order to enable the service enquirer to use the DataEngine after all. The code fragment below illustrates in detail how the DataEngine is approached.

try

// create a ServiceDescriptor

36


Version 1.1


lServiceDescriptor := TserviceDescriptor.Create(snDataDefinition, stData, spNeed);

try

Search DataEngine with ServiceDescriptor

lDataEngine := TIDataEngine(Fframework.CreateServiceProvider(lServiceDescriptor));

if not (lDataEngine = nil) then

begin

// do something with the DataEngine

end;

finally

lServiceDescriptor.Free;

end;

except

Fframework.Notify(cRaiseError, cDoSomethingWhenFailed);

end;

For each SRWDataObject sending data to and from the DataEngine, it must be indicated which DateDefinition is used. A DataDefinition can be requested as follows:

lDataDefinition := lDataEngine.GetDataDefinition( cNameIdOfDataDefinition );

As soon as the DataEngine and DataDefinition are known to a framework component, an SRWDataObject can be created. An SRWDataObject comprises the following interface:

• SetParent(aSRWDataObject: TISRWDataObject)

Puts a reference to the SRWDataObject which this object is part of.

• GetParent()

Provides a reference to the SRWDataObject which this object is part of.

• GetCaseID()

Gives a unique identification of the case in which the SRWDataObject is used.

• GetDataDefinition()

Provides the DataDefinition on which the data exchanged by the SRWDataObject is based.

• GetDataValues()

Provides a reference to the collection of DataValue objects.

• GetDataLists()

Provides a reference to the collection of DataListDefinition objects.

• GetChildInstance(aDataDefinition: TIDataDefinition)

Creates a new sub-SRWDataObject. The object itself becomes the parent of the new subobject.

• ValueByName(aNameID: TNameID)

Provides a reference to the DataValue object belonging to the aNameID name.

A SRWDataObject comprises two lists:

37


Version 1.1


• a list of singular values (DataStructures)

• a list of composed values (DataLists) A singular value is saved in a DataValue object. This object contains the value and the value type (integer, string, boolean or double). DataLists are applied for composed values. A DataList contains a reference to another DataDefinition. The collection of such DataLists are saved in an SRWDataObject list, this list uses DataListDefinition objects. A DataListDefinition object contains a new DataDefinition and a list of corresponding SRWData objects.

7.2.3 Scope of a DataDefinition Each DataDefinition has a certain scope. The following distinctions are made:

• SRW – The DataDefinition applies to each case (for example, a reference to an executable in a model application).

• Case – The DataDefinition applies to a particular case (for example, the start and end time of a model application).

• Object – The DataDefinition applies to one component in a particular case (for example, the output file name of a model application).

7.3 Data definitions for model applications A model application must have a DataDefinition, so that all model application settings can be re-used when opening a previously created case. Obvious settings are:

• Start time of case model;

• End time of case model;

• Computational time step of model;

• Input file name;

• Output file name; If the above data are included in a DataDefinition, this definition may appear as follows:

<SRWXML>

<HEADER>

<NAMEID>MODELAPPLICATIONINSTANCE</NAMEID>

<TDESCRIPTION>ModelApplication properties</TDESCRIPTION>

<VERSION>0.1</VERSION>

<DEVICE>XML</DEVICE>

<SCOPE>OBJECT</SCOPE>

<OWNER>

<COMPANY>SRW B.V.</COMPANY>

<AUTHOR>SRW Employee</AUTHOR>

38


Version 1.1


</OWNER>

</HEADER>

<SRWDEFINITION>

<SRWSTRUCTURE>

<NAMEID>STARTTIME</NAMEID>

<TYPE>Double</TYPE>

</SRWSTRUCTURE>

<SRWSTRUCTURE>

<NAMEID>ENDTIME</NAMEID>

<TYPE>Double</TYPE>

</SRWSTRUCTURE>

<SRWSTRUCTURE>

<NAMEID>TIMESTEP</NAMEID>

<TYPE>Double</TYPE>

</SRWSTRUCTURE>

<SRWSTRUCTURE>

<NAMEID>INPUTFILE</NAMEID>

<TYPE>String</TYPE>

</SRWSTRUCTURE>

<SRWSTRUCTURE>

<NAMEID>OUTPUTFILE</NAMEID>

<TYPE>String</TYPE>

</SRWSTRUCTURE>

</SRWDEFINITION>

</SRWXML>

Each model application is responsible for loading this data upon initiating and for saving the data upon exiting. Each model application therefore contains Load() and Save() operations. These operations can be carried out as follows for the above example:

Load: // execute default implementation Result := inherited Load(aSRWDataObject); lDataDefinition := nil; // find DataEngine lServiceDescriptor := TServiceDescriptor.Create(snDataDefinition,stData,spProvide); try lDataEngine := TIDataEngine(FFramework.CreateServiceProvider(lServiceDescriptor));

if lDataEngine <> nil then begin lDataDefinition :=

DataEngine.getDataDafinition(cModelDataDefinitionNameID); end;

finally lServiceDescriptor.Free;

end; //finally if lDataDefinition = nil then exit;

39


Version 1.1


// load settings lSRWDataObject := TSRWDataObject.Create(lDataDefinition, FCaseID); lSRWDataObject.setObjectID(self.getObjectID); try lSRWDataObject := lDataEngine.ReadSRWData(lSRWDataObject); if lSRWDataObject <> nil then begin

lIterator := lSRWDataObject.GetDataValues; try while not lIterator.Done do begin

lDataValue := TDataValue(lIterator.NextElement); lNameID := lDataValue.getDataStructure.getNameId; if lNameID = cStarttime then begin

FSettings.Starttime := DoubleDataValue(lDataValue).GetValue; continue;

end; if lNameID = cEndtime then begin

FSettings.Endtime := TDoubleDataValue(lDataValue).GetValue; continue;

end; if lNameID = cTimestep then begin

FSettings.MinTimestep := TDoubleDataValue(lDataValue).GetValue; continue;

end; if lNameID = cInputFileName then begin

FSettings.InputFileName := TStringDataValue(lDataValue).GetValue; continue;

end; if lNameID = cOutputFileName then begin

FSettings.OutputFileName := TStringDataValue(lDataValue).GetValue; continue;

end; end; //while Iterator

finally lIterator.Free;

end; //finally end; // <> nil

finally lSRWDataObject.Free;

end; //finally Result := orSuccessful;

40


Version 1.1


Save:

// default implementation Result := inherited Save(aSRWDataObject); // find DataEngine lServiceDescriptor := TServiceDescriptor.Create(snDataDefinition,stData,spProvide);

try lDataEngine :=

TIDataEngine(FFramework.CreateServiceProvider(lServiceDescriptor));

lDataDefinition := lDataEngine.getDataDafinition(cSwapInstanceDataDefinitionNameID);

if lDataDefinition = nil then exit; finally lServiceDescriptor.Free;

end; //finally if (lDataEngine = nil) then exit; // Save settings if (Result <> nil) then begin RetrieveCaseID; lSRWDataObject := TSRWDataObject.Create(lDataDefinition, FCaseID); lSRWDataObject.setObjectID(self.getObjectID); lIterator := lSRWDataObject.GetDataValues; try

while not lIterator.Done do begin

lDataValue := TDataValue(lIterator.NextElement); lNameID := lDataValue.getDataStructure.getNameId; if lNameID = cStarttime then begin

TDoubleDataValue(lDataValue).SetValue(FSettings.Starttime); continue;

end; if lNameID = cEndtime then begin

TDoubleDataValue(lDataValue).SetValue(FSettings.Endtime); continue;

end; if lNameID = cTimestep then begin

TDoubleDataValue(lDataValue).SetValue(FSettings.Timestep); continue;

end; if lNameID = cInputFileName then begin

TStringDataValue(lDataValue).SetValue(FSettings.InputFileName); continue;

end; if lNameID = cOutputFileName then begin

TStringDataValue(lDataValue).SetValue(FSettings.OutputFileName); continue;

end; end; //while Iterator

finally lIterator.Free;

41


Version 1.1


end; //finally lDataEngine.WriteSRWData(lSRWDataObject); lSRWDataObject.Free;

end;

7.4 Data definitions for generic tools A generic tool must have a DataDefinition, so that all tool settings can be re-used when opening a previously created case. Obvious settings are:

• Start time of case generic tool;

• End time of case generic tool;

• Colours used in a graph or map, for example. Once again, a DataDefinition in XML format must be created. This structure is analogous to a DataDefinition of a model application. The Load and Save operations of a generic tool must be carried out, in order to ensure that the DataDefinition is actually applied during loading and exiting a case. The implementation is identical to the Load and Save operations of a model application.

8 Standards and name conventions

8.1 Introduction Standardisation enables products from various ‘suppliers’ to be exchanged. GF is developed with this in mind. The standardisation of framework component interfaces makes this exchange process possible. Besides this interface standardisation, additional agreements may accelerate the insight of the structure and operation of framework components. The standards created during the implementation of GF version 1, concern XML and name conventions in Delphi.

8.2 Use of XML How to use XML is described in section 3.4. XML is extremely suitable for exchanging and, in particular, describing data. The rapid increase of XML usage and its prominent position in recent developments, such as .NET technology, affirm the power of this language. Application of XML is particularly important to component builders when creating a DataDefinition. This DataDefinition describes which framework component data must be saved for future use. In GF version 1, the MSXML parser (version 2.5) is used which provides GF with sufficient options. Updates of this parser are being released under new names (because the version number is included in the DLL name), to make parallel use of other XML parsers possible.

42


Version 1.1


8.3 Name conventions At least the interface must be written in Delphi in order to program framework components. The structure of this code is more or less identical for all framework components. It is therefore logical to use this code of other framework components. The use of certain name conventions will increase code readability. The name conventions applied in GF are shown in the table below.

Table 1 – Name conventions GF Delphi code

Code element Prefix (case sensitive) Example

Constant c cFileName

Type (class) T TMyObject

Enumeration (set) T TMyOption

Local variable l lString

Unit variable u uStatus

Global variable g gInifile

Argument a aOwner

Property F FMyObject

Read/Write operation

Get/Set GetName/SetName

Form f fMain

Data module d dCustomers

Unit u uMyClass

43


Version 1.1


9 References [GAMMA, 1995] Gamma, E., R. Helm, R. Johnson, and J. Vlissides, Design Patterns: Elements of Re-usable Object-Oriented Software, Addion-Wesley, Reading, MA 1995 [GF-PoA] Supervisory Committee for Realisation of the Generic Framework, Plan of Approach, Specification and Realisation of version 1 of the GF, 11-01-2000 [GF-A] Wal, T. Van der (ed.), Architectural Design of the Generic Framework, GF Consortium, March 2000 [GF-FD] Tacke, J.H.P.M. (MX.systems BV), Brinkman, R. (WL | Delft Hydraulics),

Frieswijk, E. (EDS International BV), Levelt, D. (WL | Delft Hydraulics), Otjens, T. (W!SL / Alterra), 2000, SRW2000 Generic Framework – version 1.0 Functional Design version 1.1, ISBN 90-5773-141-x, Foundation of Applied Water Research, report2001-29, Directorate-General for Public Works and Water Management, Institute of Inland Water Management and Waste Water Treatment (RIZA), Lelystad, The Netherlands, report 2001.037, 27 p.

[GF-TD] Tacke, J.H.P.M. (MX.Systems BV), Brinkman, R. (WL | Delft Hydraulics),

Frieswijk, E. (EDS International BV), Levelt, D. (WL | Delft Hydraulics), Otjens, A.J. (W!SL/Alterra), 2001, Generic Framework – version 1.0, Technical Design version 1.1, ISBN 90-5773-142-8, Foundation for Applied Water Research (STOWA), Utrecht, report 2001-W-06, Directorate-General for Public Works and Water Management, Institute of Inland Water Management and Waste Water Treatment (RIZA), Lelystad, report 2001.125X, 51p.

44


Version 1.1


Appendix A: Contents of SRWLib Component Unit name Classes included

uBasicFrameworkComponent TBasisFrameworkComponent

uBuildingFrameworkComponent TBuildingFrameworkComponent

uCase TCase

uCaseVisualisation TCaseVisualisation

uComponentDescriptor TComponentDescriptor

TFileObject

uCondition TCondition

uConnection TConnection

uConverter TConverter

uDataStructure TDataStructure

TDataStructureList

TDataValue

TDataValueList

TDataValue subclasses for defining a DataDefinition (see uIDataDefinition)

uEmptyComponentReference TEmptyComponentReference

uFrameworkComponent TFrameworkComponent

TComponentReference

uGenericTool TGenericTool

uGeometry TGeometry

TWKSPoint

TWKSLineString

uICaseManager TICaseManager

uIDataDefinition TIDataDefinition

TIDataDefinitionList

uIFramework TIFramework

uIMessages TISRWMessages

uIProcessManager TIProcessManager

uISrwData TISrwData

uModelApplication TModelApplication

uModelApplicationInterface TIModelApplication

uModelAttribute TModelAttribute

TExchangeItem

SRW interface

uModelComponent TModelComponent

45


Version 1.1


Component Unit name Classes included

uModelElement TModelElement

TConnector

TCompositeConnector

TSingleConnector

TCompositeModelElement

TSingleModelElement

uObserver TPublisher

TInternalSubject

TSubscriber

TSubscription

TSubscriptionList

TSubjectList

TInternalSubjectList

TSubscriberList

uPosition TPosition

uPredicate TPredicate

uPresentationComponent TPresentationComponent

TPresentationModelComponent

TPresentationModelAttribute

uRootObject TRootObject

uServiceDescriptor TServiceDescriptor

uSrwData TSRWDataObject

TSRWDataList

TSRWDataListDefinition

uSrwEditInterface TISRWEditor

uUnitOfMeasurement TUnitOfMeasurement

TConversion

TConversionCollection

uConsts All resource strings used

uDLLIntf Standard functions for loading and releasing an SRW component in DLL format

uMainMenuButton Specific tool button, if a framework component wants to add a menu item to the framework application

uTypeDefinitions All types and enumerations used

Constants and basic types

uAggregationList TAggregationList Collections

and iterators uArrayIterator TArrayIterator

46


Version 1.1


Component Unit name Classes included

uAssociationList TAssociationList

uCollection TCollection

uCombinedIterator TCombinedIterator

uEmptyIterator TEmptyIterator

uFastAggregationList TFastAggregationList

uFastAssociationList TFastAssociationList

uIndexedCollection TIndexedCollection

uIndexedCollectionIterator TIndexedCollectionIterator

uIterator TIterator

uManagedAggregationList TManagedAggregationList

uSingletonIterator TSingletonIterator

uTempAssociationList TTempAssociationList

uTempIndexedCollectionIterator TTempIndexedCollectionIterator

MSXML_TLB Library type for MSXML.DLL (XML parser)

uEmptyXMLDocument TEmptyXMLDocument

uXMLDefinitions TXMLDefinition

TDescriptorDefinition

TRepositoryDefinition

uXMLDOM TXMLNode

TXMLDocument

XML and GML

uAddBuildingFCEvent TAddBuildingFCEvent

uConfirmEvent TConfirmEvent

uEvent TDistributedEvent

TSubject

uProgressEvent TProgressEvent

Events

uStatusEvent TStatusChangedEvent

Appendix B: Delphi Settings During the development of a model application or a generic tool for GF, a DLL is developed using the Delphi development environment. A Project is made in Delphi in order to compile a DLL. The source code for the DLL is implemented and compiled in this project. A standard project can be used in order to develop a model application: DefaultModelapplication. A number of settings can be applied for each Project in Delphi, which more or less influence the operation and behaviour of the definitive DLL. The

47


Version 1.1


screen dumps below illustrate the settings advised for GF components. A distinction is made between a DLL Debug version and a DLL Release version. In Delphi, Project settings can be requested using the menu option: Project – Options (or shift-ctrl-F11).

GF DLL Debug version settings (For tabs not shown, default Delphi settings are used)

48


Version 1.1


49


Version 1.1


GF DLL Release version settings (For tabs not shown, default Delphi settings are used)

50


Version 1.1


Appendix C: Commonly asked questions

• Can a framework component be developed in a language other than Delphi?

A framework component should be developed as a Dynamic Link Library (DLL). In principle, a DLL is language independent. So-called ‘calling conventions’ do exist for functions provided by a DLL. These calling conventions can be language specific. For example, a calling convention establishes how to read function arguments. ‘STDCALL’ is the selected GF calling convention. The fact that an object is the result of one of the functions offered by DLL (GF DLL interface only consists of two functions) applies specifically for GF framework components. The framework expects an object of a certain type, and must be able to check this. Since the framework is programmed in Delphi, it only recognises Delphi object types. This is the reason why the DLL must be compiled in Delphi. In the DLL, it is possible to use a different DLL or executable developed in a different language. A computational unit of a model application can, for example, be developed in Fortran or C, which means the interface to the framework is programmed in Delphi.

• Does GF support the use of distributed models? Due to the fact that a framework component must be available as DLL, framework components must be installed on the same computer as the framework application. The DLL is, however, able to create a connection with a computational unit at a different location using a self-

51


Version 1.1


selected communication protocol. In this way, heavy computational tasks can be performed at a different location (a server, for example). In this case, the framework only has contact with the local DLL, which functions as a so-called ‘Proxy’ therefore.

• Which requirements does my model have to meet in order to be able to migrate to an GF model application?

GF makes very few demands on a model. Since each model is ‘wrapped’ in an GF DLL, required conversions can be performed in this DLL. An example of this is the provision of a the connecting points of a model schematisation. A model can work with a specific model schematisation, the wrapper subsequently converts the data to the GF connecting points, the so-called ‘ModelComponents’. Required modifications to a model itself often concern the timekeeping included in existing model applications. Time control is operated by GF (the ProcessManager). GF must therefore be able to assign computational tasks with specific time intervals. After each computational time step (a day, for example), GF must be able to request results of the connecting point properties of that model. Model usage can be further facilitated through the development of a so-called ‘Property Editor’. Consequently, model specific settings can be set using GF.

• How can I adjust my model to GF specifications? There is a phased planning which describes how an existing model can be modified to GF specifications, as shown in Chapter 5 of this document. In general, the development comprises: 1. Entering standard DLL functions and compilation of the DLL;

2. Entering specific operation implementations of the interfaces FrameworkComponent, BuildingFrameworkComponent and ModelApplication;

3. Implementation of link with existing model

• Do I have to modify my specific format of input and output files before I can use my model in GF? No standards are defined for saving data in GF. It is possible to apply a standard as Adventus, a specific format can also be used. Despite the diversity of data formats, agreements are necessary to allow for the application of a generic DataEngine (used for saving (interim)results). The solution concentrates on a standard description of data formats, instead of a standard data format description. This means each format can be maintained, as long as it is written in the ‘GF way’. XML ( eXtensible Markup Language) plays an important role in this. A data format can be written using this language. Its structure is described in Chapter 7 of this document.

52