![](media/image1.png){width="2.1041666666666665in"
height="0.5in"}![](media/image2.jpeg){width="0.5013888888888889in"
height="0.5013888888888889in"}

![](media/image3.png){width="1.2090277777777778in"
height="1.1416666666666666in"}

caCORE SDK

Generated System Detail Design

> Version No: 1.1
>
> Last Modified: 08/17/2006
>
> Author: Daniel Dumitru
>
> Team: caCORE SDK
>
> Client: National Cancer Institute - Center for Bioinformatics,
>
> National Institutes of Health,
>
> US Department of Health and Human Services
>
> This document was prepared NCI Center for Bioinformatics
>
> Pursuant to the caCORE Software Development Kit (SDK)\
> Project (REF: Solicitation No. S06-234).

# Document History {#document-history .unnumbered}

## Document Location

> The most current version of this document is located in CVS under
> cacoresdk/Project/SDK v3.2/Development/Design.

## Revision History

  -------------------------------------------------------------------------------
  **Version   **Revision   **Author**         **Summary of Changes**
  Number**    Date**                          
  ----------- ------------ ------------------ -----------------------------------
  1.0         07/11/06     Daniel Dumitru     Initial draft

  1.1         07/14/06     Satish Patel       Formatting, grammar changes

  1.2         07/19/06     Daniel Dumitru     Added Persistence Detail Design
                                              section

  1.3         07/26/06     Daniel Dumitru     Added Query Detail Design section

  1.4         08/23/06     Daniel Dumitru     Updated per Document Review(s)

                                              
  -------------------------------------------------------------------------------

## Review

  ------------ --------------- ------------- ------------ ---------------------
  **Name**     **Team/Role**   **Version**   **Date       **Reviewer Comments**
                                             Reviewed**   

  Satish Patel                 1.1           07/14/2006   Formatting, grammar
                                                          changes

  Steve Hunter QA              1.2           08/17/2006   Formatting, grammar

                                                          

                                                          

                                                          
  ------------ --------------- ------------- ------------ ---------------------

## Related Documents

> **More information can be found in the following related documents:**

  -----------------------------------------------------------------------
  **Document Name**

  -----------------------------------------------------------------------

# Table of Contents {#table-of-contents .unnumbered}

[Document History 2](#document-history)

[0.1 Document Location 2](#document-location)

[0.2 Revision History 2](#revision-history)

[0.3 Review 2](#review)

[0.4 Related Documents 2](#related-documents)

[Table of Contents 3](#table-of-contents)

[Table of Figures 5](#table-of-figures)

[1. Introduction 6](#introduction)

[1.1 Purpose 6](#purpose)

[1.2 Intended Audience 6](#intended-audience)

[1.3 Scope 6](#scope)

[1.4 Overview 6](#overview)

[1.5 Definitions, Acronyms, and Abbreviations
6](#definitions-acronyms-and-abbreviations)

[2. Exception Handling Detail Design
7](#exception-handling-detail-design)

[2.1 Current Design - Problem Scenario
7](#current-design---problem-scenario)

[2.1.1 Analysis of Current caCORE SDK Exception Class Definitions and
Usage 7](#__RefHeading___Toc144115342)

[2.1.2 Problems with the ApplicationException Class
8](#problems-with-the-applicationexception-class)

[2.2 Proposed Exception Handling Enhancements
10](#proposed-exception-handling-enhancements)

[2.2.1 Introduction of More Specific Exception Classes
10](#introduction-of-more-specific-exception-classes)

[2.2.2 Code Changes to Classes that Use (Throw) ApplicationException
12](#code-changes-to-classes-that-use-throw-applicationexception)

[3. Query Detail Design 13](#query-detail-design)

[3.1 The Query Interfaces within the caCORE SDK Tiered Architecture
13](#the-query-interfaces-within-the-cacore-sdk-tiered-architecture)

[3.2 Supported SDK Query Types 14](#supported-sdk-query-types)

[3.2.1 Simple Search Query Type 15](#simple-search-query-type)

[3.2.2 Nested Search Query Type 16](#nested-search-query-type)

[3.2.3 Detached Criteria Query Type 16](#detached-criteria-query-type)

[3.2.4 HQL Criteria Query Type 16](#hql-criteria-query-type)

[3.3 Supported SDK Query Interfaces 17](#supported-sdk-query-interfaces)

[3.4 Java API 17](#java-api)

[3.4.1 gov.nih.nci.system.applicationservice.ApplicationServiceProvider
19](#gov.nih.nci.system.applicationservice.applicationserviceprovider)

[3.4.2 gov.nih.nci.system.comm.client.ApplicationServiceClientImpl
20](#gov.nih.nci.system.comm.client.applicationserviceclientimpl)

[3.4.3 gov.nih.nci.system.comm.server.ApplicationServiceServerImpl
21](#gov.nih.nci.system.comm.server.applicationserviceserverimpl)

[3.4.4 gov.nih.nci.system.applicationservice.impl.ApplicationServiceImpl
22](#gov.nih.nci.system.applicationservice.impl.applicationserviceimpl)

[3.4.5
gov.nih.nci.system.applicationservice.impl.ApplicationServiceBusinessImpl
23](#gov.nih.nci.system.applicationservice.impl.applicationservicebusinessimpl)

[3.4.6 gov.nih.nci.common.util.ListProxy
24](#gov.nih.nci.common.util.listproxy)

[3.5 Web Services API 26](#web-services-api)

[3.5.1 Web Services Client 27](#web-services-client)

[3.5.2 Axis Web Services API 28](#axis-web-services-api)

[3.5.3 gov.nih.nci.system.webservice.WSQuery
28](#gov.nih.nci.system.webservice.wsquery)

[3.5.4 gov.nih.nci.system.webservice.WSTransformer
29](#gov.nih.nci.system.webservice.wstransformer)

[3.6 XML-HTTP API 30](#xml-http-api)

[3.6.1 gov.nih.nci.system.proxy.HTTPQuery
31](#gov.nih.nci.system.proxy.httpquery)

[3.6.2 gov.nih.nci.common.util.HTTPUtils
34](#gov.nih.nci.common.util.httputils)

[4. Persistence Tier Detail Design 36](#persistence-tier-detail-design)

[4.1 The Persistence Tier within the caCORE SDK Tiered Architecture
36](#the-persistence-tier-within-the-cacore-sdk-tiered-architecture)

[4.2 Base Delegate Query Interface 37](#base-delegate-query-interface)

[4.2.1
gov.nih.nci.system.applicationservice.impl.ApplicationServiceBusinessImpl
38](#gov.nih.nci.system.applicationservice.impl.applicationservicebusinessimpl-1)

[4.2.2 gov.nih.nci.common.net.Request
39](#gov.nih.nci.common.net.request)

[4.2.3 gov.nih.nci.common.net.Response
40](#gov.nih.nci.common.net.response)

[4.2.4 gov.nih.nci.system.delegator.BaseDelegate
41](#gov.nih.nci.system.delegator.basedelegate)

[4.2.5 gov.nih.nci.system.servicelocator.ServiceLocator
41](#gov.nih.nci.system.servicelocator.servicelocator)

[4.2.6 gov.nih.nci.system.dao.DAOFactory
42](#gov.nih.nci.system.dao.daofactory)

[4.2.7 gov.nih.nci.system.dao.ORMDAOFactory
43](#gov.nih.nci.system.dao.ormdaofactory)

[4.2.8 gov.nih.nci.system.dao.impl.orm.ORMDAOImpl
44](#gov.nih.nci.system.dao.impl.orm.ormdaoimpl)

[4.2.9 gov.nih.nci.system.dao.impl.orm.ORMConnection
44](#gov.nih.nci.system.dao.impl.orm.ormconnection)

[4.2.10 gov.nih.nci.common.util.NestedCriteria2HQL
45](#gov.nih.nci.common.util.nestedcriteria2hql)

[4.3 Writable DAO Create, Read, Update, Delete Interface
46](#writable-dao-create-read-update-delete-interface)

[4.3.1 gov.nih.nci.system.applicationservice.impl.ApplicationServiceImpl
48](#gov.nih.nci.system.applicationservice.impl.applicationserviceimpl-1)

[4.3.2 gov.nih.nci.system.dao.WritableDAO
49](#gov.nih.nci.system.dao.writabledao)

[4.3.3 gov.nih.nci.system.servicelocator.ServiceLocator
50](#gov.nih.nci.system.servicelocator.servicelocator-1)

[4.3.4 gov.nih.nci.system.dao.impl.orm.ORMConnection
50](#gov.nih.nci.system.dao.impl.orm.ormconnection-1)

[5. Configuration/Deployment Considerations
51](#configurationdeployment-considerations)

[5.1 Property/Configuration Files 51](#propertyconfiguration-files)

[5.2 Deployment Considerations 51](#deployment-considerations)

[6. Resources 52](#resources)

[6.1 Technical Manuals/Articles 52](#technical-manualsarticles)

[6.2 Core J2EE Patterns 52](#core-j2ee-patterns)

[6.3 Hibernate Reference Manual 52](#hibernate-reference-manual)

[6.4 caCORE SDK Documentation 52](#cacore-sdk-documentation)

# Table of Figures {#table-of-figures .unnumbered}

[Figure 1: Current Set of caCORE SDK Exception Classes
7](#__RefHeading___Toc144115436)

[Figure 2: An Example: The Use of Class DAOException
8](#__RefHeading___Toc144115437)

[Figure 3: Packages that Use ApplicationException
9](#__RefHeading___Toc144115438)

[Figure 4: Classes that Use (Throw) ApplicationException
10](#__RefHeading___Toc144115439)

[Figure 5: Proposed Exception Class Hierarchy
11](#__RefHeading___Toc144115440)

[Figure 6: Current Exception Handling Practice
12](#__RefHeading___Toc144115441)

[Figure 7: Proposed Exception Handling Practice
12](#__RefHeading___Toc144115442)

[Figure 8: Query Interfaces within the caCORE SDK Tiered Architecture
13](#__RefHeading___Toc144115443)

[Figure 9: SDK Query Types 15](#__RefHeading___Toc144115444)

[Figure 10: Query Sequence - Local Java Client
18](#__RefHeading___Toc144115445)

[Figure 11: Query Sequence - Remote Java Client
19](#__RefHeading___Toc144115446)

[Figure 12:
gov.nih.nci.system.applicationservice.ApplicationServiceProvider Outline
Diagram 20](#__RefHeading___Toc144115447)

[Figure 13: gov.nih.nci.system.comm.client.ApplicationServiceClientImpl
Outline Diagram 21](#__RefHeading___Toc144115448)

[Figure 14: gov.nih.nci.system.comm.server.ApplicationServiceServerImpl
Outline Diagram 22](#__RefHeading___Toc144115449)

[Figure 15:
gov.nih.nci.system.applicationservice.impl.ApplicationServiceImpl
Outline Diagram 23](#__RefHeading___Toc144115450)

[Figure 16:
gov.nih.nci.system.applicationservice.impl.ApplicationServiceBusinessImpl
Diagram 24](#__RefHeading___Toc144115451)

[Figure 17: gov.nih.nci.common.util.ListProxy Outline Diagram
25](#__RefHeading___Toc144115452)

[Figure 18: Query Sequence - Web Service Client
27](#__RefHeading___Toc144115453)

[Figure 19: gov.nih.nci.system.webservice.WSQuery Outline Diagram
29](#__RefHeading___Toc144115454)

[Figure 20: gov.nih.nci.system.webservice.WSTransformer Outline Diagram
30](#__RefHeading___Toc144115455)

[Figure 21: Query Sequence -- XML-HTTP Client
31](#__RefHeading___Toc144115456)

[Figure 22: XML-HTTP Servlet Mappings 32](#__RefHeading___Toc144115457)

[Figure 23: gov.nih.nci.system.proxy.HTTPQuery Outline Diagram
33](#__RefHeading___Toc144115458)

[Figure 24: gov.nih.nci.common.util.HTTPUtils Outline Diagram
35](#__RefHeading___Toc144115459)

[Figure 25: Persistence Tier within the caCORE SDK Tiered Architecture
36](#__RefHeading___Toc144115460)

[Figure 26: Persistence Tier (Base Delegate Query Interface) Sequence
Diagram 37](#__RefHeading___Toc144115461)

[Figure 27: gov.nih.nci.system.ApplicationBusinessImpl Outline Diagram
39](#__RefHeading___Toc144115462)

[Figure 28: gov.nih.nci.common.net.Request Outline Diagram
40](#__RefHeading___Toc144115463)

[Figure 29: gov.nih.nci.common.net.Response Outline Diagram
41](#__RefHeading___Toc144115464)

[Figure 30: gov.nih.nci.system.delegator.BaseDelegate Outline Diagram
41](#__RefHeading___Toc144115465)

[Figure 31: gov.nih.nci.system.servicelocator.ServiceLocator Outline
Diagram 42](#__RefHeading___Toc144115466)

[Figure 32: gov.nih.nci.common.net.Request Outline Diagram
43](#__RefHeading___Toc144115467)

[Figure 33: gov.nih.nci.system.dao.ORMDAOFactory Outline Diagram
44](#__RefHeading___Toc144115468)

[Figure 34: gov.nih.nci.system.dao.ORMDAOImpl Outline Diagram
44](#__RefHeading___Toc144115469)

[Figure 35: gov.nih.nci.system.dao.ORMConnection Outline Diagram
45](#__RefHeading___Toc144115470)

[Figure 36: gov.nih.nci.system.dao.ORMConnection Outline Diagram
46](#__RefHeading___Toc144115471)

[Figure 37: Persistence Tier (Base Delegate Query Interface) Sequence
Diagram 47](#__RefHeading___Toc144115472)

[Figure 38: ApplicationService Interface and Related Classes Diagram
48](#__RefHeading___Toc144115473)

[Figure 39: gov.nih.nci.system.dao.ORMConnection Outline Diagram
49](#__RefHeading___Toc144115474)

[Figure 40: gov.nih.nci.system.dao.WritableDAO Outline Diagram
50](#__RefHeading___Toc144115475)

# Introduction

## Purpose

> The purpose of this document is to describe the current architecture,
> including **Exception handling** practices, within the ***generated
> system*** of the caCORE SDK, and to document opportunities for
> enhancements.
>
> The information presented in this document is meant to supplement (not
> replace) information already available in the caCORE Software
> Development Kit 1.1 *Programmer's* and *Technical Guide*.

## Intended Audience

> The intended audience for this document includes caCORE SDK
> **Developers, Project Administrators,** and **End Users** interested
> in the obtaining an overview of the current Query and Persistence
> Design, as well as insight into proposed enhancements to the caCORE
> SDK generated system.

## Scope

> The scope of this document is limited to a discussion of current
> caCORE SDK ***generated system*** design, along with proposed changes
> for improved stability and usability.
>
> A discussion of the exception handling practices within the Code
> Generation portion of the caCORE SDK is beyond the scope of this
> document.

Additionally, an analysis of exception handling practices within the Web
services portion of the generated system has been postponed due to time
constraints, and will be addressed during a later iteration.

## Overview

> The following sections provide:

1)  A brief overview of the current exception handling practices with
    the caCORE SDK generated system

2)  Recommended changes to enhance the usability and improve the
    communication of exceptional conditions to the system, developers,
    and end users.

3)  A description of the current Query and Persistence design and
    opportunities for improving it.

4)  Considerations on configuration and deployment.

## Definitions, Acronyms, and Abbreviations

> All definitions, acronyms, and abbreviations are provided in the
> centralized definition document found at cacoresdk/Project/SDK
> v3.2/Miscellaneous/Acronyms.doc.

# Exception Handling Detail Design

This section discusses exception handling practices within the generated
portion of the caCORE SDK.

## Current Design - Problem Scenario

This section describes the current **Exception handling** practices
within the ***generated system*** of the caCORE SDK along with details
as to why enhancements are desired.

### Analysis of Current caCORE SDK Exception Class Definitions and Usage

> A high-level analysis of the current caCORE SDK **example** code
> base[^1] shows that there is a relatively well-defined, specific set
> of Exception type classes, as shown below:
>
> ![](media/image4.png){width="6.627777777777778in"
> height="4.270138888888889in"}

[]{#__RefHeading___Toc144115436 .anchor}Figure 1: Current Set of caCORE
SDK Exception Classes

> A closer inspection of the exception handling practices within the
> example generated system shows that, *for the most part*, exceptions
> are defined and used in a manner consistent with exception handling
> Best Practices:[^2] the exception name (type) communicates the kind of
> exception, the stack trace communicates the location to the SDK
> developer or programmer, and the exception message communicates
> additional information to the end user that might be helpful in
> determining and correcting the error.
>
> As an example, let's examine the usage of the **DAOException** class,
> shown below:
>
> ![](media/image5.png){width="6.615277777777778in"
> height="6.263888888888889in"}

[]{#__RefHeading___Toc144115437 .anchor}Figure 2: An Example: The Use of
Class DAOException

> The DAOException class is both defined and applied within the dao
> packages and their classes. The use of the DAOException is also
> consistent with its type and definition; i.e., the methods that throw
> DAOException, such as get\[DAO\]Factory and query, are related to data
> access functions. The developer, calling system, or end user that
> receives a DAOException thus has a good indication of the nature of
> the exception, its location, and the root cause of the problem.
>
> However, as we will examine in the next section, this is not the case
> with the exception class, **ApplicationException.**

### Problems with the ApplicationException Class

> The **ApplicationException** seems to be defined and used in an
> effective manner. Its name also seems to accurately convey the
> exception type, and is also consistent with its placement within the
> **applicationservice** **package**, and association with the
> **ApplicationService interface**.
>
> However, the ApplicationException class, when applied with the
> generated system, is used for handling a wide variety of exceptional
> conditions. Some of these conditions include: query/search,
> persistence, and security functions (see diagrams below).
>
> ![](media/image6.png){width="6.614583333333333in"
> height="2.7243055555555555in"}

[]{#__RefHeading___Toc144115438 .anchor}Figure 3: Packages that Use
ApplicationException

> The listing and diagram below detail the variety of disparate classes,
> contained within the above package listing, that are associated with
> (i.e. that throw) ApplicationException:

-   SecurityEnabler

-   WriteableDAO

-   Client Session

-   ApplicationService

-   ApplicationServiceClientImpl

-   ApplicationServiceServerImpl

> ![](media/image7.wmf){width="6.7444444444444445in" height="6.1125in"}

[]{#__RefHeading___Toc144115439 .anchor}Figure 4: Classes that Use
(Throw) ApplicationException

> Within this context, the ApplicationException name (type) becomes too
> general, and its usage too broad, to effectively communicate the root
> cause of the exceptional condition. End users are required to spend
> more time and effort than necessary interpreting and investigating the
> exception in order to determine the nature of the exception, its
> location, and the root cause of the problem.

## Proposed Exception Handling Enhancements

This section describes the proposed exception handling enhancements that
will clarify the cause of checked exceptions but still remain backwards
compatible with the current release.

### Introduction of More Specific Exception Classes

> In order to enhance the exception handling of the caCORE SDK generated
> system in a manner that preserves backwards compatibility with the
> current release, it is proposed that a more specific exception class
> hierarchy be created, as shown below:
>
> ![](media/image8.wmf){width="6.746527777777778in" height="4.075in"}

[]{#__RefHeading___Toc144115440 .anchor}Figure 5: Proposed Exception
Class Hierarchy

> For improved readability, the same exception class hierarchy is
> provided below in list format:
>
> Alternate or additional persistence related exception classes under
> consideration (inspired by the javax.PersistenceException API[^3])
> include:
>
> Sub-classing the proposed exceptions from a common parent,
> **ApplicationException**, allows exception handling to proceed in a
> more object-oriented manner. Callers that invoke the
> ApplicationService interface(s) can choose to treat all Application
> Exceptions equally as they do now with a single catch block. However,
> if the callers desire to deal with one of the proposed exception
> classes in a specific manner, they can catch the more specific
> exception type first and recover appropriately.

### Code Changes to Classes that Use (Throw) ApplicationException

> Classes that currently use (throw) ApplicationException will be
> modified to now throw one of the three (3) more specific exception
> classes, **QueryException, DAOException**, or **SecurityException**,
> as illustrated below:

[]{#__RefHeading___Toc144115441 .anchor}Figure 6: Current Exception
Handling Practice

[]{#__RefHeading___Toc144115442 .anchor}Figure 7: Proposed Exception
Handling Practice

> With this practice, none of the existing method signatures would
> change, thus preserving backwards compatibility with the current
> release.
>
> Additionally, the proposed exception handling practice now also
> preserves the original exception via the constructor that takes a
> throwable cause as the second argument, thus providing more detailed
> information to the caller catching the thrown exception.[^4]

# Query Detail Design

This section details the current SDK Query design, and, where
applicable, describes opportunities to improve it. The information
described herein is intended to complement the information contained
within Chapter 3, *Interacting with caCORE* of the caCORE 3.1 *Technical
Guide*. It is recommended that Chapter 3 be read before, or in
conjunction with, this section in order to obtain the greatest clarity
and comprehension.

Areas covered in this section include:

-   The caCORE SDK tiered architecture, with the Query interface area
    highlighted

-   Supported query types, including Simple, Nested, Detached Criteria,
    and HQL Search types

-   Supported query interfaces, including the Java, XML-HTTP, and Web
    Service API's

-   How a Query is parsed and converted into one of the supported query
    types

## The Query Interfaces within the caCORE SDK Tiered Architecture

Any system generated by the caCORE SDK shares the architecture shown
below, which divides the generated application into a series of layers,
or tiers[^5]:

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

[]{#__RefHeading___Toc144115443 .anchor}Figure 8: Query Interfaces
within the caCORE SDK Tiered Architecture

While various functional areas, or tiers, are shown in the diagram,
attention is focused in this section primarily to the query interaction
between the Client and Application Service tiers, as highlighted
above[^6].

The following sections discuss the various query types and interfaces,
and details query processing sequences that take place within the
Application Service layer prior to being handed off to the to the
Persistence Tier for final processing.

## Supported SDK Query Types

As described in the *Technical Guide*, the caCORE architecture includes
an Application Service layer, or tier, that provides a single, common
access paradigm to clients that rely heavily on strongly typed objects
and an object-in/object-out mechanism. The methodology used for
obtaining data from caCORE systems is often referred to as
*Query-by-Example*. This methodology means that the inputs to the query
methods are themselves domain objects that provide the criteria for the
returned data.

The four (4) generalized types of queries, or searches, provided via the
Application Service interface include:

-   **Simple Search**: takes one or more domain objects as input, and
    returns a collection of objects from a persistent data source that
    meets the criteria specified by the input object.

-   **Nested Search**: also takes one or more domain objects as input,
    but determines the type of objects in the result set by traversing a
    known path of associations from the domain model.

-   **Detached Criteria Search**: takes a Hibernate Detached Criteria
    object as input, which is used to provide a greater level of control
    over the results of a search due to its ability to more readily
    specify Boolean operations, and range values.

-   **HQL Query Search**: takes a Hibernate Query Language (HQL) string
    as input.

A sequence diagram illustrating the various possible query type
interactions between a client and the SDK Application Service interface
is shown below[^7]:

![](media/image10.wmf){width="7.247222222222222in"
height="4.747916666666667in"}

[]{#__RefHeading___Toc144115444 .anchor}Figure 9: SDK Query Types

> As illustrated in the diagram above, support for all four query types
> is implemented via a total of seven (7) application service methods.
> Each method is described briefly below.

### Simple Search Query Type

> The **Simple Search** query type is implemented via the following two
> Application Service interface query methods:

-   **Single Criteria Object \[List:= search(Class targetClass, Object
    domainObj)\]**: Returns a List collection containing objects of the
    same type as the targetClass parameter that conform to the criteria
    defined by the domain object parameter, domainObj. Note that the
    single criteria object can be a compound (composite) object.

> Example: search(Gene.class, gene).

-   **Criteria Object Collection \[List:= search(Class targetClass,
    Object domainObjList)\]**: Returns a List collection containing
    objects of the same type as the targetClass parameter that conform
    to the criteria defined by a collection of objects in domainObjList.
    The returned objects must meet ANY criteria in domainObjList (i.e. a
    logical OR is performed).

> Example: search(Gene.class, geneCollection).

### Nested Search Query Type

> The **Nested Search** query type is implemented via the following two
> Application Service interface query methods:

-   **Single Criteria Object \[List:= search(String traversalPath,
    Object domainObj)\]**: Returns a List collection containing objects
    conforming to the criteria defined by domainObj and whose resulting
    objects are of the type reached by traversing the node graph
    specified by traversalPath.

> Example: search(\"gov.nih.nci.cabio.domain.Protein, gov.nih.nci.
> cabio.domain.Gene\", nucleicAcidSequence)

-   **Criteria Object Collection \[List:= search(String traversalPath,
    List domainObjList)\]**: Returns a List collection containing
    objects conforming to the criteria defined by the objects in
    domainObjList and whose resulting objects are of the type reached by
    traversing the node graph specified by traversalPath.

> Example: search(\"gov.nih.nci.cabio.domain.Protein,
> gov.nih.nci.cabio.domain.Gene\", sequenceList)

### Detached Criteria Query Type

> The **Detached Criteria**[^8] **Search** query type is implemented via
> the following two Application Service interface query methods:

-   **Initial Search \[List:= query(DetachedCriteria detachedCriteria,
    String targetClassName)\]**: Returns a List collection conforming to
    the criteria specified by Hibernate detachedCriteria and whose
    resulting objects are of the type specified by targetClassName.

> Example: query(criteria, \"gov.nih.nci.cabio.domain.Gene\").

-   **Subsequent or Paging Search \[List:= query(Object criteria, int
    firstRow, int resultsPerQuery, String targetClassName)\]**:
    Identical to the previous query method, but allows for greater
    control over the size of the returned result set by specifying the
    row number of the first row and the maximum number of objects to be
    returned.

> Example: query(criteria, 101, 100, targetClassName).

### HQL Criteria Query Type

> The **HQL**[^9] **Criteria Search** query type is implemented via the
> following Application Service interface query method:

-   **HQL Search \[List:= query(HQLCriteria hqlCriteria, String
    targetClassName)\]**: Returns a List collection of objects of the
    type specified by targetClassName that conform to the query in
    Hibernate Query Language (HQL) syntax contained in hqlCriteria.

> Example: query(hqlCriteria, \"gov.nih.nci.cabio.domain.Gene\")
>
> In an effort to minimize repetition, please refer to the *Service
> Methods* and *Examples of Use* sections of the caCORE 3.1 *Technical
> Guide*, pages 17-26 for a more detailed description of each of the
> service method signatures, as well as some example code.

## Supported SDK Query Interfaces

As described in the *Technical Guide*, the caCORE architecture includes
a service layer that provides a single, common access paradigm to
clients via four (4) interfaces, including:

-   Java API

-   Web Services API

-   XML-HTTP API

Each of the interfaces is discussed below.

## Java API

As described in the caCORE 3.1 *Technical Guide*, the Java API provides
direct access to domain objects and all application service methods for
both *local* and *remote* Java clients. Because caCORE is natively built
in Java, this API provides the fullest set of features and capabilities,
and supports all four basic query types discussed in the section,
[Supported SDK Query Types](#supported-sdk-query-types).

A Sequence diagram illustrating the query interaction between a *local*
Java client and the SDK native Java interface is shown below:

![](media/image11.wmf){width="7.2444444444444445in"
height="4.586111111111111in"}

[]{#__RefHeading___Toc144115445 .anchor}Figure 10: Query Sequence -
Local Java Client

A Sequence diagram illustrating the query interaction between a *remote*
Java client and the SDK native Java interface is shown below:

![](media/image12.wmf){width="7.247222222222222in"
height="5.254861111111111in"}

[]{#__RefHeading___Toc144115446 .anchor}Figure 11: Query Sequence -
Remote Java Client

The following sections detail the Java API SDK classes participating in
the Sequence diagram shown above.

### gov.nih.nci.system.applicationservice.ApplicationServiceProvider

> The gov.nih.nci.system.applicationservice.ApplicationServiceProvider
> class implements a variation of the Creational Factory Pattern[^10],
> which, given a super class and n sub-classes, and based on data
> provided, creates and returns the object of one of the sub-classes.
>
> In the case of the SDK, the ApplicationServiceProvider creates an
> appropriate local or remote instance of the Application Service
> Interface super class, depending on whether the client that is
> invoking the ApplicationServiceProvider getRemote() method is local or
> remote, and returns it to the client.
>
> An outline diagram listing the ApplicationServiceProvider attributes
> and methods is shown below[^11]:
>
> ![](media/image13.png){width="3.3229166666666665in" height="2.95in"}

[]{#__RefHeading___Toc144115447 .anchor}Figure 12:
gov.nih.nci.system.applicationservice.ApplicationServiceProvider Outline
Diagram

### gov.nih.nci.system.comm.client.ApplicationServiceClientImpl

> The gov.nih.nci.system.comm.client.ApplicationServiceClientImpl class
> provides the client-side, local implementation of the Application
> Service interface class, and is returned by the
> ApplicationServiceProvider Factory class in the case when the Java
> client is remote to the SDK server.
>
> The ApplicationServiceClientImpl forwards all query/search calls to
> its server-side counterpart, ApplicationServiceServerImpl, which is
> discussed in the next section.
>
> An outline diagram listing the ApplicationServiceClientImpl attributes
> and methods is shown below. Note the implementation of the seven (7)
> application service methods that support all four query types
> discussed in the section, [Supported SDK Query
> Types](#supported-sdk-query-types):
>
> ![](media/image14.png){width="3.7708333333333335in"
> height="5.678472222222222in"}

[]{#__RefHeading___Toc144115448 .anchor}Figure 13:
gov.nih.nci.system.comm.client.ApplicationServiceClientImpl Outline
Diagram

### gov.nih.nci.system.comm.server.ApplicationServiceServerImpl

> The gov.nih.nci.system.comm.server.ApplicationServiceServerImpl class
> provides the server-side, remote implementation of the Application
> Service interface class, and is used in the case when the Java client
> is remote to the SDK server.
>
> ApplicationServiceServerImpl forwards all query/search calls to
> ApplicationServiceImpl, which is discussed in the next section.
>
> An outline diagram listing the ApplicationServiceServerImpl public
> methods is shown below. Note the implementation of the seven (7)
> application service methods that support all four query types
> discussed in the section, [Supported SDK Query
> Types](#supported-sdk-query-types):
>
> ![](media/image15.png){width="3.7708333333333335in"
> height="4.559027777777778in"}

[]{#__RefHeading___Toc144115449 .anchor}Figure 14:
gov.nih.nci.system.comm.server.ApplicationServiceServerImpl Outline
Diagram

### gov.nih.nci.system.applicationservice.impl.ApplicationServiceImpl

> The gov.nih.nci.system.applicationservice.impl.ApplicationServiceImpl
> class is a business service object that implements the business logic
> of the ApplicationService interface, which provides a variety of
> query/search methods for querying the SDK generated HTTP server.
>
> Additionally, the ApplicationServiceImpl class implements the
> persistence Writeable DAO functionality, which is discussed in the
> section [Writeable DAO: Create, Read, Update, Delete
> Interface](#writable-dao-create-read-update-delete-interface).
>
> The ApplicationServiceImpl forwards all query/search calls to
> ApplicationServiceBusinessImpl, which is discussed in the next
> section.
>
> An outline diagram listing the ApplicationServiceBusinessImpl
> attributes and methods is shown below. Note the implementation of the
> seven (7) application service methods that support all four query
> types discussed in the section, [Supported SDK Query
> Types](#supported-sdk-query-types):
>
> ![](media/image16.png){width="4.28125in" height="4.843055555555556in"}

[]{#__RefHeading___Toc144115450 .anchor}Figure 15:
gov.nih.nci.system.applicationservice.impl.ApplicationServiceImpl
Outline Diagram

### gov.nih.nci.system.applicationservice.impl.ApplicationServiceBusinessImpl

> The
> gov.nih.nci.system.applicationservice.impl.ApplicationServiceBusinessImpl
> class is a business service object that implements the business logic
> of the ApplicationService interface, which provides a variety of
> query/search methods for querying the SDK generated HTTP server.
>
> An outline diagram listing the ApplicationServiceBusinessImpl
> attributes and methods is shown below. Note the implementation of the
> seven (7) application service methods that support all four query
> types discussed in the section, [Supported SDK Query
> Types](#supported-sdk-query-types):
>
> ![](media/image17.png){width="3.7708333333333335in"
> height="4.168055555555555in"}

[]{#__RefHeading___Toc144115451 .anchor}Figure 16:
gov.nih.nci.system.applicationservice.impl.ApplicationServiceBusinessImpl
Diagram

### gov.nih.nci.common.util.ListProxy

> The gov.nih.nci.common.util.ListProxy class implements the List
> interface, extending the ArrayList class. It is used to hold the
> results of a given query, along with details of the original request,
> including the original query criteria object, start index,
> serverAddress, targetClassName, and the real size of result list, if
> completely materialized.
>
> An outline diagram listing the ListProxy attributes and methods is
> shown below.
>
> ![](media/image18.png){width="3.925in" height="7.872222222222222in"}

[]{#__RefHeading___Toc144115452 .anchor}Figure 17:
gov.nih.nci.common.util.ListProxy Outline Diagram

## Web Services API

As described in the caCORE 3.1 *Technical Guide*, the caCORE Web
services API allows access to caCORE data from development environments
where the Java APIs cannot be used, or where use of XML Web services is
more desirable. This includes non-Java platforms and languages such as
Perl, C/ C++, .NET Framework (C#, VB.Net), Python, etc. The Web services
interface can be used in any language-specific application that provides
a mechanism for consuming XML Web services based on the Simple Object
Access Protocol (SOAP). In these environments, connecting to caCORE can
be as simple as providing the endpoint URL. Some platforms and languages
require additional client-side code to handle the implementation of the
SOAP envelope and the resolution of SOAP types. A list of packages
catering to different programming languages is available at
<http://www.w3.org/TR/SOAP/> and at <http://www.soapware.org/>.

To maximize standards-based interoperability, the caCORE Web service
conforms to the Web Services Interoperability Organization (WS-I) Basic
Profile[^12].

The Web Services API provides a limited subset of the query features and
capabilities of the SDK, and only supports one (Simple Search) of the
four basic query types discussed in the section, [Supported SDK Query
Types](#supported-sdk-query-types).

A Sequence diagram illustrating the query interaction between a Web
Service client and the SDK Web Service interface is shown below:

![](media/image19.wmf){width="7.24375in" height="7.440277777777778in"}c

[]{#__RefHeading___Toc144115453 .anchor}Figure 18: Query Sequence - Web
Service Client

The following sections detail the Web Services API SDK classes
participating in the Sequence diagram shown above.

### Web Services Client

> The Web Services Client actor represents a client written in any of
> the languages, such as Perl, C/ C++, .NET Framework (C#, VB.Net), or
> Python, that support XML Web Services based on the Simple Object
> Access Protocol (SOAP).

### Axis Web Services API

On the SDK server side of the Web Services API, Apache Axis is used to
provide SOAP-based inter-application communication. Axis provides the
appropriate serialization and de-serialization methods for the Java
beans to achieve an application-independent interface[^13].

### gov.nih.nci.system.webservice.WSQuery

The gov.nih.nci.system.webservice.WSQuery is the backend implementation
class for the Axis Web Services API, and implements the queryObject and
query operations.

The queryObject operation performs a search for objects conforming to
the criteria defined by the criteria domain object input parameter. The
resulting objects can be reached by traversing the node graph specified
by the parameter that indicates the target class name path. The result
is a set of serialized objects.

The query operation is almost identical to the queryObject operation.
The query operation allows for control over the result by specifying the
row number of the first row via the startIndex parameter, and setting
the maximum number of objects to return via the recordCounter parameter.

As mentioned before, the Web Services API provides a limited subset of
the query features and capabilities of the SDK, and only supports one
(Single Criteria Object, Simple Search) of the four basic query types
discussed in the section, [Supported SDK Query
Types](#supported-sdk-query-types). More specifically, the queryObject
and query operations provide a Web Service interface to the Single
Criteria Object Simple Search query type discussed in the section,
[Simple Search Query Type](#simple-search-query-type).

An example of an Axis client Web Service invocation is shown below:

> Object\[\] resultList = (Object\[\])call.invoke(
>
> new Object\[\]{\"gov.nih.nci.cabio.domain.ws.Gene\", gene });

An outline diagram listing the WSQuery attributes and methods is shown
below:

![](media/image20.png){width="3.6875in" height="4.888888888888889in"}

[]{#__RefHeading___Toc144115454 .anchor}Figure 19:
gov.nih.nci.system.webservice.WSQuery Outline Diagram

Please refer to the *Operations*, Web Services API section of the caCORE
3.1 *Technical Guide* documentation for more information and examples.

### gov.nih.nci.system.webservice.WSTransformer

The gov.nih.nci.system.webservice.WSTransformer is a Helper class used
by the WSQuery class to transform (deserialize) a query request (via the
buildSearchCriteria(), getSearchClassName(), and getSearchCriteria()
methods) into a format understood by the Application Service interface.

The WSTransformer class also provides a method, generateWSResults(),
which serializes query results into a format suitable for transport and
return to the Web Service Client.

An outline diagram listing the WSTransformer attributes and methods is
shown below:

![](media/image21.png){width="3.0520833333333335in"
height="2.573611111111111in"}

[]{#__RefHeading___Toc144115455 .anchor}Figure 20:
gov.nih.nci.system.webservice.WSTransformer Outline Diagram

## XML-HTTP API

As described in the caCORE 3.1 *Technical Guide*, the caCORE XML-HTTP
API, based on the Representational State Transfer (REST)[^14]
architectural style, provides a simple interface using the HTTP
protocol. In addition to its ability to be invoked from most internet
browsers, developers can use this interface to build applications that
do not require any programming overhead other than an HTTP client. This
is particularly useful for developing web applications using AJAX
(asynchronous JavaScript and XML).

A Sequence diagram illustrating the query interaction between an XML or
HTTP client and the SDK XML-HTTP API is shown below:

![](media/image22.wmf){width="7.238194444444445in"
height="5.9118055555555555in"}

[]{#__RefHeading___Toc144115456 .anchor}Figure 21: Query Sequence --
XML-HTTP Client

The following sections detail the XML-HTTP API SDK classes participating
in the Sequence diagram shown above.

### gov.nih.nci.system.proxy.HTTPQuery

The gov.nih.nci.system.proxy.HTTPQuery extends the standard
javax.servlet.http.HttpServlet class. One of its primary functions is to
interpret the query request embedded within a standard HttpRequest
object, and to make the appropriate calls to the caCORE Server. The
results are sent back to the user as an XML or HTML document depending
upon whether the GetXML or GetHTML Servlet request was made.

XQuery-like syntax is used to generate the query. The syntax of the
query is shown below:

> http://{server}/{servlet}?query={returnClass}&{criteria}&
>
> resultCounter={counter}&startIndex={index}&
>
> pageSize={pageSize}&pageNumber={pageNumber}

An example of the query is shown below:

> http://server/servlet/GetXML?query=Gene&Gene\[@symbol=brca\*\]

The value of {servlet} must be either GetXML, or GetHTML, as specified
below in the highlighted portion of the web.xml file. Note that both the
GetXML and GetHTML queries map to the same SDK HTTPQuery Servlet:

![](media/image23.png){width="6.563888888888889in"
height="4.907638888888889in"}

[]{#__RefHeading___Toc144115457 .anchor}Figure 22: XML-HTTP Servlet
Mappings

An outline diagram listing the HttpQuery attributes and methods is shown
below:

![](media/image24.png){width="3.7395833333333335in"
height="3.7368055555555557in"}

[]{#__RefHeading___Toc144115458 .anchor}Figure 23:
gov.nih.nci.system.proxy.HTTPQuery Outline Diagram

Please refer to the *Service Location and Syntax*, XML-HTTP API section
of the caCORE 3.1 *Technical Guide* documentation for more information
on the XML-HTTP query syntax, as well as usage examples.

### gov.nih.nci.common.util.HTTPUtils

As its name implies, the HTTPUtils is a utility, or helper class used by
the HTTPQuery class discussed in the previous section. The HTTPUtils
class provides various methods to generate search criteria from XQuery
like syntax, and also class also provides functionality to generate XML
results.

An outline diagram listing the HttpQuery public methods is shown below:

![](media/image25.png){width="3.1770833333333335in"
height="6.455555555555556in"}

[]{#__RefHeading___Toc144115459 .anchor}Figure 24:
gov.nih.nci.common.util.HTTPUtils Outline Diagram

# Persistence Tier Detail Design

This section details the current SDK persistence design, and describes
opportunities to improve it. Areas covered in this section include:

-   The Persistence Tier within the caCORE SDK Tiered Architecture

-   The Base Delegate Query Interface

-   The Writable DAO Create, Read, Update, Delete (CRUD) Interface

## The Persistence Tier within the caCORE SDK Tiered Architecture

Any system generated by the caCORE SDK is divided into a series of
layers, or tiers[^15] (see Figure 25 below).

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

[]{#__RefHeading___Toc144115460 .anchor}Figure 25: Persistence Tier
within the caCORE SDK Tiered Architecture

While various functional areas are shown in the diagram, the focus of
this section is to what has been termed the "Persistence Tier." The
"Persistence Tier" includes: the Data Source delegation,
Object-Relational Mapping (ORM), and the non-ORM mapping functional
areas highlighted above.

Interaction between the Application Service and the Persistence Tiers
currently occurs via one of the two following "interfaces":

-   Base Delegate Query Interface

-   Writable DAO Create, Read, Update, Delete (CRUD) Interface

Each interface is discussed below.

## Base Delegate Query Interface

The following sequence diagram illustrates the interaction between the
Application Service and Object-Relational Mapping (ORM) Persistence tier
classes (including several Hibernate ORM classes), as implemented via
the Base Delegate Query interface:

![](media/image26.wmf){width="7.245138888888889in"
height="5.458333333333333in"}

[]{#__RefHeading___Toc144115461 .anchor}Figure 26: Persistence Tier
(Base Delegate Query Interface) Sequence Diagram

> The Sequence diagram above provides a structured representation of the
> SDK persistence behavior as a series of sequential steps over time as
> implemented via the Base Delegate Query interface. The diagram also
> illustrates the message passing between various participating SDK
> classes, and how these classes cooperate over time to process a
> gov.nih.nci.common.net.Request object to produce a query result
> returned in the form of a gov.nih.nci.common.net.Response object.
>
> Presentation Tier clients, as well as RDBMS data sources, are omitted
> from the diagram in order to preserve focus, and also due to space
> limitations.
>
> The following sections detail the SDK classes participating in the
> Sequence diagram shown above.

### gov.nih.nci.system.applicationservice.impl.ApplicationServiceBusinessImpl

> The
> gov.nih.nci.system.applicationservice.impl.ApplicationServiceBusinessImpl
> class is a business service object that implements the
> ApplicationService interface, which provides a variety of methods for
> querying the HTTP server.
>
> An outline diagram listing the ApplicationServiceBusinessImpl
> attributes and methods is shown below[^16]:

![](media/image27.png){width="3.5652777777777778in"
height="7.355555555555555in"}

[]{#__RefHeading___Toc144115462 .anchor}Figure 27:
gov.nih.nci.system.ApplicationBusinessImpl Outline Diagram

### gov.nih.nci.common.net.Request

> The gov.nih.nci.common.net.Request class (not shown in the sequence
> diagram due to space limitations) implements a variation of the Data
> Transfer Object pattern[^17], which is used to encapsulate and
> transfer business data across application tiers.
>
> The Request class encapsulates a client's query request details,
> including configuration data to connect to a specified data source,
> the name (type) of the domain object being queried, and the selection
> criteria.
>
> An outline diagram listing the Request attributes and methods is shown
> below:
>
> ![](media/image28.png){width="2.7680555555555557in"
> height="4.29375in"}

[]{#__RefHeading___Toc144115463 .anchor}Figure 28:
gov.nih.nci.common.net.Request Outline Diagram

### gov.nih.nci.common.net.Response

> The gov.nih.nci.common.net.Response class (not shown in the sequence
> diagram due to space limitations) implements a variation of the Data
> Transfer Object pattern[^18], which is used to encapsulate and
> transfer business data across application tiers.
>
> The Response object encapsulates the result of a client's query
> request, including a List of objects (stored in the response
> attribute) that met the query criteria. The type and number of objects
> returned in the list is determined, in part, by the name of the domain
> object stored in the Request domainObjectName attribute and the
> filtering criteria stored in the Request request attribute.
>
> An outline diagram listing the Response attributes and methods is
> shown below:

## ![](media/image29.png){width="2.5104166666666665in" height="3.0180555555555557in"}

[]{#__RefHeading___Toc144115464 .anchor}Figure 29:
gov.nih.nci.common.net.Response Outline Diagram

### gov.nih.nci.system.delegator.BaseDelegate

> The gov.nih.nci.system.delegator.BaseDelegate class implements a
> variation of the Business Delegate pattern[^19]. This pattern strives
> to reduce coupling between presentation-tier clients and business
> services.
>
> In the case of the caCORE SDK, the BaseDelegate class hides the
> underlying implementation details of the query business service (such
> as the lookup and access details of the data access object
> architecture implemented within the persistence tier) from its
> internal client, the ApplicationService
> (ApplicationServiceBusinessImpl) class.
>
> An outline diagram listing the BaseDelegate attributes and methods is
> shown below:
>
> ![](media/image30.png){width="2.59375in"
> height="1.9909722222222221in"}

[]{#__RefHeading___Toc144115465 .anchor}Figure 30:
gov.nih.nci.system.delegator.BaseDelegate Outline Diagram

### gov.nih.nci.system.servicelocator.ServiceLocator

> The gov.nih.nci.system.servicelocator.ServiceLocator class implements
> a variation of the Service Locator pattern[^20]. This pattern reduces
> coupling between presentation-tier clients and business services.
>
> In the case of the caCORE SDK, the ServiceLocator class hides the
> implementation details of the Data Access Object (DAO) lookup and
> access within the SDK persistence tier.
>
> An outline diagram listing the ServiceLocator attributes and methods
> is shown below:
>
> ![](media/image31.png){width="3.2375in" height="3.0972222222222223in"}

[]{#__RefHeading___Toc144115466 .anchor}Figure 31:
gov.nih.nci.system.servicelocator.ServiceLocator Outline Diagram

### gov.nih.nci.system.dao.DAOFactory

> The gov.nih.nci.system.dao.DAOFactory class implements the *Factory
> for Data Access Objects* strategy (see also the Factory Method \[GoF\]
> pattern)[^21], which deals with the problem of creating objects
> (products) without specifying the exact class of object that will be
> created. *Factory Method*, one of the patterns from the Design
> Patterns book, handles this problem by defining a separate method for
> creating the objects, which subclasses can then override to specify
> the derived type of product that will be created.
>
> In the case of the caCORE SDK, the DAOFactory abstract class specifies
> the signature of the getFactory(int whichFactory) method common to all
> caCORE concrete DAO Factory subclasses, including the Object
> Relational Mapping Data Access Object Factory (ORMDAOFactory) class
> discussed in the following section.
>
> An outline diagram listing the DAOFactory attributes and methods is
> shown below:
>
> ![](media/image32.png){width="2.75in" height="1.823611111111111in"}

[]{#__RefHeading___Toc144115467 .anchor}Figure 32:
gov.nih.nci.common.net.Request Outline Diagram

### gov.nih.nci.system.dao.ORMDAOFactory

> The gov.nih.nci.system.dao.ORMDAOFactory object is a concrete subclass
> of the abstract DAOFactory class discussed in the previous section. It
> is responsible for creating Object Relational Mapping (ORM) DAO
> instances. It also implements the query(Request) method specified in
> the parent DAOFactory class.
>
> An outline diagram listing the ORMDAOFactory attributes and methods is
> shown below:
>
> ![](media/image33.png){width="2.9791666666666665in"
> height="2.4159722222222224in"}

[]{#__RefHeading___Toc144115468 .anchor}Figure 33:
gov.nih.nci.system.dao.ORMDAOFactory Outline Diagram

### gov.nih.nci.system.dao.impl.orm.ORMDAOImpl

> The gov.nih.nci.system.dao.impl.orm.ORMDAOImpl class implements the
> Data Access Object (DAO) pattern[^22]. This pattern abstracts and
> encapsulates all access to a given data source. The DAO also manages
> the connection with the data source to obtain and store data.
>
> ORMDAOImpl also implements the query(Request) method. This method
> converts a caCORE gov.nih.nci.common.net.Request into a corresponding
> Hibernate query that returns results from a specified ORM data source.
>
> An outline diagram listing the ORMDAOImpl attributes and methods is
> shown below:
>
> ![](media/image34.png){width="2.9166666666666665in"
> height="2.615972222222222in"}

[]{#__RefHeading___Toc144115469 .anchor}Figure 34:
gov.nih.nci.system.dao.ORMDAOImpl Outline Diagram

### gov.nih.nci.system.dao.impl.orm.ORMConnection

> The gov.nih.nci.system.dao.impl.orm.ORMConnection is a Singleton
> object that creates and manages up to two instances of the Hibernate
> SessionFactory object. This Hibernate object is responsible for
> creating Hibernate Sessions. Threads servicing client requests obtain
> Sessions from the factory.
>
> An outline diagram listing the
> gov.nih.nci.system.dao.impl.orm.ORMConnection attributes and methods
> is shown below:
>
> ![](media/image35.png){width="3.0104166666666665in"
> height="3.216666666666667in"}

[]{#__RefHeading___Toc144115470 .anchor}Figure 35:
gov.nih.nci.system.dao.ORMConnection Outline Diagram

### gov.nih.nci.common.util.NestedCriteria2HQL

> The gov.nih.nci.common.util.NestedCriteria2HQL class primarily
> converts, or translates, a gov.nih.nci.common.util.NestedCriteria into
> a Hibernate HQL org.hibernate.Query, which is an object-oriented
> representation of a Hibernate query obtained by calling
> Session.createQuery().
>
> An outline diagram listing the NestedCriteria2HQL attributes and
> methods is shown below:

![](media/image36.png){width="3.636111111111111in"
height="4.009722222222222in"}

[]{#__RefHeading___Toc144115471 .anchor}Figure 36:
gov.nih.nci.system.dao.ORMConnection Outline Diagram

## Writable DAO Create, Read, Update, Delete Interface

The following sequence diagram illustrates the interaction between the
Application Service and Object-Relational Mapping (ORM) Persistence tier
classes (including several Hibernate ORM classes), as implemented via
the Writable DAO interface.

![](media/image37.wmf){width="7.242361111111111in"
height="5.786111111111111in"}

[]{#__RefHeading___Toc144115472 .anchor}Figure 37: Persistence Tier
(Base Delegate Query Interface) Sequence Diagram

> The Sequence diagram above provides a structured representation of the
> SDK persistence behavior. It is displayed as a series of sequential
> steps over time, as implemented via the Writable DAO CRUD interface.
> The createObject(), updateObject(), and removeObject() all share the
> same basic set of sequential steps, with the exception of the
> Hibernate Session save(), update(), and delete() method invocations.
> The WritableDAO getObjects() method has a slightly different sequence
> of steps, and is shown separately at the bottom of the diagram.
>
> The diagram also illustrates the message passing between various
> participating SDK classes, and how these classes cooperate over time
> to process a gov.nih.nci.common.net.Request object to produce a query
> result returned in the form of a gov.nih.nci.common.net.Response
> object.
>
> Presentation Tier clients, as well as RDBMS data sources, are omitted
> from the diagram in order to preserve focus.
>
> The following sections detail the SDK classes participating in the
> Sequence diagram shown above.

### gov.nih.nci.system.applicationservice.impl.ApplicationServiceImpl

> The gov.nih.nci.system.applicationservice.impl.ApplicationServiceImpl
> class implements the local (server side) instance of the
> ApplicationService[^23] interface (in contrast to the
> gov.nih.nci.system.comm.client.ApplicationServiceClientImpl class,
> which implements the remote (client side) instance).
>
> The ApplicationServiceImpl class also acts as a wrapper class,
> forwarding the responsibility for handling requests to the
> ApplicationServiceBusinessImpl class; i.e., it just calls methods from
> the ApplicationServiceBusinessImpl class without doing any work
> itself.
>
> A class diagram illustrating the relationships between the various
> ApplicationService interface related classes is shown below

## ![](media/image38.wmf){width="7.378472222222222in" height="3.96875in"}

[]{#__RefHeading___Toc144115473 .anchor}Figure 38: ApplicationService
Interface and Related Classes Diagram

> An outline diagram listing the ApplicationServiceImpl attributes and
> methods is shown below:

## ![](media/image39.png){width="4.057638888888889in" height="5.175694444444445in"}

[]{#__RefHeading___Toc144115474 .anchor}Figure 39:
gov.nih.nci.system.dao.ORMConnection Outline Diagram

## 

### gov.nih.nci.system.dao.WritableDAO

> The gov.nih.nci.system.dao.WritableDAO class implements the Data
> Access Object (DAO) pattern[^24], which abstracts and encapsulates all
> access to a given data source. The DAO also manages the connection
> with the data source to obtain and store data.
>
> The WritableDAO implements Create, Read, Update, and Delete (CRUD)
> functionality for those domain objects managed via the Hibernate
> object/relational persistence and query service.
>
> An outline diagram listing the WritableDAO attributes and methods is
> shown below:
>
> ![](media/image40.png){width="2.46875in"
> height="2.5416666666666665in"}

[]{#__RefHeading___Toc144115475 .anchor}Figure 40:
gov.nih.nci.system.dao.WritableDAO Outline Diagram

### gov.nih.nci.system.servicelocator.ServiceLocator

> Briefly, the gov.nih.nci.system.servicelocator.ServiceLocator class
> implements a variation of the Service Locator pattern[^25], which
> reduces coupling between presentation-tier clients and business
> services.
>
> The ServiceLocator class was already discussed in the earlier
> [ServiceLocation](#gov.nih.nci.system.servicelocator.servicelocator)
> section; please refer to this section for more information.

### gov.nih.nci.system.dao.impl.orm.ORMConnection

> The gov.nih.nci.system.dao.impl.orm.ORMConnection is a Singleton
> object that creates and manages up to two instances of the Hibernate
> SessionFactory object, which, in turn, is responsible for creating
> Hibernate Sessions. Threads servicing client requests obtain Sessions
> from the factory.
>
> The ORMConnection class was already discussed in the earlier
> [ORMConnection](#gov.nih.nci.system.dao.impl.orm.ormconnection)
> section; please refer to this section for more information.

# Configuration/Deployment Considerations

## Property/Configuration Files

  ---------- -------------------------------------------- ------------------------------ -----------------------
  **New (\*) **File Location**                            **File Name**                  **Description of
  or                                                                                     Change**
  Modified                                                                               
  (#)**                                                                                  

  \#         gov.nih.nci.system.dao                       WriteableDAO.java              Modify class to throw
                                                                                         PesistenceException
                                                                                         cast as an
                                                                                         ApplicationException.

  \#         gov.nih.nci.system.comm.server               ApplicationServiceServerImpl   Modify class to throw
                                                                                         sub classed exceptions
                                                                                         of
                                                                                         ApplicationException.

  \#         gov.nih.nci.system.comm.client               ApplicationServiceClientImpl   Modify class to throw
                                                                                         sub classed exceptions
                                                                                         of
                                                                                         ApplicationException.

  \#         gov.nih.nci.system.comm.client               ClientSession                  Modify class to throw
                                                                                         sub classed exceptions
                                                                                         of
                                                                                         ApplicationException.

  \#         gov.nih.nci.system.applicationservice.impl   ApplicationServiceImpl         Modify class to throw
                                                                                         sub classed exceptions
                                                                                         of
                                                                                         ApplicationException.

  \#         gov.nih.nci.system.server.mgmt               SecurityEnabler                Modify class to throw
                                                                                         sub classed exceptions
                                                                                         of
                                                                                         ApplicationException.

  \*         gov.nih.nci.system.applicationservice        SecurityException              New Subclass of
                                                                                         ApplicationException

  \*         gov.nih.nci.system.applicationservice        AuthenticationException        New Subclass of
                                                                                         SecurityException

  \*         gov.nih.nci.system.applicationservice        AuthorizationException         New Subclass of
                                                                                         SecurityException

  \*         gov.nih.nci.system.applicationservice        DAOException                   Modified Subclass of
                                                                                         ApplicationException

  \*         gov.nih.nci.system.applicationservice        CreateException                New Subclass of
                                                                                         DAOException

  \*         gov.nih.nci.system.applicationservice        QueryException                 New Subclass of
                                                                                         DAOException

  \*         gov.nih.nci.system.applicationservice        UpdateException                New Subclass of
                                                                                         DAOException

  \*         gov.nih.nci.system.applicationservice        DeleteException                New Subclass of
                                                                                         DAOException

  \*         gov.nih.nci.system.applicationservice        SessionException               New Subclass of
                                                                                         DAOException

  \*         gov.nih.nci.system.applicationservice        RollbackException              New Subclass of
                                                                                         DAOException

                                                                                         
  ---------- -------------------------------------------- ------------------------------ -----------------------

## Deployment Considerations

N/A.

# Resources

This section contains a list of recommended reading materials,
resources, and references that can be useful for becoming familiar with
the concepts contained within this guide.

## Technical Manuals/Articles

-   Exceptional Practices:
    <http://java.sun.com/developer/technicalArticles/Programming/exceptions/>.

-   Exceptional Practices, Part 2:
    <http://java.sun.com/developer/technicalArticles/Programming/exceptions2/>.

-   javax.persistence class hierarchy:
    http://java.sun.com/javaee/5/docs/api/javax/persistence/package-tree.html.

-   See also the java.lang.Throwable API regarding the Exception
    Chaining facility.

## Core J2EE Patterns

-   [Core J2EE Patterns: Best Practices and Design
    Strategies](http://www.amazon.com/exec/obidos/ASIN/0130648841/corej2eepatte-20),
    [Deepak Alur, John Crupi and Dan
    Malks](http://java.sun.com/blueprints/corej2eepatterns/AboutTheAuthors.html).
    Publisher: Prentice Hall / Sun Microsystems Press. ISBN:0130648841;
    1st edition (June 26, 2001).

> ![](media/image41.jpeg){width="1.0416666666666667in"
> height="1.3520833333333333in"}

## Hibernate Reference Manual

-   Hibernate Reference Manual:
    <http://www.hibernate.org/hib_docs/v3/reference/en/html/>.

## caCORE SDK Documentation

-   Chapter 3, *Interacting with caCORE,* of the caCORE 3.1 *Technical
    Guide*.

[^1]: The **cabio example system** provided with the caCORE SDK is used
    in our discussion for the sake of simplicity. However, the ideas
    discussed in this document apply to any caCORE-like system generated
    via the SDK.

[^2]: See the Resource section at the end of this document for a list of
    references to Exception Handling related articles.

[^3]: See
    http://java.sun.com/javaee/5/docs/api/javax/persistence/package-tree.html.

[^4]: As noted in the java.lang.Throwable API, this feature is also
    known as the chained exception facility, as the cause can, itself,
    have a cause, and so on. This leads to a \"chain\" of exceptions,
    each caused by another.

    One reason that a throwable may have a cause is that the class that
    throws it is built atop a lower layered abstraction, and an
    operation on the upper layer fails due to a failure in the lower
    layer. It would be bad design to let the throwable thrown by the
    lower layer propagate outward, as it is generally unrelated to the
    abstraction provided by the upper layer. Further, doing so would tie
    the API of the upper layer to the details of its implementation,
    assuming the lower layer\'s exception was a checked exception.
    Throwing a \"wrapped exception\" (i.e., an exception containing a
    cause) allows the upper layer to communicate the details of the
    failure to its caller without incurring either of these
    shortcomings. It preserves the flexibility to change the
    implementation of the upper layer without changing its API (in
    particular, the set of exceptions thrown by its methods).

    A second reason that a throwable may have a cause is that the method
    that throws it must conform to a general-purpose interface that does
    not permit the method to throw the cause directly. For example,
    suppose a persistent collection conforms to the Collection
    interface, and that its persistence is implemented atop java.io.
    Suppose the internals of the put method can throw an IOException.
    The implementation can communicate the details of the IOException to
    its caller while conforming to the Collection interface by wrapping
    the IOException in an appropriate unchecked exception. (The
    specification for the persistent collection should indicate that it
    is capable of throwing such exceptions.)

[^5]: This diagram has been borrowed from the caCORE SDK 1.1
    Programmer's Guide, page 8. For a more detailed discussion of the
    overall caCORE architecture, please refer to the Programmer's Guide,
    Chapter 2: *NCICB caCORE Infrastructure*, page 5.

[^6]: For an overview of the query interaction between the Application
    Service and Persistence Tiers, please refer to the Persistence
    Detail Design section of this document.

[^7]: A Java client is used in the diagram because it provides access to
    all the query types due to the fact that the SDK itself is also
    written in Java. Other types of clients, such as XML/HTTP or Web
    Service clients, can also be used to query domain objects, but they
    do not provide access to all four (4) query types. More information
    is provided in the following sections that discuss the four primary
    query interfaces.

[^8]: For more information regarding Hibernate's Detached Criteria,
    please refer to chapter [14: HQL: The Hibernate Query
    Language](http://www.hibernate.org/hib_docs/v3/reference/en/html/queryhql.html)
    of the [Hibernate Reference
    Documentation](http://www.hibernate.org/hib_docs/v3/reference/en/html/).

[^9]: For more information regarding Hibernate's HQL, please refer to
    chapter [15: Criteria
    Queries](http://www.hibernate.org/hib_docs/v3/reference/en/html/querycriteria.html)
    of the [Hibernate Reference
    Documentation](http://www.hibernate.org/hib_docs/v3/reference/en/html/).

[^10]: See the *Creational Patterns -- Java Factory Pattern* page for
    more information regarding the Java Factory Pattern:
    <http://www.allapplabs.com/java_design_patterns/factory_pattern.htm>.

[^11]: The class outline and diagram essentially provide the same data,
    i.e., a listing of attributes and methods found within the class.

[^12]: The WS-I Basic Profile provides a set of non-proprietary
    specifications and implementation guidelines enabling
    interoperability between diverse systems. More information about
    WS-I compliance is available at
    [http://www.ws-i.org](http://www.ws-i.org/).

[^13]: For more information about Axis, visit
    <http://ws.apache.org/axis/>.

[^14]: For more information, please refer to the Wikipedia
    Representational State Transfer (REST) page:
    <http://en.wikipedia.org/wiki/Representational_State_Transfer>.

[^15]: This diagram has been borrowed from the caCORE SDK 1.1
    Programmer's Guide, page 8. For a more detailed discussion of the
    overall caCORE architecture, please refer to the Programmer's Guide,
    Chapter 2: *NCICB caCORE Infrastructure*, which starts on page 5.

[^16]: The class outline and diagram essentially provide the same data
    (i.e. a listing of attributes and methods found within the class).
    While the class diagram more closely conforms to the UML
    specification, the outline format is used here as it (arguably)
    offers improved readability with its use of colors, symbols, and
    icons.

[^17]: See the *Core J2EE Patterns -- Data Transfer Object* page for
    more information on the context, problem, forces, and solution
    associated with the Data Transfer Object pattern:
    <http://java.sun.com/blueprints/corej2eepatterns/Patterns/TransferObject.html>.

[^18]: See the *Core J2EE Patterns -- Data Transfer Object* page for
    more information on the context, problem, forces, and solution
    associated with the Data Transfer Object pattern:
    <http://java.sun.com/blueprints/corej2eepatterns/Patterns/TransferObject.html>.

[^19]: See the *Core J2EE Patterns - Business Delegate* page for more
    information on the context, problem, forces, and solution associated
    with the Business Delegate pattern:
    <http://java.sun.com/blueprints/corej2eepatterns/Patterns/BusinessDelegate.html>.

[^20]: See the *Core J2EE Patterns -- Service Locator* page for more
    information on the context, problem, forces, and solution associated
    with the Service Locator pattern:
    <http://java.sun.com/blueprints/corej2eepatterns/Patterns/ServiceLocator.html>.

[^21]: See the *Implementing Factory for Data Access Objects Strategy*
    section of the *Core J2EE Patterns -- Data Access Object* page for
    more information on the context, problem, forces, and solution
    associated with the Data Access Object Factory pattern:
    <http://java.sun.com/blueprints/corej2eepatterns/Patterns/DataAccessObject.html>.
    See also the Factory Method Pattern:
    <http://en.wikipedia.org/wiki/Factory_method_pattern>.

[^22]: See the *Core J2EE Patterns -- Data Access Object* page for more
    information on the context, problem, forces, and solution associated
    with the Data Access Object pattern:
    <http://java.sun.com/blueprints/corej2eepatterns/Patterns/DataAccessObject.html>

[^23]: The ApplicationService interface is an abstract class that
    combines the BaseDelegate Query and the WritableDAO CRUD
    functionality, again suggesting that the two persistence paths
    should be refactored and combined.

[^24]: See the *Core J2EE Patterns -- Data Access Object* page for more
    information on the context, problem, forces, and solution associated
    with the Data Access Object pattern:
    <http://java.sun.com/blueprints/corej2eepatterns/Patterns/DataAccessObject.html>

[^25]: See the *Core J2EE Patterns -- Service Locator* page for more
    information on the context, problem, forces, and solution associated
    with the Service Locator pattern:
    <http://java.sun.com/blueprints/corej2eepatterns/Patterns/ServiceLocator.html>.