Difference between revisions of "Equinox Application Model Demo"

From Eclipsepedia

Jump to: navigation, search
(The Projects)
(3 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 
The Eclipse platform implements an application container that is based on the OSGi Application Admin Service specification.  This demo shows how Eclipse applications can be managed using the OSGi Application Admin Service specification
 
The Eclipse platform implements an application container that is based on the OSGi Application Admin Service specification.  This demo shows how Eclipse applications can be managed using the OSGi Application Admin Service specification
 
== The Projects ==
 
== The Projects ==
The projects for the demo are stored in the Equinox Incubator on the main Eclispe CVS repository (dev.eclipse.org:/cvsroot/eclipse).  All projects are under the directory '''equinox-incubator/demos/app-model/'''.
+
The projects for the demo are stored in the Equinox Incubator on the main Eclispe CVS repository (dev.eclipse.org:/cvsroot/rt).  All projects are under the directory '''org.eclipse.equinox/incubator/demos/app-model/'''.
 +
 
 +
A prebuilt version of the demo is available [http://eclipse.org/equinox/demos/DemoAppModel.zip here].
 
=== org.eclipse.equinox.examples.app.selector ===
 
=== org.eclipse.equinox.examples.app.selector ===
 
This project provides a simple RCP application that uses the application admin service to manage the other applications installed on the platform.
 
This project provides a simple RCP application that uses the application admin service to manage the other applications installed on the platform.
Line 15: Line 17:
  
 
== Running using the application selector GUI ==
 
== Running using the application selector GUI ==
This approach launches an RCP application called application selector.  This application is provided by the org.eclipse.equinox.examples.app.selector project.  Since this approach uses an RCP application many other bundles are required to run.  For example, the org.eclipse.ui.workbench and all of its dependencies.  The application selector displays the following information about each SWT example application installed on the platform:
+
Applications can be run using the application selector GUI or directly from the OSGi consoleThe application selector is an RCP application included in the org.eclipse.equinox.examples.app.selector bundle.  Since the selector is an RCP application, many other bundles are required to run.  For example, the org.eclipse.ui.workbench and all of its dependencies.  The application selector displays the following information about each SWT example application installed on the platform:
 
# The application name
 
# The application name
 
# If the application is enabled.
 
# If the application is enabled.
 
# The application state (inactive, starting, running, stopping)
 
# The application state (inactive, starting, running, stopping)
To start the application selector use the ''Eclipse Application'' launcher called ''demoAppSelector''.  This launcher is included in the org.eclipse.equinox.examples.app.selector project.
+
To start the application selector use the ''Eclipse Application'' launch configuration called ''demoAppSelector''.  This launch configuration is included in the org.eclipse.equinox.examples.app.selector project.
=== Start an Application ===
+
=== Starting applications ===
Select an application to start from the application selector then use the context menu to run the ''start'' operation.  Note that the ''start'' operation will be disabled if the application state is not currently ''inactive''.  This will cause the application to launch.  You should notice the state of the application move to ''running'' and the application will become disabled.  Disabled indicates that the application is no longer available for launch.  This is because all applications in this demo have a cardinality of 1.  Try launching other applications at the same time.  You will be able to launch all applications that are enabled at the same time.
+
To launch an application, select it in the application selector UI then use the context menu to run the '''start''' operation.  Note that the '''start''' action is disabled if the application state is not currently ''inactive''.  Once running the UI should show the application as ''running'' and the application should appear disabled.  The application is disabled (i.e., no longer available for launch) because all applications in this demo have a cardinality of 1 meaning that only one instance can be running at at time.  Try launching other applications at the same time.  You should be able to run one instance of all enabled applications.
  
=== Stop an Application ===
+
=== Stopping applications ===
Select an application to stop from the application selector then use the context menu to run the ''stop'' operation.  Note that the ''stop'' operation will be disabled if the application state is currently ''inactive''.  This will cause the application to stop.  You should notice the state of the application move to ''inactive''.
+
To stop an application, select it in the application selector then use the '''stop''' context menu operation.  Note that '''stop''' is disabled if the application state is currently ''inactive''.  Once the application is stopped you should notice that it moves to the ''inactive'' state.
  
 
=== Stop the Application Selector ===
 
=== Stop the Application Selector ===
If the application selector is stopped while one or more of the example SWT applications are running then it will stop all of them before exiting the application selector.
+
If the application selector is stopped while one or more of the example SWT applications are running then it stops all of them before exiting the application selector. '''this is not quite accurate currently.  Exiting the app selector leaves all applications running'''
  
 
== Running using the headless application ==
 
== Running using the headless application ==
This approach launches a ''headless application'' which sets up a shared display for the example SWT applications to use.  This application is provided by the org.eclipse.equinox.examples.sharedisplay projectThis approach does not use an RCP application which allows it to run with a minumum set of bundles.  Since there is no UI available to control applications we must use the osgi> console commands provided by the org.eclipse.equinox.app bundle to start and stop the applications.
+
Applications can also be launched and managed using a headless mechansim and the OSGi console.  The ''headless application'' sets up a shared display for the example SWT applications to use.  This application is provided by the org.eclipse.equinox.examples.sharedisplay bundleThe fact that it is headless allows it to run with a minumum set of bundles but of course you must use the osgi> console commands provided by the org.eclipse.equinox.app bundle to start and stop the applications.
  
 
To start the application selector use the ''OSGi Framework'' launcher called ''equinoxShareDisplay''.  This launcher is included in the org.eclipse.equinox.examples.sharedisplay project.
 
To start the application selector use the ''OSGi Framework'' launcher called ''equinoxShareDisplay''.  This launcher is included in the org.eclipse.equinox.examples.sharedisplay project.
=== Start an Application ===
+
=== Starting applications ===
To see a list of applications run the ''apps'' console command
+
To see a list of applications run the '''apps''' console command
 
<code>
 
<code>
 
  osgi> apps
 
  osgi> apps
Line 45: Line 47:
 
  org.eclipse.swt.examples.clipboard.app [enabled]
 
  org.eclipse.swt.examples.clipboard.app [enabled]
 
</code>
 
</code>
Pick an application id to start and run the ''startApp'' command.  This will cause the application to launch.
+
Pick an application id to start and run the '''startApp''' command.  This launches the application.
 
<code>
 
<code>
 
  osgi> startApp org.eclipse.swt.examples.paint.app
 
  osgi> startApp org.eclipse.swt.examples.paint.app
 
  Launched application: org.eclipse.swt.examples.paint.app
 
  Launched application: org.eclipse.swt.examples.paint.app
 
</code>
 
</code>
You should notice the application becomes disabled.  Disabled indicates that the application is no longer available for launch.  This is because all applications in this demo have a cardinality of 1.
+
You should notice that the application moves to disabled state indicating that it is no longer available for launch.  Again, this is because all applications in this demo have a cardinality of 1.
 
<code>
 
<code>
 
  osgi> apps
 
  osgi> apps
Line 62: Line 64:
 
</code>
 
</code>
  
Try launching other applications at the same time.  You will be able to launch all applications that are enabled at the same time.
+
Try launching other applications at the same time.  Again, you should be able to run one instance of each application at the same time.
=== Stop an Application ===
+
=== Stopping applications ===
To see a list of active applications run the ''activeApps'' console command
+
To see a list of active applications run the '''activeApps''' console command
 
<code>
 
<code>
 
  osgi> activeApps
 
  osgi> activeApps
Line 70: Line 72:
 
  org.eclipse.swt.examples.paint.app [running]
 
  org.eclipse.swt.examples.paint.app [running]
 
</code>
 
</code>
Pick an application id to stop and run the ''stopApp'' command.  This will cause the application to stop.
+
Pick an application id to stop and run the '''stopApp''' command.   
 
<code>
 
<code>
 
  osgi> stopApp org.eclipse.swt.examples.paint.app
 
  osgi> stopApp org.eclipse.swt.examples.paint.app
Line 76: Line 78:
 
</code>
 
</code>
 
=== Stop the Headless Share Display Application===
 
=== Stop the Headless Share Display Application===
If the headless application is stopped while one or more of the example SWT applications are running then it will stop all of them before exiting the headless application.
+
If the headless application is stopped while one or more of the example SWT applications are running then it will stop all of them before exiting the headless application. '''need to verify this'''
 +
 
 
== How it Works ==
 
== How it Works ==
 
=== The applications extension point ===
 
=== The applications extension point ===

Revision as of 22:30, 19 April 2009

The Eclipse platform implements an application container that is based on the OSGi Application Admin Service specification. This demo shows how Eclipse applications can be managed using the OSGi Application Admin Service specification

Contents

The Projects

The projects for the demo are stored in the Equinox Incubator on the main Eclispe CVS repository (dev.eclipse.org:/cvsroot/rt). All projects are under the directory org.eclipse.equinox/incubator/demos/app-model/.

A prebuilt version of the demo is available here.

org.eclipse.equinox.examples.app.selector

This project provides a simple RCP application that uses the application admin service to manage the other applications installed on the platform.

org.eclipse.equinox.examples.sharedisplay

This project provides a simple headless application that sets up a shared display that other applications can share when they are launched.

example SWT applications

Each of the following projects provide an example SWT application that can be launched using the application admin service

  • org.eclipse.swt.examples.addressbook
  • org.eclipse.swt.examples.browserexample
  • org.eclipse.swt.examples.clipboard
  • org.eclipse.swt.examples.graphics
  • org.eclipse.swt.examples.paint

Running using the application selector GUI

Applications can be run using the application selector GUI or directly from the OSGi console. The application selector is an RCP application included in the org.eclipse.equinox.examples.app.selector bundle. Since the selector is an RCP application, many other bundles are required to run. For example, the org.eclipse.ui.workbench and all of its dependencies. The application selector displays the following information about each SWT example application installed on the platform:

  1. The application name
  2. If the application is enabled.
  3. The application state (inactive, starting, running, stopping)

To start the application selector use the Eclipse Application launch configuration called demoAppSelector. This launch configuration is included in the org.eclipse.equinox.examples.app.selector project.

Starting applications

To launch an application, select it in the application selector UI then use the context menu to run the start operation. Note that the start action is disabled if the application state is not currently inactive. Once running the UI should show the application as running and the application should appear disabled. The application is disabled (i.e., no longer available for launch) because all applications in this demo have a cardinality of 1 meaning that only one instance can be running at at time. Try launching other applications at the same time. You should be able to run one instance of all enabled applications.

Stopping applications

To stop an application, select it in the application selector then use the stop context menu operation. Note that stop is disabled if the application state is currently inactive. Once the application is stopped you should notice that it moves to the inactive state.

Stop the Application Selector

If the application selector is stopped while one or more of the example SWT applications are running then it stops all of them before exiting the application selector. this is not quite accurate currently. Exiting the app selector leaves all applications running

Running using the headless application

Applications can also be launched and managed using a headless mechansim and the OSGi console. The headless application sets up a shared display for the example SWT applications to use. This application is provided by the org.eclipse.equinox.examples.sharedisplay bundle. The fact that it is headless allows it to run with a minumum set of bundles but of course you must use the osgi> console commands provided by the org.eclipse.equinox.app bundle to start and stop the applications.

To start the application selector use the OSGi Framework launcher called equinoxShareDisplay. This launcher is included in the org.eclipse.equinox.examples.sharedisplay project.

Starting applications

To see a list of applications run the apps console command

osgi> apps
org.eclipse.swt.examples.paint.app [enabled]
org.eclipse.swt.examples.graphics.app [enabled]
org.eclipse.swt.examples.addressbook.app [enabled]
org.eclipse.equinox.examples.sharedisplay.application [disabled]
org.eclipse.equinox.app.error [disabled]
org.eclipse.swt.examples.browserexample.app [enabled]
org.eclipse.swt.examples.clipboard.app [enabled]

Pick an application id to start and run the startApp command. This launches the application.

osgi> startApp org.eclipse.swt.examples.paint.app
Launched application: org.eclipse.swt.examples.paint.app

You should notice that the application moves to disabled state indicating that it is no longer available for launch. Again, this is because all applications in this demo have a cardinality of 1.

osgi> apps
org.eclipse.swt.examples.paint.app [disabled]
org.eclipse.swt.examples.graphics.app [enabled]
org.eclipse.swt.examples.addressbook.app [enabled]
org.eclipse.equinox.examples.sharedisplay.application [disabled]
org.eclipse.equinox.app.error [disabled]
org.eclipse.swt.examples.browserexample.app [enabled]
org.eclipse.swt.examples.clipboard.app [enabled]

Try launching other applications at the same time. Again, you should be able to run one instance of each application at the same time.

Stopping applications

To see a list of active applications run the activeApps console command

osgi> activeApps
org.eclipse.equinox.examples.sharedisplay.application [running]
org.eclipse.swt.examples.paint.app [running]

Pick an application id to stop and run the stopApp command.

osgi> stopApp org.eclipse.swt.examples.paint.app
Stopped application: org.eclipse.swt.examples.paint.app

Stop the Headless Share Display Application

If the headless application is stopped while one or more of the example SWT applications are running then it will stop all of them before exiting the headless application. need to verify this

How it Works

The applications extension point

Each application is declared using the org.eclipse.core.runtime.applications extension point. A bundle can declare an org.eclipse.core.runtime.applications extension to define an application in their plugin.xml file. An application extension is used to declare the following characteristics about an application.

  1. The application ID
  2. The application Name
  3. The application Cardinality. How many instances of the application can be running at the same time
  4. What thread must the application run on.
  5. What class provides the application implementation (IApplication)

The following is the Address Book application extension

<extension
  id="app"
  name="Address Book"
  point="org.eclipse.core.runtime.applications">
  <application
    cardinality="1"
    thread="any">
    <run
     class="org.eclipse.swt.examples.addressbook.Application">
    </run>
  </application>
</extension>

This extension defines the Address Book application and specifies that it can only have 1 instance running at a time and can run on any thread. It is important that it runs on any thread because in the demo the driving applications (the Application Selector or the Headless Application) are run on the main thread. This is necessary so that an SWT Display can be created and the SWT Event loop can be started on the main thread by the driving applications. All other applications are launched using separate threads and share the display created by the driving application.

ApplicationDescriptor Services

For each application extension defined the Eclipse application container registers an ApplicationDescriptor service (org.osgi.service.application.ApplicationDescriptor). This service can be used to perform the following operations

  1. Query properties of an installed application using the getProperties method. For example, if the application is enabled.
  2. Launch the application using the launch method.
  3. Schedule a condition to launch the application using the schedule method.
  4. Lock an application using the lock method.
  5. Unlock an application using the unlock method.

When an application is launched an ApplicationHandle is returned and is registered as a service. The ApplicationHandle can be used to stop an application using the destroy method.