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

Difference between revisions of "Orion/Documentation/Developer Guide/Project services"

(Service methods)
(orion.project.handler)
(12 intermediate revisions by 2 users not shown)
Line 9: Line 9:
 
* Adding dependencies of given type
 
* Adding dependencies of given type
 
* Adding additional information to project page
 
* Adding additional information to project page
 +
 +
An example implementation can be found in [https://github.com/eclipse/orion.client/blob/master/bundles/org.eclipse.orion.client.git/web/git/plugins/gitPlugin.js#L321-L469 <tt>gitPlugin.js</tt>].
  
 
== Service attributes ==
 
== Service attributes ==
Line 15: Line 17:
 
; type
 
; type
 
: <tt>String</tt> the unique identifier of the project type (for instance ''git'' or ''jazz'')
 
: <tt>String</tt> the unique identifier of the project type (for instance ''git'' or ''jazz'')
; addParamethers
+
; addParameters
 
: <tt>ParameterDefinition[]</tt> Array of objects containing '''id''' <tt>String</tt>, '''type''' <tt>String</tt> describing one of the html5 input types or "textarea" and '''name''' being a display <tt>String</tt> for the parameter. Those parameters will be used to generate an input form when user tries init and new project or dependency.
 
: <tt>ParameterDefinition[]</tt> Array of objects containing '''id''' <tt>String</tt>, '''type''' <tt>String</tt> describing one of the html5 input types or "textarea" and '''name''' being a display <tt>String</tt> for the parameter. Those parameters will be used to generate an input form when user tries init and new project or dependency.
; optionalParamethers
+
; optionalParameters
: ''Since 5.0'' <tt>arameterDefinition[]</tt> a list of optional parameters that will display in a separate dialog when user clicks "More" in the input form with '''addParamethers'''
+
: ''Since 5.0'' <tt>parameterDefinition[]</tt> a list of optional parameters that will display in a separate dialog when user clicks "More" in the input form with '''addParameters'''
 
; addDependencyName
 
; addDependencyName
 
: <tt>String</tt> Name of the action for adding dependency
 
: <tt>String</tt> Name of the action for adding dependency
Line 30: Line 32:
 
: ''optional'' <tt>String</tt> comment displayed when project or dependency are being initialized
 
: ''optional'' <tt>String</tt> comment displayed when project or dependency are being initialized
 
; validationProperties
 
; validationProperties
''optional'' <tt>ValidationProperties[]</tt> that define if given item can be handled by this project handler, see [[Orion/Documentation/Developer Guide/Plugging into Orion_pages#Validation_Properties | Validation Properties]]
+
: ''optional'' <tt>ValidationProperties[]</tt> that define if given item can be handled by this project handler, see [[Orion/Documentation/Developer Guide/Plugging into Orion_pages#Validation_Properties | Validation Properties]]
 +
 
 +
=== Service attributes for translation ===
 +
The following attributes are all optional.
 +
; nls
 +
: <tt>String</tt> Name of the message bundle used to translate this project handler's translateable attributes.
 +
; addDependencyNameKey
 +
: <tt>String</tt> Property name used to look up the translated value of <tt>dependencyName</tt> within the message bundle.
 +
; addDependencyTooltipKey
 +
: <tt>String</tt> Property name used to look up the translated value of <tt>addDependencyTooltip</tt> within the message bundle.
 +
; addProjectNameKey
 +
: <tt>String</tt> Property name used to look up the translated value of <tt>addProjectName</tt> within the message bundle.
 +
; addProjectTooltipKey
 +
: <tt>String</tt> Property name used to look up the translated value of <tt>addProjectTooltip</tt> within the message bundle.
  
 
== Service methods ==
 
== Service methods ==
Line 64: Line 79:
 
: '''dependency''' ''optional'' <tt>DependencyDescription</tt> that contains <tt>Type</tt>, <tt>Name</tt> and <tt>Location</tt>. Location should describe the dependency in a way it allows to recreate it in the user's workspace. If invocation of this method contains <tt>dependency</tt> it means that user had the dependency defined and used '''Connect''' action to initialize its content in his workspace.
 
: '''dependency''' ''optional'' <tt>DependencyDescription</tt> that contains <tt>Type</tt>, <tt>Name</tt> and <tt>Location</tt>. Location should describe the dependency in a way it allows to recreate it in the user's workspace. If invocation of this method contains <tt>dependency</tt> it means that user had the dependency defined and used '''Connect''' action to initialize its content in his workspace.
 
: '''params''' parameters inputted by the user while requesting to create a new dependency. User is at first not prompt for parameters if he chooses to connect exiting dependency. Then <tt>DependencyDescription</tt> is passed as '''dependency'''. This function may request for extra parameters in the same way '''initProject''' does.
 
: '''params''' parameters inputted by the user while requesting to create a new dependency. User is at first not prompt for parameters if he chooses to connect exiting dependency. Then <tt>DependencyDescription</tt> is passed as '''dependency'''. This function may request for extra parameters in the same way '''initProject''' does.
: '''projectMetadata''' contains an object with project metadata, in particular this object contains WorkspaceLocation.
+
: '''projectMetadata''' contains an object with project metadata, in particular this object contains WorkspaceLocation.  
 
; getDependencyDescription (item)
 
; getDependencyDescription (item)
 +
: This function should return <tt>DependencyDescription</tt> containing <tt>Type</tt>, <tt>Name</tt> and <tt>Location</tt> for given item. This function is used to find dependency in users workspace. This function is only invoked when <tt>validationProperties</tt> are matched with <tt>item</tt>
 
; paramsToDependencyDescription (params)
 
; paramsToDependencyDescription (params)
 +
: This function should return <tt>DependencyDescription</tt> containing <tt>Type</tt>, <tt>Name</tt> and <tt>Location</tt> created based on given <tt>params</tt>. This function is used to check if the dependency that should be created based on parameters inputted by the user already exists in this workspace.
 +
 +
= orion.project.deploy =
 +
 +
The <tt>orion.project.deploy</tt> service is used to provide ways to deploy the project contents.
 +
 +
== Service attributes ==
 +
; id
 +
: <tt>String</tt>
 +
; name
 +
: <tt>String</tt>
 +
; tooltip
 +
: <tt>String</tt>
 +
; deployTypes
 +
: <tt>String[]</tt> The list of deploy types, for instance ["ftp"]
 +
; priorityForDefault
 +
: ''optional'' <tt>Integer</tt> If there are more then one deployment of type defined in deployTypes this number will help which plugin should be use to perform the deployment
 +
; logLocationTemplate
 +
: ''optional'' <tt>UrlTemplate</tt> A template to location to deployment logs that will be resolved using the launchConfiguration, for instance "{+OrionHome}/deployment/logs.html#{Name,Params*}",
 +
; validationProperties
 +
: ''optional'' <tt>ValidationProperties[]</tt> that define if given item can be deployed by this deploy service, see [[Orion/Documentation/Developer Guide/Plugging into Orion_pages#Validation_Properties | Validation Properties]]
 +
 +
=== Service attributes for translation ===
 +
The following attributes are optional, and are only used for translation.
 +
; nls
 +
: <tt>String</tt> The message bundle used to translate this deploy service's properties.
 +
; nameKey
 +
: <tt>String</tt> The property name used to look up the translated name of this deploy service within the message bundle.
 +
; tooltipKey
 +
: <tt>String</tt> The property name used to look up the translated tooltip for this deploy service within the message bundle.
 +
 +
== Service methods ==
 +
; deploy(project, launchConf)
 +
: Preform the deployment. Returns the deploy result (may contain launch configuration to save) in callback or an error in errback
 +
; getState(properties)
 +
: ''optional'' Check the state of the deployed application, example result {State: "STARTED"}
 +
; start(properties)
 +
: ''optional'' Starts the deployed application, can return a state of the application
 +
; stop(properties)
 +
: ''optional'' Stops the deployed application, can return a state of the application
 +
; getDeployProgressMessage(project, launchConf)
 +
: ''optional'' Can return a string that will be displayed as a progress message while the application is being deployed
 +
 +
== Response fields, applicable to all methods ==
 +
; ToSave
 +
: <tt>Object {Name(String), Params(Object), Url(String), ManageUrl(String, optional), Path(String, optional), Type(String)}</tt> Launch configuration description. Should be returned if launch configuration should be saved in the project and included in "Deployment Information" section on project page. Params attribute should contain all the information necessary to redeploy the application, Type must be identical with one of the deployTypes. Url contains the link to deployed application. ManageUrl should contain a link to any external configuration of the application provided. Path is default root of project.
 +
; Saved
 +
: <tt>Object {Name(String), Params(Object), Url(String), ManageUrl(String, optional), Path(String, optional), Type(String)}</tt> Same as ToSave, but indicates that the launch configuration was saved elsewhere outside of Orion and should be added to the view, but not saved to the file
 +
; Message
 +
: <tt>String</tt> Message to display to the user
 +
; State
 +
: <tt>String NOT_DEPLOYED, STARTED, STOPPED</tt> If application state was changed by the action
 +
; Retry
 +
: If some extra information is necessary Retry may contain a description of the parameters that user should be asked about. The results will be mixed in with the parameters when the function is retried. Example:
 +
<source lang="javascript" enclose="div" line="GESHI_FANCY_LINE_NUMBERS">
 +
Retry: {
 +
    parameters: [
 +
        {id: "user", type: "text", name: "User:"},
 +
        {id: "password", type: "password", name: "Password:"}
 +
    ]
 +
}
 +
</source>
 +
; UriTemplate
 +
: Instead of Retry, plugin may return a template for a URL to load and take over the deployment, including the parameters collection. The full response example:
 +
 +
<source lang="javascript" enclose="div" line="GESHI_FANCY_LINE_NUMBERS">
 +
{
 +
    UriTemplate: "{+OrionHome}/cfui/deployInteractive.html",
 +
    Width: "400px",
 +
    Height: "350px",
 +
    UriTemplateId: "org.eclipse.orion.client.cf.deploy.uritemplate"
 +
}
 +
</source>

Revision as of 16:45, 31 October 2014

Overview of project services

Orion allows to extend the project functionality by adding other project types. Project types are not exclusive, one project may be of two different types.

orion.project.handler

The orion.project.handler service is used to provide a custom project handler. Creating a custom project handler enables to:

  • Creating project of given type
  • Adding dependencies of given type
  • Adding additional information to project page

An example implementation can be found in gitPlugin.js.

Service attributes

id
String
type
String the unique identifier of the project type (for instance git or jazz)
addParameters
ParameterDefinition[] Array of objects containing id String, type String describing one of the html5 input types or "textarea" and name being a display String for the parameter. Those parameters will be used to generate an input form when user tries init and new project or dependency.
optionalParameters
Since 5.0 parameterDefinition[] a list of optional parameters that will display in a separate dialog when user clicks "More" in the input form with addParameters
addDependencyName
String Name of the action for adding dependency
addDependencyTooltip
String Tooltip of the action for adding dependency
addProjectName
String Name of the action for adding project
addProjectTooltip
String Tooltip of the action for adding project
actionComment
optional String comment displayed when project or dependency are being initialized
validationProperties
optional ValidationProperties[] that define if given item can be handled by this project handler, see Validation Properties

Service attributes for translation

The following attributes are all optional.

nls
String Name of the message bundle used to translate this project handler's translateable attributes.
addDependencyNameKey
String Property name used to look up the translated value of dependencyName within the message bundle.
addDependencyTooltipKey
String Property name used to look up the translated value of addDependencyTooltip within the message bundle.
addProjectNameKey
String Property name used to look up the translated value of addProjectName within the message bundle.
addProjectTooltipKey
String Property name used to look up the translated value of addProjectTooltip within the message bundle.

Service methods

getAdditionalProjectProperties (item, projectMetadata)
optional returns ProjectPageSectionDescription[] Implementing this function allows to add extra information to project page.
Example returned project page section description:
[
 {
   name: "Git",
   children: [
    {
      name: "Git Url",
      value: clone.GitUrl
    },
    {
      name: "Git Status",
      value: "Git Status",
      href: "{+OrionHome}/git/git-status.html#" + item.Git.StatusLocation
    }
  ]
 }
]
will result in rendering the additional section on the project page:
GitSectionOnProjectView.png
initProject (params, projectMetadata)
optional if implemented users will able to add projects of given type. The function should initialize project in the workspace (including adding project.json to it) and return the project description containing at least ContentLocation
params contains an object of parameters collected from the user based on description in addParamethers attribute. If the list of parameters is not complete rejecting the returned deferred with additional addParamethers attribute will invoke asking user for additional parameters. Afterwords all collected parameters will be resend, so there is no need to remember previously send params.
projectMetadata contains an object with some extra potential project metadata, in particular this object contains WorkspaceLocation.
initDependency (dependency, params, projectMetadata)
optional if implemented users will be able to add associated content of given type. This function should initialize the dependency in user's workspace and return the DependencyDescription
dependency optional DependencyDescription that contains Type, Name and Location. Location should describe the dependency in a way it allows to recreate it in the user's workspace. If invocation of this method contains dependency it means that user had the dependency defined and used Connect action to initialize its content in his workspace.
params parameters inputted by the user while requesting to create a new dependency. User is at first not prompt for parameters if he chooses to connect exiting dependency. Then DependencyDescription is passed as dependency. This function may request for extra parameters in the same way initProject does.
projectMetadata contains an object with project metadata, in particular this object contains WorkspaceLocation.
getDependencyDescription (item)
This function should return DependencyDescription containing Type, Name and Location for given item. This function is used to find dependency in users workspace. This function is only invoked when validationProperties are matched with item
paramsToDependencyDescription (params)
This function should return DependencyDescription containing Type, Name and Location created based on given params. This function is used to check if the dependency that should be created based on parameters inputted by the user already exists in this workspace.

orion.project.deploy

The orion.project.deploy service is used to provide ways to deploy the project contents.

Service attributes

id
String
name
String
tooltip
String
deployTypes
String[] The list of deploy types, for instance ["ftp"]
priorityForDefault
optional Integer If there are more then one deployment of type defined in deployTypes this number will help which plugin should be use to perform the deployment
logLocationTemplate
optional UrlTemplate A template to location to deployment logs that will be resolved using the launchConfiguration, for instance "{+OrionHome}/deployment/logs.html#{Name,Params*}",
validationProperties
optional ValidationProperties[] that define if given item can be deployed by this deploy service, see Validation Properties

Service attributes for translation

The following attributes are optional, and are only used for translation.

nls
String The message bundle used to translate this deploy service's properties.
nameKey
String The property name used to look up the translated name of this deploy service within the message bundle.
tooltipKey
String The property name used to look up the translated tooltip for this deploy service within the message bundle.

Service methods

deploy(project, launchConf)
Preform the deployment. Returns the deploy result (may contain launch configuration to save) in callback or an error in errback
getState(properties)
optional Check the state of the deployed application, example result {State: "STARTED"}
start(properties)
optional Starts the deployed application, can return a state of the application
stop(properties)
optional Stops the deployed application, can return a state of the application
getDeployProgressMessage(project, launchConf)
optional Can return a string that will be displayed as a progress message while the application is being deployed

Response fields, applicable to all methods

ToSave
Object {Name(String), Params(Object), Url(String), ManageUrl(String, optional), Path(String, optional), Type(String)} Launch configuration description. Should be returned if launch configuration should be saved in the project and included in "Deployment Information" section on project page. Params attribute should contain all the information necessary to redeploy the application, Type must be identical with one of the deployTypes. Url contains the link to deployed application. ManageUrl should contain a link to any external configuration of the application provided. Path is default root of project.
Saved
Object {Name(String), Params(Object), Url(String), ManageUrl(String, optional), Path(String, optional), Type(String)} Same as ToSave, but indicates that the launch configuration was saved elsewhere outside of Orion and should be added to the view, but not saved to the file
Message
String Message to display to the user
State
String NOT_DEPLOYED, STARTED, STOPPED If application state was changed by the action
Retry
If some extra information is necessary Retry may contain a description of the parameters that user should be asked about. The results will be mixed in with the parameters when the function is retried. Example:
  1. Retry: {
  2.     parameters: [
  3.         {id: "user", type: "text", name: "User:"},
  4.         {id: "password", type: "password", name: "Password:"}
  5.     ]
  6. }
UriTemplate
Instead of Retry, plugin may return a template for a URL to load and take over the deployment, including the parameters collection. The full response example:
  1. {
  2.     UriTemplate: "{+OrionHome}/cfui/deployInteractive.html",
  3.     Width: "400px",
  4.     Height: "350px",
  5.     UriTemplateId: "org.eclipse.orion.client.cf.deploy.uritemplate"
  6. }

Back to the top