Difference between revisions of "Sirius/Session API"

Revision as of 10:55, 10 February 2014

This page will be used to discuss the design of a new, improved Session API. See https://bugs.eclipse.org/bugs/show_bug.cgi?id=427799

Problems with the current API and its implementation

Non-exhaustive list of problems with the current implementation that the new version should fix:

• The Session interface provides both too much and too little. Too much in the sense that it exposes implementation details (like the notion of DView) and too little in that many operations which should be simple (like enabling a viewpoint) are actually so complex that they require the use of non-obvious helpers scattered across the code base (e.g. ViewpointSelectionCallback, UserSession).
• "The Session API" is actually much more than just the org.eclipse.sirius.business.api.session.Session interface, it includes many auxilliary interfaces and classes scattered in many places. Because they are not well organized, there is a lot of duplication and inconsistencies between those.
• The actual contract of these APIs, in most cases, are not well defined and documented. The existing documentation is silent on many important aspects like concurrency and thread-safety and performance characteristics.
• The lifecycle of a session is not clearly defined, and the vocabulary used is not consistent (created vs loaded vs opened vs added (to the SessionManager)).
• The de-facto contract of the Session (not always explicit in the documentation but lots of code actually relies on this) implies that all the resources used directly or indirectly by a session are fully loaded as soon as it is started. This makes it impossible to perform any kind of lazy loading to defer costly operations only when really needed.
• The session's behavior is not very configurable. There are a few ad-hoc configuration points (like setting the SavingPolicy) but many other behaviors are not configurable. This can be very problematic when some behaviors impose some overhead (in time or memory): everybody pays them even when they do not need it, because they simply have no possibility to opt-out. See for example DAnalysisSessionImpl.notifyNewMetamodels(Resource) which imposes a complete walk over the contents of newly added semantic resources; it is only needed to support very specific -- and rare -- scenarios, but the cost is paid every time, by everybody.

What constitutes "the Session API"?

• All the content of org.eclipse.sirius.business.internal.session and sub-packages.
• org.eclipse.sirius.ui.business.api.viewpoint.ViewpointSelectionCallback and related classes: needed to enable/disable viewpoints reliably, but in a completely different part of the code (and in the UI plug-in).
• org.eclipse.sirius.ui.business.api.session.UserSession, described as "An API to manipulate user session easily". Should not exist, it is an admission that the normal APIs are too complex for several common tasks.