Latest revision as of 21:49, 15 July 2014

Long running operations in services and plugins

Methods in Orion plugins may run asychronusly returning a promise (see orion/Deferred.js). The result of the method should be returned by calling deferred.resolve or deferred.reject methods. If you wish to report progress you should use deferred.progress method. Progress information will be reported on UI if argument passed to progress method describes an operation, with API as follows:

Operation Description

type: String one of: loadstart, progress, error, abort, load, loadend
timestamp: Long the time when the operation war run
lengthComputable: Boolean true if the progress is deterministic
loaded: Integer Optional applicable if lengthComputable is true, number of items loaded/process
total: Integer Optional applicable if lengthComputable is true, total number of items to load/process
Location: URL Optional the location of task where we can find more details and perform operations like update.
Important! this attribute should not be present if this operation status is only important when current page is opened. If operation should be tracked also outside of the current page, for instance in All Operations page plugin provider is required to provide Operation Service.
expires: Long timestamp to which the operation will be available under given location
cancelable: Boolean Optional true if operation can be cancelled. Setting this field to true requires enabling reaction on deferred.cancel() each time we return deferred representing given operation.

Deferred Representing Operation

To handle operation as long running it should be returned as a deferred or promise (see orion/Deferred.js). This is the contract how service/plugin should handle the deferred:

deferred.progress(progress): Optional should be called each time operation information changes. The progress should contain #Operation Description. If the progress method is never called the method invocation will be still handled properly, but the operation progress will not be displayed.
deferred.resolve(result): should be called when operation is finished correctly to return the result of the operation.
deferred.reject(error): should be called when operation failed. Error attribute should contain the description of error. Error may be returned in plain text or as a Json object containing fields
Message brief description of the problem
DetailedMessage detailed description of the problem
Severity Optional "Warning" or "Error"
onError(error): function passed as a second argument to then or a third argument to when. This function needs to be implemented when cancelable option is turned on in operation description. Function should check if error.canceled attribute is set, and based on it handle the operation cancellation:

```
deferred.then(null, function(error){
```
```
	if(error.canceled){
```
```
		cancelOperation();
```
```
	}
```
```
});
```

Operation Service

Service methods

getOperation(location): Returns promise that should act the same way as the one that started the operation. When operation is running updates in format of Operation Description should be returned by deferred.progress. When operation is finished returned promise should be resolved or rejected containing operation result. If operation was finished before getOperation was called the returned promise should be resolved straight away.
removeCompletedOperations(): Removes all completed operations tracked by this Operation Service, returns an array of locations of operations that are left.
removeOperation(location): Removed operation represented by this location.

Service properties

name: String Name of the service
pattern: String or URI the base URI for Operations location or the pattern that should match the location. Based on this property services will be matched with given operation location.

Examples

Adding "UPPER" action to editor via long running operation without operation service:

var provider = new orion.PluginProvider();

```
var serviceImpl = {
```
```
    run: function (text) {
```

        var deferred = new orion.Deferred();

        var timestamp = new Date().getTime();

```
        var operationFinished = false;
```
```
        setTimeout(function () {
```

            deferred.resolve(text.toUpperCase());

```
            operationFinished = true;
```
```
        }, 5000);
```
```
 
```
```
        function reportProgress() {
```
```
            if (operationFinished)
```
```
                return;
```
```
            deferred.progress({
```
```
                type: "progress",
```
```
                timestamp: timestamp
```
```
            });
```

            setTimeout(reportProgress, 1000);

```
        }
```
```
 
```
```
        reportProgress();
```
```
 
```
```
        return deferred.promise;
```
```
    }
```
```
};
```
```
var serviceProps = {
```
```
    name: "UPPERCASE",
```
```
    img: "../images/gear.gif",
```
```
    key: ["u", true]
```
```
};
```

provider.registerService("orion.edit.command", serviceImpl, serviceProps);

```
provider.connect();
```

The same example, but with persistent operations that can be viewed on All Operations page. Operations persistence based on localStorage.

var provider = new orion.PluginProvider();

```
 
```
```
var base = "myOperations:";
```
```
 
```
```
function saveOperation(operation) {
```

    var operations = JSON.parse(localStorage.getItem(base) || "{}");

    operations[operation.Location] = operation;

    localStorage.setItem(base, JSON.stringify(operations));

```
}
```
```
 
```
```
function generateLocation() {
```

    var operationNumber = 1 + parseInt(localStorage.getItem("lastOperation") || "0");

    localStorage.setItem("lastOperation", operationNumber);

```
    return base + operationNumber;
```
```
}
```
```
 
```

function reportProgress(deferred, operation) {

    if (operation.type !== "load" && operation.type !== "progress")

```
        return;
```
```
    operation.type = "progress";
```
```
    saveOperation(operation);
```
```
    deferred.progress(operation);
```
```
    setTimeout(function () {
```

        reportProgress(deferred, operation)

```
    }, 1000);
```
```
}
```

provider.registerService("orion.edit.command", {

```
    run: function (text) {
```

        var deferred = new orion.Deferred();

        var timestamp = new Date().getTime();

```
        var operation = {
```
```
            type: "load",
```
```
            timestamp: timestamp,
```

            Location: generateLocation()

```
        };
```
```
        saveOperation(operation);
```
```
        setTimeout(function () {
```

            deferred.resolve(text.toUpperCase());

```
            operation.type = "loadend";
```
```
            saveOperation(operation);
```
```
        }, 5000);
```
```
 
```

        reportProgress(deferred, operation);

```
        return deferred.promise;
```
```
    }
```
```
}, {
```
```
    name: "UPPERCASE",
```
```
    img: "../images/gear.gif",
```
```
    key: ["u", true]
```
```
});
```
```
 
```

provider.registerService("orion.core.operation", {

```
    getOperation: function (location) {
```

        var deferred = new orion.Deferred();

        var operation = JSON.parse(localStorage.getItem(base) || "{}")[location];

```
        if (!operation) {
```

            deferred.reject("Cannot find operation: " + location);

```
            return deferred.promise;
```
```
        }
```

        if (operation.type !== "load" && operation.type !== "progress") {

```
            deferred.resolve();
```
```
        }
```

        reportProgress(deferred, operation);

```
        return deferred.promise;
```
```
    },
```

    removeCompletedOperations: function () {

        var operations = JSON.parse(localStorage.getItem(base) || "{}");

        for (var operationLocation in operations) {

            var operation = operations[operationLocation];

            if (operation.type !== "load" && operation.type !== "progress") {

                delete operations[operationLocation];

```
            }
```
```
        }
```

        localStorage.setItem(base, JSON.stringify(operations));

```
        return Object.keys(operations);
```
```
    },
```

    removeOperation: function (location) {

        var operations = JSON.parse(localStorage.getItem(base) || "{}");

```
        delete operations[location];
```
```
    }
```
```
}, {
```
```
    name: "Upper Tasks",
```
```
    pattern: base
```
```
});
```
```
provider.connect();
```

@@ Line 1: / Line 1: @@
 =Long running operations in services and plugins=
-Methods in Orion plugins may run asychronusly returning a promise (see [http://git.eclipse.org/c/orion/org.eclipse.orion.client.git/tree/bundles/org.eclipse.orion.client.core/web/orion/Deferred.js orion/Deferred.js]). The result of the method should be returned by calling '''deferred.resolve''' or '''deferred.reject''' methods. If you wish to report progress you should use '''deferred.progress''' method. Progress information will be reported on UI if argument passed to '''progress''' method describes an '''operation''', with API as fallows:
+Methods in Orion plugins may run asychronusly returning a promise (see [http://git.eclipse.org/c/orion/org.eclipse.orion.client.git/tree/bundles/org.eclipse.orion.client.core/web/orion/Deferred.js orion/Deferred.js]). The result of the method should be returned by calling '''deferred.resolve''' or '''deferred.reject''' methods. If you wish to report progress you should use '''deferred.progress''' method. Progress information will be reported on UI if argument passed to '''progress''' method describes an '''operation''', with API as follows:
 ==Operation Description==

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Difference between revisions of "Orion/Documentation/Developer Guide/Long running operations in services and plugins"

Latest revision as of 21:49, 15 July 2014

Contents

Long running operations in services and plugins

Operation Description

Deferred Representing Operation

Operation Service

Service methods

Service properties

Examples

Breadcrumbs

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Difference between revisions of "Orion/Documentation/Developer Guide/Long running operations in services and plugins"

Latest revision as of 21:49, 15 July 2014

Contents

Long running operations in services and plugins

Operation Description

Deferred Representing Operation

Operation Service

Service methods

Service properties

Examples