Skip to content

Migration to SwingSet 4.x

Jump to bottom
Brian Pangburn edited this page Oct 24, 2021 · 17 revisions

The big change from SwingSet 2.x to 3.0.0 was that the package name was changed to all lowercase to comply with standard Java naming conventions.

So to migrate from SwingSet 2.x to 3.0.0, developers only needed to update their imports from: import com.nqadmin.swingSet.X to: import com.nqadmin.swingset.X

SwingSet 4 was a major rewrite of SwingSet:

  • Moved recurring data members and logic to SSCommon
  • Established SSComponentInterface interface to be implemented by all SwingSet components and eliminate redundant code.
  • Elimination of bound JTextFields/Document Listeners for components NOT based on JTextComponent
  • Support for null/blank item in combo boxes
  • SSComboBox and SSDBComboBox use GlazedLists filtering by default
  • Using custom jdbcrowsetimpl to support Java 11+ (see https://github.com/bpangburn/jdbcrowsetimpl)
  • Deprecated SSConnection, SSRowSet, and SSJdbcRowSetImpl. Now using java.sql.Connection, javax.sql.RowSet (com.nqadmin.rowset.JdbcRowSetImpl), and com.nqadmin.swingset.datasources.RowSetOps, which is a utility class with RowSet convenience methods.
  • Addition of SSFormViewScreenHelper and SSDataGridScreenHelper to SwingSet utils package to assist with standardized screen creation.
  • See CHANGELOG.txt for additional details: https://github.com/bpangburn/swingset/blob/master/swingset/CHANGELOG.txt

One unintended benefit of changing the package name to all lowercase in SwingSet 3.0.0 is that 3+ jars can co-exist with older SwingSet jars. This allows UI screens to be converted in phases.

The rest of these instructions presume the developer is upgrading from SwingSet 2.x to SwingSet 4.

Any search/replace described herein was done in the Eclipse IDE using "Eclipse->Search->File..." and making sure "Case sensitive" is checked. Generally, the "Scope" was set to "Selected resource in 'Project Explorer'".

Fix imports:

  1. replace com.nqadmin.swingSet with com.nqadmin.swingset (when converting from SwingSet versions prior to 3.0.0)
  2. replace com.nqadmin.swingset.datasources.SSJdbcRowSetImpl with javax.sql.RowSet
  3. add import com.nqadmin.rowset.JdbcRowSetImpl; to classes with import javax.sql.RowSet;

Update RowSet variables:

  1. replace new SSJdbcRowSetImpl( with new JdbcRowSetImpl(
  2. replace SSJdbcRowSetImpl with RowSet
  3. replace SSRowSet with RowSet

Fix general deprecations:

  1. replace SSConnection with Connection (Do NOT limit to 'Whole word' in order to capture method calls. E.g., getSSConnection() to getConnection())
  2. replace SSDBNavImp with SSDBNavImpl (adding "l")

Fix combo box deprecations (SSComboBox and SSDBComboBox):

getSelectedValue() and setSelectedValue() have been deprecated and replaced by getSelectedMapping() and setSelectedMapping().

getSelectedIndex() and setSelectedIndex() have been deprecated and are to be avoided due to availability of null/blank first item in some comboboxes. This can dynamically impact what is stored at Index==0 (and thus all other indices).

getSelectedIndex() and setSelectedIndex() can generally be replaced by getSelectedMapping() and setSelectedMapping(), but only when there are NO custom mappings specified. If there are custom mappings, then getSelectedIndex() will generally return a different value than getSelectedMapping(). For example, with a custom mapping of ({red, green, blue},{10,5,27}), if 'blue' is selected, getSelectedIndex() will return '2' (if there is not a null/blank first item) and getSelectedMapping() will return '27'.

Terminology and method names have been updated for clarity and consistency. Generally combo boxes are comprised of 'Options', which are the items displayed in the combo box and optionally specified 'Mappings', which are the corresponding values for each Option and bound to a database table column. If Mappings are not supplied then Mapping values are automatically assigned sequentially starting from 0. Previously, 'Item' or 'StringValue" were used to refer to the Options displayed in a combo box and 'Value' was used to refer to the corresponding Mapping for each Option.

Previously there were three 'PredefinedOptions' for SSComboBoxes: YES_NO_OPTION, INCLUDED_EXCLUDE_OPTION, and SEX_OPTION. These have been replaced with Java Enumerations, YesNo, IncludedExclude, and Gender3 all in the com.nqadmin.swingset.enums package. The method setPredefinedOptions() has been deprecated and now setOptions() will take an enumeration class name as a parameter (e.g., setOptions(YesNo.class)). The developer may also user their own custom enumeration classes. All enumerations have implied Mappings indexed sequentially from 0. Enumerated combo box options may be referenced with getSelectedEnum(), setSelectedEnum(<enum>), getSelectedMapping(), and setSelectedMapping(<int>). E.g. myIECombo.setSelectedEnum(IncludeExclude.EXCLUDE), myYNCombo.setSelectedMapping(1) (to set to Yes since YES is the second enumerated item in YesNo), if (myYNCombo.getSelectedEnum()==YesNo.YES {).

  1. replace setPredefinedOptions(SSComboBox.YES_NO_OPTION) with setOptions(YesNo.class) and add import com.nqadmin.swingset.enums.YesNo;
  2. replace setPredefinedOptions(SSComboBox.INCLUDE_EXCLUDE_OPTION) with setOptions(IncludeExclude.class) and add import com.nqadmin.swingset.enums.IncludeExclude;
  3. replace setPredefinedOptions(SSComboBox.SEX_OPTION) with setOptions(Gender3.class) and add import com.nqadmin.swingset.enums.Gender3;
  4. replace setSelectedIndex(-1) with setSelectedMapping(null)
  5. replace setSelectedValue with setSelectedMapping (enums should result in a compile error so change those to setSelectedEnum)
  6. replace setSelectedStringValue with setSelectedOption
  7. replace setSelectedIndex with setSelectedMapping - CAUTION: Only safe if combo mappings are sequential and start from 0. See example above.
  8. replace getSelectedIndex with getSelectedMapping - CAUTION: Only safe if combo mappings are sequential and start from 0. See example above.
  9. replace getSelectedValue with getSelectedMapping
  10. replace addItem with addOption
  11. replace updateItem with updateOption

Other:

  1. Make sure application user interface (UI) is instantiated on the Swing Event Dispatch Thread. E.g., SwingUtilities.invokeLater(() -> new MyTopLevelScreen());
  2. Avoid empty constructor for SSDBComboBox() in declarations as parameterized constructor is typically used to initialize database connection, sql, primary key column and display column. If query is to be set in updateSSDBComobBoxes() method of SSFormViewScreenHelper, then null can be passed as _query parameter in constructor.
  3. When using SSFormViewScreenHelper, there is no need to create/maintain an SSTextField for the primary key column. The helper maintains one that can be accessed via get getTxtPrimaryKey();
Clone this wiki locally