gemma: pkg/imports/queue.go comparison

comparison pkg/imports/queue.go @ 1497:b41ad15cc55f

Backend: Documented the internal API of the global import queue.

author	Sascha L. Teichmann <sascha.teichmann@intevation.de>
date	Tue, 04 Dec 2018 18:54:50 +0100
parents	d26e3e1fcff1
children	b10aa02d7819

comparison

equal deleted inserted replaced

-:3bf1f0de0763
+:b41ad15cc55f
 	"gemma.intevation.de/gemma/pkg/auth"
 	"gemma.intevation.de/gemma/pkg/config"
 )
 type (
+	// Feedback is passed to the Do method of a Job to log
+	// informations, warnings or errors.
 	Feedback interface {
+		// Info logs informations.
 		Info(fmt string, args ...interface{})
+		// Warn logs warnings.
 		Warn(fmt string, args ...interface{})
+		// Error logs errors.
 		Error(fmt string, args ...interface{})
 	}
+	// Job is the central abstraction of an import job
+	// run by the import queue.
 	Job interface {
-		Do(context.Context, int64, *sql.Conn, Feedback) (interface{}, error)
+		// Do is called to do the actual import.
+		// Bind transactions to ctx and conn, please-
+		// id is the number of the import job.
+		// feedback can be used to log the import process.
+		// If no error is return the import is assumed to
+		// be successfull. The non-error return value is
+		// serialized as a JSON string into the database as
+		// a summary to the import to be used by the review process.
+		Do(ctx context.Context, id int64, conn *sql.Conn, feedback Feedback) (interface{}, error)
+		// CleanUp is called to clean up ressources hold by the import.
+		// It is called whether the import succeeded or not.
 		CleanUp() error
 	}
+	// JobKind is the type of an import.
+	// Choose a unique name for every import.
 	JobKind string
+	// JobCreator is used to bring a job to life as it is stored
+	// in pure meta-data form to the database.
 	JobCreator interface {
+		// Create build the actual job.
+		// kind is the name of the import type.
+		// data is a free form string to pass arguments to the creation
+		// process. This is useful to tell e.g. where to find data
+		// in the file system to be used for importing.
 		Create(kind JobKind, data string) (Job, error)
+		// Depends returns a list of ressources locked by this type of import.
+		// Imports are run concurrently if they have disjoint sets
+		// of dependencies.
 		Depends() []string
+		// StageDone is called if an import is positively reviewed
+		// (state = accepted). This can be used to finalize the imported
+		// data to move it e.g from the staging area.
 		StageDone(context.Context, *sql.Tx, int64) error
 	}
 	idJob struct {
 		id   int64
 	creators:   map[JobKind]JobCreator{},
 	usedDeps:   map[string]struct{}{},
 }
 var (
+	// ImportStateNames is a list of the states a job can be in.
 	ImportStateNames = []string{
 		"queued",
 		"running",
 		"failed",
 		"pending",
 	q.creatorsMu.Lock()
 	defer q.creatorsMu.Unlock()
 	q.creators[kind] = jc
 }
+// FindJobCreator looks up a JobCreator in the global import queue.
 func FindJobCreator(kind JobKind) JobCreator {
 	return iqueue.jobCreator(kind)
 }
+// ImportKindNames is a list of the names of the imports the
+// global import queue supports.
 func ImportKindNames() []string {
 	return iqueue.importKindNames()
 }
+// RegisterJobCreator adds a JobCreator to the global import queue.
+// This a good candidate to be called in a init function for
+// a particular JobCreator.
 func RegisterJobCreator(kind JobKind, jc JobCreator) {
 	log.Printf("info: register import job creator for kind '%s'\n", kind)
 	iqueue.registerJobCreator(kind, jc)
 }
 		}
 	}
 	return id, err
 }
+// AddJob adds a job to the global import queue to be executed
+// as soon as possible. This is gone in a separate Go routine
+// so this will not block.
 func AddJob(kind JobKind, user, data string) (int64, error) {
 	return iqueue.addJob(kind, user, data)
 }
 type logFeedback int64

Mercurial > gemma

comparison pkg/imports/queue.go @ 1497:b41ad15cc55f