Skip to main content

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.

Jump to: navigation, search

Orion/Client API

< Orion
Revision as of 17:47, 21 January 2011 by Aniefer.gmail.com (Talk | contribs)

Orion client API can roughly be divided into services and library objects.

Services are available via a service registry. They are not instantiated in client code, nor are references to service objects maintained in client code. All requests of a service are made through the registry, so that the registry can use appropriate communication mechanisms, depending on where the service resides (locally or in another domain). All interaction with services are asynchronous. If there is a return value to be obtained from a service upon issuing a particular request, it is provided via a callback object passed in by the client.

Library objects are either stateless objects providing utility functions, or stateful objects that are instantiated directly by each client that needs one. Library objects never contain shared state that is available to multiple plugins or services.

See Examples for how these APIs are used.

Services

We expect some subset of the E4/Eclipse Application Services (aka "the twenty things") from the desktop Eclipse platform to be useful in Orion. Rather than assume that all desktop services are important on the web, we wish to collect Orion/EAS/EAS Web Use Cases to prioritize the development of services.

The services discussed below have been implemented at some level in the initial code contribution, so they represent a starting point.

Command Service

The command service allows plug-ins to contribute commands onto Orion client pages (such as the navigator or editor). See Orion/EAS/CommandService for early discussions about this service.

eclipse.CommandService
The command service manages the available commands.Refer to CommandService for API details.
eclipse.Command
A command is an object that describes an action a user can perform, as well as when and what it should look like when presented in various contexts.Refer to Command for API details.
eclipse.KeyBinding
A KeyBinding represents of a key code and a modifier state that can be triggered by the user using the keyboard.Refer to KeyBinding for API details.

Dialog Service

eclipse.DialogService
Common dialog services.Refer to DialogService for API details.

File Service

eclipse.FileService
Provides operations on files, folders, and projects.Refer to FileService for API details.

Getting directory contents

Function
getChildren(parentItem, updateFunction)
Overview
Get all the files and sub-directories of a directory.
Parameters
Name Type Description
parentItem Object The given directory object , must have a "children" attribute
updateFunction Function(Obj, Array) Function to invoke after the server sends back the directory contents without errors. Obj is the directory object with its children field(Obj.children) filled up by the server JSON response . Array is the reference of the children.
Return Value
Error response if fails otherwise no return value.
Example Code
this.registry.callService("IFileService", "getChildren", null, [parentItem,
   dojo.hitch(this, function(parent, children) {
   	onComplete(children);
   	if(postExpandFunc)
           postExpandFunc(args);
})]);
Detailed Explanation
This service uses server directory service.As shown in the example above , this service user uses the children to do something by the function onComplete. See also service registry.


Creating work space

Function
createWorkspace(name, onCreate)
Overview
Creates a new workspace with the given name , using server workspace service
Parameters
Name Type Description
name string The name of the new workspace
onCreate Function The function to invoke after the workspace is created
Return Value
Error response if fails otherwise jsonData.
Example Code
this.createWorkspace("MyWorkspace", onLoad);
Detailed Explanation


Loading work space

Function
loadWorkspace(location, onLoad)
Overview
Loads the workspace with the given id and sets it to be the current workspace.
Parameters
Name Type Description
location String The location of the workspace to load. Should be url of the workspace. An empty string means to load the first work space.
onLoad Function(jsonData) Function to invoke when the workspace is loaded. The response JSON representation is passed as the parameter of the function.
Return Value
Error response if fails otherwise the response JSON representation from server workspace service.
Example Code
this.registry.callService("IFileService", "loadWorkspace", null, [path, function(jsonData){//do something with jsonData}]);
Detailed Explanation
This service uses server workspace service.As shown in the example above , the service user uses the JSON representation to do something. See also service registry.


Creating folder

Function
createFolder(name, baseItem, updateFunction)
Overview
Creates a folder by given name under a base folder.
Parameters
Name Type Description
name String The name of the new folder.
baseItem Object The base folder object. Should have baseItem.Location field.
updateFunction Function(baseItem) Function to invoke when the folder is created. The baseItem is passed as the parameter of the function.
Return Value
Error response if fails otherwise the response JSON representation from server directory creation.
Example Code
this.registry.callService("IFileService", "createFolder", null, [name, item, dojo.hitch(this, function(item){
   this.registry.callService("IFileService", "getChildren", null, [item, dojo.hitch(this.myTree, this.myTree.refreshAndExpand)])}]);
Detailed Explanation
This service uses server directory creation. As shown in the example above , the service user uses the baseItem to call the Getting directorycontents to render the new folder , with its siblings. See also service registry.


Creating file

Function
createFile(fileName, baseItem, updateFunction)
Overview
Creates a file by given name under a base folder. See also folder creation
Parameters
Name Type Description
fileName String The name of the new file.
baseItem Object The base folder object where the file will be created. Should have baseItem.Location field.
updateFunction Function(baseItem) Function to invoke when the file is created. The baseItem is passed as the parameter of the function.
Return Value
Error response if fails otherwise the response JSON representation from server file creation.
Example Code
this.registry.callService("IFileService", "createFile", null, [name, item, dojo.hitch(this, function(item){
   this.registry.callService("IFileService", "getChildren", null, [item, dojo.hitch(this.myTree, this.myTree.refreshAndExpand)])}]);
Detailed Explanation
This service uses server file creation. As shown in the example above , the service user uses the baseItem to call the Getting directory contents to render the new file , with its siblings. See also service registry.


Deleting a file or folder

Function
deleteFile(item, updateFunction)
Overview
Delete a file or folder by given item.
Parameters
Name Type Description
item Object The file or folder to be deleted. Should have item.Location field.
updateFunction Function(item) Function to invoke when the file or folder is deleted. The item or item.parent is passed as the parameter of the function.
Return Value
Error response if fails otherwise the response JSON representation from server file deletion.
Example Code
this.registry.callService("IFileService", "deleteFile", null, [name, item, dojo.hitch(this, function(item){
   this.registry.callService("IFileService", "getChildren", null, [item, dojo.hitch(this.myTree, this.myTree.refreshAndExpand)])}]);
Detailed Explanation
This service uses server file deletion. As shown in the example above , the service user uses the item to call the Getting directory contents to render the item's parent in order to remove the file or folder visually. See also service registry.


Editing Services

eclipse.InputService
Services for editor inputs. Refer to InputService for API details.
eclipse.SaveableService
Service for saving things. Refer to SaveableService for API details.

Log Service

eclipse.LogService
Services for logging. Refer to LogService for API details.
eclipse.StatusReportingService
Service for reporting status. Refer to StatusReportingService for API details.

Preferences

eclipse.Preferences
A preference object provides functions for accessing and setting preferences. Refer to Preferences for API details.

Getting preference

Function
get(key, onDone)
Overview
Retrieves the preference with the given key.
Parameters
Name Type Description
key String The preference key. The key is either a simple name, or a path where the key is the final segment.
onDone Function(pref) A function that is invoked with the loaded preference as an argument, or with no argument if the preference could not be retrieved.
Return Value
A null value is returned if there is no preference defined or if there was an error retrieving the value.
Example Code
this._registry.callService("IPreferenceService", "get", null, ["jsunit_test/configs", function(prefs) {
   if (prefs) {
       var prefJson = JSON.parse(prefs);
       for (var i = 0 ; i < prefJson.length ; i++) {
           var configValues = prefJson[i].value;
           var config = {name:prefJson[i].name, value:[]};
       }
   }  
}]);
Detailed Explanation
This service uses server preference API. As shown in the example above , the service user uses the prefs as JSON data . See also service registry.


Putting preference

Function
put(key, value)
Overview
Sets the preference with the given key to the provided value.
Parameters
Name Type Description
key String The preference key. The key is either a simple name, or a path where the key is the final segment.
value String The preference value that can be parsed as JSON.
Return Value
no return value on success but error response on failure.
Example Code
this._registry.callService("IPreferenceService", "put", null, ["jsunit_test/configs", JSON.stringify(storedConfigs)]);
Detailed Explanation
See also service registry.


Selection Service

eclipse.SelectionService
Service for providing selections. Refer to SelectionService for API details.

User Service

eclipse.UserService
Service for keeping track of the user. Refer to UserService for API details.

Library Objects

Editor

The following objects are related to the Orion rich text editor found in editor.js.

eclipse.Editor
A Editor is a user interface for editing text.
eclipse.DestroyEvent
This is the event sent when the editor is destroyed.
eclipse.LineStyleEvent
This is the event sent when the editor needs the style information for a line.
eclipse.ModelChangedEvent
This is the event sent when the text in the model has changed.
eclipse.ModelChangingEvent
This is the event sent when the text in the model is about to change.
eclipse.ModifyEvent
This is the event sent when the text is modified by the editor.
eclipse.Ruler
This interface represents a ruler for the editor.
eclipse.ScrollEvent
This is the event sent when the editor scrolls.
eclipse.Selection
A Selection represents a range of selected text in the editor.
eclipse.SelectionEvent
This is the event sent when the selection changes in the editor.
eclipse.Style
This object is used to define style information for the editor.
eclipse.StyleRange
This object is used to style range.
eclipse.TextModel
The TextModel is an interface that provides text for the editor.
eclipse.VerifyEvent
This is the event sent when the text is about to be modified by the editor.

Outliner

eclipse.Outliner
An Outliner provides an itemized overview of a resource and acts as a selection provider on that resource. Refer to Outliner for API details.

Search

eclipse.Searcher
Provides API for searching the workspace. Refer to Searcher for API details.

Service Registry

The service registry is somewhat unusual as a library object. Although a client can directly instantiate a private service registry and populate it with their own services, a registry is more typically passed into services and plug-ins upon construction. This avoids objects having to "reach out" and know who or what defines a given service.

The following objects are all related to the service registry:

eclipse.Plugin
A plugin is an object that is isolated in its own frame, and obtains and provides services via the asynchronous postMessage mechanism. Refer to Plugin for API details.
eclipse.Registry
The registry manages the set of available plugins. Refer to Registry for API details.
eclipse.Service
Represents a concrete service instance. Refer to Service for API details.
eclipse.ServiceProvider
A Service Provider is an object that implements a Service Type. Refer to ServiceProvider for API details.
eclipse.ServiceReference
A ServiceReference enables services to be called and released. Refer to ServiceReference for API details.

Registering a local service

Function
registerLocalService(serviceType, id, serviceImpl, properties)
Overview
Registers a local service implementation in the service registry.
Parameters
Name Type Description
serviceType String The type of the service.
id String The service id.
serviceImpl Object A function instance representing the implementation of the service.
properties Object Optional . The properties of the service.
Return Value
No return value.
Example Code
registry.registerLocalService("ITestConfigs", "TestConfigService", new eclipse.TestConfigService({serviceRegistry: registry}));
Detailed Explanation


Calling a registered service

Function
callService(serviceType, methodName, callback, params, instanceId)
Overview
Registers a local service implementation in the service registry.
Parameters
Name Type Description
serviceType String The type of the service. Refer to serviceType in service registration.
methodName String The method/function name from the service.
callback Function(result) Optional.If not null the result of the method/function described by methodName will be passed as the parameter to the callback.
params Array The parameters to be passed to the method/function described by methodName.
instanceId String Optional. The id of the service implementation registered as serviceType. Refer to id in service registration. If id is not defined the first service implementation of serviceType is used.
Return Value
No return value.
Example Code
this.registry.callService("IFileService", "createFile", null, [name, item, dojo.hitch(this, this.changedItem)]);
Detailed Explanation


Table tree

eclipse.TableTree
Generates an HTML table where one of the columns is indented according to depth of children. Refer to TableTree for API details.

Constructing A Table Tree

Function
TableTree (options)
Overview
Generates an HTML table where one of the columns is indented according to depth of children.
Parameters
Name Type Description
options.model Object Model that generates children items. The model must implement:
getRoot(onItem) to provide the root of the model
getChildren(parentItem, onComplete) to provide children items by a given parent item
getId(item) to provide id of a given item ,which must be a valid DOM id
options.renderer Object Renderer that generates the HTML table row for each child. The renderer must implement:
initTable(tableNode)to set up table attributes and a header if desired
render(item, tr) to generate tds for the row
labelColumnIndex() to provide 0 based index of which td contains the primary label which will be indented
options.showRoot Boolean Option to show the root or not
options.indent int Option to provide the indent pixels
options.id String The table DOM id .
Return Value
No return value.
Example Code
this._navTree = new eclipse.TableTree({id: this._navTreeId,model: this._navModel,showRoot: true,parent: this._navDivId,labelColumnIndex: 1,renderer: this._renderer});
Detailed Explanation
A renderer can be supplied which generates the HTML table row for each child. Custom rendering allows clients to use checkboxes, images, links, etc. to describe each element in the tree. Renderers handle all clicks and other behavior via their supplied row content.


Explorer

eclipse.Explorer
A table-based explorer component.Refer to Explorer for API details.
eclipse.Model
Tree model used by eclipse.Explorer.Refer to Model for API details.
eclipse.TreeModel
Tree model used by eclipse.ExplorerTree.Refer to TreeModel for API details.

Utilities

eclipse.util
eclipse.util holds stateless utility methods. Refer to util for API details.

Back to the top