[RFC] Jalview 2.9-> 3.0 architecture: package coding guidelines

Jalview Developers
1

Hi all. This is a request for comments.

I thought it worth resurrecting a conversation Mungo and I started back in January about deciding what packages should have what code. For OSGi, we need to have clear separation between concrete GUI implementations, and core modules implementing the datamodel, IO, analysis, rendering, and view/model/controller functions.

Please have a look at the discussion below. Email comments/revisions to this thread, and I’ll integrate all into a master document as we develop our 3.0 vision. For now, its also worth reviewing code you’ve created to see how it fits with these guidelines…

Jim.

···

I don’t know if you are online today, but if so could you remind me of the rules about what is, or in particular isn’t, allowed to go in the jbgui classes?

The rule with jbgui is that it should only include platform gui implementation code. No application GUI logic (although there are some exceptions which should be fixed re certain menus), and absolutely no controller/datamodel/view logic. There’s a much longer braindump below that I’d like to refine to some working rules for all of us.

But… read on first.

Reason: I have been refactoring the duplicated code in AppJmol and ChimeraViewFrame into GStructureViewer in my local branch. I suspect I may have overdone it, and need instead to create a common base class in the gui package.

nooo! The refactoring strategy here needs to be independent of the jbgui package.

As I see it, the parallels are that Chimera is a peer for viewing structure data mapped to sequences shaded according to current alignment view state and can take commands to create superpositions according to alignments. All these functions are GUI independent, but map to logical structureViewer operations so they should be in a non-gui controller package that implements a structureViewerModel API that Jalview’s GUI can employ.

Unlike Jmol and MView, Chimera doesn’t provide a rendering window, so the concrete GUI implementation for Chimera only serves as a proxy for the external chimera instance. Its geometry needs to be preserved on restore, but the way that chimera sessions are saved and restored is different to Jmol, so that functionality shouldn’t be shoehorned into the same inheritance model.

More generally, thre refactoring rule I’m following is to introduce a non-GUI dependent model wherever possible that is employed by a GUI class to maintain state, allowing multiple GUI implementations to employ the same core logic. This gets around Java’s lack of support for multiple inheritance, and to avoid lockin to particular Java platform APIs that may not always be available. jbgui classes are only necessary for concrete swing windows, and it only makes sense to inherit from the same jbgui class if the end products are different flavours of the same swing window.

Now, the braindump… which - as mentioned is a work in progress…

The basic rules I have been following are:

  1. Refactor or implement data views and associated get/set/modify logic to concrete classes which implement interfaces defined in jalview.api. The first one of these was the Viewport.

  2. Keep Desktop or applet specific model/state logic in gui and appletgui.

This bit needs to change [in order to create Jalview 3.0]. Originally, each one contained runtime/setup logic, actions to execute data analysis steps and construct new views from the results, and view state analysis code to make the GUI reflect current model state. What we ideally want is a full separation… so:

  1. Refactor any control logic to classes in jalview.controller - should only import from non-gui packages.

  2. Place any code dependent on both jalview and non-jalview APIs in ext.

  3. Insulate GUI API dependent code (e.g. swing, awt, etc) from jalview by creating flyweight or wrapper classes implementing jalview interfaces. ** these are UI interfaces, not model interfaces - suggest these will live in a separate subpackage of the api **

Currently, the jalview2xml logic doesn’t follow the above at all. Ideally we should have a factory/GUI service interface which takes jalview view/datamodel objects, that is initialised at runtime according to jalview’s mode (e.g. running on swing, android, web, etc…).

For OSGi, I envision one or more Jalview executable modules that can be told which GUI implementation to use, and autodiscover any other available modules for runtime functionality (database accession sources, database search interfaces, file parsers, alignment and analysis methods, rendering systems) that are compatible with runtime configuration (e.g. sandboxed applet, full desktop application, headless commandline analysis engine, android app, etc).

2

Attached is a raw listing of which packages import which packages in Jalview.
It may spark some comments like “that shouldn’t be there!” (e.g. jalview.datamodel importing from Varna).

Generated by running the following bash command in the src folder (feel free to enhance!):

  • ​traverse directories

  • grep *.java for “import” lines

  • remove duplicates

  • remove "import "

  • remove the class name by reversing, removing the first field by ‘.’, reversing back

  • remove duplicates

  • remove “import java.*”

for file in $(find . -type d); do echo -e “\n$file” imports; grep -sh ^import $file/*.java | sort -u | cut -c 8- | rev | cut -f2- -d. | rev | sort -u; done | grep -v ^java.

mungo

The University of Dundee is a registered Scottish Charity, No: SC015096

imports.txt (12.3 KB)

···

Mungo Carstairs
Jalview Computational Scientist
The Barton Group
Division of Computational Biology
College of Life Sciences
University of Dundee, Dundee, Scotland, UK.
www.jalview.org
www.compbio.dundee.ac.uk

From: jalview-dev-bounces@jalview.org jalview-dev-bounces@jalview.org on behalf of Jim Procter jprocter@compbio.dundee.ac.uk
Sent: 17 June 2015 12:13
To: Jalview Development List
Subject: [Jalview-dev] [RFC] Jalview 2.9-> 3.0 architecture: package coding guidelines

Hi all. This is a request for comments.

I thought it worth resurrecting a conversation Mungo and I started back in January about deciding what packages should have what code. For OSGi, we need to have clear separation between concrete GUI implementations, and core modules implementing the datamodel, IO, analysis, rendering, and view/model/controller functions.

Please have a look at the discussion below. Email comments/revisions to this thread, and I’ll integrate all into a master document as we develop our 3.0 vision. For now, its also worth reviewing code you’ve created to see how it fits with these guidelines…

Jim.

On 07/01/2015 11:06, Mungo Carstairs (Staff) wrote:

I don’t know if you are online today, but if so could you remind me of the rules about what is, or in particular isn’t, allowed to go in the jbgui classes?

The rule with jbgui is that it should only include platform gui implementation code. No application GUI logic (although there are some exceptions which should be fixed re certain menus), and absolutely no controller/datamodel/view logic. There’s a much longer braindump below that I’d like to refine to some working rules for all of us.

But… read on first.

Reason: I have been refactoring the duplicated code in AppJmol and ChimeraViewFrame into GStructureViewer in my local branch. I suspect I may have overdone it, and need instead to create a common base class in the gui package.

nooo! The refactoring strategy here needs to be independent of the jbgui package.

As I see it, the parallels are that Chimera is a peer for viewing structure data mapped to sequences shaded according to current alignment view state and can take commands to create superpositions according to alignments. All these functions are GUI independent, but map to logical structureViewer operations so they should be in a non-gui controller package that implements a structureViewerModel API that Jalview’s GUI can employ.

Unlike Jmol and MView, Chimera doesn’t provide a rendering window, so the concrete GUI implementation for Chimera only serves as a proxy for the external chimera instance. Its geometry needs to be preserved on restore, but the way that chimera sessions are saved and restored is different to Jmol, so that functionality shouldn’t be shoehorned into the same inheritance model.

More generally, thre refactoring rule I’m following is to introduce a non-GUI dependent model wherever possible that is employed by a GUI class to maintain state, allowing multiple GUI implementations to employ the same core logic. This gets around Java’s lack of support for multiple inheritance, and to avoid lockin to particular Java platform APIs that may not always be available. jbgui classes are only necessary for concrete swing windows, and it only makes sense to inherit from the same jbgui class if the end products are different flavours of the same swing window.

Now, the braindump… which - as mentioned is a work in progress…

The basic rules I have been following are:

  1. Refactor or implement data views and associated get/set/modify logic to concrete classes which implement interfaces defined in jalview.api. The first one of these was the Viewport.

  2. Keep Desktop or applet specific model/state logic in gui and appletgui.

This bit needs to change [in order to create Jalview 3.0]. Originally, each one contained runtime/setup logic, actions to execute data analysis steps and construct new views from the results, and view state analysis code to make the GUI reflect current model state. What we ideally want is a full separation… so:

  1. Refactor any control logic to classes in jalview.controller - should only import from non-gui packages.

  2. Place any code dependent on both jalview and non-jalview APIs in ext.

  3. Insulate GUI API dependent code (e.g. swing, awt, etc) from jalview by creating flyweight or wrapper classes implementing jalview interfaces. ** these are UI interfaces, not model interfaces - suggest these will live in a separate subpackage of the api **

Currently, the jalview2xml logic doesn’t follow the above at all. Ideally we should have a factory/GUI service interface which takes jalview view/datamodel objects, that is initialised at runtime according to jalview’s mode (e.g. running on swing, android, web, etc…).

For OSGi, I envision one or more Jalview executable modules that can be told which GUI implementation to use, and autodiscover any other available modules for runtime functionality (database accession sources, database search interfaces, file parsers, alignment and analysis methods, rendering systems) that are compatible with runtime configuration (e.g. sandboxed applet, full desktop application, headless commandline analysis engine, android app, etc).

3

Updated extract of what packages each package imports attached (with empty entries removed manually).

The University of Dundee is a registered Scottish Charity, No: SC015096

jalview_2.9.0b2Imports.txt (11.7 KB)

···

Mungo Carstairs
Jalview Computational Scientist
The Barton Group
Division of Computational Biology
School of Life Sciences
University of Dundee, Dundee, Scotland, UK.
www.jalview.org
www.compbio.dundee.ac.uk

From: jalview-dev-bounces@jalview.org jalview-dev-bounces@jalview.org on behalf of Mungo Carstairs (Staff) g.m.carstairs@dundee.ac.uk
Sent: 23 June 2015 15:32
To: Jalview Development List
Subject: Re: [Jalview-dev] [RFC] Jalview 2.9-> 3.0 architecture: package coding guidelines

Attached is a raw listing of which packages import which packages in Jalview.
It may spark some comments like “that shouldn’t be there!” (e.g. jalview.datamodel importing from Varna).

Generated by running the following bash command in the src folder (feel free to enhance!):

  • traverse directories

  • grep *.java for “import” lines

  • remove duplicates

  • remove "import "

  • remove the class name by reversing, removing the first field by ‘.’, reversing back

  • remove duplicates

  • remove “import java.*”

for file in $(find . -type d); do echo -e “\n$file” imports; grep -sh ^import $file/*.java | sort -u | cut -c 8- | rev | cut -f2- -d. | rev | sort -u; done | grep -v ^java.

mungo

The University of Dundee is a registered Scottish Charity, No: SC015096

Mungo Carstairs
Jalview Computational Scientist
The Barton Group
Division of Computational Biology
College of Life Sciences
University of Dundee, Dundee, Scotland, UK.
www.jalview.org
www.compbio.dundee.ac.uk

From: jalview-dev-bounces@jalview.org jalview-dev-bounces@jalview.org on behalf of Jim Procter jprocter@compbio.dundee.ac.uk
Sent: 17 June 2015 12:13
To: Jalview Development List
Subject: [Jalview-dev] [RFC] Jalview 2.9-> 3.0 architecture: package coding guidelines

Hi all. This is a request for comments.

I thought it worth resurrecting a conversation Mungo and I started back in January about deciding what packages should have what code. For OSGi, we need to have clear separation between concrete GUI implementations, and core modules implementing the datamodel, IO, analysis, rendering, and view/model/controller functions.

Please have a look at the discussion below. Email comments/revisions to this thread, and I’ll integrate all into a master document as we develop our 3.0 vision. For now, its also worth reviewing code you’ve created to see how it fits with these guidelines…

Jim.

On 07/01/2015 11:06, Mungo Carstairs (Staff) wrote:

I don’t know if you are online today, but if so could you remind me of the rules about what is, or in particular isn’t, allowed to go in the jbgui classes?

The rule with jbgui is that it should only include platform gui implementation code. No application GUI logic (although there are some exceptions which should be fixed re certain menus), and absolutely no controller/datamodel/view logic. There’s a much longer braindump below that I’d like to refine to some working rules for all of us.

But… read on first.

Reason: I have been refactoring the duplicated code in AppJmol and ChimeraViewFrame into GStructureViewer in my local branch. I suspect I may have overdone it, and need instead to create a common base class in the gui package.

nooo! The refactoring strategy here needs to be independent of the jbgui package.

As I see it, the parallels are that Chimera is a peer for viewing structure data mapped to sequences shaded according to current alignment view state and can take commands to create superpositions according to alignments. All these functions are GUI independent, but map to logical structureViewer operations so they should be in a non-gui controller package that implements a structureViewerModel API that Jalview’s GUI can employ.

Unlike Jmol and MView, Chimera doesn’t provide a rendering window, so the concrete GUI implementation for Chimera only serves as a proxy for the external chimera instance. Its geometry needs to be preserved on restore, but the way that chimera sessions are saved and restored is different to Jmol, so that functionality shouldn’t be shoehorned into the same inheritance model.

More generally, thre refactoring rule I’m following is to introduce a non-GUI dependent model wherever possible that is employed by a GUI class to maintain state, allowing multiple GUI implementations to employ the same core logic. This gets around Java’s lack of support for multiple inheritance, and to avoid lockin to particular Java platform APIs that may not always be available. jbgui classes are only necessary for concrete swing windows, and it only makes sense to inherit from the same jbgui class if the end products are different flavours of the same swing window.

Now, the braindump… which - as mentioned is a work in progress…

The basic rules I have been following are:

  1. Refactor or implement data views and associated get/set/modify logic to concrete classes which implement interfaces defined in jalview.api. The first one of these was the Viewport.

  2. Keep Desktop or applet specific model/state logic in gui and appletgui.

This bit needs to change [in order to create Jalview 3.0]. Originally, each one contained runtime/setup logic, actions to execute data analysis steps and construct new views from the results, and view state analysis code to make the GUI reflect current model state. What we ideally want is a full separation… so:

  1. Refactor any control logic to classes in jalview.controller - should only import from non-gui packages.

  2. Place any code dependent on both jalview and non-jalview APIs in ext.

  3. Insulate GUI API dependent code (e.g. swing, awt, etc) from jalview by creating flyweight or wrapper classes implementing jalview interfaces. ** these are UI interfaces, not model interfaces - suggest these will live in a separate subpackage of the api **

Currently, the jalview2xml logic doesn’t follow the above at all. Ideally we should have a factory/GUI service interface which takes jalview view/datamodel objects, that is initialised at runtime according to jalview’s mode (e.g. running on swing, android, web, etc…).

For OSGi, I envision one or more Jalview executable modules that can be told which GUI implementation to use, and autodiscover any other available modules for runtime functionality (database accession sources, database search interfaces, file parsers, alignment and analysis methods, rendering systems) that are compatible with runtime configuration (e.g. sandboxed applet, full desktop application, headless commandline analysis engine, android app, etc).

4

here’s a slightly prettified pic courtesy of d3… this currently gives class level import dependencies… I need to overlay packages so we can see how class dependencies fit with the package usage.

http://www.compbio.dundee.ac.uk/user/jprocter/jalviewdoc/doc/classdiag/jalview_flare.html

···

On 26/10/2015 11:32, Mungo Carstairs (Staff) wrote:

I don’t know if you are online today, but if so could you remind me of the rules about what is, or in particular isn’t, allowed to go in the jbgui classes?

The rule with jbgui is that it should only include platform gui implementation code. No application GUI logic (although there are some exceptions which should be fixed re certain menus), and absolutely no controller/datamodel/view logic. There’s a much longer braindump below that I’d like to refine to some working rules for all of us.

But… read on first.

Reason: I have been refactoring the duplicated code in AppJmol and ChimeraViewFrame into GStructureViewer in my local branch. I suspect I may have overdone it, and need instead to create a common base class in the gui package.

nooo! The refactoring strategy here needs to be independent of the jbgui package.

As I see it, the parallels are that Chimera is a peer for viewing structure data mapped to sequences shaded according to current alignment view state and can take commands to create superpositions according to alignments. All these functions are GUI independent, but map to logical structureViewer operations so they should be in a non-gui controller package that implements a structureViewerModel API that Jalview’s GUI can employ.

Unlike Jmol and MView, Chimera doesn’t provide a rendering window, so the concrete GUI implementation for Chimera only serves as a proxy for the external chimera instance. Its geometry needs to be preserved on restore, but the way that chimera sessions are saved and restored is different to Jmol, so that functionality shouldn’t be shoehorned into the same inheritance model.

More generally, thre refactoring rule I’m following is to introduce a non-GUI dependent model wherever possible that is employed by a GUI class to maintain state, allowing multiple GUI implementations to employ the same core logic. This gets around Java’s lack of support for multiple inheritance, and to avoid lockin to particular Java platform APIs that may not always be available. jbgui classes are only necessary for concrete swing windows, and it only makes sense to inherit from the same jbgui class if the end products are different flavours of the same swing window.

Now, the braindump… which - as mentioned is a work in progress…

The basic rules I have been following are:

  1. Refactor or implement data views and associated get/set/modify logic to concrete classes which implement interfaces defined in jalview.api. The first one of these was the Viewport.

  2. Keep Desktop or applet specific model/state logic in gui and appletgui.

This bit needs to change [in order to create Jalview 3.0]. Originally, each one contained runtime/setup logic, actions to execute data analysis steps and construct new views from the results, and view state analysis code to make the GUI reflect current model state. What we ideally want is a full separation… so:

  1. Refactor any control logic to classes in jalview.controller - should only import from non-gui packages.

  2. Place any code dependent on both jalview and non-jalview APIs in ext.

  3. Insulate GUI API dependent code (e.g. swing, awt, etc) from jalview by creating flyweight or wrapper classes implementing jalview interfaces. ** these are UI interfaces, not model interfaces - suggest these will live in a separate subpackage of the api **

Currently, the jalview2xml logic doesn’t follow the above at all. Ideally we should have a factory/GUI service interface which takes jalview view/datamodel objects, that is initialised at runtime according to jalview’s mode (e.g. running on swing, android, web, etc…).

For OSGi, I envision one or more Jalview executable modules that can be told which GUI implementation to use, and autodiscover any other available modules for runtime functionality (database accession sources, database search interfaces, file parsers, alignment and analysis methods, rendering systems) that are compatible with runtime configuration (e.g. sandboxed applet, full desktop application, headless commandline analysis engine, android app, etc).

5

very cute!

···

On 26/10/2015 17:26, Jim Procter wrote:

On 26/10/2015 11:32, Mungo Carstairs (Staff) wrote:

I don’t know if you are online today, but if so could you remind me of the rules about what is, or in particular isn’t, allowed to go in the jbgui classes?

The rule with jbgui is that it should only include platform gui implementation code. No application GUI logic (although there are some exceptions which should be fixed re certain menus), and absolutely no controller/datamodel/view logic. There’s a much longer braindump below that I’d like to refine to some working rules for all of us.

But… read on first.

Reason: I have been refactoring the duplicated code in AppJmol and ChimeraViewFrame into GStructureViewer in my local branch. I suspect I may have overdone it, and need instead to create a common base class in the gui package.

nooo! The refactoring strategy here needs to be independent of the jbgui package.

As I see it, the parallels are that Chimera is a peer for viewing structure data mapped to sequences shaded according to current alignment view state and can take commands to create superpositions according to alignments. All these functions are GUI independent, but map to logical structureViewer operations so they should be in a non-gui controller package that implements a structureViewerModel API that Jalview’s GUI can employ.

Unlike Jmol and MView, Chimera doesn’t provide a rendering window, so the concrete GUI implementation for Chimera only serves as a proxy for the external chimera instance. Its geometry needs to be preserved on restore, but the way that chimera sessions are saved and restored is different to Jmol, so that functionality shouldn’t be shoehorned into the same inheritance model.

More generally, thre refactoring rule I’m following is to introduce a non-GUI dependent model wherever possible that is employed by a GUI class to maintain state, allowing multiple GUI implementations to employ the same core logic. This gets around Java’s lack of support for multiple inheritance, and to avoid lockin to particular Java platform APIs that may not always be available. jbgui classes are only necessary for concrete swing windows, and it only makes sense to inherit from the same jbgui class if the end products are different flavours of the same swing window.

Now, the braindump… which - as mentioned is a work in progress…

The basic rules I have been following are:

  1. Refactor or implement data views and associated get/set/modify logic to concrete classes which implement interfaces defined in jalview.api. The first one of these was the Viewport.

  2. Keep Desktop or applet specific model/state logic in gui and appletgui.

This bit needs to change [in order to create Jalview 3.0]. Originally, each one contained runtime/setup logic, actions to execute data analysis steps and construct new views from the results, and view state analysis code to make the GUI reflect current model state. What we ideally want is a full separation… so:

  1. Refactor any control logic to classes in jalview.controller - should only import from non-gui packages.

  2. Place any code dependent on both jalview and non-jalview APIs in ext.

  3. Insulate GUI API dependent code (e.g. swing, awt, etc) from jalview by creating flyweight or wrapper classes implementing jalview interfaces. ** these are UI interfaces, not model interfaces - suggest these will live in a separate subpackage of the api **

Currently, the jalview2xml logic doesn’t follow the above at all. Ideally we should have a factory/GUI service interface which takes jalview view/datamodel objects, that is initialised at runtime according to jalview’s mode (e.g. running on swing, android, web, etc…).

For OSGi, I envision one or more Jalview executable modules that can be told which GUI implementation to use, and autodiscover any other available modules for runtime functionality (database accession sources, database search interfaces, file parsers, alignment and analysis methods, rendering systems) that are compatible with runtime configuration (e.g. sandboxed applet, full desktop application, headless commandline analysis engine, android app, etc).

-- 
Geoff Barton | Professor of Bioinformatics | Head of Division of Computational Biology   
School of Life Sciences | University of Dundee, Scotland, UK | [g.j.barton@dundee.ac.uk](mailto:g.j.barton@dundee.ac.uk) 
Tel: +44 1382 385860 | [www.compbio.dundee.ac.uk](http://www.compbio.dundee.ac.uk) | twitter: @gjbarton
 

The University of Dundee is registered Scottish charity: No.SC015096