**\
**

**caIntegrator-CGOM API**

**Software Design Description**

**Version 2.0**

**\[*Insert approval date of document*\]**

Document Change Record

  ------------- -------------- -------------------------------------------
  Version       Date           Description
  Number                       

  1.0           7/24/06        Initial document

  1.0           7/28/06        Incorporated Team comments

  1.0           8/25/06        Added Ram's DTO design
  ------------- -------------- -------------------------------------------

TABLE OF CONTENTS

1\. Introduction [1](#introduction)

1.1 Project Background [1](#project-background)

1.2 IdentifIcation [2](#identification)

1.3 System Overview [2](#system-overview)

1.4 Document Overview [2](#document-overview)

2\. System Architecture [4](#system-architecture)

2.1 System Architecture Overview [4](#system-architecture-overview)

2.1.1 Clinical Genomic Object Model (CG-OM)
[5](#clinical-genomic-object-model-cg-om)

2.1.2 CG-OM API Service Layer [6](#cg-om-api-service-layer)

2.1.3 CG Database Schema [6](#cg-database-schema)

2.1.4 WebGenome Integration [6](#webgenome-integration)

2.1.5 Security [7](#security)

3\. Components [8](#components)

3.1 Clinical GeNOMIC Object MODEL (CG-OM)
[8](#clinical-genomic-object-model-cg-om-1)

3.2 CG-OM MetaDATA REGISTRATION [8](#cg-om-metadata-registration)

3.3 Controlled Vocabularies and Terminologies
[9](#controlled-vocabularies-and-terminologies)

3.4 Object Query Service [9](#object-query-service-1)

3.5 Study Query Service [10](#study-query-service-1)

3.6 Analytical Query Service
[19](#however-when-no-panel-criteria-is-mentioned-this-situation-does-not-happen-analytical-query-service)

3.7 webGenome Integration [22](#webgenome-integration-1)

3.7.1 BioAssayService [24](#bioassayservice)

3.7.2 ApplicationStateService [24](#applicationstateservice)

3.8 Error Handling [25](#error-handling)

3.8.1 caIntegrator Findings Specification Errors
[25](#caintegrator-findings-specification-errors)

Appendix A -- acronym List [27](#appendix-a-acronym-list)

\[*Appendix B -- Forms and Templates*\]
[28](#appendix-b-forms-and-templates)

\[APPENDIX C -- DATABASE\] [29](#appendix-c-database)

\[*Appendix D -- Other Appendix*\] [34](#appendix-d-other-appendix)

# Introduction

The Software Design Description (SDD) describes the design decisions,
architectural design, and the detailed design needed to implement the
caIntegator's Clinical Genomic Object Model (CG-OM) Application
Programming Interface (API). The SDD is used as the basis for
implementing the software. It provides the acquirer visibility into the
design and provides information needed for software support.

This document will provide instruction and strategy for documenting the
design of requirements. The SDD is used as the basis for implementing
the software.

*This document must include or reference requirements traceability.*

***Requirements Traceability***

-   ***Design to Requirements Traceability** -- Refer to the project\'s
    RTM or insert traceability from each design element identified in
    this plan to the requirements and, if applicable, software system
    requirements it addresses.*

## Project Background 

In 2004, NCICB along with NCI's Neuro-Oncology Branch (NOB) initiated
development of a publicly accessible database known as REMBRANDT, a
Glioma Molecular Diagnostic Initiative (GMDI) which is being jointly led
by NCI and the National Institute of Neurological Disorders and Stroke
(NINDS).

GMDI includes a retrospective study of about 300 glioma tumor specimens
and a 1,000- to 1,500-patient prospective study involving two NCI-funded
brain tumor consortia and other NCI-funded institutions. Patients in the
prospective study have samples of their surgically-removed tumors sent
to NCI for genetic and molecular analyses; findings are then correlated
with each patient\'s clinical course. REMBRANDT houses both molecular
and genetic data on all brain tumor types.

Similar to REMBRANDT, NCICB is involved in the development of I-SPY
Trail Data Analysis Portal. I-SPY TRIAL is short for Investigation of
Serial Studies to Predict Your Therapeutic Response with Imaging and
Molecular Analysis.

It is an ambitious nationwide breast cancer research. The goal is to
find a way to identify the best breast cancer chemotherapy for each
individual patient. Standard chemotherapy treatments for breast cancer
may be given for months prior to surgery to remove the tumor, or else
for months afterward. Women with especially aggressive cancer might
receive chemotherapy both before and after surgery. These standard
treatments have proved generally effective in treating the disease and
lessening the likelihood of cancer returning.

But individual cancer cases differ in how they resist or succumb to
chemotherapy. I-SPY researchers and physicians want to help each patient
choose the most promising chemotherapy -- one that will offer the best
likelihood of long-term, cancer-free survival. The project is
coordinated through a UCSF group led by Laura Esserman, breast cancer
surgeon and

the clinical leader of the UCSF Comprehensive Cancer Center's Breast
Oncology Program, and by Nola Hylton, a physicist who developed the MR
imaging techniques used in the study. The program is designated as a
Specialized Program of Research Excellence (SPORE) and funded by the
National Cancer Institute (NCI). All NCI's breast cancer SPORE sites are
participating in I-SPY, which also is supported by two national clinical
research groups, CALGB and ACRIN.

Cancer Genetic Markers of Susceptibility (CGEMS) is a three-year
initiative that will identify genetic alterations that make people
susceptible to prostate and breast cancer. Scientists involved will use
DNA available from five large studies of prostate cancer and five large
studies of breast cancer to "scan" the genome for common genetic
variations between patients who have these cancers and controls that do
not have cancer. NCICB in collaboration with Division of Cancer
Epidemiology and Genetics (DCEG), the NCI Core Genotyping Facility
(CGF), and the NCI Office of Cancer Genomics (OCG) is helping develop
the CGEMS data repository.

The caIntegrator version 1.0 addressed Rembrandt 1.0 and I-SPY portal
version 0.5 use cases and was release in Jan 2006. The caIntegrator
version 2.0 expands and updates the CG-OM to address Rembrandt version
1.5, I-SPY version 1.0 and CGEMS use cases as well as provides a caBIG
compatible API.

## IdentifIcation 

The release version of caIntegrator-CGOM API that this document applies
is version 2.0.

## System Overview

## Document Overview

This Software Design Description defines the strategies necessary to
accomplish the design activities associated with caIntegrator-CGOM API.
Design related procedural instructions are included in the Standard
Operating Procedures (SOPs). The remaining Software Design Description
sections are organized as follows:

-   **Section 2. System Architecture:** Describes and overview of the
    API, the conceptual and architectural design, interfaces and the
    various environments that will be used throughout the development
    lifecycle.

-   **Section 3. Components:** Identifies and describes each component
    broken down into its parts that are described in detail.

-   \[***Section 4. Notes:** Contains general information that aids in
    the understanding of this document.*\]

-   **Appendix A. Acronym List:** Defines the acronyms to be used on the
    project.

-   \[***Appendix B. Forms and Templates:** Contains the forms and
    templates that will be used on the project.*\]

-   **Appendix C. Database**: Describes database-wide design decisions
    about the database\'s behavioral design and other decisions
    affecting further design of the database broken down into its parts
    that are described in detail.

-   ***\[Appendix D. Other appendices**: Provides any additional
    information published separately for convenience in document
    maintenance.}*

\[***Reference documents -** Refer to the HST Software Engineering
Handbook for additional information. For additional project specific
information, refer to the following documents:*

-   *\[Project Name\]\'s Software Development Plan (SDP)*

-   *\[Project Name\]\'s Configuration Management (SCM) Plan*

```{=html}
<!-- -->
```
-   *Add any additional relationships, if any, of the Software Design
    Description to related project management plans.*

    *The following Standard Operating Procedures for design will be used
    on this project and are referenced in this document.*

```{=html}
<!-- -->
```
-   *List any project specific SOPs\]*

# System Architecture

## System Architecture Overview

The overall goal of caIntegrator project is to provide a framework with
the infrastructural components needed to develop enterprise level
translational applications such as Rembrandt, I-SPY, CGEMS and EAGLE.
Some of the core guiding principles that will be used to develop this
framework include:

-   Driven by user requirements.

-   User-friendly for a wide range of audience (physician scientists,
    programmers, statisticians)

-   Standards-based and pattern-driven.

-   Extensible and scalable.

-   Reuse/extend existing open-source technologies.

> ![](media/image1.wmf)

The framework leverages Java 2 Enterprise Edition, a hybrid star schema,
caCORE SDK and various open source technologies. Following are some of
the high level features of the caIntegrator framework:

### Clinical Genomic Object Model (CG-OM)

Clinical Genomic Object Model (CG-OM) is a domain model based on a
common set of use cases that were derived from various translational
studies such as Rembrandt, I-SPY and CGEMS. The purpose of the CG-OM is
to model the translation space that high lights the integration of
clinical domain with genomic domain within a context of a clinical
study. The CG-OM is further discussed in detail in Section 3.1, 3.2 and
3.3

### CG-OM API Service Layer

The purpose of the CG-OM API Service Layer to allow programmatic and
logical access to the underlying Data Mart via the clinical genomic
domain objects. The API is organized by three separate services; each
compliments the other to provide a full suit of tools that allows
researchers and bioinformatics developers to analyze, search and
retrieve clinical genomic data.

#### Object Query Service

The Object Query Service allows the API users to initiate search from
any object within the CG-OM and retrieve the query results in the form
of a domain object graph. caIntegator leverages the caCORE SDK tool kit
to implement the Object Query Service. The service further described in
detail in section 3.4

#### Study Query Service

The Study Query Service allows the API users to initiate search from a
Criteria Data Transfer Object (DTO) and retrieve the query results in
the form of a CG domain object graph or a Report DTO. This services
provides a domain specific aggregation of query criteria and results and
is further described in detail in section 3.5

#### Analytical Query Service

The Analytical Query Service allows the API users to perform run time
analysis of clinical genomic data that currently supports class
comparison analysis, principle component analysis and hieratical
analysis. It is designed to easily incorporate other types of analysis
in the future and scale to provide performance. This services is further
described in detail in section 3.6

### CG Database Schema

The caIntegrator hybrid data system consists of the star schema database
which contains the clinical and annotation data as dimensions,
pre-calculated gene expression copy number data as facts and CSM tables
for user provisioning data. For performance reasons, normalized gene
expression data used by the real time analysis module is stored as
R-binary files.

### WebGenome Integration

A generic interface to allow visualization of both genomic and gene
expression data via the WebGenome application.

### Security

In version 1.0, caIntegrator only needed to support data access control
based on study group/institution level. It uses CSM version 3.0.1 for
LDAP authentication and user registration. Due to performance
considerations, it does not utilize CSM's authorization API or schema.

For Authorization use cases, caIntegrator will perform as follows:

1\. Use the User -- Protection Group Relationship in CSM's
UserProvisioningManager.

2\. During the run time it will obtain the User object by passing the
user name and calling the getUser method of the UserProvisioningManager.

3\. Using the user id of the user obtained, call the getGroups method of
the UserProvisioningManager. This returns a Set of the Group objects to
which the user belongs.

4\. Retrieve the group name by iterating through them.

5\. Constrain the caIntegrator query with the retrieved group name.

##  {#section .unnumbered}

#  Components

The domain that each of studies involve may be different or even highly
specific to the study, but the most important use case that each of
these studies is trying to accomplish is to allow clinical scientists
and bioinformatician to analyze, query and search translational findings
in a simple and user friendly manner.

## Clinical GeNOMIC Object MODEL (CG-OM)

\[*This paragraph shall identify a requirement by a project-unique
identifier and shall describe the unit. The description shall include
the following information, as applicable. Alternatively, this paragraph
may designate a group of requirements and identify and describe the
requirements in subparagraphs. Requirements that contain other
requirements may reference the descriptions of those requirements rather
than repeating information.*

**Requirement:** ***Built an Object-oriented domain information model
which is expressed in UML as class diagram and as an XMI file, and is
reviewed and validated by the VCDE Workspace. Ensure that the
information model is harmonized across the caBIG Domain Workspace.
(caBIG Compatibility Guidelines Revision 2)***

Design of the CG-OM is driven by use cases from three critical
NCI-sponsored studies, a brain tumor trail called GMDI and a breast
cancer study called I-SPY TRIAL and CGEMS. The model represents data
from clinical trials, micro array-based gene expression, SNP genotyping
and copy number experiments, Fluorescent IN SITU Hybridization (FISH),
Somatic Mutation, Cell Lycate and Immunohistochemistry-based protein
assays.

Study domain objects in CGOM allow access to the Study, treatment arms,
patient information and specimen histology and information on the
biospecimen. The "Finding objects" model the in-silico transformation
and analyses performed on the raw experimental datasets. The clinical
findings domain objects provide clinical observations and assessments.
Annotation objects such as GeneBiomarker, ProteinBiomarker and
SNPAnnotation help provide context to the various Findings.

***[CGOM_v2_1.EAP](http://cabigcvs.nci.nih.gov/viewcvs/viewcvs.cgi/caintegrator-spec/model/CGOM_v2_1.EAP?cvsroot=opendevelopment).***

### Clinical Genomic Package Structure

The goal of translational research is to accelerate the adoption of
therapies and findings that are gathered from genomics and clinical
research during a clinical trial study.

The caIntegrator project provides bio-medical software developers with a
universal framework and a clinical genomic domain model that allows them
to easily traverse from study related domain to clinical and genomic
domains to related genomic annotation domain.

The challenge is that not every type of clinical or genomic domain may
apply to every study that wants to build upon the caIntegrator
framework. Therefore, we want to package these domains in a way similar
to aisles in a supermarket where related products are located close to
each other so that shoppers can gather them efficiently, although each
product is actually unrelated or independent of each other, but they all
come together at the check out line, where they may be bagged together.

Similarly the Clinical Genomic Object Model is packaged into several
domain related packages such as gov.nih.nci.caIntegrator.study,
gov.nih.nci.caIntegrator.findings and
gov.nih.nci.caIntegrator.annonations.

The gov.nih.nci.caintegrator.findings package is further sub packaged
based on the domain such as gov.nih.nci.caintegrator.findings.clinical,
gov.nih.nci.caintegrator.findings.geneExpression,
gov.nih.nci.caintegrator.findings.copyNumber,
gov.nih.nci.caintegrator.findings.FISH etc.

The gov.nih.nci.caintegrator.annotation package is grouped in sub
packages such as gov.nih.nci.caintegrator.annotation.gene,
gov.nih.nci.caintegrator.annotation.protein and
gov.nih.nci.caintegrator.annotation.snp.

Universal study related objects such as StudyParticipant, Study,
TimeCourse, Histology, Specimen and other related objects are grouped
under the gov.nih.nci.caintegrator.study package.

Even though products on supermarket shelves are independent of each
other, they do in fact have dependencies regarding where they can be
located in the supermarket because they may be perishable or
non-perishable item (interfaces). Therefore supermarkets display items
on selves, refrigerators, freezers and chillers (implementations) based
on if the item's behavior whether the item is perishable or
non-perishable.

Similarly objects in the CGOM that have dependencies across packages
will be abstracted behind interfaces. In particular, the association
from study package objects such as SubjectParticipant, Study and
Specimen to their related findings will be abstracted behind a common
interface called FindingInterface that has a method
getFindings(FindingType) and is implemented by the Speciemen and
StudyParticipant objects and will return any type of Finding rather than
getGEFinding() or getCopyNumberFinding() which might not applicable to
every study.

Similar to the check out clerk at a supermarket that interfaces with
both the customers and products, each study's implementation of the
caIntegrator service layer will allow end users to perform queries that
go across the different findings and annotations that are relevant to
that particular study.

###  {#section-1 .unnumbered}

## CG-OM MetaDATA REGISTRATION

**Requirement*: Common Data Elements (CDEs) built from controlled
terminologies and according to practices validated by the VCDE workspace
are used throughout the CG-OM and caIntegratorbased application. CDEs
are registered as ISO/IEC 11179 metadata components in the caBIG Context
of the cancer Data Standards Repository (caDSR). (From caBIG
Compatibility Guidelines Revision 2)***

The CG-OM will be completely annotated and processed thru the caCORE's
Semantic Integration Workbench (SIW) and uploaded to caDSR via the UML
loader tool.

## Controlled Vocabularies and Terminologies

**Requirement**: ***All terminologies and term definitions used for all
appropriate data collection fields and attributes of data objects are
reviewed and validated by the caBIG VCDE Workspace. (From caBIG
Compatibility Guidelines Revision 2)***

The caIntegrator team will work with the EVS Curation Team to fully
curate the domain model and its associated Value Domains. Value Domains
will be searched in EVS and new ones created where applicable. Domain
Standards such as HUGO gene symbols, GO terms, BioCarta Pathway Names,
GeneBank Accession Numbers, Entrez Gene Identifier, DB SNP Identifier
and Uniprot Identifiers will be utilized by caIntegrator.

## Object Query Service 

**Requirement**: ***Create well-described API's approved by the caBIG
Architecture workspace that provide access to data in the form of data
objects that are instances of classes represented by a domain model.
Electronic data formats reviewed and approved by the caBIG Architecture
Workspace are supported for both input to and output from the system.
Messaging protocols approved by the caBIG Architecture Workspace are
supported wherever messaging is indicated by the use cases.***

The Object Query Service allows the API users to initiate search from
any object within the CG-OM and retrieve the query results in the form
of a domain object graph. caIntegator project is planning to accomplish
this requirement by leveraging the caCORE SDK tool kit to implement the
Object Query Service as a "caCORE-like" API.

![](media/image2.wmf){width="3.251968503937008in"
height="3.9133858267716537in"}

1)  The above diagram describes caCORE SDK work flow to generated a
    caBIG compatible API. The CG-OM UML will be designed using a caBIG
    approved UML tool.

2)  Model will be annotated via the Semantic Integrator Workbench (SIW).

3)  Next the model's metadata will be registered using the UML Loader.

4)  Using the caCORE Code Generator, the Object Query Service will be
    generated as a caCORE-like API and deploy.

## Study Query Service 

**Requirement**: ***Create a well-described API that provides ability to
perform arithmetic operations such as less than, greater than less than
equal to, greater than equal to and set range values on date and numeric
attributes. The API should provide a well defined coarse grain as well
as a fine interface to perform translational queries. The API should be
able to handle collections of objects as inputs. The API should provide
ability to return a particular set of Findings based on another
Finding.(see CGEMS_use_case.doc)***

Typically when an application\'s presentation tier is defined, it is not
necessary that the presentation layer will map directly with the
underlying domain model objects in a one-to-one mapping. Also from the
domain model prospective, how the overlying applications transfers the
data or how the presentation layer\'s work flow is defined is not a
domain models' core concerns. The task of mapping domain objects to the
presentation data elements can be cumbersome task and hard to maintain,
especially as the domain keeps evolving over time.

In addition, a complex object model such as CG-OM has many
bi-directional associations which can lead to conical queries. Even
thought these queries might eventually return the correct results, they
may not be the most efficient way of retrieving them.

Based on the study use cases and presentation needs caIntegrator\'s
Study Query Service will provide the ability query based on Data
Transfer Objects (DTOs) that map to the underlying Domain Object model.

Martin Fowler coined the phrase Data Transfer Objects or DTOs. The basic
idea is that a DTO helps encapsulate the business data. A single method
call is used to send and retrieve the Transfer Object. The middle tier
is then responsible for deconstructing the DTO back into domain objects,
assembling the results and returning the desired results as another DTO
(if required) or simply as Domain Objects.

![](media/image3.wmf){width="5.998611111111111in"
height="4.591666666666667in"}

For example, if the presentation layer wants to allow users to search
for a Finding based on a HUGO gene symbol, gene alias, SNP identifier, a
chromosome location or study participants control status then the middle
tier should provide the presentation tier with an AnnotationCriteriaDTO
object that takes Gene Symbol, Gene Alias, SNP Identifier, etc as
attributes and maps these attributes to the underlying Domain objects.
If required, similar type of DTOs can be created for the returned result
sets that allow selected attributes from one or more objects, otherwise
the domain object graph will be returned.

For the Study Query Service to be scalable for all caIntegrator based
studies, the HQL used to perform these queries has to be dynamically
assembled. Additionally, caIntegrator will utilize NCIA team\'s
hibernate performance bench mark and tips as the starting point for this
effort.

The Study Query Service will also provide methods to address the
"Findings to Findings" use case, so that the presentation layer is
abstracted from the low level mappings involved in resolving such
Findings.

For illustrating this approach, CGEMS Criteria DTOs is used as an
example to describe the details of the Study Query Service API. Please
refer to the below diagram:

-   There is a FindingCriteriaDTO that corresponds to each type of
    Finding (such as GetotypeFindingCriteriaDTO corresponds to
    GenotypeFinding). All attributes within the
    GetotypeFindingCriteriaDTO will be ANDed together.

-   Each of these FindingCriteriaDTO objects will allow user to specify
    a set of well defined criteria such as "Within" clause for range
    attributes like Physical Position and Date, "GreaterThan/LessThan"
    for numeric attributes, along with the ability to specify multiple
    values for any given attribute such as Gene Symbol list.

-   The AnnotationCriteriaDTO allows searches on genomic annotations and
    provides a simple way to nest annotation lists provided by the user
    such as Gene symbols, GOTerms, Pathways, Cytoband etc. All
    attributes within the AnnotationCriteriaDTO will be ORed together.

-   The AnnotationCriteriaDTO may be nested with the above
    GetotypeFindingCriteriaDTO with an AND operator.

-   Similarly there is a StudyParticipantCriteriaDTO class that
    encapsulates study domain objects such as Study, TimeCourse,
    Specimen, StudyParticipant, etc. The StudyParticipantCriteriaDTO can
    be nested with the above GetotypeFindingCriteriaDTO with an AND
    operator.

![](media/image4.wmf){width="6.490277777777778in"
height="7.733333333333333in"}

![](media/image5.wmf){width="7.993055555555555in"
height="10.677777777777777in"}

[The following describes the above sequence diagram:]{.underline}

1.  Client will call the static method getFindings() method on
    **FindingsManager** class. This class acts as a controller between
    client and persistent layer. This method returns
    SpecimenBasedMolecularFinding [type]{.underline} objects. It does
    this by simply delegating to corresponding
    **SpecimenFindingHandler** (based on
    SpecimenBasedFindingSearchCriteria)

2.  **SpecimenFindingHandler** is the super class for all types of
    FindingHandlers. This class uses [Template pattern]{.underline} in
    combination with [Strategy pattern]{.underline}. It mainly requires
    the sub classes to implement 3 methods out of which handle() method
    is the main method that is implemented by all concrete finding
    handlers (such as GetotypeFindingHandler). This method is
    responsible for handling the corresponding SearchCriteria and
    returns HSQL (hibernate query language) that will primarily take
    care of all criteria specified for the Finding itself. This handle()
    method also uses **AnnotationCriteriaHandler** to handle
    AnnotationCriteriaDTO that was nested and generates combined HSQL.
    So sequence of execution is as follows:

    1.  **FindingsManager** first calls the inherited method
        **getFindings()** (from the super class
        **SpecimenFindingHandler)** on the corresponding handler.

    2.  This **getFindings()** method calls **handle()** method on the
        corresponding Specimen FindingHandler to get the above mentioned
        HSQL to handle the criteria for the Finding itself.

    3.  It then instantiates corresponding type of
        **StudyParticipantHandler** based on
        **StudyParticipantCriteriaDTO** specified in the
        **SpecimenBasedFindingSearchCriteria** passed in. This
        **StudyParticipantHandler** generates HSQL to handle **any** sub
        type of **StudyParticipantCriteriaDTO.** It then adds this HSQL
        to the above HSQL (required to handle Finding itself) and then
        executes this entire HSQL as a single query to retrieve all
        Findings of the corresponding type.

### API Usage

Here is an example of study query service methods for a germ line study
such as CGEMS that clients may call:

1.  **public static Collection\<? extends Finding\>
    FindingsManager.getFindings (**

> **FindingCriteriaDTO findingCritDTO, int fromIndex, int toIndex );**

2.  **public static Collection\<SNPAnnotation\> FindingsManager.**

> **getSNPAnnotations(AnnotationCriteria annotationCrit);**

3.  **public static Collection\<Study\> FindingsManager.
    getStudies(StudyCriteria**

> **studyCrit);**

#### getFindings method 

For example in the case of CGEMS study, the Study Query Service allows
the users to get the foloowing types of findings:

a.  GenotypeFinding

b.  SNPAssociationFinding

c.  SNPFrequencyFinding.

> The following method supports the searching of all three types of
> findings mentioned above:
>
> **public static Collection\<? extends Finding\>
> FindingsManager.getFindings (**
>
> **FindingCriteriaDTO findingCritDTO, int fromIndex, int toIndex );**
>
> All these findings extend [abstract]{.underline} Finding class (refer
> to the CG-OM). In addition the domain objects, the DTO model
> facilitates the clients to nest object queries in the form of Criteria
> objects. (See the germ line DTO model diagram).
>
> The *[FindingCriteriaDTO]{.underline}* corresponding to each of the
> above 3 types of findings are as follows:

a.  GenotypeFindingCriteriaDTO

b.  SNPAssociationFindingCriteriaDTO

c.  SNPFrequencyFindingCriteriaDTO

> All these 3 DTO's extend from abstract FindingCriteriaDTO similar to
> Findings. Each of these DTO consists of a set of Criteria objects.
> Each of these *[FindingCriteriaDTO]{.underline}* objects will allow
> user to specify a set of [rich criteria]{.underline} for the
> corresponding Finding object attributes (such as within clause,
> GreaterThan/LessThan, Within clause etc along with the ability to
> specify multiple values for any given attribute). All this attribute
> criteria within the *[FindingCriteriaDTO]{.underline}* will be ANDed
> together.
>
> The AnnotationCriteria class encapsulates all Annotation criteria and
> provides a simple way to nest multiple lists of Annotations (such as
> geneSymbols, SNPIdentifiers etc). Also the user can specify
> annotations such as PhysicalPosition, PanelCriteria etc in this
> AnnotationCriteria. AnnotationCriteria is different than other
> criteria the attributes within the AnnotationCriteria object are ORed
> when the Findings are retrieved.
>
> In other words, all the annotation criteria will be ORed while the
> Finding object attributes themselves will be ANDed. And what comes out
> of this nested query is entire the Object Graph of corresponding
> Finding objects which includes that is shown in the domain model.

As described above, Each of these *[FindingCriteriaDTO]{.underline}*
implements getHandler() method that returns corresponding FindingHandler
(through polymorphism). This handler is responsible for handling the
nested query (by parsing and creating Hibernate Queries using HQL &
Hibernate Criteria API and eventually generating required SQL which is
tuned to give best performance).

Example of a code snippet that demonstrates the usage of
**FindingCriteriaDTO**.

public class GenotypeFindingTest {

protected AnnotationCriteria annotCrit;

private GenotypeFindingCriteriaDTO gfDTO;

private StudyParticipantCriteria spCrit;

private void setUp() throws Exception {

gfDTO = new GenotypeFindingCriteriaDTO();

annotCrit = new AnnotationCriteria();

gfDTO.setAnnotationCriteria(annotCrit);

spCrit = new StudyParticipantCriteria();

gfDTO.setStudyParticipantCriteria(spCrit);

}

protected void setUpSNPPhysicalPositionCrit() {

PhysicalPositionCriteria ppc = new PhysicalPositionCriteria();

ppc.setChromosome(\"8\");

ppc.setStartPosition(new Integer(76065000));

ppc.setEndPosition(new Integer(76075000));

annotCrit.setPhysicalPositionCriteria(ppc);

}

private void setUpGenotypeCrit() {

gfDTO.setQualityScore(new Float(0.50), ArithematicOperator.LT);

}

protected void setUpPanelCrit() {

PanelCriteria p = new PanelCriteria();

p.setName(\"HumanHap300\");

p.setVersion(\"1.1\");

annotCrit.setPanelCriteria(p);

}

public void testGenotypeFindingCriteriaDTO() {

setU p();

> setUpSNPPhysicalPositionCrit();

setUpGenotypeCrit ();

setUpPanelCrit ();

Collection\<? extends Finding\> findings =

**FindingsManager.getFindings**( gfDTO,startIndex, endIndex);

for (Iterator\<? extends Finding\> iter = findings.iterator();

> iter.hasNext();) {

**GenotypeFinding** finding **= (GenotypeFinding)**iterator.next();

System.out.println(\"QualityScore: \" + finding.getQualityScore());

System.out.println(\"Allel1: \" + finding.getAllele1());

System.out.println(\"Allel2: \" + finding.getAllele2());

//..... so on ....

}

}

#### Other methods

Besides getFindings method, for convenience the study query service
provides other service methods to retrieve domain objects. As an
example:

**public static Collection\<Study\> getStudies(StudyCriteria
studyCrit);**

The user can simply instantiate a StudyCriteria object and set
attributes on this (such as name, sponsorStudyIdentifier) and call the
above service method. This will return Study objects (domain objects)
that satisfies the criteria specified. If no attributes were specified,
then it will return all Study Objects.

Code Snippet:

private StudyCriteria studyCrit ;

studyCrit = new StudyCriteria();

studyCrit.setName(\"A\");

Collection\<Study\> studyObjs = FindingsManager.getStudies(studyCrit);

for (Iterator\<Study\> iterator = studyObjs.iterator();
iterator.hasNext();) {

> Study study = iterator.next();

System.out.println(\"Study Name: \" + study.getName());

// ..... so on ....

}

### CGEMS-1.1 Study Service Layer Example Involving SNPPanel Criteria

#### In CGEMS-1.1 release, SNPPanel criteria and Study criteria have been implemented. The service methods details are as follows. {#in-cgems-1.1-release-snppanel-criteria-and-study-criteria-have-been-implemented.-the-service-methods-details-are-as-follows. .unnumbered}

#### public static Collection\<SNPPanel\> getPanels(StudyCriteria studyCrit) in FindingsManager can be called to retrieve all SNPPanels that belong to the given study. If no Study name is mentioned, then all SNPPanels in the system will be retrieved.

#### To get all findings associated with a given SNPPanel (such as SNPFrequencyFindings & SNPAssociationFindings), PanelCriteria object will be created. And the panel name(s) will be set on that. Then this PanelCriteria is set on AnnotationCriteria and passed in to FindingsHandler (thro' FindingsManager)

#### For getting findings in a throttled fashion, the below service method in FindingsManager can be called: (also referred as ReportQuery findings)

#### public static Collection\<? extends Finding\> getFindings(FindingCriteriaDTO findingCritDTO, int fromIndex, int toIndex).  {#public-static-collection-extends-finding-getfindingsfindingcriteriadto-findingcritdto-int-fromindex-int-toindex. .unnumbered}

#### FindingsManager then instantiates corresponding FindingsHandler (such as SNPFrequencyFindingHandler ) and calls gerFindings() method of this handler object, passing the finding criteria object.

#### FindingsHandler then parses the criteriaDTO and determines if only PanelCriteria is specified. From this point onwards, code branches out. 

#### If [only]{.underline} PanelCriteria is specified in AnnotationCriteria, then executePanelOnlySearch() method in corresponding concrete FindingsHandler will be called passing the criteria object.

#### Otherwise, getMyFindings() method in corresponding concrete FindingsHandler will be called passing the criteria object.

#### Further design details of each of these two scenarios are described as below. {#further-design-details-of-each-of-these-two-scenarios-are-described-as-below. .unnumbered}

#### 3.5.13.3.b.I: Scenario: [Only PanelCriteria is specified]{.underline}:  {#b.i-scenario-only-panelcriteria-is-specified .unnumbered}

#### As explained above in this case, executePanelOnlySearch() method of corresponding concrete FindingsHandler gets called. This method generates HQL required to join target Finding type class with SNPAssay class based on corresponding SNPAnnotation object. It then also appends HQL for corresponding target FindingCriteria object attribute criteria along with any other specified criteria objects that are associated with target FindingCriteria.

#### Then HibernateQuery object is created and SQL (from the above HQL) is executed and target Finding type objects are materialized from the results from Data base. 

#### Further initializeProxies() method is called for required associations. 

#### The following Sequence diagram (ReportQueryDiagram) depicts the sequence of method calls involved in the entire execution of service method. {#the-following-sequence-diagram-reportquerydiagram-depicts-the-sequence-of-method-calls-involved-in-the-entire-execution-of-service-method. .unnumbered}

####  {#section-2 .unnumbered}

####  {#section-3 .unnumbered}

####  {#section-4 .unnumbered}

####  {#section-5 .unnumbered}

####  {#section-6 .unnumbered}

####  {#section-7 .unnumbered}

#### ![](media/image6.wmf){width="8.055555555555555in" height="12.363194444444444in"} {#section-8 .unnumbered}

####  {#section-9 .unnumbered}

####  {#section-10 .unnumbered}

#### 3.5.13.3.b.II: Scenario: [PanelCriteria and Other Annotation Criteria is specified]{.underline}:  {#b.ii-scenario-panelcriteria-and-other-annotation-criteria-is-specified .unnumbered}

#### In this case, getFindings() method first calls SNPAnnotationCriteriaHandler.handle() to retrieve SNPAnnotationIDs corresponding to Annotation criteria specified. It then calls getMyFindings () method of corresponding handler passing these SNPAnnotationIDs. 

#### This method then in a loop calls executeAnnotationQueryForFindingSets() of corresponding FindingsHandler passing 100 (configurable) SNPAnnotationIDs each time.

#### executeAnnotationQueryForFindingSets method appends these SNPAnnotationIDs to HQL. It then appends HQL for corresponding target FindingCriteria object attribute criteria along with any other specified criteria objects that are associated with target FindingCriteria. 

#### Then HibernateQuery object is created and SQL (from the above HQL) is executed and target Finding type objects are materialized from the results from Data base. 

#### Further initializeProxies() method is called for required associations.

#### For getting findings for FTP Download functionality, the below service method in FindingsManager can be called: (also called FTPQuery findings)

#### public static void populateFindings(FindingCriteriaDTO findingCritDTO, List toBePopulated)  {#public-static-void-populatefindingsfindingcriteriadto-findingcritdto-list-tobepopulated .unnumbered}

#### FindingsManager then instantiates corresponding FindingsHandler (such as SNPFrequencyFindingHandler ) and calls getFindingForFTP() method of this handler object, passing the finding criteria object.

#### FindingsHandler then parses the criteriaDTO and determines if only PanelCriteria is specified. From this point onwards, code branches out. 

#### If [only]{.underline} PanelCriteria is specified in AnnotationCriteria, then populateFindingsForPanelOnly () method in FindingsHandler will be called passing the criteria object and the List object to be populated. 

#### Otherwise, populateFindings () method in FindingsHandler will be called passing the critera object and the List object to be populated. 

#### Further design details of each of these two scenarios are described as below. {#further-design-details-of-each-of-these-two-scenarios-are-described-as-below.-1 .unnumbered}

#### 3.5.13.4.b.I: Scenario: [Only PanelCriteria is specified]{.underline}:  {#b.i-scenario-only-panelcriteria-is-specified-1 .unnumbered}

#### As explained above if [only]{.underline} PanelCriteria is specified in AnnotationCriteria, then populateFindingsForPanelOnly () method in FindingsHandler will be called passing the criteria object, and the List object to be populated.

#### This populateFindingsForPanelOnly () then in a loop calls executePanelOnlySearch() method of corresponding FindingsHandler in batches of 500 (configurable) objects. 

#### Then three steps explained above in 3.5.13.3.b.I section (shown as bullets) will be repeated

#### Then the synchronized method process() in BatchFindingsHandler will be called passing the above retrieved concrete findings and the list toBePopulated (which was passed from client in the initial populateFindings() service method call). 

#### This process() method has synchronized code (on toBePopulated list object) because, the client reads from the findings from the same list object and then clears it so that it can receive next batch of findings.

#### The following Sequence diagram (FTPQueryDiagram) depicts the sequence of method calls involved in the entire execution of service method. {#the-following-sequence-diagram-ftpquerydiagram-depicts-the-sequence-of-method-calls-involved-in-the-entire-execution-of-service-method. .unnumbered}

####  {#section-11 .unnumbered}

####  {#section-12 .unnumbered}

#### ![](media/image7.wmf){width="8.046527777777778in" height="13.52361111111111in"} {#section-13 .unnumbered}

####  {#section-14 .unnumbered}

#### 3.5.13.4.b.II: Scenario: [PanelCriteria and Other Annotation Criteria is specified]{.underline}:  {#b.ii-scenario-panelcriteria-and-other-annotation-criteria-is-specified-1 .unnumbered}

#### As explained above, in this case, In this case, populateFindings() in FindingsHandler is called. This method first calls SNPAnnotationCriteriaHandler.handle() to retrieve SNPAnnotationIDs corresponding to Annotation criteria specified. It then calls sendMyFindings () method of corresponding handler passing these SNPAnnotationIDs and List object to be populated. 

#### This sendMyFindings () primarily appends all required HQL for handling target Finding attribute criteria and HQL for specified associated criteria. 

#### It then prepares HQL query and executes the query for every 100 (configurable) SNPAnnotationIDs in a loop.

#### When the target findings are materialized from DB results, this method calls populateCurrentResultSet() (synchronized method) for every 500 (configurable) findings. These findings and list toBePopulated (which was passed from client in the initial populateFindings() service method call) are passed in to this populateCurrentResultSet() method.

#### This populateCurrentResultSet() method has synchronized code (on toBePopulated list object) because, the client reads from the findings from the same list object and then clears it so that it can receive next batch of findings

#### [Performance/Design Decisions With Searches involving only PanelCriteria:]{.underline} {#performancedesign-decisions-with-searches-involving-only-panelcriteria .unnumbered}

####  [Issue:]{.underline} As explained above, when there is an AnnotationCriteria is specified, the handler first retrieves all SNPs specified in the Annotation criteria object. Then it uses these SNPs along (with study participants if applicable) to query against the Finding tables. So when a Panel criteria is mentioned,  {#issue-as-explained-above-when-there-is-an-annotationcriteria-is-specified-the-handler-first-retrieves-all-snps-specified-in-the-annotation-criteria-object.-then-it-uses-these-snps-along-with-study-participants-if-applicable-to-query-against-the-finding-tables.-so-when-a-panel-criteria-is-mentioned .unnumbered}

#### It joins SNPPanel object with SNPAnnotation object (based on O-R mappings specified) to retrieve all SNPs in that Panel. 

#### It further appends HQL to constrain these SNPs based on other Annotation criteria specified in the Annotation criteria. 

#### However, when only Panel criteria was specified in Annotation criteria (without any other criteria such as physical position etc) only the first step above executes. This causes retrieving huge number of SNPs from SNPAnnotation table for that Panel. Hence the Query a takes very very long time. {#however-when-only-panel-criteria-was-specified-in-annotation-criteria-without-any-other-criteria-such-as-physical-position-etc-only-the-first-step-above-executes.-this-causes-retrieving-huge-number-of-snps-from-snpannotation-table-for-that-panel.-hence-the-query-a-takes-very-very-long-time. .unnumbered}

#### To fix this issue with performance, a check was introduced in getFidning() / getFindingForFTP() methods in FindingsHandler to see if only Panel criteria is specified. If so, then code takes a different path. In stead of first retrieving the SNPs that are in that Panel, it directly joins Finding object with SNPAssay using SNPAnnotation object (moving the step 1 above to Findings HQL itself). The SQL generated this way was much faster than executing as two different SQL statements as described above. {#to-fix-this-issue-with-performance-a-check-was-introduced-in-getfidning-getfindingforftp-methods-in-findingshandler-to-see-if-only-panel-criteria-is-specified.-if-so-then-code-takes-a-different-path.-in-stead-of-first-retrieving-the-snps-that-are-in-that-panel-it-directly-joins-finding-object-with-snpassay-using-snpannotation-object-moving-the-step-1-above-to-findings-hql-itself.-the-sql-generated-this-way-was-much-faster-than-executing-as-two-different-sql-statements-as-described-above. .unnumbered}

#### However when no Panel criteria is mentioned, this situation does not happen Analytical Query Service {#however-when-no-panel-criteria-is-mentioned-this-situation-does-not-happen-analytical-query-service .unnumbered}

**Requirement**: ***Create a well-described API that provides ability to
perform on-the-fly computational analysis capability for applications
built on the caIntegrator application framework (i.e., Rembrandt and
I-SPY) (see Rembrandt/I-SPY use cases documents)***

The Analytical Server provides an on-the-fly computational analysis
capability for applications built on the caIntegrator application
framework (i.e., Rembrandt and I-SPY). The Analytical Server
communicates with the application middle-tier via the Java Messaging
Service (JMS).

JMS allows the Analytical Server to communicate asynchronously with the
application via the AnalysisServerClientManager object located in the
application middle-tier. The middle-tier makes analysis requests via
AnalysisRequest objects. The Analytical Server performs computations and
sends AnalysisResult objects back to the middle-tier.

![](media/image8.jpeg){width="6.25in" height="1.7472222222222222in"}

The analytical server consists of one or more analysis nodes. Each
analysis node is intended to be located on a separate computer. The
analysis nodes communicate with the middle-tier via the JMS Analysis
Request and Analysis Result queues. These queues are located on the
JBoss server hosting the application middle-tier. AnalysisRequest and
AnalysisResult objects are passed between the middle tier and the
analytical server using JMS object messages. JMS object messages allow
serializable Java objects to be imbedded in JMS messages.

The AnalysisServerClientManager is a class that resides in the
middle-tier that handles all of the messaging between the middle tier
and the analytical server. It places AnalysisRequest objects on the
Analysis Request Queue and listens for AnalysisResponse objects on the
Analysis Result Queue.

The JMS Message Handler component of each analysis node listens for
AnalysisRequest objects on the Analysis Request Queue and places
AnalysisResult objects on the Analysis Result Queue.

The JMS infrastructure insures that only one and only one analysis node
will receive a given analysis request. JMS also distributes the request
across the analysis nodes so that each node will receive approximately
the same number of requests.

An analysis node determines the type of analysis to perform based on the
type of the received AnalysisRequest object. For example, if a
ClassComparisonAnalysisRequest object is received, the analysis node
will perform a class comparison computation using the parameters
contained in the request and then send a response of type
ClassComparisonAnalysisResult. The ClassComparisonAnalysisResult
contains the results of the class comparison computation.

Each specific computational method has a corresponding AnalysisRequest
and AnalysisResult object. The three computational methods that are
currently being implemented are: class comparison, principal component
analysis, and hierarchal clustering. The corresponding message types
are: ClassComparisonAnalysisRequest, ClassComparisonAnalysisResult,
PrincipalComponentAnalysisRequest, PrincipalComponentAnalysisResult,
HierarchicalClusteringAnalysisRequest, and
HierarchicalClusteringAnalysisResult. Each request object is a subclass
of the abstract AnalysisRequest object and each response object is a
subclass of the abstract AnalsyisResponse object.

To add a new type of analysis, the developer would create new request
and response objects corresponding to the new statistical method.

Each analysis node consists of a JMS message handler, a thread pool
executor, and one or more compute threads as illustrated in the diagram
below.

![](media/image9.jpeg){width="3.1798611111111112in" height="2.25in"}

On a multi-processor computer the number of compute threads would
usually be set to equal or exceed the number of available processors.
The thread pool executor is derived from the Java 1.5
ThreadPoolExecutor. It is responsible for distributing compute tasks to
the compute threads and for queuing tasks that can not be immediately
assigned to a compute thread.

![](media/image10.jpeg){width="5.819444444444445in"
height="3.4944444444444445in"}

Each compute thread is derived from the Java Thread class. In the
diagram above the compute threads are called R Compute Threads because
they contain all of the code and data needed to perform a given
statistical computation using the R statistical package. The Rserve
package (see: <http://stats.math.uni-augsburg.de/Rserve/>) is used to
call the R system from the R compute thread. Rserve provides Java
classes to execute R commands and to retrieve results as Java objects.
Each R compute thread contains one R connection (a line of communication
to an R process).

The code snippet below illustrates how R commands can be called from
Java:

double varianceFilterValue = 0.9;

**c***.voidEval(\"pcaResult \<- computePCA(dataMatrix,\" +
varianceFilterValue + \" )\");*

*double\[\] pca1 = c.eval(\"pcaMatrixX \<-
pcaResult\$x\[,1\]\").asDoubleArray();*

*double\[\] pca2 = c.eval(\"pcaMatrixY \<-
pcaResult\$x\[,2\]\").asDoubleArray();double\[\] double\[\] pca3 =
c.eval(\"pcaMatrixZ \<- pcaResult\$x\[,3\]\").asDoubleArray();*

c is a previously instantiated Rconnection object. The code above will
call the R function computePCA and place the results into the Java
double arrays pca1, pca2, and pca3.

The analysis node design allows for calling other types of statistical
packages. The diagram below illustrates using SAS instead of R. The SAS
ComputeThread and the SAS ThreadPoolExecutor classes would contain all
of the SAS specific code necessary to execute SAS within the analysis
node.

![](media/image11.jpeg){width="5.25in" height="2.6694444444444443in"}

## webGenome Integration

**Requirement**: ***One of requirements of caIntegrator is to help
researchers better analyze and visualize the results in a user
friendlier manner by creating an interface between caIntegrator and
webGenome and extend webGenome's capabilities with new plots and
functionality.***

***(see Rembrandt 1.0 use cases documents)***

WebGenome is a plotting application. The goal is to show the data from
the Rembrandt report in genomic plots of WebGenome. Then WebGenome can
further query Rembrandt application for more data (for selected samples
in Rembrandt report). To achieve this integration, an EJB architecture
was proposed. The proposed architecture is that WebGenome come up with
set of Interfaces to represent their data sources. So that any client
(such as Rembrandt) that wants to integrate with WebGenome, will
implement these interfaces and will make these interface type objects
available to WebGenome application (using some type of remote protocol).
Rembrandt uses EJB to achieve this remote capability. And make these
objects available through JNDI. Please see below for the architecture
diagram.

The main interface that needs to be implemented is
org.rti.webgenome.client.BioAssayMgr. (This is of type Remote). Rest is
set of Data Transfer Objects (DTO) interfaces. Please refer below the
attached DTO interfaces (model)

![](media/image12.jpeg){width="6.495138888888889in"
height="6.550694444444445in"}

DTOs;

1.  org.rti.webgenome.client.ExperimentDTO

2.  org.rti.webgenome.client. BioAssayDTO

3.  org.rti.webgenome.client. BioAssayDatumDTO

4.  org.rti.webgenome.client. ReporterDTO

And a constraints object
org.rti.webgenome.client.BioAssayDataConstraints to specify the query
criteria.

### BioAssayService

This is implemented as EJB Stateless Session Bean. The class that
implements this is gov.nih.nci.caIntegrator.services.bioAssay.ejb.
BioAssayServiceBean. The two main methods that are implemented are

ExperimentDTO\[\] getExperiments(String\[\] experimentIDs,
BioAssayDataConstraints bioAssayDataConstraints, String clientID)

&

public ExperimentDTO getExperiment(String experimentID,
BioAssayDataConstraints assayDataConstraints, String clientID)

From ExperimentDTO all other DTO can be accessed. This
BioAssayServiceBean class uses strategies pattern to serve different
types of data. It contains BioAssayService type that actually does the
job. Currently Copy number data, Gene Expression Data and LOH data are
supported. There are three classes (CopyNumberDataService,
GeneExprDataService and LOHDataService) that implement the above
mentioned BioAssayService interface. This design will leave the
flexibility to support more data types in future. At that time, that
class simply need to implement BioAssayService. All these classes uses
current Rembrandt code base (multi-threaded query model) to retrieve the
data.

### ApplicationStateService

There is also another generic service implemented to support this
integration effort. It is
gov.nih.nci.caIntegrator.services.appState.ApplicationStateService. The
main purpose of this is to provide services to publish and retrieve
application states between the calls. That is any application which is
interested in saving its state (to be queried later by other apps) can
implement an interface (TrackableAppState) and utilize the services of
this class to publish and retrieve its state. These services are exposed
utilizing EJB Session bean. The two main methods in this are service
are:

public Integer publishReportState(TrackableAppState stateDTO) &

public TrackableAppState getReportState(Integer stateDTOID)

The former method publishes the application state (passed as
TrackableAppState type) and returns the auto-generated ID under which it
was saved. The client can use this ID to retrieve this application state
(as TrackableAppState) at later point of time before the predefined time
expires.

The later method returns application state as TrackableAppState object
for the stateDTOID passed in.

Rembrandt application utilizes the ApplcationState service. It will
publish the Rembrandt report state to this service before it launches
the WebGenome application (in a separate window) Then the above
mentioned BioAssayMgrService utilizes this ApplicationState service to
retrieve the report state It then uses this state data in querying /
filtering the data before it send it to WebGenome for display. Below is
the Sequence diagram that describes all of this.

![](media/image13.jpeg){width="6.491666666666666in"
height="4.548611111111111in"}

## Error Handling

### caIntegrator Findings Specification Errors

An effort has been made to create a simple error checking/handling
mechanism for the findings framework. In other locations of the
application, other than the UI, exceptions when they can not be handled
are to be thrown up to the calling class, and never to be caught and
left unhandled. All exceptions will use the application logging
mechanism to log the date/time, exception type and if available, a stack
trace.

All middle-tier to persistent tier exception thrown exceptions are to be
wrapped in one of the following four classes shown in FIGURE and then
sent back through the Findings API to the calling classes. In most
circumstances this will be the UI or web interface which will then wrap
or handle the exception into it's handling mechanism.

![](media/image14.wmf){width="6.495833333333334in"
height="3.1645833333333333in"}

Figure 1 - Findings/Analysis Wrapping Exceptions

# Appendix A -- acronym List {#appendix-a-acronym-list .unnumbered}

\[*Insert an alphabetical listing of all acronyms, abbreviations, and
their meanings as used in this document.*\]

  ---------- -------------------------------------------------------------
  Acronym    Description

  \[????\]   \[*Insert Project Name acronym*\]

  \[????\]   \[*Insert Project all other project Software Design
             Description specific acronyms and resort the table*\]

  CI         Configuration Item

  DBA        Database Administrator

  MS         Microsoft

  PM         Project Manager

  RM         Requirements Manager

  RTM        Requirements Traceability Matrix

  SCM        Software Configuration Management

  *SDD*      Software Design Description

  SDLC       Software Development Lifecycle

  SDP        Software Development Plan

  SE         Software Engineering

  SEPG       Software Engineering Process Group

  SPE        Software Product Engineering

  SM         Software Manager

  SOP        Standard Operating Procedure

  SPI        Software Process Improvement

  SQA        Software Quality Assurance

  SRS        Software Requirement Specification

  SW         Software

  TM         Test Manager
  ---------- -------------------------------------------------------------

# \[*Appendix B -- Forms and Templates*\] {#appendix-b-forms-and-templates .unnumbered}

\[*Attach any design forms or templates used on the project. Use dynamic
links; do not paste the forms and template in this file/document.*\]

# \[APPENDIX C -- DATABASE\] {#appendix-c-database .unnumbered}

**Overview --** *This section shall describe any changes made to the
database/back end. All changes should be maintained in CCR/Release
folders in PVCS. The entity changes will be updated in ER tool
(Erwin/Oracle Designer etc) at the implementation time. The database
changes will be updated in PVCS at the time of implementation. Examples
of database changes include:*

-   *Table*

    -   *New Table*

        -   *Purpose:*

        -   *Schema:*

        -   *Create Script including indexes, constraints and grants,
            sequences, snapshots:*

        -   *Type of Table: normal, index organized, materialized view
            etc.*

        -   *Data expected in 1 year:*

        -   *Data Retention Period: Will data be archived from time to
            time?*

        -   *Are there data that need to be loaded into the table at the
            creation time? What and where are the scripts to load the
            data?*

        -   *Location of scripts, data etc.*

    -   *Modifications to Old Table*

        -   *Purpose:*

        -   *Schema:*

        -   *Modification Script (include changes to the storage clause,
            indexes, sequences and grants as well):*

        -   *Procedure to Modify: Describe the process to modify the old
            table; for example if adding a column, simply provide the
            script to add the column; if modifying the data type of a
            column, provide the necessary steps like export, drop
            recreate and import clearly*

        -   *Data Modifications: Will the modified table require
            modifications to data or require insertions of additional
            data? Provide scripts as required.*

        -   *Location of scripts, data etc.*

    -   *Obsolete Tables:*

        -   *Reason the object has become obsolete?*

        -   *Schema:*

        -   *Should the data be retained for any reason and for how
            long? This will help decide whether to store an export file
            on server or tape. Regardless of the retention period, the
            data should be retained online until the Release has been
            implemented and approved.*

        -   *Script to delete table, views build upon the table,
            synonyms for the table and any referential integrity*

        -   *Location of Script:*

-   *Data Modifications*

    -   *Purpose:*

    -   *Schema:*

    -   *Script to add/modify data (include changes to storage clause,
        indexes and grants as well as necessary statements to disable
        and enable constraints and triggers before and after the data
        modifications):*

    -   *Step by step process to modify the data:*

-   *Stored Objects (Trigger, Procedure, Package, Function, View)*

    -   *Purpose:*

    -   *Obsolete/New/Modification Description:*

    -   *Will the stored objects change the data retention/growth of any
        table? If so, describe the change.*

    -   *Location of Scripts:*

-   *Database Links*

    -   *Purpose:*

    -   *New/Modification/Obsolete:*

        -   *If new or modification: is the database link
            private/public? If the database link is public, state the
            justification. If a public database link is created, ensure
            the schema used in the link will not compromise security.*

    -   *For modified or obsolete database links, are there any outside
        users of the link that need to be notified?*

    -   *Location of Scripts:*

-   *Init.ora*

    -   *Purpose:*

    -   *Addition/Modification*

    -   *Temporary? If the addition/modification is temporary, what is
        the time period?*

    -   *Expected Results: For example, will this addition/modification
        change the performance?*

    -   *Location of new Init.ora file & distribution:*

    -   *Comments:*

-   *Listener.ora*

    -   *Purpose:*

    -   *Modification:*

    -   *Temporary: for example, is the change required to troubleshoot
        an issue by placing a trace level?*

    -   *If adding more listeners or changing ports, are there any users
        that need to be notified to reference the new ports?*

    -   *Location of new Listener.ora file & distribution:*

-   *Tnsnames.ora*

    -   *Purpose:*

    -   *Addition/Modification/Deletion:*

    -   *Location of new tnsnames.ora file:*

-   *Server Batch jobs:*

    -   *New*

        -   *Purpose:*

        -   *Command File:*

        -   *Owner:*

        -   *Privileges required to execute batch job:*

        -   *Schedule:*

        -   *Expected length of execution? Will the new length interfere
            with other command files/backups?*

        -   *Maintenance of log files generated by command file: will
            the command file maintain its own log files or is there
            another command file that maintains all log files on the
            server?*

        -   *Location of command file:*

    -   *Modification*

        -   *Purpose:*

        -   *Modified Command File:*

        -   *Schedule change?*

        -   *Change in length of execution? If the execution time
            increases, will there be any interference to other command
            files/backups?*

        -   *Location of command file:*

    -   *Obsolete*

        -   *Purpose:*

        -   *Name of Command file and any other scripts called by
            command file:*

-   *Oracle jobs:*

    -   *New*

        -   *Purpose:*

        -   *Name of sql package/procedure or external script:*

        -   *Owner:*

        -   *Privileges required to execute job:*

        -   *Schedule:*

        -   *Expected length of execution? Will the new length interfere
            with other jobs backups?*

        -   *Maintenance of log files/tables generated by job: will the
            job maintain its own log files/tables or is there another
            job that maintains all log files/log tables in the
            database?*

    -   *Modification*

        -   *Purpose:*

        -   *Modified sql code:*

        -   *Schedule change?*

        -   *Change in length of execution? If the execution time
            increases, will there be any interference to other
            jobs/backups?*

    -   *Obsolete*

        -   *Purpose:*

        -   *Name of job and any other scripts called by the job:*

-   *Arvhive Log File Maintenance:*

    -   *Purpose:*

    -   *Change in the maintenance schedule or retention period?*

    -   *Is there sufficient space on disk to support the change?*

-   *Storage Maintenance:*

    -   *Of all the data modifications, new tables and retention changes
        for this CCR/Release, consider the availability of resources in
        the following areas:*

        -   *Tablespace: Does the tablespace have enough space to
            capture the new data?*

        -   *If datafiles need to be added/resized, are there enough
            space on the disks?*

        -   *Will the generation of redo log files change thus changing
            the amount of archive log files that are kept on line? If
            yes, then is there enough disk space on the server?*

#######  {#section-15 .unnumbered}

# \[*Appendix D -- Other Appendix*\] {#appendix-d-other-appendix .unnumbered}

\[*Appendixes may be used to provide information published separately
for convenience in document maintenance (e.g., charts, classified data).
As applicable, each appendix shall be referenced in the main body of the
document where the data would normally have been provided. Appendixes
may be bound as separate documents for ease in handling. Appendixes
shall be lettered alphabetically (A, B, etc.).*\]