Difference between revisions of "Issue subsystem general description"

From Developer Documents
Jump to navigation Jump to search
 
(18 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 
The Simantics issue subsystem is defined in various plugins including
 
The Simantics issue subsystem is defined in various plugins including
 +
 +
Please note, that the issue subsystem is still in early stage of development and is subject to changes in the near future.
  
 
* Issue model
 
* Issue model
*# '''org.simantics.issues.ontology''' ([[svn:issues/trunk/org.simantics.issues.ontology|SVN]])
+
** '''org.simantics.issues.ontology''' ([[svn:issues/trunk/org.simantics.issues.ontology|SVN]])
 
* Issue user interface model
 
* Issue user interface model
*# '''org.simantics.issues.ui.ontology''' ([[svn:issues/trunk/org.simantics.issues.ui.ontology|SVN]])
+
** '''org.simantics.issues.ui.ontology''' ([[svn:issues/trunk/org.simantics.issues.ui.ontology|SVN]])
 
* Headless issue code
 
* Headless issue code
*# '''org.simantics.issues''' ([[svn:issues/trunk/org.simantics.issues|SVN]])
+
** '''org.simantics.issues''' ([[svn:issues/trunk/org.simantics.issues|SVN]])
*# '''org.simantics.issues.common''' ([[svn:issues/trunk/org.simantics.issues.common|SVN]])
+
** '''org.simantics.issues.common''' ([[svn:issues/trunk/org.simantics.issues.common|SVN]])
 
* Issue user interface code
 
* Issue user interface code
*# '''org.simantics.issues.ui''' ([[svn:issues/trunk/org.simantics.issues.ui|SVN]])
+
** '''org.simantics.issues.ui''' ([[svn:issues/trunk/org.simantics.issues.ui|SVN]])
  
 
= Basics =
 
= Basics =
  
An issue describes a condition in a model. Issues are categorized by
+
An issue describes a condition in a model. Issues are categorized by '''severity''' in the following way
'''severity''' in the following way
 
  
 
* '''Fatal''' issues indicate situations which should not occur in normal operation
 
* '''Fatal''' issues indicate situations which should not occur in normal operation
Line 21: Line 22:
 
* '''Info''' issues are good to know information
 
* '''Info''' issues are good to know information
 
* '''Note''' issues are markers for documentation purposes
 
* '''Note''' issues are markers for documentation purposes
 +
 +
Severity is modelled using '''ISSUE.HasSeverity''' and '''ISSUE.Severity'''
  
 
Issues are somewhat related to events. The main difference between issues and events is that while events happen at a particular time, issues are conditions with a lifecycle. The different issue states are
 
Issues are somewhat related to events. The main difference between issues and events is that while events happen at a particular time, issues are conditions with a lifecycle. The different issue states are
  
* '''Active''', which means that the condition is true
+
* '''Active''' (default), which means that the condition is true
* '''Resolved''', which means that the condition is no longer true
+
* '''Resolved''' ('''ISSUE.Resolved tag'''), which means that the condition is no longer true
  
 
Further issues can be categorized as
 
Further issues can be categorized as
  
* '''User''' issues, which indicates that the user has manually created the condition
+
* '''User''' issues ('''ISSUE.UserIssue''' tag), which indicates that the user has manually created the condition
* '''Hidden''' issues, which can be used as a hint for user interfaces.
+
* '''Hidden''' issues ('''ISSUE.Hidden''' tag), which can be used as a hint for user interfaces.
  
 
The following also applies for issues
 
The following also applies for issues
  
* Issues are directly linked to a model with L0.ConsistsOf and named with UUIDs.
+
* Issues are directly linked to a model with '''L0.ConsistsOf'''
 +
* Issues are given unique and harmless names (e.g. UUIDs)
  
 
Issues are identified by the following data
 
Issues are identified by the following data
  
* A type resource (L0.InstanceOf)
+
* A type resource ('''L0.InstanceOf''')
* A list of context resources (ISSUE.Issue.HasContexts), where the first resource is a '''main context'''
+
* A list of context resources ('''ISSUE.Issue.HasContexts'''), where the first resource is a '''main context'''
 +
 
 +
All issues declare the following properties needed to e.g. display the issue in the Issue View.
 +
 
 +
* Description ('''L0.HasDescription'''), which is a one-line text about the issue
 +
* Resource ('''ISSUE.Issue.resource'''), which is a textual representation of the main context resource
 +
* Path ('''ISSUE.Issue.path'''), which is a textual representation of the location of the main context resource
 +
* Severity ('''ISSUE.Issue.severity'''), which is a textual representation of issue severity
 +
* Creation time ('''ISSUE.HasCreationTime'''), which is a textual representation of time of creation of the issue
 +
 
 +
Typically these are computational properties and e.g. the Description value is asserted in the issue type and computed from context resources.
 +
 
 +
= Issues View =
 +
 
 +
The ''Issues'' view shows all issues in the active model(s). Active models are determined from the set of models linked to the current '''project''' with '''L0X.Activates'''.
  
All issues declare the following properties needed to e.g. display the
+
= User issues =
issue in the Issue View.
 
  
* Description, which is a one-line text about the issue
+
User issues are created by
* Resource, which is a textual representation of the main context resource
 
* Path, which us a textual representetion of the location of the main
 
context resource
 
  
Typically these are computational properties and e.g. the Description is asserted in the issue type and computed from context resources.
+
* '''org.simantics.issues.common.IssueUtils.newUserIssue
 +
* '''org.simantics.issues.common.IssueUtils.newUserIssueForModel
 +
 
 +
User issues are removed by
 +
 
 +
* '''org.simantics.db.layer0.util.RemoverUtil.remove'''
 +
 
 +
= Browsing =
 +
 
 +
For example the following requests are defined for browsing issues
 +
 
 +
* '''org.simantics.issues.common.AllIssues'''
 +
* '''org.simantics.issues.common.AllActiveIssues'''
 +
* '''org.simantics.issues.common.<severity>Issues'''
 +
* '''org.simantics.issues.common.IssuesOfSeverity'''
 +
 
 +
= Computational issues =
  
 
The lifecycle of computational issues is determined by '''issue sources'''. Issue sources are divided into the following categories
 
The lifecycle of computational issues is determined by '''issue sources'''. Issue sources are divided into the following categories
  
* Batch issue sources, which can compute on demand a set of issues
+
* Batch issue sources, which can compute on demand a set of issues from given context
from given context
 
 
* Continuous issue sources, which can track the set of issues from given context
 
* Continuous issue sources, which can track the set of issues from given context
 +
 +
= Batch issue sources =
 +
 +
Batch issue source instances (ISSUE.BatchIssueSource) adapt to the interface '''org.simantics.issues.common.BatchIssueSource'''.
 +
 +
The code '''org.simantics.issues.ui.handler.RunActiveValidations''' performs active batch validations. Currently batch issue sources are searched from the '''project''' resource by relation '''L0X.Activates'''. The activations are put in place using project features that link the project to the issue sources in the ontology.
 +
 +
= Continuous issue sources =
 +
 +
Continuous issue source instances (ISSUE.IssueSource with ISSUE.IsContinuous) adapt to the interface '''org.simantics.issues.common.IssueSource'''.
 +
 +
Currently the only supported implementation of IssueSource is '''org.simantics.issues.common.DependencyIssueSource2'''. The implementation is defined for '''ISSUE.Sources.DependencyTracker'''. It uses
 +
 +
* DependencyChanges metadata for determining which resources need revalidation. The set of changed resources from DependencyChanges is expanded to include all resources reachable by '''L0.IsDependencyOf'''.
 +
* '''ISSUE.Sources.DependencyTracker.HasType''' for determining which resource instances to validate
 +
* '''ISSUE.Sources.DependencyTracker.HasSearchType''' for determining which resource to traverse after changes and before applying the '''extension'''.
 +
* '''ISSUE.Sources.DependencyTracker.HasExtension''' for applying an extension function for the set of potentially changed resources
 +
* '''ISSUE.Sources.DependencyTracker.HasBaseFunction''' for determining a resource under which changes are tracked (by default before this function the base resource is the L0.PartOf of the issue source)
 +
* '''ISSUE.Sources.DependencyTracker.HasConstraint''' for defining the test to be performed on the selected resources
 +
 +
The main codes for continuous validation are
 +
 +
* '''org.simantics.issues.common.IssueUtils.listenActiveProjectIssueSources'''
 +
* '''org.simantics.issues.common.DependencyIssueValidator2''' for validating a context resource
 +
* '''org.simantics.issues.common.DependencyIssueSynchronizer2''' for synchronizing the model
 +
 +
In practice, the developer needs to define
 +
 +
* A set of issue types with asserted properties (with computation) and severity
 +
* A set of constraints assigned to types and associated issue sources
 +
* Possible extension functions for ensuring proper updates for all relevant changes
 +
 +
The issue ontology supplies some templates for modelling typical cases
 +
 +
= Miscellaneous code =
 +
 +
The issue model can be manipulated using '''org.simantics.issues.common.Issue''' and especially '''org.simantics.issues.common.StandardIssue'''. The interface and implementation supports manipulation, comparison and storing of issues into database. StandardIssue assumes that all properties of an issue are determined by assertions in the issue type (i.e. the issue is fully determined by type, contexts, name and creation time)
 +
 +
Some utility codes can be found in
 +
 +
* '''org.simantics.issues.common.IssueUtils'''

Latest revision as of 15:51, 15 March 2012

The Simantics issue subsystem is defined in various plugins including

Please note, that the issue subsystem is still in early stage of development and is subject to changes in the near future.

  • Issue model
    • org.simantics.issues.ontology (SVN)
  • Issue user interface model
    • org.simantics.issues.ui.ontology (SVN)
  • Headless issue code
    • org.simantics.issues (SVN)
    • org.simantics.issues.common (SVN)
  • Issue user interface code
    • org.simantics.issues.ui (SVN)

Basics

An issue describes a condition in a model. Issues are categorized by severity in the following way

  • Fatal issues indicate situations which should not occur in normal operation
  • Error issues indicate a severe issue which blocks calculation
  • Warning issues point out a possible error
  • Info issues are good to know information
  • Note issues are markers for documentation purposes

Severity is modelled using ISSUE.HasSeverity and ISSUE.Severity

Issues are somewhat related to events. The main difference between issues and events is that while events happen at a particular time, issues are conditions with a lifecycle. The different issue states are

  • Active (default), which means that the condition is true
  • Resolved (ISSUE.Resolved tag), which means that the condition is no longer true

Further issues can be categorized as

  • User issues (ISSUE.UserIssue tag), which indicates that the user has manually created the condition
  • Hidden issues (ISSUE.Hidden tag), which can be used as a hint for user interfaces.

The following also applies for issues

  • Issues are directly linked to a model with L0.ConsistsOf
  • Issues are given unique and harmless names (e.g. UUIDs)

Issues are identified by the following data

  • A type resource (L0.InstanceOf)
  • A list of context resources (ISSUE.Issue.HasContexts), where the first resource is a main context

All issues declare the following properties needed to e.g. display the issue in the Issue View.

  • Description (L0.HasDescription), which is a one-line text about the issue
  • Resource (ISSUE.Issue.resource), which is a textual representation of the main context resource
  • Path (ISSUE.Issue.path), which is a textual representation of the location of the main context resource
  • Severity (ISSUE.Issue.severity), which is a textual representation of issue severity
  • Creation time (ISSUE.HasCreationTime), which is a textual representation of time of creation of the issue

Typically these are computational properties and e.g. the Description value is asserted in the issue type and computed from context resources.

Issues View

The Issues view shows all issues in the active model(s). Active models are determined from the set of models linked to the current project with L0X.Activates.

User issues

User issues are created by

  • org.simantics.issues.common.IssueUtils.newUserIssue
  • org.simantics.issues.common.IssueUtils.newUserIssueForModel

User issues are removed by

  • org.simantics.db.layer0.util.RemoverUtil.remove

Browsing

For example the following requests are defined for browsing issues

  • org.simantics.issues.common.AllIssues
  • org.simantics.issues.common.AllActiveIssues
  • org.simantics.issues.common.<severity>Issues
  • org.simantics.issues.common.IssuesOfSeverity

Computational issues

The lifecycle of computational issues is determined by issue sources. Issue sources are divided into the following categories

  • Batch issue sources, which can compute on demand a set of issues from given context
  • Continuous issue sources, which can track the set of issues from given context

Batch issue sources

Batch issue source instances (ISSUE.BatchIssueSource) adapt to the interface org.simantics.issues.common.BatchIssueSource.

The code org.simantics.issues.ui.handler.RunActiveValidations performs active batch validations. Currently batch issue sources are searched from the project resource by relation L0X.Activates. The activations are put in place using project features that link the project to the issue sources in the ontology.

Continuous issue sources

Continuous issue source instances (ISSUE.IssueSource with ISSUE.IsContinuous) adapt to the interface org.simantics.issues.common.IssueSource.

Currently the only supported implementation of IssueSource is org.simantics.issues.common.DependencyIssueSource2. The implementation is defined for ISSUE.Sources.DependencyTracker. It uses

  • DependencyChanges metadata for determining which resources need revalidation. The set of changed resources from DependencyChanges is expanded to include all resources reachable by L0.IsDependencyOf.
  • ISSUE.Sources.DependencyTracker.HasType for determining which resource instances to validate
  • ISSUE.Sources.DependencyTracker.HasSearchType for determining which resource to traverse after changes and before applying the extension.
  • ISSUE.Sources.DependencyTracker.HasExtension for applying an extension function for the set of potentially changed resources
  • ISSUE.Sources.DependencyTracker.HasBaseFunction for determining a resource under which changes are tracked (by default before this function the base resource is the L0.PartOf of the issue source)
  • ISSUE.Sources.DependencyTracker.HasConstraint for defining the test to be performed on the selected resources

The main codes for continuous validation are

  • org.simantics.issues.common.IssueUtils.listenActiveProjectIssueSources
  • org.simantics.issues.common.DependencyIssueValidator2 for validating a context resource
  • org.simantics.issues.common.DependencyIssueSynchronizer2 for synchronizing the model

In practice, the developer needs to define

  • A set of issue types with asserted properties (with computation) and severity
  • A set of constraints assigned to types and associated issue sources
  • Possible extension functions for ensuring proper updates for all relevant changes

The issue ontology supplies some templates for modelling typical cases

Miscellaneous code

The issue model can be manipulated using org.simantics.issues.common.Issue and especially org.simantics.issues.common.StandardIssue. The interface and implementation supports manipulation, comparison and storing of issues into database. StandardIssue assumes that all properties of an issue are determined by assertions in the issue type (i.e. the issue is fully determined by type, contexts, name and creation time)

Some utility codes can be found in

  • org.simantics.issues.common.IssueUtils