1. Ergo Developer Tutorial

2. Eclipse RCP installation

3. Eclipse RCP Installation
Objective
To learn how to install Eclipse Rich Client Platform (RCP)
Contents
System Prerequisites
Eclipse Download and Installation
Updating Eclipse to latest release

4. System Prerequisites Operating System
Linux (just about any version)
MacOSX (10.5 Leopard or higher)
Windows (XP and higher)
Java: Eclipse requires Oracle or IBM Java
Need Java SDK
Java 1.7 or higher
Java 1.7 is the same as JDK 7.0
The GNU Java Compiler (GCJ), which comes standard on Linux, will not work.
OpenJDK, distributed with some Linux distributions, comes closer to working, but should not be used

5. Eclipse Packages
The current version of Eclipse (4.4) is also known as “Luna”
Eclipse is available in a number of different packages for different kinds of development
For Ergo, we recommend the Eclipse for RCP and RAP Developers

6. Exercise
Download the “Eclipse for RCP and RAP Developers” package to your laptop
If your machine is Linux or Mac OS X, untar the file
On Mac OS X you can just double-click in the Finder
If your machine is Windows, unzip the file
This creates an eclipse folder containing the executable as well as other support files and folders

7. Starting Eclipse Linux Mac OS X Windows
From a terminal window, enter “<eclipse_installation_path>/eclipse/eclipse &”
Or, open the eclipse folder
Double-click on the eclipse executable
Mac OS X
From Finder, open the eclipse folder where you installed
Double-click on the Eclipse application
Or from a terminal window
Windows
Open the eclipse folder

8. Specifying a Workspace
Eclipse prompts for a workspace location at startup time
The workspace contains all user- defined data
Projects and resources such as folders and files
The default workspace location is fine for this tutorial

9. Eclipse Welcome Page Displayed when Eclipse is run for the first time
Select “Go to the Workbench”

10. Updating Eclipse RCP
Eclipse releases two service packs per major release
To check for updates, select Help > Check for Updates…
If there are updates installed, Restart eclipse after installing
Ergo can be updated in a similar way

11. Additional Features for Ergo
Ergo requires the Graphical Editing Framework (GEF) and Zest Visualization Toolkit SDKs that are not included in the RCP installation
Go to Help > Install New Software…
In the Work With: dropdown box, select the update site:
Luna -

12. Install GEF and Zest SDKs
In the dialog box, expand Modeling and select
Graphical Editing Framework GEF SDK
Graphical Editing Framework Zest Visualization Toolkit SDK
Select Next, Eclipse calculates required plug-ins
Select Next again.
Accept the License agreement and Select Finish

13. Exercise Launch Eclipse RCP and select the default workspace
Go to Help > Install New Software… and select GEF and Zest Framework SDKs
Install GEF and Zest SDKs
Restart Eclipse once the installation is completed

14. Eclipse RCP/Ergo Overview

15. Eclipse RCP/Ergo Overview
Objective
To introduce the Eclipse RCP platform and Ergo Platform architecture
Contents
What is Eclipse RCP?
What is Ergo?

16. The Eclipse Platform
Integrated development environments(IDEs) for Java, C/C++, Fortran, etc
Factor out the language independent parts (platform)
Then, add in the language-specific pieces later (plug-ins)
“The Eclipse platform itself is a sort of universal tool platform – it is an IDE for anything and nothing in particular.” – Eclipse Platform Overview

17. What is Eclipse? Universal platform for integrating development tools
Open, extensible architecture based on plug-ins
Plug-ins are installed into Eclipse to add new behavior
JDT is just a collection of plug-ins
Plug-in Dev. Env (PDE)
Java Dev Tools (JDT)
Eclipse Platform
Java VM

18. RCP Core

19. Eclipse Plug-in Architecture
OSGi is a specification describing a modular approach for Java applications
Plug-in – smallest unit of Eclipse function
Extension Point – named entity for collecting “contributions”
Example: extension point for Ergo analysis
Extension – a contribution
Example: an Ergo analysis

20. Eclipse Plug-in Arch. (2)
Each plug-in
Contributes to 1 or more extension points
Optionally declares new extension points
Depends on a set of other plug-ins
Contains Java code libraries and other files
May export Java-based APIs for downstream plug-ins
Lives in its own plug-in subdirectory
Details are defined in the plug-in manifest
Manifest declares contributions
Code implements contributions and provides API
plugin.xml file in root of plug-in subdirectory

21. Eclipse Plug-in Arch. (3)
Plugin example
Plug-in A
Declares extension point P
Declares interface I to go with P
Plug-in B
Implements interface I with its own class C
Contributes class C to extension point P
Plug-in A instantiates C and calls its I methods
plug-in A
plug-in B
extension point P
extension
interface I
class C

22. Core Technologies OSGI Provides plug-in based environment for Eclipse
Permits lazy-loading of plug-ins
Permits multiple version of the same plugin/packages to co-exist
Every Eclipse plug-in is an OSGi plug-in (or bundle)
Every OSGi plug-in can be treated as a standard JAR outside of OSGi

23. Core Technologies (2)
SWT – a platform independent widget toolkit that wraps native widgets offering a native look and feel across platforms
JFace – provides Model-View-Controller wrapping for SWT widgets (e.g. TreeViewer, TableViewer, etc)
Model – consists of application data, business rules, logic and functions
View – visual representation of the data (e.g. chart, diagram)
Controller – mediates input converting commands for the model or view

24. Eclipse Basics
The workbench contains the menus, toolbars, editors, and views that make up the main Eclipse Window
The workbench represents the desktop development environment
Contains a set of tools for resource management
Provides a common way to navigate through the resources
Multiple workbenches can be opened simultaneously
Only one workbench per workspace
View
View
Editor
View

25. Perspectives
A Perspective is a visual container for a set of views/editors
They are task oriented, i.e. they contain specific views for doing certain tasks
Java Perspective – Java development
C++ Perspective – C++ development

26. View
A View is typically used to work on a set of data, might be hierarchical
Example: Eclipse package explorer, Ergo Scenarios view
Views can be freely positioned in the User Interface

27. Components of RCP App.
Main program – a RCP main application class implements IApplication, synonymous to the main method for a standard Java application
This class should be defined via extension point org.eclipse.core.runtime.application
A Perspective – defines the layout of your application
Declared via extension point org.eclipse.ui.perspective
Workbench Advisor – controls the appearance of the application (menus, toolbars, perspectives, etc)

28. Ergo EQ Architecture Plug-ins, Provenance, Environment  Dynamic
New Third-Party
Analyses
Compare, Contrast,
Validate
Auto-update
Ergo-EQ
GIS
Workflow
Data
Eclipse RCP
Plug-in Framework

29. Ergo-EQ Architecture (2)

30. Ergo Core Technologies
Eclipse RCP
Geotools
Visualization Toolkit
JFreeChart
Ktable
Jasper Reports

31. More RCP Resources Eclipse RCP Tutorial Eclipse RCP Wiki
rticle.html
Eclipse RCP Wiki
atform

32. Setup Ergo Development Environment

33. Setup Ergo Development Environment
Objective
Checkout all required Ergo projects for development
Content
Step by step instructions to checkout each repository
Adding projects to working sets
Full instructions on Ergo wiki: nce/display/ERGO/environment_setup_10

34. Ergo Repositories
One Git repositories make up Ergo and Ergo-EQ with package names specific to core, earthquake, gis, etc
ergo
If you check out the repository in different workspace;
Delete the project (without deleting the content)
Move the repository to desired location
Switch to Git Repository Exploring Perspective
Click on “Add existing local repository”
Select the your Git repository
Right-click on the git repo and select “import projects”

35. Checkout Ergo Repository
In Eclipse, go to File > Import > Git > Projects from Git
Click Next
Select Clone URI and Click Next
Copy and Paste into the URI field: ois.edu:7999/ergo/ergo.git
For u/p, enter your opensource credentials, click Next

36. Checkout Ergo Repository (2)
Select master, develop-v1, develop-v2
Click Next

37. Checkout Ergo Repository (3)
Assuming the default “workspace”, we recommend creating a git directory in the workspace and then checking out the repository to that directory (e.g. eclipse_workspace/git /ergo)
Click Next

38. Checkout Ergo Repository (4)
Select Import existing projects
Click Next

39. Checkout Ergo Repository (5)
Select all projects
Uncheck the box Search for nested projects
Check Add project to working sets
See next slide...

40. Checkout Ergo Repository (6)
To add the checked out files to a working set:
Click Select
Click New
Select Java
Click Next
Where it says “Working set name” enter ergo-core
Click Finish
Check the box that says ergo- core
Click OK
See Next Slide

41. Checkout Ergo Repository (7)
Your Import Projects dialog should look similar to this
Click Finish
Projects will be checked out into workspace/git/ergo and added to the working set ergo-core

42. Show Working Sets
Use dropdown menu to organize projects by Working Sets

43. Exercise Checkout ergo git repository into working set ergo-core
In Package Explorer, select to show Working Sets

44. Launch Ergo-EQ Find project edu.illinois.ncsa.ergo.eq.rcp
Double click on the file ergo-eq.product
Under Testing click on Launch an Eclipse application
If you see a dialog with the message “errors exist in org.geotools”, click Proceed

45. Analysis framework

46. Analysis Framework Objective Content Create a new Ergo Analysis
Create the analysis description file (User Interface)
Create the Analysis Task
Register Analysis with newAnalyses extension point
Register Task with ogreTasks extension point
Launch Ergo-EQ with new analysis

47. Step 1. Analysis Description File
XML file specifying the inputs, outputs, and parameters for the new analysis
Defines User Interface for New Analysis
Put file in defining plug-ins descriptions folder

48. Create New Plug-in
Create new eclipse plugin, File > New > Plug-in Project
Project Name: edu.illinois.ncsa.ergo.eq.tu torial
Leave rest as default
Click Next

49. Create New Plug-in (2)
Uncheck the box “This plug- in will make contributions to the UI”
Leave rest as default
Click Finish
You can find your project under “Other Projects” working set

50. Create Descriptions Folder
Right click on the new project and select New > Folder
Where it says “Folder Name:” enter descriptions
Click Finish

51. Create Analysis Desc. File
Similar to the folder creation, right click on the descriptions folder and select New > File
Where it says “File name” enter NewBuildingDamage.xml
Click Finish

52. Exercise Create new Plug-in Project Create descriptions folder
Create empty file NewBuildingDamage.xml

53. Analysis Description Tag
id (required) – must match the id given to the analysis in the edu.illinois.ncsa.ergo.core.analysis.newAnalyses extension point (we will add the id later)
help-context (optional) – assigns a help context id to this analysis
Code:
<analysis-description id="" help-context="">

54. Analysis Type Tag <analysis-type> Code:
type (required) - specifies analysis iteration type
property (required)
name – special keyword to identify which dataset is the dataset being iterated over
value – dataset to iterate over
Code:
<analysis-type type="simpleIteration">
<property name="iteratingDatasetKey" value="buildings"/>
</analysis-type>

55. Groups Tag <groups> Code:
Specify the grouping of User Interface Inputs and parameters
Code:
<group-name>Required</group-name>
<group-name>Advanced</group-name>
</groups>

56. Parameter Tag Attributes
group (unused) – string that must match a member of <groups>
format – the format of whatever phylum parameter this is. For datasets, indicates type of dataset (mapping, shapefile, etc)
phylum – type of parameter, currently supports string, dataset, or boolean
cardinality – how many of this type, currently supports single or multiple
key – name of property which will correspond to Analysis Task Setter (e.g. key = “building”, Analysis Task must have setBuilding)
friendly-name – name that should be displayed in the User Interface
optional – value of true denotes this parameter is not needed to perform the analysis
advanced – a value of true denotes this is an advanced parameter and should be in that grouping. It is required, but this will hide it in the UI under Advanced grouping

57. Parameter Tag (2) Elements
<types> A list of types that are accepted by this <parameter>, this should match the tag field of the dataset type defined at edu.illinois.ncsa.ergo.gis.gisSchemas
<description> A textual description of the parameter.  Primarily used to generate tooltips in the UI.

58. Result Name Code: <!-- Name of result dataset -->
<parameter format="resultName" phylum="string" cardinality="single" key="buildingDamagev4.resultName" friendly- name="Result Name"/>

59. Building Dataset Code: <!-- Building Dataset Input -->
<parameter phylum="dataset" cardinality="single" key="buildings" friendly-name="Buildings">
<types>
<type>buildingv4</type>
<type>buildingv5</type>
</types>
</parameter>

60. Hazard Dataset Code: <!-- Hazard Dataset Input -->
<parameter phylum="dataset" cardinality="multiple" key="hazard" friendly-name="Hazard">
<types>
<type>hazardRaster</type>
<type>deterministicHazardRaster</type>
<type>hazard</type>
</types>
</parameter>

61. Fragility Dataset Code:
<!-- Building Fragility Dataset Input -->
<parameter advanced="true" phylum="dataset" cardinality="single" key="fragilities" friendly-name="Fragilities">
<types>
<type>buildingFragilities</type>
</types>
</parameter>

62. Output Tag <output> - two required properties Attributes
base-dataset-key – the key of the <parameter> which is the base for this new Dataset
Schema – The id of the schema that this Dataset implements (see edu.illinois.ncsa.gis.gisSchemas extension point)
Attributes
format – the format of the parameter, currently supports string or dataset
key – the name of the property for which value should be added. No spaces allowed
friendly-name – name of property for which value should be added
Elements
property – additional properties required by output

63. Output Code: <!-- OUTPUTS -->
<output friendly-name="Building Damage" key="buildingDamagev4" phylum="dataset" format="shapefile" geom="buildings" guids="buildings">
<property name="buildings" type="base-dataset-key" value="buildings"/>
<property name="schema" type="schema" value=“edu.Illinois.ncsa.ergo.eq.schemas.buildingDamageVer 4.v1.0"/>
</output>

64. Produced Types Tag
<produced-types> - types produced by this analysis
Elements
<type> – should match the output type (e.g. the tag in the edu.illinois.ncsa.ergo.gis.gisSchemas extension
Code:
<produced-types>
<type>buildingDamagev4</type>
</produced-types>

65. Closing Tag Code: </analysis-description>
Ctrl-s to save the file

66. Exercise
Add the analysis description pieces for the new analysis

67. Step 2. Create Analysis Task
Java class performs the work
Must implement the Analysis Task that corresponds to the <analysis-type> (e.g. SimpleFeatureTask)
Keys given to each parameter must match set methods in this class
Column names given to the outputs must match values given in the output schema type

68. Add Required Dependencies
Open project MANIFEST.MF under META-INF folder
Select Dependencies tab
Under Required Plug-ins, click Add
edu.illinois.ncsa.ergo.core.analysis
edu.illinois.ncsa.ergo.gis
edu.illinois.ncsa.ergo.eq
edu.illinois.ncsa.ergo.eq.hazard
ncsa.tools.elf.core
ncsa.tools.common
ncsa.tools.ogrescript
org.dom4j
org.geotools
Finish dependencies
Ctrl-s to save MANIFEST.MF

69. Create New Java Class Right click on the project, New > Class
Package:
edu.illinois.ncsa.ergo.eq.tutorial.tasks
Name:
NewBuildingDamageTask
Superclass:
SimpleFeatureTask
edu.illinois.ncsa.ergo.core.analysis.ogrescript.tasks.core. SimpleFeatureTask
Click Finish

70. Add Unimplemented Methods
If your eclipse already add the method, you don’t need to do this part.
Click on the red x in the class and select add unimplemented methods
Adds handleFeature method – each building is passed in 1 at a time, we will add our business logic here

71. Add Set Methods For key=buildings For key=hazard For key=fragilities
Nothing to set, this is our iterating dataset
For key=hazard
setHazard(List<RasterDataset> hazardList)
For key=fragilities
setFragilities(FragilityDataset fragilities)
Note: if your eclipse complaints “can’t resolve a type”, ctrl+shift+o (it will import all classes you need)
RasterDataset is the parent of HazardDataset for scenario eq

72. Hazard Input Add class variable Code:
private FragilityHazardSet hazardSet = new FragilityHazardSet();
Add Set Method
public void setHazard(List<RasterDataset> hazardList) {
hazardSet.setDatasets(hazardList); }

73. Fragility Input
Add Class Variable
Code:
private FragilityDataset fragilities;
Add Set Method
Code
public void setFragilities(FragilityDataset fragilities) {
this.fragilities = fragilities; }

74. Exercise Add class variable for fragility and Set Method
Add class variable for hazard and Set method

75. Implement handleFeature
Code:
Point location = (Point) feature.getAttribute(0);
// Period of Demand Type
double period = 0.0;
// Demand Type for Fragility
String demandHazardType = "PGA";
// Units of Demand for Fragility
String demandHazardUnits = "g";
// Default
int spectrumOverride = 0;

76. Implement handleFeature (2)
Get hazard that best matches the period, demand type and demand units. It will find the dataset that can best provide the hazard
Code:
//Find Hazard Value at Location
double hazardVal = hazardSet.getHazardVal(location, period, demandHazardType, demandHazardUnits, spectrumOverride);

77. Implement handleFeature (3)
Get the first fragility set in the map and get the damage value for the first fragility curve in the set for the hazard value
Store the result in the resultMap associated with the Task
Code:
FragilitySet randomFragility = fragilities.getFragilitySets().values().iterator().next();
double damage = randomFragility.getFragilities().get(0).getValueAtPoint(haz ardVal);
resultMap.put("meandamage", damage );

78. Exercise Implement handleFeature Get hazard value at building location
Get Fragility curve and corresponding damage for the hazard value
Store damage as meandamage

79. Step 3. Register Analysis
Objective
Register analysis with edu.illinois.ncsa.ergo.core.analysis.newAnalyses extension point
Content
How to register a new analysis

80. Analysis Extension Point
Inside the project edu.illinois.ncsa.ergo.eq.tutor ial, open MANIFEST.MF
Click on the Extensions tab
Click Add
Where it says Extension Point filter, search for edu.illinois.ncsa.ergo.core.a nalysis.newAnalyses
Select the Extension Point and Click Finish

81. Create Analysis Extension
To create a new extension, right click on edu.illinois.ncsa.ergo.core.analysis.newAnalyses and select New > analysis
Your eclipse may already add the new analysis for you, in this case, you don’t need to add another analysis
This will create a blank analysis extension with the following attributes:
id – This id must match the id given in the analysis description file, NewBuildingDamage.xml
name – Friendly name of the analysis and should be i18n
tag – This tag must match the tag in the ncsa.tools.ogrescript.ogreTasks extension. No spaces allowed
descriptor – Location of the analysis description file
category – The category to put the new analysis in, for display purposes
description – brief description of the new analysis

82. Analysis Extension Details
Fill in the following for our new analysis id
edu.illinois.ncsa.ergo.eq.tutorial.NewBu ildingDamage
name
New Building Damage
tag
tutorialBuildingDamage
descriptor
descriptions/NewBuildingDamage.xml
category
Building
description
new building damage analysis

83. Update Analysis Description
Open NewBuildingDamage.xml
Replace
<analysis-description id="" help-context="">
With
<analysis-description id="edu.illinois.ncsa.ergo.eq.tutorial.NewBuild ingDamage" help-context="">

84. Exercise Add Extension Point in MANIFEST.MF
Add Extension to Extension Point for new Analysis in MANIFEST.MF
Update NewBuildingDamage.xml with analysis id

85. Step 4. Register Analysis Task
Objective
Register new analysis task with ncsa.tools.ogrescript.ogreTasks extension point
Content
How to register a new analysis task

86. Analysis Task Extension Point
Inside the project edu.illinois.ncsa.ergo.eq.tut orial, open MANIFEST.MF
Click on the Extensions tab
Click Add
Where it says Extension Point filter, search for ncsa.tools.ogrescript.ogreTa sks
Select the Extension Point and Click Finish

87. Create Analysis Task Extension
Similar to the newAnalyses extension, right click on ncsa.tools.ogrescript.ogreTasks and select New > ogreTasks
This will create a blank analysis task extension with the following attributes:
id – This id should match the fully qualified class name of the task (see class attribute)
name – This is the friendly name of the Task and should be i18n
tag – This tag must match the tag in the edu.illinois.ncsa.ergo.core.analysis.newAnalyses extension point
class – This points to the implementing class we created previously

88. Analysis Task Extension Details
Fill in the following for our new analysis task id
edu.illinois.ncsa.ergo.eq.tutorial. tasks.NewBuildingDamageTask
name
New Building Damage Task
tag
tutorialBuildingDamage
Class
edu.illinois.ncsa.ergo.eq.tutorial.task s.NewBuildingDamageTask

89. Add Plug-in to Ergo Go to Run > Run Configurations…
Under Eclipse Applications select ergo-eq.product
Select the Plug-ins tab
Locate our plugin edu.illinois.ncsa.ergo.eq .tutorial and check the box to include it
Click Run

90. Update Preferences Click on File > Preferences
Select File Locations
Change Repository update service URL to
Windows - file:\\\C:\repositories.xml
Linux /Mac – file:/home/user- name/repositories.xml
Or wherever you put the file
Click OK

91. Sync Repositories
Click on Synchronize button to fetch defined repositories

92. Create New Scenario Select File > New Scenario
Where it says Name enter Tutorial Scenario
Click Next

93. Create New Scenario (2)
Where it says Country select United States of America
Expand Tennessee and select Shelby county
Click Next
Click Finish

94. Execute Analysis
Right Click on the new scenario and select Execute Analysis
Expand Building and select New Building Damage
Click Finish

95. New Building Damage
Click on the New Building Damage box to build the User Interface
Note: the analysis is currently red because not all input parameters are satisified
See next slide for inputs

96. New Building Damage (2) For Result Name, enter Building Damage
For Buildings, click Search and locate Shelby County RES3
For Hazard, click Search and locate Memphis 7.7M PGA
For Fragilities, click Search and locate Default Building Fragilities 1.0
Click the Execute button that should now be enabled

97. Exercise Run the New Building Damage analysis
You may have some problem to run because of the library we are using is out dated.

98. Advanced Topics

99. Add Dataset Type Objective Content Add new dataset type to Ergo-EQ
Creating a new dataset schema
Adding schema extension to extension point
Adding field-specific metadata

100. New Dataset Schema
Create a folder in the root directory of your plugin called gisSchemas
Create a new empty file called ergo- tutorialBuildingDamage_1.0.xsd in gisSchemas folder
See ergo-buildingDamageVer4_1.0.xsd in plugin edu.illinois.ncsa.ergo.eq as an example

101. Sample Code for Schema
<?xml version="1.0" encoding="UTF-8"?> <xsd:schema xmlns:gml=" xmlns:xsd=" targetNamespace=" xmlns:xlink=" xmlns:iwfs=" targetNamespaceOptional="true" xmlns=" elementFormDefault="qualified"> <xsd:import namespace=" schemaLocation=" <xsd:element name="TUTORIALBUILDINGDAMAGE" substitutionGroup="gml:_Feature" type="iwfs:TUTORIALBUILDINGDAMAGE"/> <xsd:complexType name="TUTORIALBUILDINGDAMAGE"> <xsd:complexContent> <xsd:extension base="gml:AbstractFeatureType"> <xsd:sequence> <xsd:element name=“ergo.meandamage" minOccurs="0" nillable="true" type="xsd:double"/> </xsd:sequence> </xsd:extension> </xsd:complexContent> </xsd:complexType> </xsd:schema>

102. Add Schema Extension Point
Go to edu.illinois.ncsa.ergo.eq.tutorial project and open MANIFEST.MF
Click on Extensions
Click Add
Add edu.illinois.ncsa.ergo.gis.gisSchemas

103. Add Schema Extension
Right click on edu.illinois.ncsa.ergo.gis.gisSchemas and select New > gisSchema
This will create a new extension with the following attributes
id – The id of the schema
name – A friendly name for the schema
version A version identifier for the schema
type – a short type name for the schema (used in analysis description to identify input types)
description – a user-friendly description of the schema
file – The schema file defined in the previous step
format – The format of the schema. Predefined formats include shapefile, fragility, mapping, raster, and table
requiredFields – The list of fields that are required as a minimum for this schema. These will be prompted to map during ingestion of data
mapLayer – For shapefiles, the suggested smart layering position in the map. Should be between 1 and 100. A mapLayer of -1 indicates dataset should be invisible by default
category – a category name for the schema. Categories determine what subfodlers the schemas appear in the repository

104. Schema Extension Details
Id - edu.illinois.ncsa.ergo.eq.tutorial.schemas.t utorialBuildingDamage.v1.0
name - Tutorial Building Damage
version - 1.0
type - tutorialBuildingDamage
description - Tutorial building damage output type
file - gisSchemas/ergo- tutorialBuildingDamage_1.0.xsd
format - Shapefile
requiredFields - meandamage
mapLayer - 10
category - Buildings

105. Field Specific Metadata
Create a folder in the root directory of your plugin called gisMetadata
Create a file name corresponding to the schema xsd file name, but ending in .xml (e.g. ergo-tutorialBuildingDamage_1.0.xml)
Ergo will automatically look for a file with the same prefix in gisMetadata when displaying fields in the User Interface

106. Metadata Attributes
Column-id – The id to match the column id from the xsd file. Should not include the ergo. prefix
Friendly-name
Is-numeric
Unit
Field-length
Importance
Is-result
Agg-type

107. Sample Metadata for Data Type
<?xml version="1.0" encoding="ISO "?> <table-metadata> <column-metadata column-id="meandamage" friendly-name="Mean Structural Damage" is-result="true" is-numeric="true" unit="decimal" importance="mainValue" agg-type="mean" field-length="10" /> </table-metadata>

108. Create Custom Iterator
Objective
Add new custom iterator
Content
What is a custom iterator
Adding a custom iterator extension

109. Custom Iterators Simple Feature Iterator Table Iterator
Iterates over a feature dataset providing 1 feature per iteration to the analysis task
Table Iterator
Iterates over a table dataset providing 1 row per iteration to the analysis task
Custom Iterator
Handles special cases where simple iteration is not applicable (e.g. see NBSR Iteration Handler)

110. Create Custom Iterator Class
Right click on the project edu.illinois.ncsa.ergo.eq.tutorial and select New > Class
Package – edu.illinois.ncsa.ergo.eq.tutorial.han dlers
Name – ExampleIterationHandler
Superclass – IterationHandler
Click Finish

111. Implement Iterator Class
This code should go inside wrappedCreateIterationElements(…)
Code:
// This must match the tag for the analysis and task
Element e = new DefaultElement("example");
// Name of the result
e.addAttribute(“result-Type", AnalysisUtils.variableizeAsConstant("result.type", “bldgresult"));
// Input - must match "key" inside analysis description
e.addAttribute("my-buildings",AnalysisUtils.variableizeAsConstant(null, "mybuildings"));
// Output - bldgresult must match to an output key in analysis description
e.addAttribute("result-bldg", AnalysisUtils.variableizeAsConstant("collection", "bldgresult"));
e.addAttribute("analysis-id", node.getUniqueId());
parent.add(e);

112. Create Analysis Task
Right click on the project edu.illinois.ncsa.ergo.eq.tutoria l and select New > Class
Package – edu.illinois.ncsa.ergo.eq.tutorial .tasks
Name – CustomIteratorAnalysisTask
Superclass – AnalysisBaseTask
Click Finish

113. Implement Custom Analysis Task
Code
private FeatureType resultType;
private FeatureDataset myBuildings;
private FeatureCollection resultBldg;
public FeatureType getResulType() {
return resultType; }
public void setResultType(FeatureType resultType) {
this.resultType = resultType;
public void setMyBuildings(FeatureDataset myBuildings) {
this.mybuildings = myBuildings;
public void getResultBldg(FeatureCollection resultBldg) {
this.resultBldg = resultBldg;

114. Implement Custom Analysis Task (2)
Code
@Override
protected void wrappedExecute(IProgressMonitor monitor)
throws ScriptExecutionException {
try {
FeatureCollection fc = myBuildings.getFeatures();
FeatureType originalSchema = fc.getSchema();
List<AttributeType> newAttributeTypes = new LinkedList<AttributeType>();
AttributeType[] attributeTypes = originalSchema.getAttributeTypes();
for (AttributeType type : attributeTypes) {
newAttributeTypes.add(type); }
String typeName = getResultType().getTypeName();
DefaultFeatureType newSchema = (DefaultFeatureType) FeatureTypeBuilder.newFeatureType(
newAttributeTypes.toArray(new AttributeType[newAttributeTypes.size()]), typeName);
FeatureIterator iter = fc.features();

115. Implement Custom Analysis Task (3)
Code
try {
while (iter.hasNext()) {
List<Object> data = new LinkedList<Object>();
Feature f = iter.next();
Object[] values = f.getAttributes(null);
for (Object obj : values) {
data.add(obj); }
Feature newf = newSchema.create(data.toArray());
resultBldg.add(newf);
} finally {
fc.close(iter);
commitFeatures(resultBldg, createFeatureStore(newSchema, "feature.store.bldgresult")); //$NON-NLS-1$
} catch (SchemaException e) {
error("Scehma problem", e); //$NON-NLS-1$
} catch (IllegalAttributeException e) {
error("AttributeType problem", e); //$NON-NLS-1$
} catch (IOException e) {
error("IO problem", e); //$NON-NLS-1$
} catch (EnvironmentAccessException e) {
error("Ogre Script Problem", e); //$NON-NLS-1$

116. Implement Custom Analysis Task (4)
Code
private FeatureStore createFeatureStore(FeatureType featureType, String featureStoreKey) throws IOException, MalformedURLException,EnvironmentAccessException {
File tempShapefile = File.createTempFile("temp", ".shp");
URL shapeURL = tempShapefile.toURI().toURL();
DataStore shapefileDatastore = new ShapefileDataStore(shapeURL);
shapefileDatastore.createSchema(featureType);
FeatureStore featureStore = (FeatureStore) shapefileDatastore.getFeatureSource(featureType.getTypeName());
environment.addOrSetEntry(featureStoreKey, featureStore, false);
return featureStore; }

117. Implement Custom Analysis Task (5)
Code
private void commitFeatures(FeatureCollection featureCollection, FeatureStore featureStore) throws IOException {
DefaultTransaction transaction = new DefaultTransaction();
try {
featureStore.setTransaction(transaction);
featureStore.addFeatures(featureCollection);
transaction.commit();
featureStore.setTransaction(Transaction.AUTO_COMMIT);
} finally {
featureCollection.clear();
transaction.close(); }

118. Exercise Create custom iterator class Implement iterator class
Create Analysis Task
Implement Analysis Task

119. Custom Analysis Description
Right click on the descriptions folder and select New > File
Where it says “File name” enter CustomIteratorBuildingDamage.xml
Click Finish

120. Custom Analysis Description (2)
Code
<analysis-description id="edu.illinois.ncsa.ergo.eq.tutorial.CustomBuildingDamage" help-context="">
<analysis-type type="customBldgIterator">
<property name="iteratingDatasetKey" value="null"/>
</analysis-type>
<!-- GROUPS input and parameter fields -->
<groups>
<group-name>Required</group-name>
<group-name>Advanced</group-name>
</groups>
<!-- INPUTS -->
<!-- Name of result dataset -->
<parameter format="resultName" phylum="string" cardinality="single" key=“bldgresult.resultName" friendly-name="Result Name"/>
<!-- Building Dataset Input -->
<parameter phylum="dataset" cardinality="single" key="mybuildings" friendly-name="Buildings">
<types>
<type>buildingv4</type>
<type>buildingv5</type>
</types>
</parameter>
<!-- OUTPUTS -->
<output friendly-name="Building Damage" key="bldgresult" phylum="dataset" format="shapefile" geom="mybuildings" guids="mybuildings">
<property name="mybuildings" type="base-dataset-key" value="mybuildings"/>
<property name="schema" type="schema" value="edu.illinois.ncsa.ergo.eq.tutorial.schemas.tutorialBuildingDamage.v1.0"/>
</output>
<produced-types>
<type>buildingDamagev4</type>
</produced-types>
</analysis-description>

121. Register Custom Iterator
Extension Point
edu.illinois.ncsa.ergo.core.analysis.iterationHan dlers
Attributes
id – This id should match the fully qualified class name of the iteration handler
tag – This tag is what will be used in the <analysis-type> xml tag to identify what iteration handler to call for the analysis
class – class that implements the new iteration handle

122. Custom Iterator Extension
Inside edu.illinois.ncsa.ergo.eq.tutorial, open the MANIFEST.MF.
Click on the Extensions tab
Click the Add button and add edu.illinois.ncsa.ergo.core.analysis.iterationHandler s
Right click on the extension point and select New > iterationHandler

123. Iteration Handler Attributes
id – edu.illinois.ncsa.ergo.eq.t utorial.handlers.ExampleIt erationHandler
name – Custom Building Iterator
tag – customBldgIterator
class - edu.illinois.ncsa.ergo.eq.t utorial.handlers.ExampleIt erationHandler

124. Register Custom Analysis
Register at newAnalyses extension point
id - edu.illinois.ncsa.ergo.eq.tutorial. CustomBuildingDamage
name – Custom Building Damage
tag - example
descriptor – descriptions/CustomIteratorBuil dingDamage.xml
category - Building

125. Register Custom Analysis Task
Register at ogreTasks extension point
id – edu.illinois.ncsa.ergo.eq.tutoria l.tasks.CustomIteratorAnalysisTa sk
name – Custom Building Damage
tag - example
class - edu.illinois.ncsa.ergo.eq.tutoria l.tasks.CustomIteratorAnalysisTa sk

126. Run Custom Iterator
To see your new analysis with custom iterator, re-launch Ergo-EQ
Open a scenario and follow the previous steps for executing a new analysis, you should see Custom Building Damage in the Building category

127. Questions?

128. Resources User/Developer Documentation
ay/ERGO/Ergo+Home
Analysis Framework Developer’s Guide
ay/ERGO/Analysis+Framework+Developer%27s+Guid e
Adding Dataset Types
ay/ERGO/Creating+New+Data+Schemas
Git e-book