Table of Contents

  1. Preface
  1. Introduction
    1. Preface
    1. First Topaz Application
    1. Working with Associations
    1. Working with Collections
    1. Working with inheritance
    1. Working with Blobs
    1. Working with Text Search
  1. Architecture
    1. Overview
    2. Object States
    3. Object State Transitions
  1. Configuration
    1. Configuring Stores
    2. Configuring Application Metadata
    1. Annotations
  1. Persistent Classes
    1. A simple POJO example
    2. Implementing inheritance
    3. Implementing equals() and hashCode()
    4. Dynamic models
    5. Binder
  1. Property Mapping
    1. Overview
    2. Types of Mapping
    3. Handling cardinality
    4. Rdf Collections and Containers
    5. Mapping values
    6. Blobs
  1. Grouping Concepts
    1. Entity
    2. Inheritance
    3. Containment
    4. Association
  1. Working with Objects
    1. Topaz object states
    2. Making objects persistent
    3. Loading an object
    4. Executing queries
    5. Modifying persistent objects
    6. Modifying detached objects
    7. Deleting persistent objects
    8. Flushing the Session
    9. Transitive persistence
    10. Using metadata
Error: Page Topaz/Manual/Section09 does not exist
Error: Page Topaz/Manual/Section10 does not exist
  1. Object Query Language
    1. Query Structure
    2. Simple Examples
    3. Query Details
    4. Advanced Features
    5. Specification
    6. Notes
Error: Page Topaz/Manual/Section12 does not exist
Error: Page Topaz/Manual/Section13 does not exist
Error: Page Topaz/Manual/Section14 does not exist
Error: Page Topaz/Manual/Section15 does not exist
Error: Page Topaz/Manual/Section16 does not exist
Error: Page Topaz/Manual/Section17 does not exist

Architecture

Overview

A higher level architecture diagram of Topaz is as follows:

  • Transaction
    • All work that an application does is in the transaction scope.
    • A transaction is started by calling the beginTransaction method on the Session.
    • Transaction wraps a JTA transaction object and does 2-Phase commits across both the TripleStore and BlobStore
  • Session
    • A single-threaded unit of work
    • A session is created by calling the openSession method on the SessionFactory
    • Only a single transaction can be active at a time on a Session
    • Maintains a cache of all Persistent Objects and Deleted Objects
    • WARN: See Object State Tracking below. All modifications an application makes to Persistent Objects are reflected in the TripleStore.
  • SessionFactory
    • Contains all configuration for Topaz
    • Supports multi-threaded access
    • validate method must be called after all configuration so that ClassMetadata objects needed by Session are created

Object States

Topaz offers state management for objects. This means the applications only need to worry about letting Topaz know about the objects that are to be persisted. Topaz tracks the changes made to the objects and updates the triple-store and blob-store as needed.

Transient Objects

An object is transient if it has just been instantiated using the new operator, and it is not associated with a Topaz Session. It has no persistent representation in the triple-store and no identifier value has been assigned. Transient instances will be destroyed by the garbage collector if the application doesn't hold a reference anymore. Use the Topaz Session to make an object persistent.

Persistent Objects

A persistent instance has a representation in the triple-store and an identifier value. It might just have been saved or loaded, however, it is by definition in the scope of a Session. Topaz will detect any changes made to an object in persistent state and synchronize the state with the database when the associated Transaction on this Session is committed.

WARN: This may at first be a surprise to anyone expecting to selectively and pro-actively persist changes. However when the object graph is complex, you would find that letting Topaz track the changes to be committed automatically to be more advantageous. There are multiple options in Topaz to fine tune this. See evict() or refresh() methods on Session for example. Similarly controlling Cascade options on associations especially how delete() cascades is a way to fine-tune.

Detached Objects

A detached instance is an object that has been persistent, but its Session has been closed. The reference to the object is still valid, of course, and the detached instance might even be modified in this state. A detached instance can be reattached to a new Session at a later point in time, making it (and all the modifications) persistent again.

Deleted Objects

A sub-state of Persistent. All objects marked for removal from the database are in this state. Objects are removed from the database only when the unit of work is completed.

Object State Transitions