Overview
Documents the terminology server domain model.
...
The terminology model is based on the capabilities of RF2, including individual classes for each of the supported refset types. Some awkwardness in RF2 prevents an exact alignment because referential integrity constraints between certain refset types (like Association Reference) can involve either description or concept identifiers and thus require splitting into multiple objects so that standard foreign-key constraints can be properly implemented. Additionally, the The model collapses the “extended map” and “complex map” types into a single internal data type with functionality sufficient to cover both cases.
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.
...
TODO: ER/class diagram
TODO: explain general features (e.g. of the "component" layer).TODO: explain concepts, descriptions, language refset, relationships (inferred/stated), transitive relationships, and "refset" members in general
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
Updating Model Objects
When adding or changing model objects all cross-cutting concerns are addressed. This includes:
- model annotations (including JPA, hibernate-search, envers, JAXB, and JSON)
- unit tests
- admin tools (updatedb, loader, reindex)
- Equals/hashcode methods
- Copy constructor
- toString()
- Getter/setter for all fields (with correct naming conventions).
...