Jump to: navigation, search

Difference between revisions of "Eclipse Web Interface"

m (Source Code: cat)
 
(37 intermediate revisions by one other user not shown)
Line 1: Line 1:
== About ==
+
==About==
  
This project aims to add the ability to invoke commands in Eclipse from an external web browser (ie: Firefox).
+
This project aims to add the ability to externally invoke commands in Eclipse via a web browser.
  
For example, this would enable a site to provide a link which causes Eclipse to fetch and open a source code file in a single click where a sample link might look similar to the following:
+
For example, this could enable a site to provide a link which would cause Eclipse to fetch and open a source code file in a single click. A sample link might look similar to the following:
  
<code><pre><a href="http://localhost:56789?command=open_file&filepath=http://someWhereOnTheWeb/foo.java">open this file in Eclipse!</a></pre></code>
+
<pre>
 +
<a href="http://localhost:56789?command=open_file&filepath=http://someWhereOnTheWeb/foo.java">open this file in Eclipse!</a>
 +
</pre>
  
The command and any of its required parameters will be contained solely within the url handed to Eclipse.  The whole idea is centered around Eclipse "listening"(on localhost aka 127.0.0.1) for commands passed via HTTP, receiving the command, and then performing the action(s) associated with that command.
+
Eclipse will listen for these requests and, when received, invoke the command in one of the currently running Eclipse instances.
  
== Primary Goals ==
+
''Note: just to avoid any confusion, this example assumes that an "open_file" command has been written which supplies the aforementioned functionality.''
  
1. Integration of a light-weight web server for intercepting remote commands.
+
==Primary Goals==
* It may be possible to utilize this? [http://easyeclipse.cvs.sourceforge.net/easyeclipse/easyupdate/org.nexb.easyeclipse.softwareupdate.test/tst/org/nexb/easyeclipse/softwareupdate/download/ NanoHTTPD]
+
  
2. Specification and integration of a generic command addition and removal interface.
+
===Legend===
 +
[[Image:Glass.gif]] Needs some investigation
 +
[[Image:Progress.gif]] Patch in progress
 +
[[Image:Ok_green.gif]] Bug fixed / Feature added
  
== Schedule ==
+
===Goals===
 +
[[Image:Ok_green.gif]] Integration of a web server for intercepting remote commands.
 +
* [http://elonen.iki.fi/code/nanohttpd/ NanoHTTPD] is currently being utilized for this purpose as it is a less complex alternative to using one of the OSGi Http Service implementations (org.eclipse.equinox.http.jetty or org.eclipse.equinox.http). See [[#Secondary Goals]].
  
Tentatively as follows:
+
[[Image:Ok_green.gif]] Look up and invoke commands
 +
* The [http://wiki.eclipse.org/index.php/Platform_Command_Framework Platform Command Framework] is being looked at as a means for accomplishing this.
  
 +
==Secondary Goals==
  
1. Analysis (up until May 28):
+
[[Image:Ok_green.gif]] Implement support for multiple instances (as outlined below)
 +
* this does not include support for headless Eclipse instances
  
This phase will involve interaction with the mentor to estimate the exact requirements of the project and research in order to gain more familiarity with the Eclipse framework.  It will also involve setting up the project infrastructure such as the code repository.
+
[[Image:Glass.gif]] Adapt to make use of an OSGi Http Service implementation
  
 +
==Design Ideas==
  
2. Development Part I (May 28 - June 21):
+
Firstly, to have the server load on startup the the [http://help.eclipse.org/help32/index.jsp?topic=/org.eclipse.platform.doc.isv/reference/extension-points/org_eclipse_ui_startup.html startup extension point] will be used.  This startup code will then start an [http://help.eclipse.org/help32/index.jsp?topic=/org.eclipse.platform.doc.isv/guide/runtime_jobs.htm eclipse job] which will run in the background and behave as a wrapper around the web server. 
  
This phase will involve the development of the code which listens for and responds to command execution requests.
+
The wrapper will do the following
 +
# check if any commands have been received by the server
 +
# if commands exist then for each command
 +
##  if a handler exists for the command then forward the parameters to that handler
  
 +
Relevant links
 +
*[http://www.eclipse.org/articles/Article-Concurrency/jobs-api.html On the Job: The Eclipse Jobs API]
 +
*[http://help.eclipse.org/help32/index.jsp?topic=/org.eclipse.platform.doc.isv/guide/runtime_jobs.htm Concurrency infrastructure]
 +
*[http://help.eclipse.org/help32/index.jsp?topic=/org.eclipse.platform.doc.isv/reference/api/org/eclipse/core/runtime/jobs/Job.html Class Job]
 +
===Dealing with multiple Eclipse instances===
  
3. Development Part II (June 22 - July 16):
+
Special handling is necessary when dealing with multiple instances of Eclipse. For example, when a command 'foo' is received (e.g. <nowiki>http://localhost:34567?command=foo</nowiki>) and there are two or more instances running, which both support the 'foo' command, which instance should execute 'foo'?
  
This phase involves the creation and implementation of a generic way to add and remove commands to a list of "active" commands.
+
One way to handle this could be to have one Eclipse instance act as a sort of 'main hub'.  To clarify, all commands would first be received by this instance.  When necessary, this main instance would forward commands to other instances.  The instance that a command gets forwarded to would be chosen by the user via a dialog which lists all viable Eclipse instances (i.e. those which support the command).
  
 +
====Implementation Strategy====
  
4. Testing and Wrap-Up (July 17 - August 28):
+
The first Eclipse instance loaded will utilize the default port (e.g. 34567) and act as the main instance as described above.
  
This phase involves thoroughly testing each aspect of the finished project and tieing up any loose ends.
+
Then, when a second(or third, fourth, etc.) instance is launched it tries to obtain the default port.  Since it will not be able to(because it's already in use by the main instance) it chooses a random unused port and then registers itself with the main instance which will always be found on a defined default port (34567 in this case).
  
 +
<pre>e.g. [Eclipse instance #2] --> http://localhost:34567?command=registereclipse&port=56789 --> [main Eclipse instance]</pre>
  
* NOTE: Some intermingling and modification of these phases will most likely be necessary :-)
+
Now the main instance is aware of the second. At this point the main instance can request a list of commands supported by the second instance.  This will be useful for disambiguating which Eclipse instance should handle a command when there are multiple instances which can handle the same command.
  
== Legend ==
+
So when the main instance receives a command a dialog can be shown which will list all the instances supporting the command. The user then picks which instance the request should be forwarded to.
[[Image:Glass.gif]] Needs some investigation
+
  
[[Image:Progress.gif]] Patch in progress
+
What should be done when an instance terminates? One approach is to require that all non-main instances send ping-like messages(e.g. resending the registereclipse command) to the main instance at a regular interval.  The purpose of these messages would be twofold:
 +
# It would allow the main instance to keep track of 'alive' secondary instances.
 +
# It would allow a secondary instance to detect if the main instance has terminated.  The discovering instance could then take over listening on the default port and become the new main instance.
  
[[Image:Ok_green.gif]] Bug fixed / Feature added
+
==Related Bugs==
 +
 
 +
* [EditorMgmt] Need ability to open a file in eclipse from the command line (see [https://bugs.eclipse.org/bugs/show_bug.cgi?id=4922 bug 4922])
 +
* [launcher] way to pass arguments from launcher to a running application instance (see [https://bugs.eclipse.org/bugs/show_bug.cgi?id=178927 bug 178927])
 +
** this could be used as the extension associated with an 'open' command
 +
* Windows Explorer Shell Extension Possible? (see [https://bugs.eclipse.org/bugs/show_bug.cgi?id=183266 bug 183266])
 +
* Provide an external program to run commands in a running Eclipse instance (like gnuclient) (see [https://bugs.eclipse.org/bugs/show_bug.cgi?id=186147 bug 186147])
 +
 
 +
==Documentation==
 +
 
 +
===Installation===
 +
 
 +
The simplest installation route is to use the update manager (''Help > Software Updates > Find and Install...'') with the following remote site:
 +
 
 +
http://eclipse-incub.cvs.sourceforge.net/*checkout*/eclipse-incub/org.eclipse.soc.ewi/update/org.eclipse.soc.ewi.update/site.xml
 +
 
 +
The other option is to get the [[#Source Code]] and install the plug-in manually.
 +
 
 +
===Quick start===
 +
 
 +
Once you've got the plugin installed, to quickly see some commands in action, here are a few sample links you can try:
 +
# [http://localhost:34567/?command=org.eclipse.ui.file.export&exportWizardId=org.eclipse.jdt.internal.ui.jarpackager.JarPackageWizard Create a New JAR File]
 +
# [http://localhost:34567/?command=org.eclipse.ui.file.export&exportWizardId=org.eclipse.jdt.internal.ui.javadocexport.JavadocWizard Generate some Javadoc]
 +
# [http://localhost:34567/?command=org.eclipse.ui.perspectives.showPerspective Select a Perspective]
 +
 
 +
To specify a command yourself, point your browser to:
 +
<pre>
 +
http://localhost:34576/?command=IDofCommand&parm1=foo&parm2=bar&parmN=bak
 +
</pre>
 +
Simply replace ''IDofCommand'' with the identifier of the command you want to run. As well, if applicable, replace ''parm1'', ''parm2'', etc. with valid parameter names and values.
 +
 
 +
Note: In the event a command actually has a parameter named "command", the first "command" value from the left will be used as the command ID and the other will be used as a parameter. So, to be safe, make sure the command you want to run is specified '''before''' any of it's parameters.
 +
 
 +
===Contributing your own commands===
 +
 
 +
To contribute your own command, your plugin must:
 +
# define a command via the [http://help.eclipse.org/help33/index.jsp?topic=/org.eclipse.platform.doc.isv/guide/workbench_cmd_commands.htm org.eclipse.ui.commands] extension point and
 +
# define a handler via the [http://help.eclipse.org/help33/index.jsp?topic=/org.eclipse.platform.doc.isv/guide/workbench_cmd_handlers.htm org.eclipse.ui.handlers] extension point
 +
 
 +
Here's a sample plugin.xml of a plugin reachable through the Web Interface:
 +
 
 +
<pre>
 +
<plugin>
 +
  <extension
 +
        point="org.eclipse.ui.commands">
 +
      <category
 +
            id="org.eclipse.soc.ewi.examples.commands"
 +
            name="Example Commands">
 +
      </category>
 +
      <command
 +
            categoryId="org.eclipse.soc.ewi.examples.commands"
 +
            description="Open a file in the active workbench window."
 +
            id="org.eclipse.soc.ewi.examples.commands.openfile"
 +
            name="Open File">
 +
        <commandParameter
 +
              id="path"
 +
              name="File Path"
 +
              optional="false">
 +
        </commandParameter>
 +
      </command>
 +
  </extension>
 +
  <extension
 +
        point="org.eclipse.ui.handlers">
 +
      <handler
 +
            class="org.eclipse.soc.ewi.examples.openfile.OpenFileHandler"
 +
            commandId="org.eclipse.soc.ewi.examples.commands.openfile">
 +
      </handler>
 +
  </extension>
 +
 
 +
</plugin>
 +
</pre>
 +
 
 +
You would invoke the above plugin by targeting:
 +
<pre>
 +
http://localhost:34567/?command=org.eclipse.soc.ewi.examples.commands.openfile&path=/path/somefile.txt
 +
</pre>
 +
 
 +
==Source Code==
 +
 
 +
For now the source code can be found in the [http://eclipse-incub.cvs.sourceforge.net/eclipse-incub/org.eclipse.soc.ewi/ org.eclipse.soc.ewi] module on [http://www.sf.net/ SourceForge.net].
 +
 
 +
* [http://eclipse-incub.cvs.sourceforge.net/eclipse-incub/org.eclipse.soc.ewi/plugins/org.eclipse.soc.ewi/ org.eclipse.soc.ewi] - this is the base plugin which provides command interception/execution functionality
 +
* [http://eclipse-incub.cvs.sourceforge.net/eclipse-incub/org.eclipse.soc.ewi/examples/org.eclipse.soc.ewi.examples.openfile/ org.eclipse.soc.ewi.examples.openfile] - this is an example of a plugin which contributes a command(opening a file) that is accessible by the base plugin
 +
 
 +
[[Category:SOC]]

Latest revision as of 16:37, 14 October 2007

About

This project aims to add the ability to externally invoke commands in Eclipse via a web browser.

For example, this could enable a site to provide a link which would cause Eclipse to fetch and open a source code file in a single click. A sample link might look similar to the following:

<a href="http://localhost:56789?command=open_file&filepath=http://someWhereOnTheWeb/foo.java">open this file in Eclipse!</a>

Eclipse will listen for these requests and, when received, invoke the command in one of the currently running Eclipse instances.

Note: just to avoid any confusion, this example assumes that an "open_file" command has been written which supplies the aforementioned functionality.

Primary Goals

Legend

Glass.gif Needs some investigation
Progress.gif Patch in progress
Ok green.gif Bug fixed / Feature added

Goals

Ok green.gif Integration of a web server for intercepting remote commands.

  • NanoHTTPD is currently being utilized for this purpose as it is a less complex alternative to using one of the OSGi Http Service implementations (org.eclipse.equinox.http.jetty or org.eclipse.equinox.http). See #Secondary Goals.

Ok green.gif Look up and invoke commands

Secondary Goals

Ok green.gif Implement support for multiple instances (as outlined below)

  • this does not include support for headless Eclipse instances

Glass.gif Adapt to make use of an OSGi Http Service implementation

Design Ideas

Firstly, to have the server load on startup the the startup extension point will be used. This startup code will then start an eclipse job which will run in the background and behave as a wrapper around the web server.

The wrapper will do the following

  1. check if any commands have been received by the server
  2. if commands exist then for each command
    1. if a handler exists for the command then forward the parameters to that handler

Relevant links

Dealing with multiple Eclipse instances

Special handling is necessary when dealing with multiple instances of Eclipse. For example, when a command 'foo' is received (e.g. http://localhost:34567?command=foo) and there are two or more instances running, which both support the 'foo' command, which instance should execute 'foo'?

One way to handle this could be to have one Eclipse instance act as a sort of 'main hub'. To clarify, all commands would first be received by this instance. When necessary, this main instance would forward commands to other instances. The instance that a command gets forwarded to would be chosen by the user via a dialog which lists all viable Eclipse instances (i.e. those which support the command).

Implementation Strategy

The first Eclipse instance loaded will utilize the default port (e.g. 34567) and act as the main instance as described above.

Then, when a second(or third, fourth, etc.) instance is launched it tries to obtain the default port. Since it will not be able to(because it's already in use by the main instance) it chooses a random unused port and then registers itself with the main instance which will always be found on a defined default port (34567 in this case).

e.g. [Eclipse instance #2] --> http://localhost:34567?command=registereclipse&port=56789 --> [main Eclipse instance]

Now the main instance is aware of the second. At this point the main instance can request a list of commands supported by the second instance. This will be useful for disambiguating which Eclipse instance should handle a command when there are multiple instances which can handle the same command.

So when the main instance receives a command a dialog can be shown which will list all the instances supporting the command. The user then picks which instance the request should be forwarded to.

What should be done when an instance terminates? One approach is to require that all non-main instances send ping-like messages(e.g. resending the registereclipse command) to the main instance at a regular interval. The purpose of these messages would be twofold:

  1. It would allow the main instance to keep track of 'alive' secondary instances.
  2. It would allow a secondary instance to detect if the main instance has terminated. The discovering instance could then take over listening on the default port and become the new main instance.

Related Bugs

  • [EditorMgmt] Need ability to open a file in eclipse from the command line (see bug 4922)
  • [launcher] way to pass arguments from launcher to a running application instance (see bug 178927)
    • this could be used as the extension associated with an 'open' command
  • Windows Explorer Shell Extension Possible? (see bug 183266)
  • Provide an external program to run commands in a running Eclipse instance (like gnuclient) (see bug 186147)

Documentation

Installation

The simplest installation route is to use the update manager (Help > Software Updates > Find and Install...) with the following remote site:

http://eclipse-incub.cvs.sourceforge.net/*checkout*/eclipse-incub/org.eclipse.soc.ewi/update/org.eclipse.soc.ewi.update/site.xml

The other option is to get the #Source Code and install the plug-in manually.

Quick start

Once you've got the plugin installed, to quickly see some commands in action, here are a few sample links you can try:

  1. Create a New JAR File
  2. Generate some Javadoc
  3. Select a Perspective

To specify a command yourself, point your browser to:

http://localhost:34576/?command=IDofCommand&parm1=foo&parm2=bar&parmN=bak

Simply replace IDofCommand with the identifier of the command you want to run. As well, if applicable, replace parm1, parm2, etc. with valid parameter names and values.

Note: In the event a command actually has a parameter named "command", the first "command" value from the left will be used as the command ID and the other will be used as a parameter. So, to be safe, make sure the command you want to run is specified before any of it's parameters.

Contributing your own commands

To contribute your own command, your plugin must:

  1. define a command via the org.eclipse.ui.commands extension point and
  2. define a handler via the org.eclipse.ui.handlers extension point

Here's a sample plugin.xml of a plugin reachable through the Web Interface:

<plugin>
   <extension
         point="org.eclipse.ui.commands">
      <category
            id="org.eclipse.soc.ewi.examples.commands"
            name="Example Commands">
      </category>
      <command
            categoryId="org.eclipse.soc.ewi.examples.commands"
            description="Open a file in the active workbench window."
            id="org.eclipse.soc.ewi.examples.commands.openfile"
            name="Open File">
         <commandParameter
               id="path"
               name="File Path"
               optional="false">
         </commandParameter>
      </command>
   </extension>
   <extension
         point="org.eclipse.ui.handlers">
      <handler
            class="org.eclipse.soc.ewi.examples.openfile.OpenFileHandler"
            commandId="org.eclipse.soc.ewi.examples.commands.openfile">
      </handler>
   </extension>

</plugin>

You would invoke the above plugin by targeting:

http://localhost:34567/?command=org.eclipse.soc.ewi.examples.commands.openfile&path=/path/somefile.txt

Source Code

For now the source code can be found in the org.eclipse.soc.ewi module on SourceForge.net.