Jump to: navigation, search

Difference between revisions of "Riena/RAP Support"

(Known Issues)
m (Set up target platform for Riena on RAP apps)
(9 intermediate revisions by 3 users not shown)
Line 1: Line 1:
This page is a whiteboard with information about running Riena on RAP and known issues.
+
{{RienaBreadcrumbs |
 +
[[Riena Project]] | [[Riena Getting started|Getting Started]] | Riena/RAP Support}}
  
== Getting Started ==
+
{| align="right"
 +
|-
 +
| __TOC__
 +
|}
  
See [http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.riena/org.eclipse.riena.releng.rap/readme.txt?root=RT_Project&view=co readme.txt] in org.eclipse.riena.releng.rap for the most current information.
+
== Set up target platform for Riena on RAP apps  ==
  
== Known Issues ==
+
For a Riena on RAP-based application to compile, a certain set of bundles (plug-ins) must be available at compile time. This set of bundles is known as a [http://help.eclipse.org/galileo/topic/org.eclipse.pde.doc.user/concepts/target.htm target platform]. Follow the steps outlined in either of the following two sections to set up the target platform for Riena on RAP applications (based on Riena 3.0.0).
  
This is ongoing work. Expect more issues to be added.
+
'''Setup'''
  
* [ui] Error Marker decoration does not show
+
*Download Eclipse IDE 3.7.x for your platform and start with a blank workspace.
* [ui] Splash Dialog is not supported in RAP - affects riena login mechanism
+
*Create a new target platform under Window => Preferences => Target Platform => Add => Nothing: Start with an empty target platform => Next
* [ui] Custom text ridgets (numeric, decimal, date) don't work because of differences in event handling
+
*Provide a name like Riena 3.0.0
* [ui] CompletionCombo - icon for drop-down button missing
+
*Click Add => Software Site
* [rap] No support for keyboard shortcuts / mnemonics
+
*Select the Indigo Repository: http://download.eclipse.org/releases/indigo/
 +
*Uncheck "Group by Category" otherwise you can't see all 3 RCP Target Components.
 +
*Uncheck "Include required software".
 +
*Select "Equinox Target Components", "Remote Application Platform (RAP) Target Components"
 +
*Go back to "Add => Software Site
 +
*Select http://download.eclipse.org/rt/riena/3.0.0.0/rap/  
 +
*Select "Riena Target Components" from here: . The result should look like this:
  
== Fixed Issues (on HEAD branch) ==
+
[[Image:Riena_RAP_Targetplatform_Screenshot.png]]  
* [ui] SWT UI Synchronizer is broken - likely fix: receive an external display reference at construction time
+
* [ui] Dialog based classes (RienaMessageDialog, UIProcessWindow) don't work - their renderer needs single-sourcing
+
* [ui] DatePicker - icon on 'picker' button missing
+
* [navi] Navigation model does not support multiple users (singleton)
+
* [navi] Submodules (i.e. tree element) sometimes need two clicks before the corresponding view is shown
+
* [ui] Playground - Link/Browser demo - link needs two clicks before browser is updated
+
  
== Common Problems ==
+
*Activate the platform.  
While ''porting'' Riena to RAP we encounter several issues (some say challenges). Most (or probably all) of these issues are well known and RAP has already solutions for them - see [[RAP/FAQ|FAQs]].
+
*Done.
  
The goals for the port are:
+
<br> '''Next Step'''
* do not place a burden to the users of Riena
+
* the impact (of this port) should not harm (efficency, code bloat, ..) Riena when used in a RCP fashion
+
* ..
+
  
The following sections describe concrete problems and patterns how to solve them.
+
Now you are ready to start writing Riena applications (ensure that in such a launch configuration the bundle '''org.eclipse.riena.ui.swt.rap''' is selected as required bundle). To get a feeling of the Riena framework, take a look at Riena's [[Riena Example Applications and Code Templates|Example Applications and Code Templates]]. Make sure that you click on "Add Required bundles" before you start any of the examples that come with Riena.
  
=== Platform specific implementations ===
+
<br> This page is a whiteboard with information about running Riena on RAP and known issues.
  
Although RAP handles a lot of SWT's funtionality for the web, there is functionality that it does not (yet) handle.
+
== Getting Started with the Source Code  ==
For these cases Elias introduced the facade factory pattern. (The following description is picked from a mail to riena-dev)
+
  
The facade factory only works because of some careful bundle/classpath engineering. It is crafted for one particular use, i.e picking between RAP/RCP.
+
*[Tooling]
 +
**Install the Rich Ajax Platform (RAP) Tools
 +
**Help -&gt; Install New Software...
  
Here are the prerequisites:
+
*[Target platform]
 +
**Use RAP 1.5 or later as your target.
 +
**http://eclipse.org/rap/downloads/
 +
**Add the Equinox SDK to the target platform.
 +
**http://download.eclipse.org/equinox/
  
* three bundles are necessary. Two of them have different dependencies (swt vs rwt)
+
*[Projects]
* facadeFactory and the facade implementations are in the same package in all three bundles
+
**Clone the Riena repository <source lang="bash">git://dev.eclipse.org/gitroot/riena/org.eclipse.riena.git</source>
* the .swt.rap and swt.rcp bundles are buddies to o.e.r.ui.swt so that the FacadeFactory has access to their classpaths and can instantiante classes from the common package.
+
**Clone the Riena RAP repository <source lang="bash">git://dev.eclipse.org/gitroot/riena/org.eclipse.riena.rap.git</source>
* there is a naming convention <FacadeName>RAP <FacadeName>RCP
+
**Import org.eclipse.riena.releng.rap/riena_on_rap-pserver.psf (CVS user: anonymous)
  
=== Singletons ===
+
*There should be (almost) no compiler errors at this point.
There are two kinds of singletons within Riena
+
# Class.getInstance() based singletons (based on a static getInstance() method), e.g. NavigationNodeProvider
+
# Class.staticMethods() based singletons (based on static methods and static fields, i.e there is some state), e.g. ApplicationNodeManager<br>''Note'': Classes with only static methods and no static fields are not singletons
+
  
To solve the singleton problem within RAP it provides the (abstract) SessionSingletonBase class that is able to create session-dependent singletons. This class may be used directly by calling it's (static) getInstance(Class type) method or by sub-classing and providing a taylored (static) getInstance() method.
+
*Launch 'RAP Mail Sample (RCP UI)' in
With this it is very easy to transform the first singleton type and a little bit more work to transform the second type - both without breaking the current interface of course.
+
**org.eclipse.riena.sample.app.client.rcpmail
  
The straightforward technique of just passing a class to the getInstance() method is for most cases sufficent. However, it does not allow to:
+
*Launch some of the other 'RAP .....launch' configurations in the other examples.
* use constructors with parameters
+
* it is not possible to "wire" the singleton (wiring is the term we use for Riena's dependency injection)
+
  
Of course, it possible to create workarounds:
+
*[Important]
* use setters instead of constructor parameters - may result in undesired usage
+
**Do not use "Add required bundles" since it may add some RCP bundles, which are not desired in a RAP launch configuration.
* do the wiring within the constructor - makes e.g. unit testing more complicated
+
  
The introduction of e.g. an IInstanceFactory interface with a single getInstance() method could solve this. The class implementing the IInstanceFactory could then internally be used for creating the key to store the singleton in the session store.
+
<br>
And the usage of generics would be a nice bonus.
+
  
=== OSGi Services ===
+
== Known Issues  ==
A OSGi Service is also some kind of singleton, i.e. it exists only once in a JVM. How to deal with services that have (session dependent) state?
+
  
=== ThreadLocal ===
+
This is ongoing work. Expect more issues to be added.
This is just a reminder! Are ThreadLocals safe?
+
  
=== ContainerModel ===
+
*[ui] Application logo does not show (no PaintListener notifications)
This is just a reminder! This utility tells whether it is running on a client or a server. This allows to implement common code that behaves differently on client or server.
+
*[ui] Navigation scrolling does not work as expected
We have to think about that!
+
*[ui] Error Marker decoration does not show
 +
*[ui] Splash Dialog is not supported in RAP - affects riena login mechanism
 +
*[ui] Custom text ridgets (numeric, decimal, date) don't work because of differences in event handling
 +
*[ui] CompletionCombo - icon for drop-down button missing
 +
*[rap] No support for keyboard shortcuts / mnemonics
 +
 
 +
== Fixed Issues (on HEAD branch)  ==
 +
 
 +
*[ui] SWT UI Synchronizer is broken - likely fix: receive an external display reference at construction time
 +
*[ui] Dialog based classes (RienaMessageDialog, UIProcessWindow) don't work - their renderer needs single-sourcing
 +
*[ui] DatePicker - icon on 'picker' button missing
 +
*[navi] Navigation model does not support multiple users (singleton)
 +
*[navi] Submodules (i.e. tree element) sometimes need two clicks before the corresponding view is shown
 +
*[ui] Playground - Link/Browser demo - link needs two clicks before browser is updated
 +
*[ui] InfoFlyout - need RAP specific implementation (also: discuss animations in RAP team)
 +
*[rap] Widget traversal by hitting TAB
 +
 
 +
== Common Problems  ==
 +
 
 +
While ''porting'' Riena to RAP we encounter several issues (some say challenges). Most (or probably all) of these issues are well known and RAP has already solutions for them - see [[RAP/FAQ|FAQs]].
 +
 
 +
The goals for the port are:
 +
 
 +
*do not place a burden to the users of Riena
 +
*the impact (of this port) should not harm (efficency, code bloat, ..) Riena when used in a RCP fashion
 +
*..
 +
 
 +
The following sections describe concrete problems and patterns how to solve them.
 +
 
 +
=== Platform specific implementations  ===
 +
 
 +
Although RAP handles a lot of SWT's funtionality for the web, there is functionality that it does not (yet) handle. For these cases Elias introduced the facade factory pattern. (The following description is picked from a mail to riena-dev)
 +
 
 +
The facade factory only works because of some careful bundle/classpath engineering. It is crafted for one particular use, i.e picking between RAP/RCP.
 +
 
 +
Here are the prerequisites:
 +
 
 +
*three bundles are necessary. Two of them have different dependencies (swt vs rwt)
 +
*facadeFactory and the facade implementations are in the same package in all three bundles
 +
*the .swt.rap and swt.rcp bundles are buddies to o.e.r.ui.swt so that the FacadeFactory has access to their classpaths and can instantiante classes from the common package.
 +
*there is a naming convention &lt;FacadeName&gt;RAP &lt;FacadeName&gt;RCP
 +
 
 +
=== Singletons  ===
 +
 
 +
There are two kinds of singletons within Riena
 +
 
 +
#Class.getInstance() based singletons (based on a static getInstance() method), e.g. NavigationNodeProvider
 +
#Class.staticMethods() based singletons (based on static methods and static fields, i.e there is some state), e.g. ApplicationNodeManager<br>''Note'': Classes with only static methods and no static fields are not singletons
 +
 
 +
To solve the singleton problem within RAP it provides the (abstract) SessionSingletonBase class that is able to create session-dependent singletons. This class may be used directly by calling it's (static) getInstance(Class type) method or by sub-classing and providing a taylored (static) getInstance() method. With this it is very easy to transform the first singleton type and a little bit more work to transform the second type - both without breaking the current interface of course.
 +
 
 +
The straightforward technique of just passing a class to the getInstance() method is for most cases sufficent. However, it does not allow to:
 +
 
 +
*use constructors with parameters
 +
*it is not possible to "wire" the singleton (wiring is the term we use for Riena's dependency injection)
 +
 
 +
Of course, it possible to create workarounds:
 +
 
 +
*use setters instead of constructor parameters - may result in undesired usage
 +
*do the wiring within the constructor - makes e.g. unit testing more complicated
 +
 
 +
The introduction of e.g. an IInstanceFactory interface with a single getInstance() method could solve this. The class implementing the IInstanceFactory could then internally be used for creating the key to store the singleton in the session store. And the usage of generics would be a nice bonus.
 +
 
 +
=== OSGi Services  ===
 +
 
 +
A OSGi Service is also some kind of singleton, i.e. it exists only once in a JVM. How to deal with services that have (session dependent) state?
 +
 
 +
=== ThreadLocal  ===
 +
 
 +
This is just a reminder! Are ThreadLocals safe?
 +
 
 +
=== ContainerModel ===
 +
 
 +
This is just a reminder! This utility tells whether it is running on a client or a server. This allows to implement common code that behaves differently on client or server. We have to think about that!  
  
 
[[Category:Riena]] [[Category:RAP]]
 
[[Category:Riena]] [[Category:RAP]]

Revision as of 12:18, 5 April 2013

Riena ProjectGetting Started ▶ Riena/RAP Support

Set up target platform for Riena on RAP apps

For a Riena on RAP-based application to compile, a certain set of bundles (plug-ins) must be available at compile time. This set of bundles is known as a target platform. Follow the steps outlined in either of the following two sections to set up the target platform for Riena on RAP applications (based on Riena 3.0.0).

Setup

  • Download Eclipse IDE 3.7.x for your platform and start with a blank workspace.
  • Create a new target platform under Window => Preferences => Target Platform => Add => Nothing: Start with an empty target platform => Next
  • Provide a name like Riena 3.0.0
  • Click Add => Software Site
  • Select the Indigo Repository: http://download.eclipse.org/releases/indigo/
  • Uncheck "Group by Category" otherwise you can't see all 3 RCP Target Components.
  • Uncheck "Include required software".
  • Select "Equinox Target Components", "Remote Application Platform (RAP) Target Components"
  • Go back to "Add => Software Site
  • Select http://download.eclipse.org/rt/riena/3.0.0.0/rap/
  • Select "Riena Target Components" from here: . The result should look like this:

Riena RAP Targetplatform Screenshot.png

  • Activate the platform.
  • Done.


Next Step

Now you are ready to start writing Riena applications (ensure that in such a launch configuration the bundle org.eclipse.riena.ui.swt.rap is selected as required bundle). To get a feeling of the Riena framework, take a look at Riena's Example Applications and Code Templates. Make sure that you click on "Add Required bundles" before you start any of the examples that come with Riena.


This page is a whiteboard with information about running Riena on RAP and known issues.

Getting Started with the Source Code

  • [Tooling]
    • Install the Rich Ajax Platform (RAP) Tools
    • Help -> Install New Software...
  • [Projects]
    • Clone the Riena repository
      git://dev.eclipse.org/gitroot/riena/org.eclipse.riena.git
    • Clone the Riena RAP repository
      git://dev.eclipse.org/gitroot/riena/org.eclipse.riena.rap.git
    • Import org.eclipse.riena.releng.rap/riena_on_rap-pserver.psf (CVS user: anonymous)
  • There should be (almost) no compiler errors at this point.
  • Launch 'RAP Mail Sample (RCP UI)' in
    • org.eclipse.riena.sample.app.client.rcpmail
  • Launch some of the other 'RAP .....launch' configurations in the other examples.
  • [Important]
    • Do not use "Add required bundles" since it may add some RCP bundles, which are not desired in a RAP launch configuration.


Known Issues

This is ongoing work. Expect more issues to be added.

  • [ui] Application logo does not show (no PaintListener notifications)
  • [ui] Navigation scrolling does not work as expected
  • [ui] Error Marker decoration does not show
  • [ui] Splash Dialog is not supported in RAP - affects riena login mechanism
  • [ui] Custom text ridgets (numeric, decimal, date) don't work because of differences in event handling
  • [ui] CompletionCombo - icon for drop-down button missing
  • [rap] No support for keyboard shortcuts / mnemonics

Fixed Issues (on HEAD branch)

  • [ui] SWT UI Synchronizer is broken - likely fix: receive an external display reference at construction time
  • [ui] Dialog based classes (RienaMessageDialog, UIProcessWindow) don't work - their renderer needs single-sourcing
  • [ui] DatePicker - icon on 'picker' button missing
  • [navi] Navigation model does not support multiple users (singleton)
  • [navi] Submodules (i.e. tree element) sometimes need two clicks before the corresponding view is shown
  • [ui] Playground - Link/Browser demo - link needs two clicks before browser is updated
  • [ui] InfoFlyout - need RAP specific implementation (also: discuss animations in RAP team)
  • [rap] Widget traversal by hitting TAB

Common Problems

While porting Riena to RAP we encounter several issues (some say challenges). Most (or probably all) of these issues are well known and RAP has already solutions for them - see FAQs.

The goals for the port are:

  • do not place a burden to the users of Riena
  • the impact (of this port) should not harm (efficency, code bloat, ..) Riena when used in a RCP fashion
  • ..

The following sections describe concrete problems and patterns how to solve them.

Platform specific implementations

Although RAP handles a lot of SWT's funtionality for the web, there is functionality that it does not (yet) handle. For these cases Elias introduced the facade factory pattern. (The following description is picked from a mail to riena-dev)

The facade factory only works because of some careful bundle/classpath engineering. It is crafted for one particular use, i.e picking between RAP/RCP.

Here are the prerequisites:

  • three bundles are necessary. Two of them have different dependencies (swt vs rwt)
  • facadeFactory and the facade implementations are in the same package in all three bundles
  • the .swt.rap and swt.rcp bundles are buddies to o.e.r.ui.swt so that the FacadeFactory has access to their classpaths and can instantiante classes from the common package.
  • there is a naming convention <FacadeName>RAP <FacadeName>RCP

Singletons

There are two kinds of singletons within Riena

  1. Class.getInstance() based singletons (based on a static getInstance() method), e.g. NavigationNodeProvider
  2. Class.staticMethods() based singletons (based on static methods and static fields, i.e there is some state), e.g. ApplicationNodeManager
    Note: Classes with only static methods and no static fields are not singletons

To solve the singleton problem within RAP it provides the (abstract) SessionSingletonBase class that is able to create session-dependent singletons. This class may be used directly by calling it's (static) getInstance(Class type) method or by sub-classing and providing a taylored (static) getInstance() method. With this it is very easy to transform the first singleton type and a little bit more work to transform the second type - both without breaking the current interface of course.

The straightforward technique of just passing a class to the getInstance() method is for most cases sufficent. However, it does not allow to:

  • use constructors with parameters
  • it is not possible to "wire" the singleton (wiring is the term we use for Riena's dependency injection)

Of course, it possible to create workarounds:

  • use setters instead of constructor parameters - may result in undesired usage
  • do the wiring within the constructor - makes e.g. unit testing more complicated

The introduction of e.g. an IInstanceFactory interface with a single getInstance() method could solve this. The class implementing the IInstanceFactory could then internally be used for creating the key to store the singleton in the session store. And the usage of generics would be a nice bonus.

OSGi Services

A OSGi Service is also some kind of singleton, i.e. it exists only once in a JVM. How to deal with services that have (session dependent) state?

ThreadLocal

This is just a reminder! Are ThreadLocals safe?

ContainerModel

This is just a reminder! This utility tells whether it is running on a client or a server. This allows to implement common code that behaves differently on client or server. We have to think about that!