Commit ad70c0b2 authored by Jörg Richter's avatar Jörg Richter

Add more Core apidocs (#375)

parent db1cc8d9
Pipeline #10649 passed with stages
in 11 minutes and 21 seconds
......@@ -9,7 +9,8 @@ import java.util.List;
/**
* ### FIXDOC: Specification of an association -- A n-ary connection between topics and other associations.
* An association with 2 ends. At each end can be a {@link DMXObject}, that is either a {@link Topic} or another
* {@link Assoc}.
*
* @author <a href="mailto:jri@deepamehta.de">Jörg Richter</a>
*/
......
......@@ -2,6 +2,14 @@ package systems.dmx.core;
/**
* An <i>association</i> at the end of an {@link Assoc}.
* <p>
* An <code>AssocPlayer</code> has an {@link Assoc} and a role type. The role type expresses the role the Assoc
* plays in the association.
* <p>
* The assoc (player) is referred to by ID. The role type is referred to by URI.
*/
public interface AssocPlayer extends Player {
Assoc getAssoc();
......
......@@ -4,6 +4,9 @@ import systems.dmx.core.model.AssocTypeModel;
/**
* Part of DMX's type system, like a class whose instances are {@link Assoc}s.
*/
public interface AssocType extends DMXType {
// === Updating ===
......
......@@ -5,8 +5,9 @@ import systems.dmx.core.model.CompDefModel;
/**
* Definition of an association between 2 topic types -- part of DMX's type system,
* like an association in a class diagram. Used to represent both, aggregations and compositions. ### FIXDOC
* A composition definition of a <i>parent type</i> and a <i>child type</i> -- part of DMX's type system.
* <p>
* The parent type is either a {@link TopicType} or an {@link AssocType}. The child type is always a {@link TopicType}.
*
* @author <a href="mailto:jri@deepamehta.de">Jörg Richter</a>
*/
......
......@@ -9,6 +9,14 @@ import java.util.List;
/**
* The (abstract) base class of both, {@link Topic} and {@link Assoc}.
* <p>
* A <code>DMXObject</code> has 5 parts: an <b>ID</b>, an <b>URI</b>, a <b>type URI</b>, a {@link SimpleValue}, and,
* in case of a <i>composite</i> DMXObject, a (recursive) collection of {@link ChildTopics} objects.
* <p>
* <code>DMXObject</code> provides methods for updating, deleting, and traversal alongside associations.
*/
public interface DMXObject extends Identifiable, JSONEnabled {
......
......@@ -7,6 +7,14 @@ import java.util.Collection;
/**
* The (abstract) base class of both, {@link TopicType} and {@link AssocType}.
* <p>
* Besides the parts derived from {@link Topic} a <code>DMXType</code> has 3 parts: a <b>data type</b>, a
* collection of <b>Composition Definitions</b> ({@link CompDef}), and a {@link ViewConfig}.
* <p>
* Types are referred to by <b>type URI</b>.
*/
public interface DMXType extends Topic, Iterable<String> {
......
......@@ -4,6 +4,12 @@ import systems.dmx.core.model.PlayerModel;
/**
* A <code>Player</code> represents one of the 2 {@link Assoc} ends.
* <p>
* A <code>Player</code> has a {@link DMXObject} and a role type. The role type expresses the role the DMXObject
* plays in the association.
*/
public interface Player extends JSONEnabled {
long getId();
......
......@@ -5,7 +5,7 @@ import systems.dmx.core.model.TopicModel;
/**
* Specification of a topic -- DMX's central data object.
* A topic -- DMX's central data object.
*
* @author <a href="mailto:jri@deepamehta.de">Jörg Richter</a>
*/
......
......@@ -2,6 +2,14 @@ package systems.dmx.core;
/**
* A <i>topic</i> at the end of an {@link Assoc}.
* <p>
* A <code>TopicPlayer</code> has a {@link Topic} and a role type. The role type expresses the role the Topic
* plays in the association.
* <p>
* The topic (player) is referred to either by ID or URI. The role type is referred to by URI.
*/
public interface TopicPlayer extends Player {
Topic getTopic();
......
......@@ -5,9 +5,7 @@ import systems.dmx.core.model.TopicTypeModel;
/**
* Specification of a topic type -- part of DMX's type system, like a class.
*
* @author <a href="mailto:jri@deepamehta.de">Jörg Richter</a>
* Part of DMX's type system, like a class whose instances are {@link Topic}s.
*/
public interface TopicType extends DMXType {
......
......@@ -10,8 +10,6 @@ import systems.dmx.core.model.ViewConfigModel;
* <p>
* Config topics can be accessed by their type URI.
* A view config can contain only one config topic with a certain type URI.
*
* @author <a href="mailto:jri@deepamehta.de">Jörg Richter</a>
*/
public interface ViewConfig {
......
......@@ -3,7 +3,10 @@ package systems.dmx.core.model;
/**
* Collection of the data that makes up an {@link Assoc}.
* The data that underly an {@link Assoc}.
* <p>
* An <code>AssocModel</code> can also be used to provide the data for an association <i>create</i> or <i>update</i>
* operation. To instantiate an <code>AssocModel</code> use the {@link ModelFactory}.
*
* @author <a href="mailto:jri@deepamehta.de">Jörg Richter</a>
*/
......
......@@ -3,13 +3,7 @@ package systems.dmx.core.model;
/**
* An association-end of an association.
* <p>
* A AssocPlayerModel object is a pair of an association ID and a role type URI.
* <p>
* Assertion: both, the association ID and the role type URI are set.
* <p>
* In the database a role type is represented by a topic of type "dmx.core.role_type".
* The data that underly an {@link AssocPlayer}.
*/
public interface AssocPlayerModel extends PlayerModel {
}
......@@ -3,7 +3,10 @@ package systems.dmx.core.model;
/**
* Data that underlies a {@link AssocType}.
* The data that underly an {@link AssocType}.
* <p>
* A <code>AssocTypeModel</code> can also be used to provide the data for an association type <i>create</i> or
* <i>update</i> operation. To instantiate an <code>AssocTypeModel</code> use the {@link ModelFactory}.
*
* @author <a href="mailto:jri@deepamehta.de">Jörg Richter</a>
*/
......
......@@ -7,10 +7,7 @@ import java.util.List;
/**
* A recursive composite of key/value pairs. ### FIXDOC
* <p>
* Keys are strings, values are non-null atomic (string, int, long, double, boolean)
* or again a <code>ChildTopicsModel</code>. ### FIXDOC
* The data that underly a {@link ChildTopics} object.
*/
public interface ChildTopicsModel extends JSONEnabled, Iterable<String> {
......
......@@ -3,10 +3,7 @@ package systems.dmx.core.model;
/**
* Definition of an association between a parent type and a child type -- part of DMX's type system;
* like a composition/aggregation in an UML class diagram.
* <p>
* The child type is a topic type. The parent type is either a topic type or an association type.
* The data that underly a {@link CompDef}.
*
* @author <a href="mailto:jri@deepamehta.de">Jörg Richter</a>
*/
......
......@@ -5,6 +5,9 @@ import systems.dmx.core.JSONEnabled;
/**
* The data that underly a {@link DMXObject}.
*/
public interface DMXObjectModel extends Identifiable, JSONEnabled, Cloneable {
// --- ID ---
......
......@@ -4,6 +4,9 @@ import systems.dmx.core.JSONEnabled;
/**
* The data that underly a {@link Player}.
*/
public interface PlayerModel extends JSONEnabled, Cloneable {
long getId();
......
......@@ -2,6 +2,14 @@ package systems.dmx.core.model;
/**
* The data that underly a {@link Topic}.
* <p>
* A <code>TopicModel</code> can also be used to provide the data for a topic <i>create</i> or <i>update</i>
* operation. To instantiate a <code>TopicModel</code> use the {@link ModelFactory}.
*
* @author <a href="mailto:jri@deepamehta.de">Jörg Richter</a>
*/
public interface TopicModel extends DMXObjectModel {
TopicModel clone();
......
......@@ -3,15 +3,7 @@ package systems.dmx.core.model;
/**
* A topic-end of an association.
* <p>
* A TopicPlayerModel object is a pair of a topic reference and a role type reference.
* The topic is refered to either by its ID or URI.
* The role type is refered to by its URI.
* <p>
* Assertion: both, the topic reference and the role type reference are set.
* <p>
* In the database a role type is represented by a topic of type "dmx.core.role_type".
* The data that underly a {@link TopicPlayer}.
*/
public interface TopicPlayerModel extends PlayerModel {
......
......@@ -3,7 +3,10 @@ package systems.dmx.core.model;
/**
* Data that underlies a {@link TopicType}.
* The data that underly a {@link TopicType}.
* <p>
* A <code>TopicTypeModel</code> can also be used to provide the data for a topic type <i>create</i> or <i>update</i>
* operation. To instantiate a <code>TopicTypeModel</code> use the {@link ModelFactory}.
*
* @author <a href="mailto:jri@deepamehta.de">Jörg Richter</a>
*/
......
......@@ -21,18 +21,11 @@ import java.util.List;
/**
* Specification of the DMX core service -- the heart of DMX.
* The DMX Core Service provides generic database operations (create, retrieve, update, delete) to deal with the DMX
* Core objects: Topics, Associations, Topic Types, Association Types.
* <p>
* The responsibility of the DMX core service is to orchestrate the control flow and allow plugins to hook in.
* The main duties of the DMX core service are to provide access to the storage layer and to dispatch events to
* the installed plugins. ### FIXDOC
* <p>
* The DMX core service is a realization of the <i>Inversion of Control</i> pattern.
* <p>
* The DMX core service provides methods to deal with topics, associations, types, and plugins.
* <p>
* Plugin developer notes: Inside the {@link PluginActivator} and {@link Migration} classes an instance of the
* DMX core service is available through the <code>dmx</code> object.
* Inside the {@link PluginActivator} and {@link Migration} (sub)classes an instance of the DMX Core Service is
* available as the <code>dmx</code> object.
*/
public interface CoreService {
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment