Hephaestus - College of Computing & Informatics · Web viewSOA stands for service oriented...

Hephaestus

Software Design Specification

Tejprakash GillJohn HaasPatrick LocknerPhil MaconiJonathan MonteiroAlex Rybak

Version InformationVersion 1.0 2/21/2012

- Initial document

Version 1.1 5/1/2012

- Minor updates to context diagram

1 | P a g e

Table of Contents1 Introduction.........................................................................................................................................4

1.1 Purpose........................................................................................................................................4

1.2 Scope...........................................................................................................................................4

1.3 Project Overview.........................................................................................................................4

1.4 Definitions, Acronyms, and Abbreviations...................................................................................4

2 Architecture.........................................................................................................................................6

2.1 Introduction.................................................................................................................................6

2.2 Context Diagram..........................................................................................................................6

2.3 Detailed Architecture...................................................................................................................7

2.4 Overview......................................................................................................................................8

2.4.1 Three-Tier Client-Server Architecture..................................................................................8

2.4.2 RESTful MVC Architecture....................................................................................................8

2.4.3 Service-Oriented Architecture.............................................................................................8

2.5 Survey of Technologies................................................................................................................8

3 Object Models...................................................................................................................................10

3.1 Introduction...............................................................................................................................10

3.2 Presentation Layer.....................................................................................................................10

3.2.1 Controllers.........................................................................................................................10

3.2.2 Views.................................................................................................................................11

3.3 Business Logic Layer...................................................................................................................15

3.3.1 Models...............................................................................................................................15

3.3.2 Services..............................................................................................................................17

3.3.3 File Converter Class Diagram.............................................................................................22

3.4 Data Layer..................................................................................................................................24

3.4.1 Data Access Objects...........................................................................................................24

4 Sequence Diagrams...........................................................................................................................25

4.1 Use Case 1: Create Account.......................................................................................................25

4.2 Use Case 2: Login.......................................................................................................................26

4.3 Use Case 3: Logout.....................................................................................................................27

2 | P a g e

4.4 Use Case 4: Reset Password.......................................................................................................28

4.5 Use Case 5: View Profile............................................................................................................29

4.6 Use Case 6: Update Profile........................................................................................................30

4.7 Use Case 7: Follow User.............................................................................................................31

4.8 Use Case 8: Unfollow User.........................................................................................................32

4.9 Use Case 9: View Wall................................................................................................................33

4.10 Use Case 10: Post to Wall..........................................................................................................34

4.11 Use Case 11: Delete from Wall..................................................................................................35

4.12 Use Case 12: View Stream.........................................................................................................36

4.13 Use Case 13: Search for User or Group......................................................................................37

4.14 Use Case 14: Create Group........................................................................................................38

4.15 Use Case 15: Request Group Access..........................................................................................39

4.16 Use Case 16: Set Group Privileges..............................................................................................40

4.17 Use Case 17: Invite User to Group.............................................................................................41

4.18 Use Case 18: Accept Group Invitation........................................................................................42

4.19 Use Case 19: Leave Group.........................................................................................................43

4.20 Use Case 20: Upload Sample.....................................................................................................44

4.21 Use Case 21: Modify Sample......................................................................................................45

4.22 Use Case 22: Delete Sample......................................................................................................46

4.23 Use Case 23: View Sample.........................................................................................................46

4.24 Use Case 24: Share Sample........................................................................................................47

4.25 Use Case 25: Add Sample Segmentation Map...........................................................................48

4.26 Use Case 26: View Sample Segmentation Data..........................................................................49

4.27 Use Case 27: Run Analysis Tool..................................................................................................50

5 Data Models......................................................................................................................................51

5.1 Database Schema......................................................................................................................51

5.1.1 Sample Tables....................................................................................................................52

5.1.2 Social Network Tables........................................................................................................54

5.2 Internal Sample Storage Specifications......................................................................................56

5.2.1 Sample Metadata...............................................................................................................57

5.3 Sample Input Specifications.......................................................................................................57

5.3.1 RAW Input Files..................................................................................................................57

3 | P a g e

5.3.2 TIFF Input Files...................................................................................................................58

5.3.3 ANG Input Files..................................................................................................................58

6 Algorithms.........................................................................................................................................60

7 Traceability Matrix.............................................................................................................................61

8 References.........................................................................................................................................63

4 | P a g e

1 Introduction

1.1 PurposeThis document specifies the software architecture and design for the Hephaestus materials engineering portal, a component of the Materials genome initiative. It contains the specifications for the system in the form of object models, data models, algorithm descriptions, and interaction details.

This document fully details how to fulfill the contract for functionality established in the Hephaestus Software Requirements Specification [1].

1.2 ScopeThis document describes the software architecture and design for the initial release of Hephaestus. The intended audience of this document exclusively includes the designers, developers, and testers of the Hephaestus portal.

1.3 Project OverviewThe Hephaestus system is a web-based portal meant to facilitate materials engineering research by providing the following high-level features to its users:

- Upload and share material samples with customizable levels of access control- Perform and share analyses on uploaded samples- Allow users to search for specific samples or analysis results- Facilitate collaboration between researchers through social networking tools- Provide system access through an exposed service interface

For more information pertaining to the capabilities of the system, see the Hephaestus Software Requirements Specification [1].

1.4 Definitions, Acronyms, and Abbreviations ANG A format for storing sample data API Application programming interface MATLAB A tool and programming language that supports complex computations MVC A framework/architecture focused on rich user interactions and

separation of presentation and logic. MVC stands for model, view, controller.

REST A distributed architecture focused on simplicity and idempotence – performing the same action more than once will not have adverse side-effects. The most well-known RESTful system is HTTP.

RAW A binary file format in which the data has not been processedSOA SOA stands for service oriented architecture, it relies on remote services

as its main components.

5 | P a g e

TIFF Abbreviation for ‘tagged image file format’. This format is commonly used in scientific imaging.

Three-Tier Architecture: An architecture that divides components into presentation, logic, or data. Presentation components can only communicate with data components by going through logic components, and vice versa.

6 | P a g e

2 Architecture

2.1 IntroductionThis section of the document shows the overall architecture of Hephaestus in increasing levels of detail. It also provides insight as to why specific design choices were made.

2.2 Context DiagramThe context diagram in Figure 1 shows how Hephaestus interfaces with external components. External components are distinguished by darker shading.

Figure 1: Context Diagram

Hephaestus has two primary means of interaction. It can be accessed by a web browser through its front-end or programmatically through its exposed web services. Hephaestus makes use of two types of external systems. It utilizes MATLAB servers to run statistical analyses on store sample data and utilizes an external email system to send notification messages to its users.

7 | P a g e

2.3 Detailed ArchitectureThe architecture diagram in Figure 2 shows how the components utilized by Hephaestus interact with one another. In Figure 2, the solid arrows signify requests and the dotted arrows signify responses. Colored objects are internal to Hephaestus and grey objects are external.

Figure 2: Architecture Diagram

8 | P a g e

2.4 OverviewThe Hephaestus system has a hybrid design combining three distinct architectures: three-tier client-server, RESTful MVC, and service-oriented.

2.4.1 Three-Tier Client-Server Architecture At the highest level, Hephaestus resembles the three-tier client-server architecture. This design separates the various system components based on their functionality into three layers: the presentation layer, the business logic layer, and the data layer.

The presentation layer is responsible for displaying information to the user. In the case of Hephaestus, this is the layer that the user interacts with through a web browser.

The business logic layer handles the system functionality by processing commands and transferring data between the surrounding layers.

The data layer handles the storage and retrieval of data from the system’s database and remote file system.

2.4.2 RESTful MVC ArchitectureSpread between the presentation layer and business logic layer of Hephaestus is a RESTful MVC subsystem.

The MVC architecture provides a way to present data to a user with rich interaction capabilities. Models represent data objects, views represent ways to display those objects, and controllers allow the user to move between views and interact with the data.

In the Hephaestus system, both the controllers and the views are handled at the presentation layer. Models are accessed in the business logic layer through standard HTTP RESTful commands.

2.4.3 Service-Oriented ArchitectureThe final aspect of the Hephaestus design is a service-oriented architecture within the business logic layer. This layer provides external programmatic access to the Hephaestus portal. By embedding the services in the business logic layer, Hephaestus guarantees that any functionality utilized by the front-end is also available through an API.

2.5 Survey of TechnologiesThere are a number of commercial and open-source technologies used by Hephaestus. This section briefly details how each external technology is utilized

- HDF5: A hierarchical data format that is designed to store large quantities of scientific data.- Hibernate: A relational persistence tool for Java and .Net that provides object based access to

a database.- MATLAB: A programming environment for algorithm development, data analysis,

visualization, and computation. MATLAB servers are used to perform analyses on samples and construct data visualizations.

9 | P a g e

- MySQL: An open-source relational database. It is used to store the various pieces of information Hephaestus needs to operate.

- Spring: An application development framework for Java. Hephaestus uses Spring to handle its MVC system, web services, dependency injection, and access control.

- TORQUE: A resource manager that provides control over batch jobs and distributed computing resources. It is utilized to access a MATLAB server cluster as well as to handle uploaded file conversions.

10 | P a g e

3 Object Models

3.1 IntroductionThis section of the document details the object models within the three tiers of the system. After each object model is a short overview of the classes and complex methods contained within it. Generic getters, setters, and constructors are not covered in the overview.

3.2 Presentation Layer

3.2.1 ControllersThe UML class diagram for the controllers can be seen in Figure 3.

11 | P a g e

Figure 3: Controller Class Diagram

3.2.1.1 Social ControllerPurpose: Serves as the root of an inheritance tree. Methods shared between all social controllers are attached to it.

Notable Methods: None, this controller contains only global getters and setters.

Related Requirements: 3.3.2.6

3.2.1.2 Sample Controller Purpose: Provides a way to interact with samples and segments.

12 | P a g e

Notable Methods: share() provides the mechanism to handle sample sharing, while unshare() provides the means to revoke sharing permissions. getSegments() retrieves the list of segments associated with a sample. getSegment() allows the user to view information about a single segment. Similarly, getSamples() and getSample() perform the same way with regards to samples. runAnalysis() provides the interface to trigger an analysis tool. Finally, editSampleMetadata() allows the user to change information that they have previously uploaded. deleteSample() allows the user to remove the sample from the system.

Related Requirements: 3.3.3.2, 3.3.3.3.*, 3.3.3.4, 3.3.3.4.1, 3.3.3.4.2, 3.3.3.4.4, 3.3.3.5.*, 3.3.4.1, 3.3.4.1.1, 3.3.4.1.2, 3.3.4.2.*

3.2.1.3 Wall ControllerPurpose: Allows for user walls to be viewed and modified.

Notable Methods: getWallItems() retrieves all posts for a user, if the requesting user is following that user. postMessage() adds a message to a user’s wall. deleteMessage() removes a post if the caller posted or received the message.

Related Requirements: 3.3.2.3.*

3.2.1.4 Stream ControllerPurpose: Gives users a way to see their stream.

Notable Methods: getStreamItems() retrieves all stream posts for the current user. deleteMessage() provides a way to remove a post from a stream if the user sent or received the message directly.


3.2.1.5 File Upload ControllerPurpose: Gives users a way to upload segments and samples.

Notable Methods: handleFormUploadSample() allows users to transfer multi-gigabyte files over HTTP to the system. handleFormUploadSegment() provides a way to add new segments to a sample.


3.2.1.6 Follower ControllerPurpose: Gives users a way to handle their follower/following relationships.

Notable Methods: getFollowers() retrieves a list of people that are following a user. getFollowing() retrieves a list of people that a user is following. Follow() and unfollow() allow a user to control their following list.


13 | P a g e

3.2.1.7 Password Reset ControllerPurpose: Gives users a way to reset their passwords.

Notable Methods: acceptForm() handles the password reset form.


3.2.1.8 Registration ControllerPurpose: Presents users with the ability to register for a Hephaestus account.

Notable Methods: acceptForm() handles the registration form.

Related Requirements: 3.3.1.1, 3.3.1.1.2

3.2.1.9 Login ControllerPurpose: Presents users with the ability to log in and out of the system

Notable Methods: login() validates the session, logout() invalidates it.

Related Requirements: 3.3.1.2, 3.3.1.2.1, 3.3.1.3

3.2.1.10 Group ControllerPurpose: Gives users a way to access their groups.

Notable Methods: acceptInvitation() allows users to accept invitations to groups, getInvitations() allows users to see their current invitations, rejectInvitation() allows users to reject their invitation to groups, requestGroupAccess() allows users to request to join a group. leaveGroup() allows users to leave a group.


3.2.1.11 Service Authentication ProviderPurpose: Used to handle session invalidation as part of the Spring framework

Notable Methods: Authenticate is triggered after the user attempts to log in via the login controller.

Related Requirements: 3.3.1.2, 3.3.1.2.1

3.2.1.12 Path GeneratorPurpose: Used to handle intermediary file placement during the upload process.


3.2.1.13 Profile ControllerPurpose: Used to handle retrieving and editing user profiles.

14 | P a g e

Notable Methods: getProfile() retrieves an individual profile, editProfile() edits the current user’s profile.


3.2.2 ViewsThe views of the presentation layer provide the rules on how to display data to the user. The transition diagram for the views in the Hephaestus system can be seen in Figure 4.

Figure 4: View Transition Diagram

In the above diagram, the views have been divided into three component categories that match up with those listed in Figure 2.

For more details pertaining to how the views should be rendered, see the Hephaestus Software Requirements Specification [1].

15 | P a g e

3.3 Business Logic Layer

3.3.1 ModelsThe UML class diagram for the models can be seen in Figure 5 and Figure 6.

Figure 5: Models Class Diagram, Part 1

16 | P a g e

Figure 6: Models Class Diagram, Part 2

In Figure 6, the classes have their methods hidden to conserve space. Each model class is simply a data object with a default constructor, a constructor that takes in each attribute, and a constructor that takes in each attribute that is not a collection. Additionally, each class has a getter and setter for every attribute.

The classes in the above figures are extremely important to the system, but do not contain any functionality. They are simply data encapsulation classes.

17 | P a g e

3.3.2 ServicesThe UML class diagrams for the web services can be seen in Figures 7-10.

18 | P a g e

Figure 7: Web Service Class Diagram, Part 1: Social Service and Group Service

19 | P a g e

Figure 8: Web Service Class Diagram, Part 2: Sample Service

20 | P a g e

Figure 9: Web Services Class Diagram, Part 3: Analysis Service

21 | P a g e

Figure 10: Web Services Class Diagram, Part 4: Account Service

3.3.2.1 Social ServicePurpose: Provides an API to interface with users, profiles, followers, friends, walls, streams, and groups.

Notable Methods: All methods in this class are notable. Most of the method names are self-descriptive, however. The postMessageUserUser() specifies that a message is from a user to another user, while postMessageUserGroup() specifies that a message is from a user to a group.

Related Requirements: 3.3.2.1.3, 3.3.2.1.7, 3.3.2.2.*, 3.3.2.3.*, 3.3.2.4.*, 3.3.2.5

3.3.2.2 Group ServicePurpose: Provides an API to deal specifically with user groups.

Notable Methods: The methods in this class are general CRUD (create, update, delete) actions pertaining to groups.

Related Requirements: 3.3.2.1.3, 3.3.2.1.7, 3.3.2.2.*, 3.3.2.3.*, 3.3.2.4.*, 3.3.2.5

22 | P a g e

3.3.2.3 Sample ServicePurpose: Provides an API to deal with samples, segments, and visualizations.

Notable Methods: This class has methods related to uploading, sharing, and retrieving samples and segments. The methods are all descriptively named.

Related Requirements: 3.3.3.*, with the exception of 3.3.3.4.3

3.3.2.4 Image ProcessorPurpose: Implements the algorithm described in Section 6, which deals with segment visualization.

Notable Methods: generateColorImage() executes the visualization algorithm. getImageColors() parses the image to get a list of all colors in use.

Related Requirements: 3.3.3.*, with the exception of 3.3.3.4.3

3.3.2.5 Path GeneratorPurpose: Supports the Sample Service and Image Processor by determining where files should be saved or found. It provides methods for HTTP retrievals as well as local retrievals.


3.3.2.6 Analysis ServicePurpose: Provides the means to trigger an analysis execution. It also supports retrieving analysis results.

Notable Methods: getAnalysisTools() returns a list of analyses that can be run. getAnalysisResults() retrieves a result based on a sample ID and tool ID. runAnalysis() triggers a remote execution of an analysis tool on a sample.


3.3.2.7 Analyze ComputerPurpose: Provides an interface for new analysis tools to plug into. Two Point Analyzer and Chord Length Analyzer are the objects currently utilizing the interface.

Related Requirements: 3.3.4.1, 3.3.4.1.1, 3.3.4.1.2

3.3.2.8 Account ServicePurpose: Provides a way to create accounts, login, reset passwords, retrieve profiles, update profiles, and search for users.

Notable Methods: All methods are descriptively named.

Related Requirements: 3.3.1.1, 3.3.1.1.2, 3.3.1.2, 3.3.1.2.1, 3.3.1.3

3.3.2.9

23 | P a g e

3.3.3 File Converter Class DiagramThe UML class diagram for the file converter can be seen in Figure 11.

Figure 11: File Converter Object Model

24 | P a g e

3.3.3.1 Sample ConverterPurpose: Provides a main() function to allow the conversion tool to act as a stand-alone application that can be deployed to remote systems.

25 | P a g e

3.3.3.2 Sample LoaderPurpose: Performs the file conversions from input data. It is responsible for the techniques described in Section 5.2 and Section 5.3.

Notable Methods: There is one method per supported input type (TIFF, RAW, and ANG). The methods take in the sample ID to convert as well as the target filename.

Related Requirements: 3.3.1.*

26 | P a g e

3.4 Data Layer

3.4.1 Data Access ObjectsThe UML class diagram for the data access objects can be seen in Figure 12.

Figure 12: Data Access Objects Class Diagram

27 | P a g e

Like the model classes in Section 3.3.1, the DAO objects are vital for the system to function. They provide direct access to the Hephaestus database (described in Section 5.1). However, methods contained within them are strictly CRUD database operations facilitated by Hibernate [3]. They do not need further explanation.

4 Sequence Diagrams

4.1 Use Case 1: Create Account

Figure 13: Create Account Sequence Diagram

The user accesses the web-based registration form and attempts to create an account. The registration controller passes the request to the account service, which attempts to create the account by accessing the DAO. The result of the attempt is conveyed back to the user.

28 | P a g e

4.2 Use Case 2: Login

Figure 14: Login Sequence Diagram

The user accesses the web-based login form and attempts to sign in. The login controller passes the request to the account service, which validates the credentials through the DAO. If the credentials pass validation, the user is brought to their home page. Otherwise an error message is displayed.

29 | P a g e

4.3 Use Case 3: Logout

Figure 15: Logout Sequence Diagram

The user presses the logout button from inside Hephaestus. The login controller processes the request, invalidates the user’s session, and redirects them to the login page.

30 | P a g e

4.4 Use Case 4: Reset Password

Figure 16: Reset Password Sequence Diagram

The user presses the reset password button on the login page. The web browser forwards the request to the password reset controller, which calls the reset password method of the account service. The service attempts to generate a password and apply it. If successful, an email is sent to the user and a message is displayed informing them to check their inbox. If unsuccessful, an error message is displayed.

31 | P a g e

4.5 Use Case 5: View Profile

Figure 17: View Profile Sequence Diagram

The user presses the link to view a profile. The browser forwards the request to the profile controller, which retrieves the profile from the account service. The account service retrieves the user information from the DAO and converts it into a profile, which is returned and displayed.

32 | P a g e

4.6 Use Case 6: Update Profile

Figure 18: Update Profile Sequence Diagram

The user clicks the button to edit their profile. The web browser processes the request. The controller returns an editable page. The user edits the page and submits their changes. The browser processes the request and the controller calls update profile from the account service. The account service uses the User DAO to make the changes and returns. The profile controller directs the user to an updated profile page.

33 | P a g e

4.7 Use Case 7: Follow User

Figure 19: Follow User Sequence Diagram

The user clicks a link to follow another user. The request gets passed to the social service by the follower controller. The service attempts to follow the other user and returns the result. The user is shown a message conveying the result.

34 | P a g e

4.8 Use Case 8: Unfollow User

Figure 20: Unfollow User Sequence Diagram

The user clicks a link to unfollow another user. The request gets passed to the social service by the follower controller. The service attempts to unfollow the other user and returns the result. The user is shown a message conveying the result.

35 | P a g e

4.9 Use Case 9: View Wall

Figure 21: View Wall Sequence Diagram

The user clicks a link to access someone’s wall. The wall controller calls getWallPosts on the social service, which retrieves the posts from the DAO. The posts are returned to the controller, which feeds them into a wall view for the user to see.

36 | P a g e

4.10 Use Case 10: Post to Wall

Figure 22: Post to Wall Sequence Diagram

The user submits a post to a wall, which is passed from the wall controller to the social service. The social service uses the social DAO to determine if the original user is allowed to post a message to the other user. If so, the message gets posted and the wall is displayed. Otherwise an error message is conveyed to the user.

37 | P a g e

4.11 Use Case 11: Delete from Wall

Figure 23: Delete from Wall Sequence Diagram

In this sequence, the user attempts to delete a post from a wall. The wall controller calls the appropriate method in social service, which checks to see that the user is either the post’s author or recipient before proceeding. If so, the user is allowed to delete the post and the wall is refreshed. Otherwise, an error message is displayed.

38 | P a g e

4.12 Use Case 12: View Stream

Figure 24: View Stream Sequence Diagram

The user decides to view their stream. The stream controller call get stream from the social service, which returns the stream after retrieving it from the Dao.

39 | P a g e

4.13 Use Case 13: Search for User or Group

Figure 25: Search for User or Group Sequence Diagram

The user submits a query into the user/group search box. The follower controller receives the request and forwards it to the appropriate account service method. The account service utilizes the user DAO to get a list of results, which are returned to the controller. The process is repeated with the group service and group DAO. The two sets of results are merged and formatted for the user.

40 | P a g e

4.14 Use Case 14: Create Group

Figure 26: Create Group Sequence Diagram

The user submits a form to create a group, which is passed to the group controller. The group controller utilizes the create group method of group service, which attempts to create a group through the group DAO. The result of the attempt is returned to the controller and processed to appropriately notify the user.

41 | P a g e

4.15 Use Case 15: Request Group Access

Figure 27: Request Group Access Sequence Diagram

In this use case, the user clicks a button to request a group invitation. The request goes through the group controller, group service, and finally group DAO before being added to the group’s request list.

42 | P a g e

4.16 Use Case 16: Set Group Privileges

Figure 28: Set Group Privileges Sequence Diagram

This diagram details how an administrator changes the privileges of members within a group. The administrator clicks a link corresponding with a promotion, which gets wired through the group controller, group service, and group DAO before affecting the target user.

This process will fail if the target user leaves the group, becomes promoted in the meantime, or if the initial user is not actually an administrator.

43 | P a g e

4.17 Use Case 17: Invite User to Group

Figure 29: Invite User to Group Sequence Diagram

In this use case, the group’s administrator is responsible for inviting members to join. The admin enters a user’s name in the invitation box and clicks a button. The invitation gets routed through the group controller, group service, and finally reaches the database when it gets to the group DAO. The group’s ID gets added to a list of invitations that a user can look at and choose to accept at any time.

44 | P a g e

4.18 Use Case 18: Accept Group Invitation

Figure 30: Accept Group Invitation Sequence Diagram

This sequence begins when a user clicks to accept a group invitation. The group controller calls the accept invitation method of the group service, which makes two calls to the group DAO. First it adds the user to the group. Then it deletes the old invitation before returning.

45 | P a g e

4.19 Use Case 19: Leave Group

Figure 31: Leave Group Sequence Diagram

The user begins this use case by clicking the leave group button on a group’s page. The request goes to the group controller, which calls the group service. The group service utilizes the group DAO in order to remove the user from the group. The group controller then notifies the user that they have left the group.

46 | P a g e

4.20 Use Case 20: Upload Sample

Figure 32: Upload Sample Sequence Diagram

For this sequence, the user submits a sample through the upload form on the website. It is saved to a temporary directory on the web server while it is being streamed to its permanent location. Once the file has been saved, the metadata passed on by the user is sent to the sample service, which uses the sample DAO to assign an ID to the sample. The sample is sent to be converted from its input type to Hephaestus’ HDF5 format (see Section 5.2).

If the sample is converted successfully, the sample service returns the sample’s new ID to the controller. The controller uses that ID to load the sample page for the user.

If the sample is not converted successfully, the sample service returns a failure exception which causes the controller to display an appropriate error message.

47 | P a g e

4.21 Use Case 21: Modify Sample

Figure 33: Modify Sample Sequence Diagram

The user clicks the edit sample button and the controller returns fields that are editable. The user makes the desired changes and hits submit. The sample controller calls the edit method on the sample service, which uses the sample DAO to try to save the changes. If successful, the user’s page is reloaded and reflects the changes. If it is not successful, the user is shown an appropriate error message.

48 | P a g e

4.22 Use Case 22: Delete Sample

4.23 Use Case 23: View Sample

Figure 34: View Sample Sequence Diagram

The user clicks a link to open a sample. The sample controller accesses the sample service to lookup the sample information by ID, which it does through the sample DAO. The DAO returns either the found sample or an exception indicating failure. If a sample is found, the service returns the information and the controller loads the detail page. Otherwise, an error message is displayed.

49 | P a g e

4.24 Use Case 24: Share Sample

Figure 35: Share Sample Sequence Diagram

50 | P a g e

4.25 Use Case 25: Add Sample Segmentation Map

Figure 36: Add Sample Segmentation Map Sequence Diagram

This process begins when the user completes the final step of the upload segment form. The segmentation image is uploaded to the sample service and the colors are extracted from it and stored in the database. The user is then notified of success.

51 | P a g e

4.26 Use Case 26: View Sample Segmentation Data

Figure 37: View Sample Segmentation Sequence Diagram

The user clicks a link to open segmentation data for a sample. The sample controller accesses the sample service to lookup the segmentation information by ID, which it does through the sample DAO. The DAO returns either the found segmentation data or an exception indicating failure. If successful, the service returns the information and the controller loads the detail page. Otherwise, an error message is displayed.

52 | P a g e

4.27 Use Case 27: Run Analysis Tool

Figure 38: Run Analysis Tool Sequence Diagram

This last sequence details how an analysis is performed after the user hits the begin button. The sample controller calls the analysis service and tells it to begin running, asynchronously. After the tool has started, the analysis service returns and gives the user a message saying that they will be emailed upon analysis completion. Once the tool has finished running, an email is sent to the user. After receiving the email, the user clicks a button to see the results. The sample controller queries the analysis service, which retrieves the results from the sample DAO to return to the user.

53 | P a g e

5 Data ModelsHephaestus has three areas of specialized data handling: the sample/social network database, and the internal sample format, and the sample input types.

5.1 Database Schema

Figure 39: Hephaestus Database Schema

54 | P a g e

5.1.1 Sample Tables

5.1.1.1 SampleColumn Name Type Notes

PK ID Long Unique identifierMaterial_name Varchar(400) Material typeName Varchar(400) Identifying name for the sampleCharacterization_technique Longtext Type of technique used to get the

sampleDescription Longtext Summary from the uploaderSpatial_dimensionality Integer 2D or 3D

FK Author_id Long UploaderFK Sample_symmetry_id Long Enumeration about samples

Dimension_x Integer Width of the sampleDimension_y Integer Height of the sampleDimension_z Integer Depth of the sampleStep_size_x Double Resolution of a pixel in X directionStep_size_y Double Resolution of a pixel in Y directionStep_size_z Double Resolution of a pixel in Z directionOrientation_x Double Rotation describing the orientation of

the volume relative to the physical orientation

Orientation_y Double Rotation describing the orientation of the volume relative to the physical orientation

Orientation_z Double Rotation describing the orientation of the volume relative to the physical orientation

Data_file_path Varchar(400) Path to store the HDF5 fileThumbnail_file_path Varchar(400) Path to store a compressed thumbnail

5.1.1.2 Funding Agency

Column Name Type NotesPK ID Long Unique identifier

Agency_name Varchar(400) Name of source of fundsDescription Varchar(400) Description of source

5.1.1.3 Sample Composition

Column Name Type NotesPK ID Long Unique identifierFK Sample_id Long Sample ID

Element Varchar(45) Chemical element namePercentage Double % composition

55 | P a g e

5.1.1.4 Sample AttributeColumn Name Type Notes

PK ID Long Unique identifierFK Sample_id Long Sample ID

Key Varchar(100) Miscellaneous key storeValue Varchar(100) Miscellaneous value storeKeyType Varchar(100) Miscellaneous descriptor

5.1.1.5 Macroscale Sample ImageColumn Name Type Notes


Image_location Varchar(500) Image path for sample visualization

5.1.1.6 SegmentColumn Name Type Notes


Name Varchar(255) Segment nameFile_path Varchar(255) Segment file location

5.1.1.7 Segment Color

Column Name Type NotesPK Hex_code Varchar(6) Hex RGB valuePK,FK

Segment_id Long Segment ID

Description Varchar(255) Color description

5.1.1.8 ToolColumn Name Type Notes

PK ID Long Unique identifiername Varchar(400) Tool used to segment data

5.1.1.9 Sample Funding Agency Map

Column Name Type NotesPK, FK

Sample_id Long Sample ID

PK, FK

Funding_agency_id Long Funding Agency ID

5.1.1.10 Segment Tool MapColumn Name Type Notes

PK, FK

Segment_id Long Segment ID

PK, Tool_id Long Tool ID

56 | P a g e

FKNumber_of_images Integer Count of images generated

5.1.1.11 Sample SymmetryColumn Name Type Notes

PK ID Long Unique identifiername Varchar(45) Enumeration values include: triclinic,

monoclinic, orthorhombic, tetragonal, trigonal, hexagonal, and cubic

5.1.1.12 Processing History

Column Name Type NotesPK ID Long Unique identifierFK Sample_id Long Sample ID

Step_number Integer Step number for the processdescription Varchar(255) Description of the process

5.1.2 Social Network Tables

5.1.2.1 User AttributeColumn Name Type Notes

PK ID Long Unique identifierEmail_address Long Sample IDPassword Varchar(100) Hashed passwordtitle Varchar(100) User titleFirst_name Varchar(100) First nameLast_name Varchar(100) Last name

FK Location_id Long User locationFK Affiliation_id Long User affiliation

5.1.2.2 Location


City Varchar(100) CityState Varchar(100) StateCountry Varchar(100) Country

5.1.2.3 AffiliationColumn Name Type Notes

PK ID Long Unique identifiername Varchar(250) Name of affiliation

5.1.2.4 Sample Project Map

Column Name Type NotesPK, Sample_id Long Sample ID

57 | P a g e

FKPK, FK

Project_id Long Project ID

5.1.2.5 Group Sample Access


Sample_id Long Sample ID

PK, FK

Group_id Long Group ID

5.1.2.6 Group RoleColumn Name Type Notes

PK, FK


PK, FK

User_id Long User ID

FK Access_level_id Long Acces level ID

5.1.2.7 Access LevelColumn Name Type Notes

PK ID Long Unique identifiername Varchar(45) Role type

5.1.2.8 Group Type


name Varchar(45) Group type

5.1.2.9 Group Project AccessColumn Name Type Notes

PK, FK

Project_id Long Project ID

PK, FK


5.1.2.10 Following


Source_group_id Long Follower group ID

PK, FK

Target_group_id Long Following group ID

5.1.2.11 Group Research InterestColumn Name Type Notes

58 | P a g e

PK, FK


PK, FK

Research_interest_id Long Research Interest ID

5.1.2.12 Research InterestColumn Name Type Notes

PK ID Long Unique identifiername Varchar(100) Description of interest

5.1.2.13 Project

Column Name Type NotesPK ID Long Unique identifierFK Owner_group_id Long Project owner ID

Name Varchar(250) Project name

5.1.2.14 User Group

Column Name Type NotesPK ID Long Unique identifierFK Type_id Long Group type ID

Name Varchar(100) Group nameBiography Longtext Group biographyWebsite Varchar(245) Group website

5.1.2.15 Message

Column Name Type NotesPK ID Long Unique identifierFK Reply_to_id Long Message ID that this replied toFK Source_group_id Long Sender group IDFK Target_group_id Long Recipient group ID

Message_body Longtext MessageisRead Bit Flag to see if the message was readTimestamp Datetime Date and time message was sent

5.2 Internal Sample Storage SpecificationsHephaestus stores materials engineering samples in an HDF5 format [2], which is a hierarchical data format that contains three distinct types of objects.

1. Datasets: multidimensional arrays of a homogenous type2. Groups: container structures that can hold datasets or other groups3. Attributes: Key/value pairs attached to groups or datasets

There are two types of data samples that can be uploaded into Hephaestus: 2D samples and 3D samples. Both of these types of data are represented the same way, internally. A group is created

59 | P a g e

for the sample. The raw data for that sample is placed into a dataset of type float within that group. Finally, metadata is attached to the sample as described in Section 5.2.1.

5.2.1 Sample MetadataSection 5.1.1 described the various pieces of metadata relating to a sample that are stored in the database. All of that information must also be mirrored within the HDF5 file, so that researchers are able to extract the data.

Attributes that have a one-to-one relationship with the sample can be directly attached to the sample dataset as HDF5 attributes. Such attributes are stored in the Sample table of the database.

Attributes that have a many-to-one relationship with the sample are encapsulated in groups within the HDF5 sample, with the group name corresponding to the database table name. That group contains child groups for each of the columns within the table. Finally, each of the children groups contains a single dataset. A row in the database table corresponds to a single entry across all of the datasets. An illustration of this process for the Sample Composition attribute can be seen in the figure below.

Figure 40: Sample Composition HDF5 Representation

5.3 Sample Input SpecificationsHephaestus accepts three file formats as input: RAW, TIFF, and ANG. Each of these formats needs to be converted to HDF5 differently.

5.3.1 RAW Input FilesRAW input files are byte streams where each byte of the data corresponds to a single element in the sample. This file format contains no metadata, so the user must supply everything.

The only metadata required to convert a RAW sample into the Hephaestus HDF5 format are the X, Y, and Z dimension specifications. As the RAW file is read, the values are inserted sequentially into the array beginning at [0, 0, 0] and incrementing X until the maximum X dimension is reached. At that point, Y is incremented by 1 and X starts over at zero. The process repeats until Y reaches its maximum value, at which point Z is incremented by 1 and both X and Y start over at 0. This process continues until the entire dataset is filled.

60 | P a g e

If the input file ends before the 3D array is filled, an exception is thrown and the conversion fails. The same occurs if the array is filled before the file ends.

5.3.2 TIFF Input FilesTIFF input files represent 2D sample data. Each pixel of the TIFF image represents a single value in the sample dataset. Although TIFF files can contain metadata attributes, the only guaranteed values are for width and height. Therefore the user is responsible for supplying all relevant information with the exception of the dimension specifications.

TIFF samples are converted to the Hephaestus HDF5 format by retrieving the color values of each pixel in the image and placing them into the same position within the dataset array.

5.3.3 ANG Input FilesANG input files are ASCII files output by an Orientation Imaging Microscopy scan. They correspond to 2D sample data. The files consist of a header, body, and footer.

Each line of the header begins with a # character and can be ignored. Comments also being with a # character and can be ignored.

The body contains nine tab-separated values:1, , 2, x, y, IQ, CI, Phase ID, and Detector Intensity. Those fields are described below:

- 1, , 2: Euler angle in Bunge’s notation for describing the lattice orientations and are given in radians. A value of 4 is given to each Euler angle when an EBSP could not be indexed. These points receive negative confidence index values when read into an OIM dataset.

- x, y: The horizontal and vertical coordinates of the points in the scan, in microns. The origin (0,0) is defined as the top-left corner of the scan.

- IQ: The image quality parameter that characterizes the contrast of the EBSP associated with each measurement point.

- CI: The confidence index that describes how confident the software is that it correctly indexed the EBSP, i.e., confidence that the angles are correct.

- Phase ID: The material phase identifier. This field is 0 for single phase OIM scans or 1, 2, 3… for multi-phase scans.

- Detector Intensity: An integer describing the intensity from whichever detector was hooked up to the OIM system at the time of data collection, typically a forward scatter detector.

The footer contains miscellaneous data and is always preceded by an empty line. The input file can stop being parsed when the footer is reached.

These files are converted into the Hephaestus HDF5 format by scanning lines until the body is reached. At that point, each of the nine fields should be parsed into their own dataset. The detector intensity reading is the measurement that is saved as the primary sample dataset.

61 | P a g e

The remaining readings are placed into the Sample Attribute group, which contains datasets for a key, a value, and a type. The key entry corresponds to the measurement index, the value corresponds to the measured value, and the type entry corresponds to the type of measurement being inserted.

62 | P a g e

6 AlgorithmsMany of the tools used to analyze materials data rely on a process called segmentation. Segmentation is a classification process that categorizes each data measurement within a sample as either relevant or ignored. For 2D samples, the process is usually completed by analyzing the color at each pixel and determining whether it falls within an allowable range.

However, it is extremely difficult to determine if a segmentation mask makes sense when looking only at raw data. Therefore Hephaestus provides a visualization of the end-result that allows researchers to quickly determine whether the segmentation appears valid.

The following diagram shows the process which converts all ignored pixels to grayscale and leaves relevant pixels in color.

Figure 41: Color Masking Algorithm

63 | P a g e

7 Traceability MatrixThe traceability matrix below is organized compactly due to the number of classes represented in this document. Instead of having the columns represent individual classes, they represent sections of the design document. The values within the light-gray rows correspond to individual classes that were previously detailed. The only requirements not filled in the traceability matrix were those that were cut due to their low priorities.

3.2.1 3.3.2 3.3.33.3.1.1 3.2.1.8 3.3.2.83.3.1.1.1

- - -

3.3.1.1.2

3.2.1.8 3.3.2.8

3.3.1.2 3.2.1.9 3.3.2.83.3.1.2.1

3.2.1.9 3.3.2.8

3.3.1.2.2

- - -

3.3.1.3 3.2.1.9 3.3.2.83.3.1.4 3.2.1.7 3.3.2.83.3.2.1 3.2.1.10 3.3.2.23.3.2.1.1

3.2.1.10 3.3.2.2

3.3.2.1.2

3.2.1.10 3.3.2.2

3.3.2.1.3

3.2.1.10 3.3.2.1

3.3.2.1.4

3.2.1.10 3.3.2.2

3.3.2.1.5

3.2.1.10 3.3.2.2

3.3.2.1.6

3.2.1.10 3.3.2.2

3.3.2.1.7

3.2.1.10 3.3.2.1

3.3.2.2 3.2.1.6 3.3.2.13.3.2.2.1

3.2.1.6 3.3.2.1

3.3.2.2.2

3.2.1.6 3.3.2.1

3.3.2.3 3.2.1.3 3.3.2.1

64 | P a g e

3.3.2.3.1

3.2.1.3 3.3.2.1

3.3.2.3.2

3.2.1.3 3.3.2.1

3.3.2.3.3

3.2.1.3 3.3.2.1

3.3.2.3.4

3.2.1.3 3.3.2.1

3.3.2.3.5

3.2.1.3 3.3.2.1

3.3.2.3.6

3.2.1.3 3.3.2.1

3.3.2.4 3.2.1.13 3.3.2.13.3.2.4.1

3.2.1.13 3.3.2.1

3.3.2.4.2

3.2.1.13 3.3.2.1

3.3.2.4.3

3.2.1.13 3.3.2.1

3.3.2.4.4

3.2.1.13 3.3.2.1

3.3.2.4.5

3.2.1.13 3.3.2.1

3.3.2.5 3.2.1.4 3.3.2.13.3.2.6 3.2.1.1 -3.3.2.6.1

3.2.1.1 -

3.3.3.1 3.2.1.5 3.3.2.3 3.3.3.23.3.3.1.1

3.2.1.5 3.3.2.3 3.3.3.2

3.3.3.1.2

3.2.1.5 3.3.2.3 3.3.3.2

3.3.3.1.3

3.2.1.5 3.3.2.3 3.3.3.2

3.3.3.1.4

3.2.1.5 3.3.2.3 3.3.3.2

3.3.3.1.5

3.2.1.5 3.3.2.3 3.3.3.2

3.3.3.2 3.2.1.2 3.3.2.33.3.3.3 3.2.1.2 3.3.2.33.3.3.3.1

3.2.1.2 3.3.2.3

3.3.3.4 3.2.1.2 3.3.2.3

65 | P a g e

3.3.3.4.1

3.2.1.2 3.3.2.3

3.3.3.4.2

3.2.1.2 3.3.2.3

3.3.3.4.3

- - -

3.3.3.4.4

3.2.1.2 3.3.2.3

3.3.3.5 3.2.1.2 3.3.2.33.3.3.5.1

3.2.1.2 3.3.2.3

3.3.3.5.2

3.2.1.2 3.3.2.3

3.3.3.5.3

3.2.1.2 3.3.2.3

3.3.3.5.4

3.2.1.2 3.3.2.3

3.3.3.6 3.2.1.5 3.3.2.33.3.3.6.1

3.2.1.5 3.3.2.3

3.3.3.6.2

3.2.1.5 3.3.2.3

3.3.3.6.3

3.2.1.5 3.3.2.3

3.3.3.7 3.2.1.2 3.3.2.33.3.3.8 3.2.1.2 3.3.2.33.3.4.1 3.2.1.2 3.3.2.63.3.4.1.1

3.2.1.2 3.3.2.6

3.3.4.1.2

3.2.1.2 3.3.2.6

3.3.4.1.3

- - -

3.3.4.1.4

- - -

3.3.4.1.5

- - -

3.3.4.2 3.2.1.2 3.3.2.63.3.4.2.1

3.2.1.2 3.3.2.6

3.3.4.2.2

3.2.1.2 3.3.2.6

3.3.4.2. - - -

66 | P a g e

33.3.4.2.4

3.2.1.2 3.3.2.6

3.3.4.2.5

3.2.1.2 3.3.2.6

3.3.4.2.6

3.2.1.2 3.3.2.6

67 | P a g e

8 References[1] Gill, et al. Hephaestus Software Specification Document. Drexel University. February 2012

[2] The HDF Group. HDF5. http://www.hdfgroup.org/HDF5/

[3] Hibernate. http://www.hibernate.org/

68 | P a g e

http://www.hibernate.org/

http://www.hdfgroup.org/HDF5/

Hephaestus - College of Computing & Informatics · Web viewSOA stands for service oriented...

Documents

Transcript of Hephaestus - College of Computing & Informatics · Web viewSOA stands for service oriented...