2020-12-29 02:04:20 +01:00
// Vikunja is a to-do list application to facilitate your life.
2021-02-02 20:19:13 +01:00
// Copyright 2018-2021 Vikunja and contributors. All rights reserved.
2019-09-25 20:44:41 +02:00
//
2020-12-29 02:04:20 +01:00
// This program is free software: you can redistribute it and/or modify
2020-12-23 16:41:52 +01:00
// it under the terms of the GNU Affero General Public Licensee as published by
2019-09-25 20:44:41 +02:00
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
2020-12-29 02:04:20 +01:00
// This program is distributed in the hope that it will be useful,
2019-09-25 20:44:41 +02:00
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
2020-12-23 16:41:52 +01:00
// GNU Affero General Public Licensee for more details.
2019-09-25 20:44:41 +02:00
//
2020-12-23 16:41:52 +01:00
// You should have received a copy of the GNU Affero General Public Licensee
2020-12-29 02:04:20 +01:00
// along with this program. If not, see <https://www.gnu.org/licenses/>.
2019-09-25 20:44:41 +02:00
package models
import (
2020-10-11 22:10:03 +02:00
"time"
2020-12-23 16:32:28 +01:00
"xorm.io/xorm"
2020-01-26 18:08:06 +01:00
"code.vikunja.io/api/pkg/user"
2019-09-25 20:44:41 +02:00
"code.vikunja.io/web"
)
// RelationKind represents a kind of relation between to tasks
type RelationKind string
// All valid relation kinds
const (
RelationKindUnknown RelationKind = ` unknown `
RelationKindSubtask RelationKind = ` subtask `
RelationKindParenttask RelationKind = ` parenttask `
RelationKindRelated RelationKind = ` related `
RelationKindDuplicateOf RelationKind = ` duplicateof `
RelationKindDuplicates RelationKind = ` duplicates `
RelationKindBlocking RelationKind = ` blocking `
RelationKindBlocked RelationKind = ` blocked `
RelationKindPreceeds RelationKind = ` precedes `
RelationKindFollows RelationKind = ` follows `
RelationKindCopiedFrom RelationKind = ` copiedfrom `
RelationKindCopiedTo RelationKind = ` copiedto `
)
/ *
* The direction of the relation goes _from_ task_id - > other_task_id .
* The relation kind only tells us something about the relation in that direction , and NOT
* the other way around . This means each relation exists two times in the db , one for each
* relevant direction .
* This design allows to easily do things like "Give me every relation for this task" whithout having
* to deal with each possible case of relation . Instead , it would just give me every relation record
* which has task_id set to the task ID I care about .
*
* For example , when I create a relation where I define task 2 as a subtask of task 1 , it would actually
* create two relations . One from Task 2 - > Task 1 with relation kind subtask and one from Task 1 - > Task 2
* with relation kind parent task .
* When I now want to have all relations task 1 is a part of , I just ask " Give me all relations where
* task_id = 1 " .
* /
func ( rk RelationKind ) isValid ( ) bool {
return rk == RelationKindSubtask ||
rk == RelationKindParenttask ||
rk == RelationKindRelated ||
rk == RelationKindDuplicateOf ||
rk == RelationKindDuplicates ||
rk == RelationKindBlocked ||
rk == RelationKindBlocking ||
rk == RelationKindPreceeds ||
rk == RelationKindFollows ||
rk == RelationKindCopiedFrom ||
rk == RelationKindCopiedTo
}
// TaskRelation represents a kind of relation between two tasks
type TaskRelation struct {
// The unique, numeric id of this relation.
2020-12-18 17:51:22 +01:00
ID int64 ` xorm:"bigint autoincr not null unique pk" json:"-" `
2019-09-25 20:44:41 +02:00
// The ID of the "base" task, the task which has a relation to another.
2020-12-18 17:51:22 +01:00
TaskID int64 ` xorm:"bigint not null" json:"task_id" param:"task" `
2019-09-25 20:44:41 +02:00
// The ID of the other task, the task which is being related.
2020-12-18 17:51:22 +01:00
OtherTaskID int64 ` xorm:"bigint not null" json:"other_task_id" `
2019-09-25 20:44:41 +02:00
// The kind of the relation.
RelationKind RelationKind ` xorm:"varchar(50) not null" json:"relation_kind" `
2020-12-18 17:51:22 +01:00
CreatedByID int64 ` xorm:"bigint not null" json:"-" `
2019-09-25 20:44:41 +02:00
// The user who created this relation
2020-01-26 18:08:06 +01:00
CreatedBy * user . User ` xorm:"-" json:"created_by" `
2019-09-25 20:44:41 +02:00
2020-02-08 13:48:49 +01:00
// A timestamp when this label was created. You cannot change this value.
2020-06-27 19:04:01 +02:00
Created time . Time ` xorm:"created not null" json:"created" `
2019-09-25 20:44:41 +02:00
web . CRUDable ` xorm:"-" json:"-" `
web . Rights ` xorm:"-" json:"-" `
}
// TableName holds the table name for the task relation table
func ( TaskRelation ) TableName ( ) string {
return "task_relations"
}
// RelatedTaskMap holds all relations of a single task, grouped by relation kind.
// This avoids the need for an extra type TaskWithRelation (or similar).
type RelatedTaskMap map [ RelationKind ] [ ] * Task
// Create creates a new task relation
// @Summary Create a new relation between two tasks
// @Description Creates a new relation between two tasks. The user needs to have update rights on the base task and at least read rights on the other task. Both tasks do not need to be on the same list. Take a look at the docs for available task relation kinds.
// @tags task
// @Accept json
// @Produce json
// @Security JWTKeyAuth
// @Param relation body models.TaskRelation true "The relation object"
// @Param taskID path int true "Task ID"
// @Success 200 {object} models.TaskRelation "The created task relation object."
2020-06-28 16:25:46 +02:00
// @Failure 400 {object} web.HTTPError "Invalid task relation object provided."
2019-09-25 20:44:41 +02:00
// @Failure 500 {object} models.Message "Internal error"
// @Router /tasks/{taskID}/relations [put]
2020-12-23 16:32:28 +01:00
func ( rel * TaskRelation ) Create ( s * xorm . Session , a web . Auth ) error {
2019-09-25 20:44:41 +02:00
// Check if both tasks are the same
if rel . TaskID == rel . OtherTaskID {
return ErrRelationTasksCannotBeTheSame {
TaskID : rel . TaskID ,
OtherTaskID : rel . OtherTaskID ,
}
}
// Check if the relation already exists, in one form or the other.
2020-12-23 16:32:28 +01:00
exists , err := s .
2019-09-25 20:44:41 +02:00
Where ( "(task_id = ? AND other_task_id = ? AND relation_kind = ?) OR (task_id = ? AND other_task_id = ? AND relation_kind = ?)" ,
rel . TaskID , rel . OtherTaskID , rel . RelationKind , rel . TaskID , rel . OtherTaskID , rel . RelationKind ) .
Exist ( rel )
if err != nil {
return err
}
if exists {
return ErrRelationAlreadyExists {
TaskID : rel . TaskID ,
OtherTaskID : rel . OtherTaskID ,
Kind : rel . RelationKind ,
}
}
rel . CreatedByID = a . GetID ( )
// Build up the other relation (see the comment above for explanation)
otherRelation := & TaskRelation {
TaskID : rel . OtherTaskID ,
OtherTaskID : rel . TaskID ,
CreatedByID : a . GetID ( ) ,
}
switch rel . RelationKind {
case RelationKindSubtask :
otherRelation . RelationKind = RelationKindParenttask
case RelationKindParenttask :
otherRelation . RelationKind = RelationKindSubtask
case RelationKindRelated :
otherRelation . RelationKind = RelationKindRelated
case RelationKindDuplicateOf :
otherRelation . RelationKind = RelationKindDuplicates
case RelationKindDuplicates :
otherRelation . RelationKind = RelationKindDuplicateOf
case RelationKindBlocking :
otherRelation . RelationKind = RelationKindBlocked
case RelationKindBlocked :
otherRelation . RelationKind = RelationKindBlocking
case RelationKindPreceeds :
otherRelation . RelationKind = RelationKindFollows
case RelationKindFollows :
otherRelation . RelationKind = RelationKindPreceeds
case RelationKindCopiedFrom :
otherRelation . RelationKind = RelationKindCopiedTo
case RelationKindCopiedTo :
otherRelation . RelationKind = RelationKindCopiedFrom
2020-10-11 22:10:03 +02:00
case RelationKindUnknown :
// Nothing to do
2019-09-25 20:44:41 +02:00
}
// Finally insert everything
2020-12-23 16:32:28 +01:00
_ , err = s . Insert ( & [ ] * TaskRelation {
2019-09-25 20:44:41 +02:00
rel ,
otherRelation ,
} )
return err
}
// Delete removes a task relation
// @Summary Remove a task relation
// @tags task
// @Accept json
// @Produce json
// @Security JWTKeyAuth
// @Param relation body models.TaskRelation true "The relation object"
// @Param taskID path int true "Task ID"
// @Success 200 {object} models.Message "The task relation was successfully deleted."
2020-06-28 16:25:46 +02:00
// @Failure 400 {object} web.HTTPError "Invalid task relation object provided."
// @Failure 404 {object} web.HTTPError "The task relation was not found."
2019-09-25 20:44:41 +02:00
// @Failure 500 {object} models.Message "Internal error"
// @Router /tasks/{taskID}/relations [delete]
2020-12-23 16:32:28 +01:00
func ( rel * TaskRelation ) Delete ( s * xorm . Session ) error {
2019-09-25 20:44:41 +02:00
// Check if the relation exists
2020-12-23 16:32:28 +01:00
exists , err := s .
2019-09-25 20:44:41 +02:00
Cols ( "task_id" , "other_task_id" , "relation_kind" ) .
Get ( rel )
if err != nil {
return err
}
if ! exists {
return ErrRelationDoesNotExist {
TaskID : rel . TaskID ,
OtherTaskID : rel . OtherTaskID ,
Kind : rel . RelationKind ,
}
}
2020-12-23 16:32:28 +01:00
_ , err = s . Delete ( rel )
2019-09-25 20:44:41 +02:00
return err
}