Ergo Developer Tutorial

Eclipse RCP installation

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

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

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 http://eclipse.org/downloads/ For Ergo, we recommend the Eclipse for RCP and RAP Developers

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

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

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

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

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

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 - http://download.eclipse.org/releases/luna

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

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

Eclipse RCP/Ergo Overview

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

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

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

RCP Core

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

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

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

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

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

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

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

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

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)

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

Ergo-EQ Architecture (2)

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

More RCP Resources Eclipse RCP Tutorial Eclipse RCP Wiki http://www.vogella.com/tutorials/EclipseRCP/a rticle.html Eclipse RCP Wiki http://wiki.eclipse.org/index.php/Rich_Client_Pl atform

Setup Ergo Development Environment

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: https://opensource.ncsa.illinois.edu/conflue nce/display/ERGO/environment_setup_10

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”

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: ssh://git@opensource.ncsa.illin ois.edu:7999/ergo/ergo.git For u/p, enter your opensource credentials, click Next

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

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

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

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

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

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

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

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

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

Analysis framework

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

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

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

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

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

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

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

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="">

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>

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>

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

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.

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

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>

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>

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>

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

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>

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>

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

Exercise Add the analysis description pieces for the new analysis

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

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

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

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

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

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

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

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

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;

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);

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 );

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

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

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

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

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

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="">

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

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

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

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

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

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

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

Sync Repositories Click on Synchronize button to fetch defined repositories

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

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

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

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

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

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

Advanced Topics

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

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

Sample Code for Schema <?xml version="1.0" encoding="UTF-8"?> <xsd:schema xmlns:gml="http://www.opengis.net/gml" xmlns:xsd="http://www.w3.org/2001/XMLSchema" targetNamespace="http://www.ionicsoft.com/wfs" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:iwfs="http://www.ionicsoft.com/wfs" targetNamespaceOptional="true" xmlns="http://www.ionicsoft.com/wfs" elementFormDefault="qualified"> <xsd:import namespace="http://www.opengis.net/gml" schemaLocation="http://schemas.opengis.net/gml/2.1.2/feature.xsd"/> <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>

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

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

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

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

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

Sample Metadata for Data Type <?xml version="1.0" encoding="ISO-8859- 1"?> <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>

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

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)

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

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);

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

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;

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();

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$

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; }

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(); }

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

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

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>

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

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

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

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

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

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

Questions?

Resources User/Developer Documentation https://opensource.ncsa.illinois.edu/confluence/displ ay/ERGO/Ergo+Home Analysis Framework Developer’s Guide https://opensource.ncsa.illinois.edu/confluence/displ ay/ERGO/Analysis+Framework+Developer%27s+Guid e Adding Dataset Types https://opensource.ncsa.illinois.edu/confluence/displ ay/ERGO/Creating+New+Data+Schemas Git e-book http://git-scm.com/book