OTM (Object/Triple Mapping)

Place holder for OTM documentation. Currently used for tracking development activities.

To do list

  1. Support for java.util.Map
  2. Cursors for query results

Otm Annotations

@Entity at Class level
   ''   ==> rdf:type
   name ==> defaults to class name
   model ==> the storage model; defaults to super-class

@Predicate at Field level
    ''  ==> predicate-uri; defaults to uriPrefix + field-name
    inverse ==> defaults to false
    model ==> the storage model; defaults to class
    dataType ==> defaults based on field type
    colType  ==> defaults to direct predicate with no min cardinality restriction ;
                 options are predicate, rdfList, rdfBag, rdfSeq, rdfAlt
    notOwned ==> defaults to false
    type ==> property type; defaults based on rest of the definition
             options are data-property or object-property
    fetch ==> for associations; defaults to lazy
             options are lazy or eager
    cascade ==> for associations; defaults to 'all'
              'all' implies saveOrUpdate, delete, flush, evict, refresh; 
              deleteOrphan - is for orphan association delete not implied by 'all'

@Id at Field level

@GeneratedValue at Field level
    generator ==> IF id-generation is desired, name of generator (e.g. "GUID")
    baseUri ==> for unique-id generation, uri prefix to use when creating ids

@UriPrefix at Class level
   '' ==> base-uri; no defaults
   alias ==> no defaults

@Alias at Global/Class level
    '' ==> uri
    alias ==> no defaults

@View at Class level
   '' ==> OQL query string for the view

@SubView at Class level

@Embeddable at Class level

@Embedded at Field level

@PredicateMap at Field level

@ValueMap at Field level (todo)
  key ==> key field from association

@Blob at Field level

@Projection at Field level for Views
   var ==> OQL projection var name 

To sum-up, class-level annotations are:
  1. One of (@Entity or @Embeddable or @View or @SubView)
  2. @UriPrefix
  3. @Alias
  

and the field-level annotations are:
   1. One of (@Predicate or @Embedded or @Id or @PredicateMap, @Blob, @Projection)
   2. @GeneratedValue

Domain models and metadata

Implementing the domain model

  1. Transparent automated persistence
    1. no special class or interface needed for persistence
    2. persistent classes can be re-used outside the context of persistence
    3. persistent classes are not aware of the underlying persistence store or aware that they are being persisted
  2. Writing POJOs and persistent entity classes
    1. POJO best practices
    2. No argument constructor
    3. get/set property accessor methods
    4. any additional business methods
  3. Implementing POJO associations
    1. Same way as other properties
  4. Adding logic to accessor methods
    1. validation etc. can be defined on set methods by the app
    2. direct field access can be configured to by-pass during load from store (todo)

Object/Triple mapping metadata

  1. xml config (todo?)
  2. annotations
  3. global config (todo - specify default model/graph etc.)
  4. global annotation metadata (todo - package-info.java or after imports in a class)
  5. Manipulating metadata at runtime
    1. make metadata mutable (why? todo?)
    2. generic/meta apps can access object values directly from Mapper

Alternative entity representations

3 modes of operation:

  • POJO - domain model implementation based on POJOs
  • MAP - no java classes; entities represented with HashMaps?; allows quick prototyping (todo)
  • DOM4J - no java classes; entities as XML elements; useful for import/export and xslt (todo)
  1. Creating dynamic applications (todo)
    1. configure an entity (xml etc.) and set props in a Map and access via Session with entity name
    2. mixing static and dynamic modes
    3. mapping a class several times - with different entity names
  1. Representing data in XML (todo)
    1. dom4j session returs dom Element for get/load etc.; tree configurable

Mapping persistent classes

Understanding entities and value types

1. Fine-grained domain models

  1. crude definition : more classes than rdf:type
  2. properties can be grouped and added to an embedded class (eg. DC for dc properties)

2. Defining the concept

  1. an object of entity type has its own id/subject-uri
  2. an object of value type has no id/subject-uri of its own (eg. DC or Address or java.util.Date)

3. Identifying entities and value types

  1. avoid shared references to value types
  2. life-cycle of a value type is bound to its owning entity instance
  3. entity classes must have an id/subject-uri property

Mapping entities with identity

1. Understanding identity and equality

  1. the == operator for instance equality
  2. equals() method for app level equality
  3. id/subject-uri identifies resources in triple-store

2. Handling triple-store identity

  1. exposed via the identifier property of entities
  2. should not change the value of identifier property (set once at load/create)

Class mapping options

1. Dynamic ITQL/SPARQL generation

  1. static/pre-cached/non-dynamic CRUD statements (todo)
  2. dirty check and skipping unmodified properties for updates (todo)

2. Making an entity immutable (todo)

  1. POJO is immutable if no setter method - all values set in constructor
  2. load from store needs to do direct field access

3. Naming entities for querying

  1. by default class name without the package prefix is imported into namespace
  2. for conflict resolution add an override (todo define @Entity())

4. Fine-grained models and mapping

  1. all properties are persisted by default except the ones with 'transient' keyword
  2. customize access-type : field|property|noop|custom.Class (todo)
  3. Using derived properties
    1. eg. @Formula("TOTAL + TAX_RATE * TOTAL) - ITQL/SPARQL support??? (todo)
    2. generated properties (eg. lastModified) - ITQL resolver??? (todo)
  4. mapping @Embedded/@Embeddable components
    1. use @AttributeOverrides? in entity class to change/define @Predicate (todo)
    2. back pointer from embedded component to parent via @Parent (todo)

Inheritence and custom types

Mapping class inheritence

  1. rdf:type identifies the class. Most specific rdf:type mapping defines the sub-class
  2. you can define an entity without an rdf:type but there is no sub-classing support

Data type and Serializers

  1. Defaults for basic java types corresponds to equivalent xsd types
  2. Untyped literals can be defined or an override can be specified
  3. Users can define new data types and register Serializers
  4. Supporting blobs

Mapping collections and associations

  1. collections must be initialized at declaration time; not in a constructor.
  2. use generics for the element type.
  3. all collections are stored as sets in the store
  4. support for rdf:list, rdf:bag etc.
  5. sorting of collections (todo)
  6. collections of componet/embedded classes
  7. no special syntax for associations; non embedded classes with no serializers are considered an assoication
  8. @Inverse to represent an inverse association (ie. the associated class references this)
  9. cascading of updates/deletes/merges

Advanced entity association mapping

  1. transparent indirect associations via a blank node (rdf:List, rdf:bag etc.)
  2. Mapping maps (todo @MapKey? - key defaults to @Id)
  3. polymorphic associations and collections - lazy loads creats only the super-class

Store level options

  1. provide options to specify custom CUD (todo)
  2. constraints. @unique @check @notnull (todo)