# Presentation: 026706

## Modeling Your Application, Data or Service

**Creating Your UML Model for caBIG®**

## Modeling Your Application, Data or Service

**Metadata Reuse**

**Create UML Model**

**Semantic Annotation**

**Transform UML Model into Metadata**

**SDK Code Generation**

**Compatibility Review**

**Create a Node on the Grid**

## Outline
caCORE SDK Process and Workflow
UML Model Basics (Optional Review) 
caDSR Introduction
Model Naming Conventions
UML Modeling for SDK, example gridPIR data service
Adding Classes and Attributes in EA
Exercise

Objectives
Discuss the SDK Process and caBIG workflow
Identify the packages to create different portions of your model
Discuss the naming conventions appropriate for a UML Model that will be run through the caCORE SDK process
Add a new Class to your UML Model 
Add Attributes to your UML Model

- caCORE SDK Process and Workflow
- UML Model Basics (*Optional Review*)
- caDSR Introduction
- Model Naming Conventions
- UML Modeling for SDK, example gridPIR data service
- Adding Classes and Attributes in EA
- Exercise
**Objectives**
- Discuss the SDK Process and caBIG workflow
- Identify the packages to create different portions of your model
- Discuss the naming conventions appropriate for a UML Model that will be run through the caCORE SDK process
- Add a new Class to your UML Model
- Add Attributes to your UML Model

**Sessions 0-4: Creating Your UML Model****Session Overview**

**Notes:**
The first step in Semantic Integration is to draw your system/project domain in UML. *

There are three parts to the system model: the logical model, data model, and data mapping model.  The logical model describes the target domain and should be created in the logical package.* The Data Model describes the database schema* and the Object relational mapping maps classes to object. All of these are drawn in UML. Throughout this presentation, the terms “logical model”, “domain model” and “object model” are used interchangeably.*

caCORE SDK tools impose modeling guidelines* such as
Java naming conventions*
Package rules*
Element constraints*
For Example, *
*Only UML class diagram elements may be used
*Cannot use interface, object, etc.
Detailed instructions on creating diagrams in UML can be found in the SDK Programmer’s Guide.

## Session 0: UML BasicsWhy Model? 

- Modeling achieves four aims:
**Helps you visualize a system**
**Permits you to specify the structure or behavior of a system**
**Guides you in constructing a system**
**Documents the decisions you have made**
- Build models of complex systems because they are difficult to comprehend in their entirety
- Build models to better understand the system you are developing.
- The caBIGTM process and architecture is model driven, it is required for interoperability and silver level compliance.

**Notes:**
Why model?

Short answer is it is absolutely required and the first step in the caCORE process is to draw your system/project domain in UML. * The model, when semantically annotated and combined with service metadata becomes the foundation that allows the grid and grid services to programmatically discover and combine relevant information from different data services. This has to be done early and well and updated as you update your data service

Remember the model is not just for your application but for interoperability with others.

In addition is helps by
Helps you visualize a system
Permits you to specify the structure or behavior of a system
Guides you in constructing a system
Documents the decisions you have made

Additional reasons are:
Build models of complex systems because they are difficult to comprehend in their entirety 
Build models to better understand the system you are developing.
The caBIG process and architecture is model driven, it is required for interoperability and silver level compliance

There are three parts to the system model: the logical model, data model, and data mapping model.  The logical model describes the target domain and should be created in the logical package.* The Data Model describes the database schema* and the Object relational mapping maps classes to object. All of these are drawn in UML. Throughout this presentation, the terms “logical model”, “domain model” and “object model” are used interchangeably.*

caCORE SDK tools impose modeling guidelines* such as
Java naming conventions*
Package rules*
Element constraints*
For Example, *
*Only UML class diagram elements may be used
*Cannot use interface, object, etc.
Detailed instructions on creating diagrams in UML can be found in the SDK Programmer’s Guide.

## Session 0: UML BasicsWhat is UML?

**UML is a language for**
- Visualizing
- Specifying
- Constructing
- Documenting
- The artifacts of a software system.
**UML allows you to build models that are precise, unambiguous and complete**
**There are many UML diagram types**
- caCORE SDK utilizes one type, the UML Class Diagram

**Notes:**
Visualizing: Communicating conceptual models to others is prone to error unless everyone involved speaks the same language. There are things about a software system you can’t understand unless you build models. An explicit model facilitates communication.
Specifying: UML allows you to build models that are precise, unambiguous and complete. There are many UML diagram types. caCORE utilizes one diagram type: UML Class Diagram
Constructing: UML models can be directly connected to a variety of programming languages. Maps to Java, C++, Visual Basic, etc. Tables in a RDBMS or persistent store in an OODBMS Permits forward engineering Permits reverse engineering
Documenting: The UML addresses documentation of system architecture, requirements, tests, project planning, and release management.

There are many UML diagram types, however caCORE utilizes one diagram type – the UML Class Diagram

Throughout this presentation we only talk about the logical model the most critical one to get right for caBIG , the terms “logical model”, “domain model” and “object model” are used interchangeably.*

## Session 0: UML BasicsUML Documenting

**UML can be used to document of system architecture, requirements, tests, project planning, and release management.**
**CaBIG requires only class diagrams for a logical model.**

**Notes:**
UML addresses documentation of system architecture, requirements, tests, project planning, and release management.

Example UML diagrams include: 
Use Case Diagrams
Deployment Diagrams
Sequence Diagrams
Class Diagrams

As stated before, caCORE utilizes only the class diagrams which will be the focus of our training today.

## Session 0: UML BasicsHow are caBIGTM models different?

- caBIGTM services are expected to have a **domain information model:**
- A Domain Information Model is a representation of our understanding of an area of knowledge
- A Domain Information Model consists of ‘Classes’ that represent ‘things’ in the real world
- In a Domain Information Model, classes contain ‘attributes’ that are characteristics of different instances of things in the real world

## Session 0: UML BasicsComponents of a Class Diagram

**Session 0: UML Basics****Components of a Class Diagram**

**ClassName**

**attributeName**

**Datatype**

**Bi-directional Association**

**associationName**

**Multiplicity**

**Generalization**

**Notes:**
Here is a logical model. It contains

The UML diagram contains
	- classes (see Protein)
	- attributes (see Organism.commonName) with datatype
	- associations with end point names, directionalities and multiplicities
	-operations (not shown)

## Modeling a Real Life Data Service (gridPIR):gridPIR - The Protein Information Resource 

**The Protein Information Resource**

**PIR is an integrated resource for proteomic research. **
**gridPIR is a caBIGTM silver level compliant data service exposing information from one of the PIR databases, the UniProt Knowledgebase (UniProtKB)**
**gridPIR’s goal is to provide comprehensive and fully annotated protein sequence and functional information for basic cancer research**

**Notes:**
Here and for the rest of these lessons we will us as an example work done with gridPIR

PIR is an integrated resource for proteomic research at Georgetown University.

gridPIR is currently a caBIG silver level compliant data service exposing information from on of the PIR databases, the UniProt Knowledgebase (UniProtKB)
Contains information for basic cancer research.

 Its goal is to provide comprehensive and fully annotated protein sequence and functional information for basic cancer research.

How can we model this service?

## Modeling a Real Life Data Service (gridPIR):A not-so-recommended approach

**Modeling Approaches: One object approach => Modeling the record using existing XML schema.**
**Is this valid? Yes**
**Is this a domain information model? No**
**Is this a good model? Not for us**

**P99999**

**<uniprot xmlns="http://uniprot.org/uniprot" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://uniprot.org/uniprot http://www.uniprot.org/support/docs/uniprot.xsd"> <entry dataset="Swiss-Prot" created="1986-07-21" modified="2007-01-23" version="44"> <accession>P99999</accession> <accession>P00001</accession> <accession>Q6NUR2</accession> <accession>Q6NX69</accession> <accession>Q96BV4</accession> <name>CYC_HUMAN</name> <protein> <name>Cytochrome c</name> </protein> <gene> <name type="primary">CYCS</name> <name type="synonym">CYC</name> </gene> <organism key="1"> <name type="scientific">Homo sapiens</name> <name type="common">Human</name> <dbReference type="NCBI Taxonomy" id="9606" key="2"/> <lineage> <taxon>Eukaryota</taxon> <taxon>Metazoa</taxon> <taxon>Chordata</taxon> <taxon>Craniata</taxon> <taxon>Vertebrata</taxon> <taxon>Euteleostomi</taxon> <taxon>Mammalia</taxon> <taxon>Eutheria</taxon> <taxon>Euarchontoglires</taxon> <taxon>Primates</taxon> <taxon>Haplorrhini</taxon> <taxon>Catarrhini</taxon> <taxon>Hominidae</taxon> <taxon>Homo</taxon> </lineage> </organism> **
**......**

**The valuable information is not exposed (e.g. protein annotation)**
**It needs to be exposed to be advertised and discovered on caGrid**

**Notes:**
One very simple and not recommended approach is to model the entire record as one object.

Obviously this is an extreme example and not be used for your service. However a record object has been proposed in some cases were there is an already established and excepted community standard for xml transfer of information, is this case it would be one object in a larger information model and the objects use would be to transmit the record for a tool that needed that format for input.

Less extreme and the first approach we took and many others have tried with poor success is to reverse engineer the xml we already had.

This reverse engineering though tempting seldom works well as the xml formats are often designed for data or record transfer and may be great for that purpose but not the best for information modelling or attaching meaningful metadata or semantics 

This can be true for applications existing UML models also.

## Modeling a Real Life Data Service (gridPIR):A reverse engineering approach

**Should You Reverse Engineer an Existing XML Model?**

**You can but it will not guarantee caBIGTM compatibility.**
**In practice reverse engineering existing models has seldom worked well in the context of caBIGTM.**
**Reverse engineering an existing model can help in understanding the domain but in practice it has not always provide a good information model for caBIGTM’s goals of interoperability. It is often been better to create a new or extensively modified version.**

**Notes:**
Less extreme and the first approach we took and many others have tried with poor success is to reverse engineer the xml we already had.

This reverse engineering though tempting seldom works well as the xml formats are often designed for data or record transfer and may be great for that purpose but not the best for information modelling or attaching meaningful metadata or semantics 

This can be true for applications existing UML models also.

So what do we need to consider in modeling?

## Modeling a Real Life Data Service (gridPIR):Modeling Considerations

**Scientific meaning** – Design a re-usable domain information model, not application-specific record model
**Use cases** – Consider search criteria objects e.g. Protein, Gene, Database Cross references
**Data related constraints** – Include only associations or objects based on your data. e.g. Gene to Protein, but not Protein to DNA Sequence as UniProt does not have DNA sequence only Xrefs to other data sources for DNA.
**Semantics** – Express semantics and avoid using non-informative “type” attributes. For example: name the ProteinFeature subclasses, don’t assign a feature “type”.
**Reuse – **Try to reuse existing models. Same “Things” can exist in other caBIGTM compatible models.
**caCORE SDK constraints** – Consider naming conventions or other SDK constraints

**Notes:**
What do you want in a ‘good’ model.

Example of SDKconstraint,  SDK versions 1-3 required an “id” attribute version 4 does notnot.

## Modeling a Real Life Data Service (gridPIR):Use cases

**Retrieving protein information using:**
***Simple search**** using only one criteria *
***Advanced search**** criteria* constructed using Boolean operators
***Database identifier***** search** without providing data source
**Search criteria can be based on:**
- Database identifiers
- Protein sequence features (annotations)
- Protein/Gene name
- Keywords/Organism

**Notes:**
We are actually building a data service for a real world database called UniProt that collects and annotates information for a variety of other scientific databases and the literature, here are our use cases

Note that the use cases already asks for creation of certain classes (things in real life) and how they should relate to each other (associations)

## Modeling a Real Life Data Service (gridPIR):Naming conventions, caCORE SDK constraints

**Naming Conventions:**
- Adopt a case convention
**camelCase **is recommended, some caBIGTM tools like the SIW support **camelCase** in mapping concepts.
- Avoid using class identifiers in attribute names
- Avoid using abbreviations, Jargon and acronyms.
- Avoid plural class or attribute names unless necessary
- Add “Collection” to association ends with multiplicity >1 (no longer required but a good practice)
**caCORE SDK constraints:**
- “id” attribute in classes (only caCORE SDK 3.0)
- Avoid use of complex data types like “List” and “Collection”

**Notes:**
These are some current best practices at least in regards to the caCore SDK which has some technical constraints, not all is absolutely required but these can help speed the review process and avoid problems or more work later

## Modeling a Real Life Data Service (gridPIR): Naming Exercise

**Are these the best names available?**
** ****Class name: Student - OK**
** ****Attribute name: name – OK**
- Student+name
** ****Attribute name: address – OK**
- Student+address
** ****Attribute name: studentID – ??**
- Student+studentID ? redundant
- Better is “identifier”
- Student+identifier

**UML Class**

**Notes:**
Okay, lets review some of the names in the previous objects it the light of semantic interoperability and see if we can do better.

Class name: Student –OK the name is obvious and commonly used for the concept student, SIW will probably find the name and concept automatically.
Attribute name: name – OK the ideal situation is when the class and attribute name together define the attribute ie the concept for Student + the concept for name joined define the meaning of “Student name”
Attribute name: address – OK
Attribute name: studentID – ?? Not recommended to repeat class name in attribute name, it is redundant information. the SIW will take care of that association, a better attribute name would be “identifier” 
The SIW would then link the known concepts of Student+identifier and  the attribute is fully defined....

## Are these the best names for the concepts?

**Modeling a Real Life Data Service (gridPIR):****Naming Exercise**

** ****Class name: Professor - OK**
** ****Attribute name: name – OK**
** ****hireDate and discipline - OK**** **
**What does status and maxLoad mean in the context of Professor?? **
**May need a better name, definitely needs a clear expert definition.**

**Notes:**
What does status and maxLoad mean in the context of Professor?? 

If status means something like tenure status it would be better to call it “tenure” or “tenureStatus”
If maxLoad means “maximum load of students” it would be better to call it something like “maxLoadStudents”

Good naming is not enough as many names will still have multiple meanings or special meanings in the context of the application or scientific field 
All these attributes need definitions.  

## Modeling a Real Life Data Service (gridPIR):A so-so model

**Good:**
**A pseudo-domain information model; classes are scientific real life things **
**Association directionality and classes based on use cases**
**R****e-use of classes from available models; e.g. caBIO **

**Bad:**
**Attributes with complex data types**** like list and collection.**
**Not all use cases are met **
**Semantics needs improvement**
**Violates some naming conventions**

**Notes:**
What does this mean here is a better model but not good enough yet.
Complex data types like collection and string are not the most informative way to model and have some technical limitations in the SDK, more on that in the next slide
The feature object uses hides useful sematics and  inhibits on of our use cases to search for all proteins with a particular ‘type’ of feature, more on that in a minute
The attribute proteinName in the class protein violates one of the naming conventions should just be called name, as you will see caBIG tools and services understand the name is in the context of the class protein.
Also the recommended convention for naming associations with multiplicity greater than 1 is Collection not used everywhere 

If we look closer at the right side of this model – the Organism class should be curated further as demonstrated next.

## Modeling a real life data service: gridPIR Improving Semantics Further

**Break up lists into collections of separate objects so gridPIR can provide searches on:**
** ****Lineage **
** ****Taxon names**
** ****Alternate names for Organism**

**Notes:**
Complex data types like collection and string are not the most informative way to model and have some technical limitations in the SDK, they can make it difficult to search inhibiting some use cases,
they should be broken out into different objects

## Modeling a Real Life Data Service (gridPIR):Improving Semantics Even Further

**Important annotations in the protein sequence are features, which ****are**** regions or sites of interest in the sequence, including:**
- Posttranslational modifications
- Binding sites
- Enzyme active sites
- Other functional domains

**Problems:**
- Using “type” makes it difficult to discover gridPIR as a protein annotation resource
- User needs to know permissible values for “type” to discover and even use the system

**Solution: Create an individual class for each feature **

**Notes:**
The feature object uses a attribute type to contain our ‘classification type name’ for different features like “binding site”, this hides very useful biological semantics and inhibits on of our use cases to search for all proteins with a particular ‘type’ of feature.

## Modeling a Real Life Data Service (gridPIR):Improving Semantics Even Further

**Protein Sequence Annotation Classes**

**Notes:**
This tells me there are ActiveSites/BindingSites exposed by the data service. Good for this case but obviously not for a case where there are thousands of features, for that might use enumerated value domain.

## Modeling a Real Life Data Service (gridPIR):Improving Semantics

**Using tagged values of UML tool**
- Enter “**CADSR_Description**” for classes and attributes

**For a gene object**

**For a gene attribute, entrezGeneId**

**Notes:**
To improve the system metadata, assist in the semantic annotation process and help anyone trying to understand and reuse your model you must also add tagged values 
This information becomes part of metadata exposed as a part of caGrid Service Metadata, caDSR stored metadata.

## Modeling a Real Life Data Service (gridPIR):Improving Semantics Even Further

**Use enumerated value lists and model them in UML – a class with “caDSR Value Domain” stereotype:**
**	**
**If appropriate to your data service or application please see the developer boot camp presentation on this subject. **** **
_**[gforge.nci.nih.gov/docman/view.php/196/6025/02_Enumerated%20Value%20Lists%20JLB.ppt](https://gforge.nci.nih.gov/docman/view.php/196/6025/02_Enumerated%20Value%20Lists%20JLB.ppt)**_

**Notes:**
It limits the value set for an attribute. When filling out a form or using a web page; which one is more informative; a textbox or a pull-down/options menu that guides you in entering values?

## Modeling a Real Life Data Service (gridPIR):Reuse of existing Common Data Elements

**Common Data Element (CDE)**
**The caBIGTM community has adopted select CDEs as standards and **_**strongly**_** encourages all to use them.**
**One of the best and **_**most important **_**steps you can take to promote interoperability is to reuse a Data Element from another caBIGTM service.**
**The Candidate, Proposed and Approved Standards can be found in the CDE Browser.**
** **_**[http://cdebrowser.nci.nih.gov/CDEBrowser/](http://cdebrowser.nci.nih.gov/CDEBrowser/)**_
**Silver to Grid Training provides additional information and options on reuse.**

**Notes:**
It limits the value set for an attribute. When filling out a form or using a web page; which one is more informative; a textbox or a pull-down/options menu that guides you in entering values?

## Additional Points: Adding Packages – Value Domains Package

**Value Domains, if applicable, should be located in a separate folder than the other classes, but still in the Logical Model Package.**

**Notes:**
This slide is an example of a UML Value Domain specification in the project view of Enterprise Architect (EA). Note that the Value Domains are located in a separate folder than the other classes but are still in the Logical Model Package.

## Additional Points: Java Wrappers

**Java Wrapper classes can be added to appropriate package**
**No need to add attributes**

## Additional Points: UML notations ignored by SIW/UML Loader

**Stereotypes (other than enumeration)**
**Attribute multiplicity (use -1 to represent many)**
**Options in Class and Attribute Details pages**
- Scope
- Abstract class
- Cardinality (always use -1 to represent many)
**Operations in classes**

## Creating Your UML Model:Getting Started

**UML Modeling Tools**
**caCORE SDK is compatible with:**
**	****Enterprise Architect by Sparx Systems:**_**[http://www.sparxsystems.com/products/ea/index.html](http://www.sparxsystems.com/products/ea/index.html)**_** **
**	**
**ArgoUML (open source): **_**[http://argouml.tigris.org](http://argouml.tigris.org/)**_
**	**
**System/project domain is drawn in UML**
**Logical model** describes target domain
- Data model describes database schema
**All UML Models should be placed in the Logical View Package of the modeling tool**

**Notes:**
The first step in Semantic Integration is to draw your system/project domain in UML. *

There are three parts to the system model: the logical model, data model, and data mapping model.  The logical model describes the target domain and should be created in the logical package.* The Data Model describes the database schema* and the Object relational mapping maps classes to object. All of these are drawn in UML. Throughout this presentation, the terms “logical model”, “domain model” and “object model” are used interchangeably.*

caCORE SDK tools impose modeling guidelines* such as
Java naming conventions*
Package rules*
Element constraints*
For Example, *
*Only UML class diagram elements may be used
*Cannot use interface, object, etc.
Detailed instructions on creating diagrams in UML can be found in the SDK Programmer’s Guide.

## Conclusion	

**In a model driven architecture, the model development is the most important step**
**caBIGTM silver-level compatible services are expected to expose domain information models**
**Reusing portions of existing silver-level compatible service models is helpful in achieving compatibility**
**Use caBIGTM best practices and knowledge of caBIGTM tool features (or limitations) to guide your modeling**

**Notes:**
Remember real life “things” may have been modeled in other silver level compatible applications. 

## Additional Points:Exercise

**Use the step by step instructions to try it yourself with EA**
- Open an existing model file in Enterprise Architect
- Add a Class and Attribute to the existing diagram
- See link below for all exercise files in 01_Exercises on gforge
- _[https://gforge.nci.nih.gov/docman/index.php?group_id=470&selected_doc_group_id=4636&language_id=1](https://gforge.nci.nih.gov/docman/index.php?group_id=470&selected_doc_group_id=4636&language_id=1)_
**Some slides from the exercise follow.**

## Exercise: Creating Your UML Model An Incomplete Information Model

**Exercise: Creating Your UML Model ****An Incomplete Information Model**

- ClassName

- attributeName

- Datatype

- Bi-directional Association

- associationName

- Multiplicity

- Generalization

**Notes:**
Here is a simplified version of gridPIR with some objects removed. Some names for parts of the UML model are indicated. One critical component of the model missing the gene object which connects proteins to the genetic material DNA, lets add it to this model.

## In the EA Project View navigate to Domain Model > Logical Model > edu > georgetown > pir > domain folder and double click on the Logical Model if the Class Diagram is not already visible.
Right click on the domain folder, select Add > Add Element
Select Type as Class
Enter the name of the class (remember the naming conventions)
Select all check boxes
Click OK
Click OK again
An new Classwill appear in thediagram

**Right click on the domain folder, select **Add **> **Add Element
**Select Type as Class**
**Enter the name of the class (remember the naming conventions)**
**Select all check boxes**
**Click OK**
**Click OK again**
**An new Class****will appear in the****diagram**

**Exercise: Creating Your UML Model ****Adding Classes**

## Exercise: Creating Your UML Model Adding Attributes to Classes

**Select the new gene Class in either the Class Diagram or the Project View, right click > attributes....**
**Enter the name of the attribute (adhere to naming convention)**
**Enter the datatype in the Type field**
- Type in the java primitive or
- 	wrapper class, using the dropdown
- 	list can cause problems
**Click **Save
**Click **New **to enter more attributes**
**Click **Close **when finished**

## Exercise: Creating Your UML Model Adding tags for definitions for classes

**Select the Gene Class in the Project View or the Class Diagram**
**Select **Element > Tagged Values** from the Main Menu **
**Enter “CADSR_Description” **
**	****as the tag name**
**Enter the class definition**** as the value**
**Click OK**
**DO NOT use Notes ****section for the definition**

## Exercise: Creating Your UML Model Adding tags for definitions for attributes

**Select the attribute entrezGeneId in the Class Gene in the Project View or Diagram**
**Select **Element > Tagged Values** from the Main Menu**
**Enter “CADSR_Description” for the tag name**
**Enter the attribute’s definition in the value field.**
**Click OK**

## Exercise: Creating Your UML Model Associations

**From the Menu button bar, select **Link > Association (or from the toolbox > Class > Associate)
**Click and hold one class **(source),** **then drag and drop to the second class (target) to create the link.
**Right click on the association **(or double click)** **and select Association Properties.
**Click the **Source Role** tab**
**Enter the role name (className)**
- Add “Collection” if >1
**Select the Multiplicity from **
**	****the dropdown**
**Click OK**
**Do the same for the **Target Role

## Exercise: Creating Your UML Model A Completed Protein Model

**Protein + Gene and Related Classes**

**Notes:**
You did it

## Acknowledgements

**Peter McGarvey **
**Baris Suzek**
**Mike Keller**
**Dianne Reeves **
**George Komatsoulis**
**Avinash Shanbhag**
**Becky Angeles**
**Jennifer Brush**
**Jamie Parker**
**Claire Wolfe**
**Ken Smith**
**Sal Mungal**
**Virginia Hetrick**
**Shannon Hastings **
**Architecture/VCDE workspace participants**