DCC. Domain Classes Coder. User Guide

Transcription

1 DCC Domain Classes Coder User Guide

2 Release Issue Date 1 2 June 2014 Copyright European Union, Reproduction is authorised, provided the source is acknowledged, save where otherwise stated. Where prior permission must be obtained for the reproduction or use of textual and multimedia information (sound, images, software, etc.), such permission shall cancel the above mentioned general permission and shall clearly indicate any restrictions on use. Disclaimer On any of the MARS pages you may find reference to a certain software package, a particular contractor, or group of contractors, the use of one or another sensor product, etc. In all cases, unless specifically stated, this does not indicate any preference of the Commission for that particular product, party or parties. When relevant, we include links to pages that give you more information about the references. Feel free to contact us, in case you need additional explanations or information. 2 DCC User Guide

3 Contents 1 Help contents 3 Credits Using DCC to generate code 5 About DCC Installing and launching DCC Workspace overview Loading or creating the file in DCC Opening an existing file Creating a new file Loading an existing Domain or Parameters class Generating the domain classes code Language reference 21 Classes description Multi language support

4 CONTENTS 2 DCC User Guide

5 Help contents 1 This Guide is targeted to advanced users of the BioMA Software Framework. In particular, this Help describes how to use DCC (Domain Classes Coder), a Windows application that allows generating C# and VB.NET (.NET 2.0 platform) code. The topics are organized as follows: Topic Using DCC to generate code on page 5 Language reference on page 21 Contents What DCC can be used for Installation procedure and workspace overview How to load or create a file for code generation How to generate the code An overview of domain classes, values classes, and VarInfo class. See also: BioMA Framework User Guide ( help/) Credits on page 4 Tip: To access the Web portal of BioMA go to DCC User Guide 3

6 1 HELP CONTENTS Credits The Domain Classes Coder was developed as an action of the FP6 project SEAMLESS (EU DG Research, contract no ). See ip.org Development and programming Marcello Donatelli Download This component is made available free of charge to non profit users. References Donatelli M. et al., 2006 SEAMLESS project deliverable Rizzoli, A.E., Davis, J.R., Abel, D.J A model management system for model integration and re use. Decision Support Systems, 4: Villa, F., M. Donatelli, A. Rizzoli, P. Krause, S. Kralisch, F. K. van Evert 2006 Declarative modelling for architecture independence and data/ model integration: a case study In: A. Voinov, A. Jakeman and A.E. Rizzoli (Editors), iemss Third Biannual Meeting Summit on Environmental Modelling and Software. International Environmental Modelling and Software Society, Burlington, USA DCC User Guide

7 Using DCC to generate code 2 This topic is organized into the following sections: About DCC on page 6 Installing and launching DCC on page 7 Workspace overview on page 8 Loading or creating the file in DCC on page 11 Generating the domain classes code on page 19 DCC User Guide 5

8 2 USING DCC TO GENERATE CODE About DCC The Domain Classes Coder (DCC) is a Windows application to generate C# and VB.NET (.NET 2.0 platform) code to be used as domain classes containing values and attributes for each variable used to model a given domain. Attributes are set via the type VarInfo, which implements a set of attributes to describe a variable: Name, MinValue, MaxValue, DefaultValue, Units, Type, Description, URL. The application targets at facilitating the labour consuming process of coding domain classes, in perspective using information retrieved via a web application from an online knowledge base linked to an ontology. A model component using domain classes encapsulates its relevant ontology. The set of attributes allows identifying univocally all the concepts (variables in component terms) used in a component. Such values can be used for general documentation, and for testing pre and post conditions, according to the design by contract approach. The content of domain classes can be either extracted from a centralized repository (via a web application which allows downloading an XML file), or defined in an Excel file and exported as a tab delimited file. Such files can be processed by DCC to produce the value and VarInfo classes code. If input data are provided via a tab delimited file, they can also be exported as an XLM file inclusive of schema. The component can be used both for tests of pre and post conditions in other components, and in applications, for field validation in user interface forms. If DCC is installed from the installation URL, every time the program is launched a check for updates is made. Related topics: Installing and launching DCC on page 7 Workspace overview on page 8 Loading or creating the file in DCC on page 11 6 DCC User Guide

9 INSTALLING AND LAUNCHING DCC Installing and launching DCC Prerequisites In order to install and run Domain Class Editor, the following prerequisites must be fulfilled: Hardware prerequisites Operative system: Windows XP/Vista/7 (32 or 64 bit) Software prerequisites The following software must be installed on your computer: NET 3.5 Framework To install it, go to net/. Follow the product s documentation, if needed. Regional Settings of your PC Ensure that the Regional Settings of your PC are set as follows: 1 Access the Windows Control Panel (Start > Control Panel > Clock, Language, and Region > Region and Language). 2 In the Region and Language window, click Additional settings. 3 Be sure that the Decimal symbol is set to point (.). Installation procedure Download it from the BioMA Components Web portal: 1 In your browser, go to default.aspx?productname=dcc/ 2 Select DCC, then click Install form URL and follow the instructions. Related topics: Workspace overview on page 8 Loading or creating the file in DCC on page 11 DCC User Guide 7

10 2 USING DCC TO GENERATE CODE Workspace overview The following shows the DCC workspace overview after a user launches the application, before loading or opening a file: The following table describes the main workspace items: Workspace item Open Domain class description Domain class loaded/to be extended Description This button allows opening a presaved XML file. When you open a file, the four fields that follow, as well as the properties within the table, are automatically assigned. (See Opening an existing file on page 11). A meaningful free text description. E.g.: Collection of variables to model soil water 1D using daily time step simulation models. The name of the new domain class that you specify when using the Load domain class from library and extend it option. (See Loading an existing Domain or Parameters class on page 16). 8 DCC User Guide

11 WORKSPACE OVERVIEW Workspace item Domain class name Name space URL Attributes table Code generation options Description The name you specify here (e.g., Crop, RadData) will be used for the value class, whereas the postfix VariInfo will be added to create the name of the VariInfo class (e.g., CropVarInfo, RadDataVarInfo). This must be the name space of the application being developed and which will implement the domain class (e.g., CRA.Clima.Rain.Interfaces). The Web address where the description of the domain type used is publicly available. The table becomes populated with the attributes if you use the Open button to load a presaved file. Otherwise, you must manually specify these attributes. (See Loading or creating the file in DCC on page 11 for further information). This area allows loading either a domain or a parameter class from a compiled DLL library by clicking the relevant button. (See Loading an existing Domain or Parameters class on page 16 for detailed instructions). Domain class A domain class includes both the inputs and the outputs, as well as the internal states of a strategy: Load domain class from library Click to upload an existing library and see/modify a domain class. Load domain class from library and extend it Click to upload an existing library, select a domain class to add properties. Parameter class A parameter class includes the parameters of a strategy: Load parameters class from strategy Click to upload an existing library and see/modify a domain class. Inputs, outputs, and parameters are described by the VarInfo property that the user defines when specifying the attributes in DCC. Inputs and outputs go into the domain class, while parameters go into the parameter class. DCC User Guide 9

12 2 USING DCC TO GENERATE CODE Workspace item Save xml Generate code About Exit Description Once you are finished, this button allows you to save your inputs as a XML file, which you can then reuse. When all fields and properties have been entered, this button allows generating the code (a domain class), which you can then use to create a modelling solution. See Generating the domain classes code on page 19. It provides information on the software release, as well as accessing this Help. It closes the application. Related topics: Loading or creating the file in DCC on page DCC User Guide

13 LOADING OR CREATING THE FILE IN DCC Loading or creating the file in DCC DCC can be used in three ways for code generation: Opening an existing file on page 11 Creating a new file on page 13 Loading an existing Domain or Parameters class on page 16 Generating the domain classes code on page 19 Opening an existing file You can open a file previously saved. You can then modify or add the attributes as needed and save the file with a new name for code generation. To open an existing file, do the following: 1 Click the Open button. Two types of files can be loaded: A Tab delimited ASCII file (.txt) as the ones which can be exported from Microsoft Excel. An XML with schema. 2 Browse to select the file and click Open. There are two possible scenarios: If you have loaded a Tab delimited file, you must specify the Domain class description, Domain class name, Namespace, and URL fields. (See Creating a new file on page 13 for a description of each field). If you have loaded an XML file, the four fields are already assigned. The following example shows DCC in case an XML file has been loaded: DCC User Guide 11

14 2 USING DCC TO GENERATE CODE 3 Edit the attributes as needed, and then do one or both of the following: To save the file with a new name for a future reuse, click Save XML. To generate the code of the domain class, click Generate code. (For further information, see Generating the domain classes code on page 19). See also: Creating a new file on page 13 Loading an existing Domain or Parameters class on page DCC User Guide

15 LOADING OR CREATING THE FILE IN DCC Creating a new file You can create a new XML file from scratch by manually entering the attributes in the DCC interface. In this case, you must also fill in all the fields. To create a new file: 1 Fill in the following fields in the upper part of the DCC window: Domain class description A meaningful free text description. Domain class name The name you specify here (e.g., Crop, RadData) will be used for the value class, whereas the postfix VariInfo will be added to create the name of the VariInfo class (e.g., CropVarInfo, RadDataVarInfo). NameSpace This must be the name space of the application being developed and which will implement the domain class (e.g., CRA.Clima.Rain.Interfaces). URL The Web address where the description of the domain type used is publicly available. 2 In the attributes table, specify the attributes for the domain class. Use the following as a reference. Note that all fields are mandatory: Attributes requirements: Attribute Name MinValue MaxValue DefaultValue Units Requirements Conventionally, it starts with an alphanumeric uppercase character. The minimum, maximum, and default values for the attribute. Note: These values are set to 0 in case of a nonnumeric Type. No VarIInfo values will be generated for non numeric types. The unit of measure used for the attribute. Note: Units are set to in case of a non numeric types. DCC User Guide 13

16 2 USING DCC TO GENERATE CODE Attribute Type Requirements This is critical for code generation. To view the allowed types, start typing into the Type field. The following popup will be displayed listing all types: Description URL Click the type you want to use to enter it in DCC and close the popup. Note that the dimension of Arrays must be specified. This is a free text description of the attribute. This is a unique locator for either a variable or for a domain type as stored in the Web ontology. If the input file to DCC is obtained downloading an XML from the Web application (under development) this field is provided like all the others; otherwise, URL can be a reference to other Web resources. 3 Once the attributes table is completed, do one or both of the following: To save the file for a future reuse, click Save XML, select the directory and enter the name for the file. To generate the code of the domain class, click Generate code (see Generating the domain classes code on page 19 for further information). 14 DCC User Guide

17 LOADING OR CREATING THE FILE IN DCC Related topics: Opening an existing file on page 11 Loading an existing Domain or Parameters class on page 16 Generating the domain classes code on page 19 DCC User Guide 15

18 2 USING DCC TO GENERATE CODE Loading an existing Domain or Parameters class You can generate the code by loading a Domain class or a Parameter class from an existing library (.DLL). After loading the library, you can select the Domain class you want to modify and then save it with a new name before generating the code. To load a class from library 1 At the bottom of the DCC window, select an option button: Domain class It includes all inputs, outputs, and internal states of a strategy. Parameter class It includes all parameters of a strategy. 2 There are two possible scenarios: a. If you select Domain class, the following buttons are displayed: b. If you select Parameters class, the following button is displayed: 3 These options allow you to: View and modify the attributes of an existing domain class, and then overwrite it (Load domain class from library). Add attributes to an existing domain class and then save it with a new name (Load domain class from library and extend it). View and modify the parameters of a strategy, and then overwrite it (Load parameters class from strategy). 16 DCC User Guide

19 LOADING OR CREATING THE FILE IN DCC To view and modify the attributes of a domain class: 1 Select the Domain class option button, then click Load domain class from library. 2 In the window that is displayed, select the library (.DLL) you want to select the domain class from and click Open. 3 In the Strategy class loader popup that is displayed, select the domain class from the dropdown box: 4 In the DCC window all attributes for that domain class will be displayed, which you can modify as required. 5 Once finished, click Generate code. As a result, the domain class will be overwritten with the new values. To add attributes to a domain class: 1 Select the Parameter class option button, then click Load parameters class from strategy. 2 In the window that is displayed, select the library (.DLL) you want to select the domain class from and click Open. DCC User Guide 17

20 2 USING DCC TO GENERATE CODE 3 In the Strategy class loader popup that is displayed, select the strategy from the dropdown box. As a result, in this case, no values will be displayed in the attributes table of DCC. 4 Add the attributes as required and then save the file. The new file s name will be composed by the former name followed by the Extended suffix. To view and modify the parameters of a domain class: This option works the same way as described in To view and modify the attributes of a domain class: on page 17. Related topics: Creating a new file on page 13 Opening an existing file on page 11 Generating the domain classes code on page DCC User Guide

21 GENERATING THE DOMAIN CLASSES CODE Generating the domain classes code The code of the domain classes, is generated when the user click the Generate code button after entering all mandatory fields and attributes. In particular: 1 Load or create a XML file. (See Loading or creating the file in DCC on page 11). 2 In the Domain class name be sure that you specify the name that is to be used to create the code files. 3 Click Generate code. 4 In the popup that is displayed, select the folder where you want to save the code and click OK. As a result, two.cs files will be created whose file name will be, respectively: The Domain class name (e.g.: Crop.cs) The Domain class name followed by the VarInfo suffix (e.g.: CropVarInfo.cs). For further information, see Classes description on page 22). The.cs files so generated can be used to create a modelling solution. Note: Files should be ready for compilation (see Multi-language support on page 23), but few minor details might require fixing. Related topics: Loading or creating the file in DCC on page 11 DCC User Guide 19

22 2 USING DCC TO GENERATE CODE 20 DCC User Guide

23 Language reference 3 In this section: Classes description on page 22 Multi language support on page 23 DCC User Guide 21

24 3 LANGUAGE REFERENCE Classes description The following table summarizes what are and how to use Domain classes, Value classes, and the VarInfo class. Table 1 Domain, Value, VarInfo classes description Class Domain classes Value classes VarInfo class Description To model a domain, we define data types called domain classes, following the approach by Rizzoli et al. (1998). Domain classes are characterized by a set of data attributes, which are the inputs, outputs and a set of accessory methods to set and get the value, and to get the attributes. A values class implements the interface IDomainClass, from the component CRA.Core.Preconditions.dll A matching class, which is conventionally called as the value class plus the postfix VarInfo, contains the attributes, each of type VarInfo. The VarInfo type is available in the component CRA.Core.Preconditions.dll, and the VarInfo class implements the interface IVarInfoClass, also available from the component CRA.Core.Preconditions.dll. According to the use in the component, there can be more than one couple of domain classes (e.g. States and SatesVarInfo, Rates and RatesvarInfo). In the VarInfo class, attributes are declared as static attributes, and the static constructor of the class sets the value for each VarInfo attribute. Each VarInfo value can be accessed as read only. The values class contains declarations of the properties listed in the input file of DCC. Also, the properties of the interface are implemented. The values class contains declarations only of the properties listed in the input file of DCC which are of a numeric type (e.g. double, int, double[]). Also, the properties of the interface are implemented. Related topics: Multi language support on page 23 Loading or creating the file in DCC on page 11 Generating the domain classes code on page DCC User Guide

25 MULTI-LANGUAGE SUPPORT Multi-language support DCC allows generating C# and VB.NET code. Other languages will be made available once the relevant code generators will become available. Code generation by DCC is meant to provide ready to compile classes, however there is a list of unresolved problem which require manual fixing in the VS 2005 IDE: C#, VarInfo class, constructor: the method called is written with a unnecessary period as prefix, to be removed. DCC User Guide 23

26 3 LANGUAGE REFERENCE 24 DCC User Guide