Difference between revisions of "Orion/Client API"

From Eclipsepedia

Jump to: navigation, search
m (Category)
 
(31 intermediate revisions by 6 users not shown)
Line 1: Line 1:
Orion client API can roughly be divided into services and library objects. Services are obtained via a service registry, rather than instantiated by the client code. All interaction with services are asynchronous. If there is a return value to be obtained from the service, it is provided via a callback object passed in by the client.  
+
Orion client API can roughly be divided into services and library objects.  
  
Library objects are either stateless objects providing utility functions, or statefull 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.
+
[[Orion/EAS|Orion Application Services]] support file read/write, command registration and access, user login, preferences, and dialogs for examples. The Services are contributed by plugins (?) and (?) and used by library objects (?) and by plugins;
 +
[[Orion/EAS|Services]] are available via a service registry.    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). They are not instantiated in client code, nor are references to service objects maintained in client code. 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.  
  
= Services =
+
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.
  
== Command Service ==
+
See the [[Orion/Documentation/Developer_Guide|Orion Developer Guide]] for complete details on available client APIs and services.
  
;eclipse.CommandService
+
See [http://orionhub.org/jsdoc/index.html Source Documentation] for object and method programming interfaces.
:The command service manages the available commands.
+
[[Category:Orion|Client How Tos]][[Category:Orion|API]]
;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.
+
;eclipse.KeyBinding
+
:A KeyBinding represents of a key code and a modifier state that can be triggered by the user using the keyboard.
+
 
+
== Dialog Service ==
+
;eclipse.DialogService
+
:Common dialog services
+
 
+
== Explorer Service ==
+
;eclipse.Explorer
+
:A table-based explorer component
+
;eclipse.Model
+
:Tree model used by eclipse.Explorer.
+
;eclipse.TreeModel
+
:Tree model used by eclipse.ExplorerTree.
+
 
+
== File Service ==
+
 
+
;eclipse.FileService
+
:Provides operations on files, folders, and projects.
+
 
+
=== Getting directory contents ===
+
{{Orion/ClientAPI
+
| function = getChildren(parentItem, updateFunction)
+
| overview = Get all the files and sub-directories of a directory.
+
| parameters =
+
{{Orion/ParamHead
+
| Rows =
+
 
+
{{Orion/ParamBody
+
| Name = parentItem
+
| Type= Object
+
| Desc= The given directory object , must have a "children" attribute
+
}}
+
 
+
{{Orion/ParamBody
+
| Name = updateFunction
+
| Type= Function(Obj, Array)
+
| Desc= 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 = Error response if fails otherwise no return value.
+
| example =
+
this.registry.callService("IFileService", "getChildren", null, [parentItem,
+
    dojo.hitch(this, function(parent, children) {
+
    onComplete(children);
+
    if(postExpandFunc)
+
            postExpandFunc(args);
+
})]);
+
| explain = This service uses [[Orion/Server_API#Getting_directory_metadata|server directory service]].As shown in the example above , this service user  uses the children to do something by the function onComplete. '''See also''' [[Orion/Architecture#Services|service registry]].
+
}}
+
 
+
=== Creating work space ===
+
{{Orion/ClientAPI
+
| function = createWorkspace(name, onCreate)
+
| overview = Creates a new workspace with the given name , using [[Orion/Server_API#Workspace_Service|server workspace service]]
+
| parameters =
+
{{Orion/ParamHead
+
| Rows =
+
 
+
{{Orion/ParamBody
+
| Name = name
+
| Type= string
+
| Desc= The name of the new workspace
+
}}
+
 
+
{{Orion/ParamBody
+
| Name = onCreate
+
| Type= Function
+
| Desc= The function to invoke after the workspace is created
+
}}
+
}}
+
 
+
| return = Error response if fails otherwise jsonData.
+
| example = this.createWorkspace("MyWorkspace", onLoad);
+
 
+
| explain =
+
}}
+
 
+
 
+
=== Loading work space ===
+
{{Orion/ClientAPI
+
| function = loadWorkspace(location, onLoad)
+
| overview = Loads the workspace with the given id and sets it to be the current workspace.
+
| parameters =
+
{{Orion/ParamHead
+
| Rows =
+
 
+
{{Orion/ParamBody
+
| Name = location
+
| Type= String
+
| Desc= The location of the workspace to load. Should be url of the workspace. An empty string means to load the first work space.
+
}}
+
 
+
{{Orion/ParamBody
+
| Name = onLoad
+
| Type= Function(jsonData)
+
| Desc= Function to invoke when the workspace is loaded. The response JSON representation is passed as the parameter of the function.
+
}}
+
}}
+
 
+
| return = Error response if fails otherwise the response JSON representation from [[Orion/Server_API#Workspace_Service|server workspace service]].
+
| example =
+
this.registry.callService("IFileService", "loadWorkspace", null, [path, function(jsonData){//do something with jsonData}]);
+
| explain = This service uses [[Orion/Server_API#Workspace_Service|server workspace service]].As shown in the example above , the service user  uses the JSON representation to do something. '''See also''' [[Orion/Architecture#Services|service registry]].
+
}}
+
 
+
=== Creating folder ===
+
{{Orion/ClientAPI
+
| function = createFolder(name, baseItem, updateFunction)
+
| overview = Creates a folder by given name under a base folder.
+
| parameters =
+
{{Orion/ParamHead
+
| Rows =
+
 
+
{{Orion/ParamBody
+
| Name = name
+
| Type= String
+
| Desc= The name of the new folder.
+
}}
+
 
+
{{Orion/ParamBody
+
| Name = baseItem
+
| Type= Object
+
| Desc= The base folder object. Should have baseItem.Location field.
+
}}
+
 
+
{{Orion/ParamBody
+
| Name = updateFunction
+
| Type= Function(baseItem)
+
| Desc= Function to invoke when the folder is created. The baseItem is passed as the parameter of the function.
+
}}
+
}}
+
 
+
| return = Error response if fails otherwise the response [[Orion/Server_API/File_API#JSON_representations|JSON representation]] from [[Orion/Server_API/File_API#Creating_a_directory|server directory creation]].
+
| example =
+
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)])}]);
+
 
+
| explain = This service uses [[Orion/Server_API/File_API#Creating_a_directory|server directory creation]]. As shown in the example above , the service user  uses the baseItem to call the [[Orion/Client_API#Getting_directory_contents| Getting directorycontents]] to render the new folder , with its siblings. '''See also''' [[Orion/Architecture#Services|service registry]].
+
}}
+
 
+
=== Creating file ===
+
{{Orion/ClientAPI
+
| function = createFile(fileName, baseItem, updateFunction)
+
| overview = Creates a file by given name under a base folder. '''See also''' [[Orion/Client_API#Creating_folder|folder creation]]
+
| parameters =
+
{{Orion/ParamHead
+
| Rows =
+
 
+
{{Orion/ParamBody
+
| Name = fileName
+
| Type= String
+
| Desc= The name of the new file.
+
}}
+
 
+
{{Orion/ParamBody
+
| Name = baseItem
+
| Type= Object
+
| Desc= The base folder object where the file will be created. Should have baseItem.Location field.
+
}}
+
 
+
{{Orion/ParamBody
+
| Name = updateFunction
+
| Type= Function(baseItem)
+
| Desc= Function to invoke when the file is created. The baseItem is passed as the parameter of the function.
+
}}
+
}}
+
 
+
| return = Error response if fails otherwise the response [[Orion/Server_API/File_API#JSON_representations|JSON representation]] from [[Orion/Server_API/File_API#Creating_an_empty_file|server file creation]].
+
| example =
+
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)])}]);
+
 
+
| explain = This service uses [[Orion/Server_API/File_API#Creating_an_empty_file|server file creation]]. As shown in the example above , the service user  uses the baseItem to call the [[Orion/Client_API#Getting_directory_contents| Getting directory contents]] to render the new file , with its siblings. '''See also''' [[Orion/Architecture#Services|service registry]].
+
}}
+
 
+
=== Deleting a file or folder ===
+
{{Orion/ClientAPI
+
| function = deleteFile(item, updateFunction)
+
| overview = Delete a file or folder by given item.
+
| parameters =
+
{{Orion/ParamHead
+
| Rows =
+
 
+
{{Orion/ParamBody
+
| Name = item
+
| Type= Object
+
| Desc= The file or folder to be deleted. Should have item.Location field.
+
}}
+
 
+
{{Orion/ParamBody
+
| Name = updateFunction
+
| Type= Function(item)
+
| Desc= Function to invoke when the file or folder is deleted. The item or item.parent is passed as the parameter of the function.
+
}}
+
}}
+
 
+
| return = Error response if fails otherwise the response [[Orion/Server_API/File_API#JSON_representations|JSON representation]] from [[Orion/Server_API/File_API#Deleting_a_file_or_directory|server file deletion]].
+
| example =
+
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)])}]);
+
 
+
| explain = This service uses [[Orion/Server_API/File_API#Deleting_a_file_or_directory|server file deletion]]. As shown in the example above , the service user  uses the item to call the [[Orion/Client_API#Getting_directory_contents| Getting directory contents]] to render the item's parent in order to remove the  file or folder visually. '''See also''' [[Orion/Architecture#Services|service registry]].
+
}}
+
 
+
== Editing Services ==
+
 
+
;eclipse.InputService
+
:Services for editor inputs
+
;eclipse.SaveableService
+
:Service for saving things
+
 
+
== Log Service ==
+
 
+
;eclipse.LogService
+
:Services for logging
+
;eclipse.StatusReportingService
+
:Service for reporting status
+
 
+
== Preferences ==
+
 
+
;eclipse.Preferences
+
:A preference object provides functions for accessing and setting preferences
+
 
+
=== Getting preference ===
+
{{Orion/ClientAPI
+
| function = get(key, onDone)
+
| overview = Retrieves the preference with the given key.
+
| parameters =
+
{{Orion/ParamHead
+
| Rows =
+
 
+
{{Orion/ParamBody
+
| Name = key
+
| Type= String
+
| Desc= The preference key. The key is either a simple name, or a path where the key is the final segment.
+
}}
+
 
+
{{Orion/ParamBody
+
| Name = onDone
+
| Type= Function(pref)
+
| Desc= A function that is invoked with the loaded preference as an argument, or with no argument if the preference could not be retrieved.
+
}}
+
}}
+
 
+
| return =  A null value is returned if there is no preference defined or if there was an error retrieving the value.
+
| example =
+
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:[]};
+
        }
+
    } 
+
}]);
+
 
+
| explain = This service uses [[Orion/Server_API#Preference_API|server preference API]]. As shown in the example above , the service user  uses the prefs as JSON data . '''See also''' [[Orion/Architecture#Services|service registry]].
+
}}
+
 
+
=== Putting preference ===
+
{{Orion/ClientAPI
+
| function = put(key, value)
+
| overview =Sets the preference with the given key to the provided value.
+
| parameters =
+
{{Orion/ParamHead
+
| Rows =
+
 
+
{{Orion/ParamBody
+
| Name = key
+
| Type= String
+
| Desc= The preference key. The key is either a simple name, or a path where the key is the final segment.
+
}}
+
 
+
{{Orion/ParamBody
+
| Name = value
+
| Type= String
+
| Desc= The preference value that can be parsed as JSON.
+
}}
+
}}
+
 
+
| return =  no return value on success but error response on failure.
+
| example =
+
this._registry.callService("IPreferenceService", "put", null, ["jsunit_test/configs", JSON.stringify(storedConfigs)]);
+
 
+
| explain = '''See also''' [[Orion/Architecture#Services|service registry]].
+
}}
+
 
+
== Selection Service ==
+
 
+
;eclipse.SelectionService
+
:Service for providing selections
+
 
+
== User Service ==
+
 
+
;eclipse.UserService
+
:Service for keeping track of the user
+
 
+
= 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.
+
 
+
== Search ==
+
 
+
;eclipse.Searcher
+
:Provides API for searching the workspace.
+
 
+
== 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.
+
;eclipse.Registry
+
:The registry manages the set of available plugins.
+
;eclipse.Service
+
:Represents a concrete service instance.
+
;eclipse.ServiceProvider
+
:A Service Provider is an object that implements a Service Type
+
;eclipse.ServiceReference
+
:A ServiceReference enables services to be called and released.
+
 
+
=== Registering a local service ===
+
{{Orion/ClientAPI
+
| function = registerLocalService(serviceType, id, serviceImpl, properties)
+
| overview = Registers a local service implementation in the service registry.
+
| parameters =
+
{{Orion/ParamHead
+
| Rows =
+
 
+
{{Orion/ParamBody
+
| Name = serviceType
+
| Type= String
+
| Desc= The type of the service.
+
}}
+
 
+
{{Orion/ParamBody
+
| Name = id
+
| Type= String
+
| Desc= The service id.
+
}}
+
 
+
{{Orion/ParamBody
+
| Name = serviceImpl
+
| Type= Object
+
| Desc= A function instance representing the implementation of the service.
+
}}
+
 
+
{{Orion/ParamBody
+
| Name = properties
+
| Type= Object
+
| Desc= Optional . The properties of the service.
+
}}
+
}}
+
 
+
| return = No return value.
+
| example =
+
registry.registerLocalService("ITestConfigs", "TestConfigService", new eclipse.TestConfigService({serviceRegistry: registry}));
+
 
+
| explain =
+
}}
+
 
+
=== Calling a registered service ===
+
{{Orion/ClientAPI
+
| function = callService(serviceType, methodName, callback, params, instanceId)
+
| overview = Registers a local service implementation in the service registry.
+
| parameters =
+
{{Orion/ParamHead
+
| Rows =
+
 
+
{{Orion/ParamBody
+
| Name = serviceType
+
| Type= String
+
| Desc= The type of the service. '''Refer to''' serviceType in [[Orion/Client_API#Registering_a_local_service|service registration]].
+
}}
+
 
+
{{Orion/ParamBody
+
| Name = methodName
+
| Type= String
+
| Desc= The method/function name from the service.
+
}}
+
 
+
{{Orion/ParamBody
+
| Name = callback
+
| Type= Function(result)
+
| Desc= Optional.If not null the result of the method/function described by '''methodName''' will be passed as the parameter to the callback.
+
}}
+
 
+
{{Orion/ParamBody
+
| Name = params
+
| Type= Array
+
| Desc= The parameters to be passed to the method/function described by '''methodName'''.
+
}}
+
 
+
{{Orion/ParamBody
+
| Name = instanceId
+
| Type= String
+
| Desc= Optional. The id of the service implementation registered as serviceType. '''Refer to''' id in [[Orion/Client_API#Registering_a_local_service|service registration]]. If id is not defined the first service implementation of serviceType is used.
+
}}
+
}}
+
 
+
| return = No return value.
+
| example =
+
this.registry.callService("IFileService", "createFile", null, [name, item, dojo.hitch(this, this.changedItem)]);
+
 
+
| explain =
+
}}
+
 
+
== Table tree ==
+
 
+
;eclipse.TableTree
+
:Generates an HTML table where one of the columns is indented according to depth of children.
+
 
+
=== Constructing A Table Tree ===
+
{{Orion/ClientAPI
+
| function = TableTree (options)
+
| overview = Generates an HTML table where one of the columns is indented according to depth of children.
+
| parameters =
+
 
+
{{Orion/ParamHead
+
| Rows =
+
 
+
{{Orion/ParamBody
+
| Name = options.model
+
| Type= Object
+
| Desc= Model that generates children items. The model must implement:<br/> '''getRoot(onItem)''' to provide the root of the model <br/>'''getChildren(parentItem, onComplete)''' to provide children items by a given parent item<br/>'''getId(item)''' to provide id of a given item ,which must be a valid DOM id
+
}}
+
 
+
{{Orion/ParamBody
+
| Name = options.renderer
+
| Type= Object
+
| Desc= Renderer that generates the HTML table row for each child. The renderer must implement:<br/>'''initTable(tableNode)'''to set up table attributes and a header if desired<br/>'''render(item, tr)''' to generate tds for the row<br/> '''labelColumnIndex()''' to provide  0 based index of which td contains the primary label which will be indented
+
}}
+
 
+
{{Orion/ParamBody
+
| Name = options.showRoot
+
| Type= Boolean
+
| Desc= Option to show the root or not
+
}}
+
 
+
{{Orion/ParamBody
+
| Name = options.indent
+
| Type= int
+
| Desc= Option to provide the indent pixels
+
}}
+
 
+
{{Orion/ParamBody
+
| Name = options.id
+
| Type= String
+
| Desc= The table DOM id .
+
}}
+
}}
+
 
+
| return = No return value.
+
| example =
+
this._navTree = new eclipse.TableTree({id: this._navTreeId,model: this._navModel,showRoot: true,parent: this._navDivId,labelColumnIndex: 1,renderer: this._renderer});
+
 
+
| explain =
+
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.
+
}}
+
 
+
== Utilities ==
+
 
+
;eclipse.util
+
:eclipse.util holds stateless utility methods.
+
 
+
[[Category:Orion|Client API]]
+

Latest revision as of 21:27, 4 March 2012

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

Orion Application Services support file read/write, command registration and access, user login, preferences, and dialogs for examples. The Services are contributed by plugins (?) and (?) and used by library objects (?) and by plugins; Services are available via a service registry. 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). They are not instantiated in client code, nor are references to service objects maintained in client code. 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 the Orion Developer Guide for complete details on available client APIs and services.

See Source Documentation for object and method programming interfaces.