Domain Model

Owned by bcarlsen (Unlicensed)
Jun 01, 2015
3 min read

Overview

Documents the terminology server domain model.

This is a placeholder page with basic information and will be developed to fully document this aspect of the system.

Details

The terminology model is based on the capabilities of RRF. 

Model objects contain annotations for multiple frameworks and integrations that add a significant amount of functionality out of the box. These include:

  • JPA annotations define the persistence model.  In general, domain objects are independently managed and do not automatically load or save connected data. There are two notable exceptions to this at the concept and description level. As a concept requires at least one description and one parent, and that description requires at least one language refset entry, adding the concept and these associated elements can be handled as a unit operation.
  • Hibernate-Search annotations define the indexing model. In general, all identifiers and text based fields are all indexed. Lucene supports field-based searching and the set of annotations in this server supports a default field for searching across all text fields simultaneously.
  • Hibernate Envers annotations define the auditing model. In general, we audit concepts and all related components in the graph.
  • JAXB annotations define the XML serialization model, including how to avoid infinite recursion when rendering the model that includes relationships.

 

Model objects have both JPA assigned identifiers as well as terminology assigned identifiers. This supports the ability to define multiple simultaneous copies of the same domain object in the same terminology at the same time – thus supporting various types of dual independent review and conflict resolution. It also means there is delayed binding in which objects can be connected to each other via JPA identifiers and terminology assigned identifiers do not actually have to be assigned until release time.

TODO: ER/class diagram

TODO: explain domain objects "in gneeral" 

TODO: discuss transitive closure, tree positions, and subset ancestor computation.

Design Principles

Some important principles used in the design of domain objects include

  • Domain objects are connected to each other through identifiers, with referential integrity enforced.  For example, there is no way to create a description that is linked to a concept that does not exist.
  • When saving domain objects, cascade is only sparingly used among the Concept, Description, Relationship, and LanguageRefSetMember objects.
  • Java bean conventions are used with corresponding get/set methods for all fields.  Get/set methods work with object references and do not copy data structures (e.g. a getList method will return the actual list, not a copy of the list).
  • For collection fields, add/remove methods are also provided.
  • Equals/Hashcode are based on a collection of fields which must be the same (see the ModelUnit test suites for what these fields are for each object).
    • A change in an equality field causes equals behavior to change.
    • A change in a non-equality field cases equals behavior to remain the same.
    • Identity fields are different than equality fields - for example, the case significance of a description is not part of its identity.  The ID handler is used to compute identity based on an object.  Equality is used to determine whether an object has changed.  Certain fields are always ignored in these computations, like effective time.
    • Equality generally involves equality of the "parent" object (e.g. two descriptions are equal only if their concept is equal as well).
    • Where XML serialization uses XmlTransient, the equality of the connected object is based on terminology id.
  • All domain objects have a copy constructor.  
    • In some cases a "deep copy" is used to also copy the nested domain model data structures
  • Xml Serialization is supported for all domain model objects.
    • To avoid cycles in the object graph, whenever a lower-level in the graph refers to a description or concept, a "reference" to that description or concept is serialized instead of the entire thing.  The reference includes the id, terminologyId, and the name.  It is assumed that concepts/descriptions connected to domain objects always have the same "terminology" and "terminologyVersion" as the domain object itself. 

 

TODO: Discuss appropaches to maintaining transitive closure

TODO: discuss

Updating Model Objects

When adding or changing model objects all cross-cutting concerns are addressed and verified with unit tests..  This includes:

  • Model annotations (including JPA, hibernate-search, envers, JAXB, and JSON)
    • Including @XmlTransient and related handling.
  • Admin tools (updatedb, loader, reindex)
  • Equals/hashcode methods
  • Copy constructor
  • toString()
  • Getter/setter for all fields (with correct naming conventions).
  • n/a