Package eu.bandm.tools.installer

Class DocumentedDistribution2<M extends Model<M>,G extends Gui>

java.lang.Object
java.awt.Component
java.awt.Container
java.awt.Window
java.awt.Frame
javax.swing.JFrame
eu.bandm.tools.installer.DocumentedDistribution2<M,G>
All Implemented Interfaces:
ImageObserver, MenuContainer, Serializable, Accessible, RootPaneContainer, WindowConstants
Direct Known Subclasses:
Application
public abstract class DocumentedDistribution2<M extends Model<M>,G extends Gui> extends JFrame
Top-Level programm for distribution of code (as binary), plus documentation, example(s) and sources.
(Since javaws/JNLP is deprecated since jse 9 and no more contained in jse 11, this is a REPLACEMENT for the deprecated @link{DocumentedDistribution}. It uses java.util.prefs.Preferences and java.awt.Desktop.getDesktop().browse(..) (as wrapped by BrowserControl) instead.)
Contains
  1. global public constant definitions
  2. the top-level control flow for the very different use cases, including prefs.Preference interfacing,
  3. Downloading "DEnS" (="Documentation,Examples and Sources"
  4. A gui with menu, options panel, message panel.
  5. Multi-language support
  6. Currently MISSING is (semi-)automated version updating; this had been done by javaws/JNLP in the preceding version @link{DocumentedDistribution}.
Further graphic panels, menu points and the executive functionality must be added by sub-classing.
(This code is an abstraction from bandm/book2 Main, Gui, etc.)
Any program derived from this class can be used as "main class" for calls by "clicking a jar file" under windows, etc., as well as by command line call: 
       class Program extends DocumentedDistribution {
         [* Here goes the pay-load code: *]
         @Override void executeBatchOperation( [*glo in optionsModel*] ){
           ...
         }
         public static void main (final String[] args){
           new Program(new DocumentedDistribution.Configuration(){
                         {programName = ...; 
                          ..}}).execute(args);
         }
       }

The type parameters of this class are one class derived from Model and a corresponding class derived from Gui, as generated by the Compiler. See the BandM metatools user doc for details.
Flag icons by FamFamFam http:famfamfam.com/lab/icons/flags (Mark James)
See Also:

  • Field Details

    • configuration

      public final DocumentedDistribution2.Configuration<M extends Model<M>,G extends Gui> configuration
      The configuration object passed to the constructor call.

    • isMuLi

      protected boolean isMuLi
      Reflects whether more than one language has been specified.

    • metatools_doc_url

      public static final String metatools_doc_url
      The string representation of the url of the metatools docu.
      See Also:

    • KEY_PATH_local_userdocumentation

      public static final String KEY_PATH_local_userdocumentation
      This is a key string pointing into the translation CatalogByString, which is required because the language of the document may depend on the current language preferences.
      See Also:

    • KEY_URL_web_userdocumentation

      public static final String KEY_URL_web_userdocumentation
      This is a key string pointing into the translation CatalogByString, which is required because the language of the document may depend on the current language preferences.
      See Also:

    • KEY_ultra_short_description

      public static final String KEY_ultra_short_description
      This is a key string pointing into the translation CatalogByString, to a three-word explanation of the program's purpose, in different languages. A one-sentence form is preferred and there should be NO FULL-STOP at the end.
      See Also:

    • KEY_about_additional_text

      public static final String KEY_about_additional_text
      This is a key string pointing into the translation CatalogByString, to an OPTIONAL additional text shown after the first (autmatically generated) sentences of the about window.
      See Also:

    • icon_flag_Germany

      public static final ImageIcon icon_flag_Germany
      An icon showing the German flag. Prepared as a call-back for the payload specific class to put it into DocumentedDistribution2.Configuration.

    • icon_flag_USA

      public static final ImageIcon icon_flag_USA
      An icon showing the flag of the USA. Prepared as a call-back for the payload specific class to put it into DocumentedDistribution2.Configuration.

    • icon_flag_romanEmpire

      public static final ImageIcon icon_flag_romanEmpire
      An icon showing the flag of the Roman Empire, for Latin translations. Prepared as a call-back for the payload specific class to put it into DocumentedDistribution2.Configuration.

    • icon_flag_Spain

      public static final ImageIcon icon_flag_Spain
      An icon showing the flag of Spain. Prepared as a call-back for the payload specific class to put it into DocumentedDistribution2.Configuration.

    • programJavaClassName

      public final String programJavaClassName

    • generationComment

      public Format generationComment

    • languagePrefs

      protected final Selection languagePrefs
      Central control for UI language switch. All visible GUI elements can register here for notification.

    • msgCounter

      protected final MessageCounter msgCounter
      Must be global.

    • msgStore

      protected final MessageStore<SimpleMessage<String>> msgStore

    • msgPrinter

      protected final MessagePrinter<SimpleMessage<String>> msgPrinter

    • msgTranslator

      protected final MessageTranslator<String> msgTranslator

    • translatedAndFormatted

      protected final MessageTee<SimpleMessage<String>> translatedAndFormatted

    • msgTee

      protected final MessageTee<SimpleMessage<String>> msgTee
      Must be global because further consumers will later be added in case of GUI use.

    • msg

      public final MessageReceiver<SimpleMessage<String>> msg
      Is only known to be a receiver, for programming discipline.

    • msgXML

      public final MessageReceiver<SimpleMessage<XMLDocumentIdentifier>> msgXML
      Receiver for messages with a line number location. Provided here as convenience for sub-classes.

    • completed_user_language_icons

      protected final List<Icon> completed_user_language_icons
      This is a copy of the original list of languages DocumentedDistribution2.Configuration.user_language_icons, completed by Gui.StringIcons when no flag icon has been provided.

    • jarRunning

      protected boolean jarRunning
      Whether this runs from a jar file.

    • codePosition

      @Opt protected @Opt String codePosition
      Disk file position of the currently running code.

    • firstSignerName

      @Opt protected @Opt String firstSignerName
      The name of the first/main signer of the code.

    • DEnS_dir

      @Opt protected @Opt String DEnS_dir
      Common root directory's position of documentation, examples and sources on the local machine.

    • DEnS_cs

      protected byte[] DEnS_cs
      Checksum of all files in the local copy of DEnS.

    • PK_DEnS_local_dir

      protected static final String PK_DEnS_local_dir
      Persistency key. Persistency entries are indexed by the payload subclass and the constants starting with "PK_..".
      See Also:

    • PK_DEnS_digest

      protected static final String PK_DEnS_digest
      Persistency key
      See Also:

    • PK_optionsLastRun

      protected static final String PK_optionsLastRun
      Persistency key
      See Also:

    • PK_optionsLanguage

      protected static final String PK_optionsLanguage
      Persistency key
      See Also:

    • emptyArgs

      public static final String[] emptyArgs
      Evident

    • optionsModel

      protected M extends Model<M> optionsModel
      The central instance holding the ooptions for all payload runs, GUI editing, serialization etc.

    • optionsGui

      protected G extends Gui optionsGui
      The central instance holdign the options GUI. Is a clone from the instance in configuration.)

    • executeButton

      protected JButton executeButton
      The button below the GUI option pane, for starting processing.

    • resetToDefaultsButton

      @Opt protected @Opt JButton resetToDefaultsButton
      The button below the GUI option pane, for resetting to default values. Its creation is controlled by configuration.

    • guiPopulated

      protected boolean guiPopulated
      Flag set after all GUI elements have been created.

    • jTabbedPane

      protected JTabbedPane jTabbedPane
      The top container for all tab panes (options, messages, and subclass specifics).

    • buttonPanel

      protected JPanel buttonPanel
      The container below the options for the "action" buttons.

    • errorMsgField

      protected SwingMessageField<SimpleMessage<String>> errorMsgField
      Text label showing always the last message sent to . Is positioned at the bottom of the main window and always visible, on each tab.

    • interactiveIsRequested

      protected boolean interactiveIsRequested
      Set to true if no payload task is defined on the command line (=no non-meta options), and can further be set true explicitly by the payload task (by callback requestInteraction(boolean) for starting the GUI nevertheless.

    • cmdLineIsEmpty

      protected boolean cmdLineIsEmpty
      Whether there are no string argument particles from a command line.

    • cmdLineDefinesTask

      protected boolean cmdLineDefinesTask
      Whether there were non-meta options in the command line, and the correspoding payload task is executed.

    • isInitialCall

      protected boolean isInitialCall
      Output to the payload task implementation whether its execution comes directly from the command lines, with no GUI interference.

    • exampleMenuItems

      protected List<JMenuItem> exampleMenuItems
      Menu items initially inactive; enabled after successful DEnS download.

    • button2textKey

      protected Map<AbstractButton,String> button2textKey
      Maps Swing objects to MuLi keys for dynamic language change. The text entries must all have the "accelerator format" like "!e!xit", see translateAndExtractShortcut(String), because the accelerator key with the language.

    • label2textKey

      protected Map<JLabel,String> label2textKey
      Maps Swing objects to MuLi keys for dynamic language change.

    • anyTabbedPane2textKey

      protected Map<Component,String> anyTabbedPane2textKey
      Maps Swing objects to MuLi keys for dynamic language change.

    • anyTabbedPane2tooltip

      protected Map<Component,String> anyTabbedPane2tooltip
      Maps Swing objects to MuLi keys for dynamic language change.

    • languageButtons

      protected final ButtonGroup languageButtons
      The language buttons appearing in the language drop-down menu.

  • Constructor Details

  • Method Details

    • closeDialogLink

      public String closeDialogLink()
      Delivers the source text of an HTML link to close a window, in the current language.

    • translate

      public String translate(String t)
      Translate the input String as defined by the catalog object and the language code priority sequence, both from msg. The current muli messages catalog is initialised from the configuration object. If no translation is defined, the KEY ITSELF is returned! The work is done by the method Catalog.translateRobust(Object,List)

    • translateNonRobust

      @Opt public @Opt String translateNonRobust(String t)
      Find a translation for the input String according to the catalog object and the language code priority sequence, both from msg, or null if not found. The current muli messages catalog is initialised from the configuration object. Is needed for optional payload specific text blocks.

    • translate

      public String translate(String t, Object... args)
      Translate the input String as defined by the catalog object and the language code priority sequence, both from msg. The current muli messages catalog is initialised from the configuration object. The work is done by the method Catalog.translateAllAndFormatRobust(Object,List,List)

    • insitu

      protected String insitu(String key, List<String> translations, Object... args)
      Makes an "in situ" definition using Catalog.insitu(Object,List,List,Object...) of the current muli messages catalog, with the current language preferences. That means it delivers a found translation immediately, but stores the translations as a side effect, for later retrieval. The current muli messages catalog is given by msg and has been initialised from the configuration object.
      Parameters:
      translations - list of PAIRS of String, each language code and text
      args - objects formatted into the translated text by printf codes

    • insitu

      protected String insitu(String key, List<String> translations)
      Makes an "in situ" definition using Catalog.insitu(Object,List,List) of the current muli messages catalog, with the current language preferences. That means it delivers a found translation immediately, but stores the translations as a side effect, for later retrieval. The current muli messages catalog is given by msg and has been initialised from the configuration object. This is the variant for constant texts, i.e. without printf embedding.
      Parameters:
      translations - list of PAIRS of String, each language code and text

    • insitu

      protected String insitu(String key, String... translations)
      See Also:

    • INSITU

      protected String INSITU(String key, String... translations)
      Makes an "in situ" definition using Catalog.INSITU(Object,List). It puts the definitions in the current translation catalog and returns the key, so this can be used immediately e.g. as the text argument for message sending.

      ATTENTION more than one calls with the same key are illegal and bring unpredictable results, because only one of both storings will be executed. The current muli messages catalog is given by msg and has been initialised from the configuration object.

      Parameters:
      key -
      translations - list of PAIRS of String, each language code and text

    • guiConfirmExit

      public void guiConfirmExit(int source)
      Parameters:
      source - 0=payload task definitely wants exit, 1=from window close 2=from menu

    • terminateApplicationDueToSevereErrors

      public void terminateApplicationDueToSevereErrors()
      If errors have been counted, then print a text to the terminal of the command line and exits the application. May only be called in command-line mode. Inquires global message counter.

    • terminateApplicationDueToSevereErrors

      public void terminateApplicationDueToSevereErrors(MessageCounter m)
      If errors have been counted, then print a text to the terminal of the command line and exits the application. May only be called in command-line mode.

    • terminateApplicationDueToSevereErrors_usage

      public void terminateApplicationDueToSevereErrors_usage(MessageCounter m)
      As terminateApplicationDueToSevereErrors(eu.bandm.tools.message.MessageCounter), with printing of the usage information in case of error. May only be called in command-line mode.

    • currentLanguage

      protected String currentLanguage()
      Evident

    • getCriticalCount

      public int getCriticalCount()
      Number of critical messages (errors, failures) in the standard message channel.

    • isInitialCall

      protected boolean isInitialCall()
      Output to the payload task implementation whether its execution comes directly from the command lines, with no GUI interference.

    • selectExampleOptions

      protected void selectExampleOptions(@Opt @Opt String shortName)
      Is called by the framework and must be implemented by the derived class to let the options in optionsModel point to a prefactored example. The shortNames of these examples must be listed in DocumentedDistribution2.Configuration.examplesShortNames and thus appear in a Menu.
      Parameters:
      shortName - the name from the menu which identifies the example. Can be =null iff there is only one example.

    • executeBatchOperation

      protected abstract void executeBatchOperation()
      Call-back main execution method, called with all parameters entered into optionsModel, coming from the GUI or command line. Must be called by one of the user-defined GUI field entries, or a button like "go!-)".
      Situations: 
         cmd-line-parameters filled in |  | interactively filled,
                                 |  |    GO button pressed
                                 |  |
   isInitialCall=true            |  | =false 
                                 |  |
   execute (possibly skip GUI)   |  | process data, return
                                 |  |  to GUI

    • addUserPagesToTabbedPane

      protected abstract void addUserPagesToTabbedPane()
      Call-back method to be overridden whenever the subclass wants to add further tabbed panes to the main windows tabbed stack. Must in turn call the service access point addMuli_jTabbedPane(Component, String), with "String" being the key for MuLi Translation.

    • addUserMenuItems

      protected abstract void addUserMenuItems()
      Call-back method to be overridden whenever the subclass wants to add further items to the main menu bar. Is called after menu-component "[0] = file" is created, but the right-most ("language" and "help") are not yet existing.

    • completeGuiPopulation

      protected abstract void completeGuiPopulation()
      Call-back method to be overridden whenever the subclass wants to add further items after the gui has been constructed and populated.

    • requestInteraction

      protected void requestInteraction(boolean rq)
      A call-back to be called from executeBatchOperation() to switch on/off gui mode, according to the analysed options, or to performance results, etc.
      Parameters:
      rq - whether the payload execution requests to start the GUI.

    • setErrorMsg

      public void setErrorMsg(String s)
      Callback for the payload implementation to show a short text in the message field

    • clearErrorMsg

      public void clearErrorMsg()
      Callback for the payload implementation to clear the message field

    • switchToTab

      public void switchToTab(Component comp)
      Callback for the payload implementation to clear the message field

    • non_static_main

      public void non_static_main(String[] args)
      Main entry for command line and for GUI operation. Can be started
      1 locally from command line (jar file as executive)
      2 by "clicking" a jar file in a "graphic" operating system.
      It shows different behaviours according to the combination of the following parameters:
      1. jar-click or cmd-line start?
      2. DEnS already downloaded or not?
      3. command line arguments present or empty?
      There are META options which have no standard gui representation. Some of them (version, help) realize the POSIX behaviour. Some of the are combinable with others, see "COMB" in the following table. The cases which are not marked COMB or ERR are currently not specified. 
           combinable with   --vers  --help  --lang  --gui  --clear --geom PAYLOAD
  META: 
    --version             --   COMB            ERR    COMB    ERR    ERR
    --help                     --       COMB   ERR    COMB    ERR    ERR
    --language                          --     COMB   COMB    COMB   COMB
    --gui                                      --     COMB    COMB   COMB
    --clearPersistency                                --      COMB   COMB
    --geometry                                                --     COMB
      The common operations are always ..
      1. Set up message channels.
      2. Parse command line options (including an empty string)
      3. If options specify a payload task, then execute main functionality by applying executeBatchOperation() on this data, controlled by the global input optionsModel
      4. if there is no such processing task, or if interactive mode has been asked for explicitly, either by the commandline or by payload run, then start the GUI mode.

      Possible use cases / combinations: 

       (A) cmd line not empty / has payload options
   - parsed w/o errors    --> execute cmd line 
   - parsed with errors   --> signal to user (gui/non-gui)
 (B) cmd line empty
   - preferences altered by user in a preceding session 
                            --> start user's preferences in Gui
                                else start with an empty Gui
      (The example option datas are not loaded automatically, but can be copied into the GUI pane by menu.)

    • compareLanguageSets

      protected void compareLanguageSets(Collection<String> A, String Aname, Collection<String> B, String Bname)
      Meta-analysis about the consistency of translations. Prints both possible differences of both sets to the standard message channel. Since this is a mere technical warning, which normally should not appear, it is only in the Compiler.LINGUA_FRANCA.

    • compareLanguageSets2

      protected void compareLanguageSets2(Collection<String> A, String Aname, Collection<String> B, String Bname)
      Meta-analysis about the consistency of translations. Prints one difference of both sets to the standard message channel.

    • isTampered

      protected boolean isTampered()
      Is only called if DEnS have been downloaded, according to perssitent storage.

    • updateStatusInformation

      protected void updateStatusInformation()
      Central self-reflecting data collection and analysis. Fills global variables.

    • makeCreditsText

      protected String makeCreditsText()
      FIXME DOCME

    • makeStatusText

      protected String makeStatusText()
      Contructs the information text which presents status to the human user, in the current language. updateStatusInformation() must have been called before, This text is presented (a) possibly as greeting text and (b) by Menu--help--about.

    • makeAboutDialog

      protected TextDialog makeAboutDialog(String title, boolean modal)
      Display a pop-up dialog window with an overall status text for the user. Is called when starting the program (if enabled by DocumentedDistribution2.Configuration.startWithStatusInformationDialog and by the "Help->about" menu. Both cases have different window titles.

    • getRunningCodeSource

      protected URL getRunningCodeSource()
      Laut https://www.edureka.co/community/5035/retrieving-the-path-of-a-runing-jar-file "new File(ABC.class.getProtectionDomain().getCodeSource().getLocation().toURI()).getPath();"

    • getFirstSignerName

      @Opt protected @Opt String getFirstSignerName()
      Returns the string representation of the name of the last signer in the first certificate chain. In most cases there will be only one(1) such certificate chain.
      Returns:
      null if no certificate or unknown certificate type. Latter case issues a warning.

    • stripHtml

      protected String stripHtml(String s)
      Convert for output on stdout/stderr by stripping all HTML formatting. Noassumptions on formatting beyond "newline" are made (e.g. no termcaps etc. is used)

    • POSIX_print_help

      protected void POSIX_print_help()
      Print standardized command line "--help" output. Language selectable. Cf https://www.gnu.org/prep/standards/html_node/002d_002d_help.html

    • POSIX_print_version

      protected void POSIX_print_version()
      Print standardized and parseable command line "--version" output. English only. Cf https://www.gnu.org/prep/standards/html_node/002d_002d_version.html

    • populate

      protected void populate()
      Generate all graphic panes and add them to the topmost window = this.

    • executeBatchOperation_caught

      protected void executeBatchOperation_caught()
      Exceptions are caught here, explicitly. Other Throwables (i.e. Errors) are caught be call to "monitor(..)" above.

    • makeMuli_JLabel

      protected JLabel makeMuli_JLabel(String text)

    • translateAndExtractShortcut

      protected String[] translateAndExtractShortcut(String text)
      Make a translation, then eliminate the shortcutIndication character at position 0 and set the one-key mnemonic to the successor of its second appearance, if any. Examples: 
               !be!enden   long=beenden   short=e
         $$quit      long=quit      short=q
         !quit            quit      short=null
         !$quit           $quit     short=null
         !$qui!t          $quit     short=t

    • addMuli_jTabbedPane

      protected void addMuli_jTabbedPane(Component p, String text)
      Adds the component at the end of the top-level JTabbedPane and memorizes it for later language switch.
      Parameters:
      text - text to translate, in "Mnemomic format": First character is deleted and its second appearance marks the mnemonic, as in "%e%xit" or "&&File".

    • addMuli_jTabbedPane

      protected void addMuli_jTabbedPane(Component p, String text, @Opt @Opt String tooltiptext)

    • addMuli_jTabbedPane

      protected void addMuli_jTabbedPane(Component p, String text, int position)
      Adds the component at the given position of the top-level JTabbedPane and memorizes it for later language switch.
      Parameters:
      text - text to translate, in "Mnemomic format": First character is deleted and its second appearance marks the mnemonic, as in "%e%xit" or "&&File".

    • makeMuli_anyTabbedPane

      protected void makeMuli_anyTabbedPane(Component p, String text, @Opt @Opt String tooltiptext)
      Memorizes the component as being contained in ANY JTabbedPane for later language switch. This version is NOT related to the top-level jTabbedPane and does not insert the component anywhere. Instead, the component must already be inserted in some JTabbedPane.
      Parameters:
      text - text to translate, in "Mnemomic format": First character is deleted and its second appearance marks the mnemonic, as in "%e%xit" or "&&File".
      Throws:
      IllegalArgumentException - in case "p" is not directly contained in a JTabbedPane.

    • updateLanguage_anyTabbedPane

      protected void updateLanguage_anyTabbedPane(Component p)
      Switch the text and the mnemonic of the tab of the JTabbedPane, containing the component.

    • makeMuli

      protected <X extends AbstractButton> X makeMuli(X button, String text)
      Should work for JButton, JMenu, JMenuItem, JRadioButton, JCheckBox. Typical usage pattern: myPanel.add(makeMuli(new JButton(), "$button$text"));
      Parameters:
      text - text to translate, in "Mnemomic format": First character is deleted and its second appearance marks the mnemonic, as in "%e%xit" or "&&File".

    • switchLanguage

      public boolean switchLanguage(String lang)
      Main service to switch the language of error messages, help functions, GUI labels, and many others. The work is carried out by switchLanguage_internal(String), and then additionally a log message is generated.

    • switchLanguage_internal

      public boolean switchLanguage_internal(String lang)
      Switch language without protocol message. Only lets pass languages which are in the configuration list. Updates all resources to the newlanguage, UNCONDITIONALLY.
      Returns:
      whether language has changed w.r.t current selection.

    • complete_icon_list

      protected void complete_icon_list(List<String> langs, List<Icon> icons)
      Add a provisonary text icon like "[it]" to the list of flag icons, if no flag is contained at the list position of the language code.

    • addMenu

      protected void addMenu()
      Add a new Menu, currently only with "File:quit", "Language" and "Help:about and docu" entries. See http://docs.oracle.com/javase/tutorial/uiswing/

    • showPreferencesInDialogWindow

      protected void showPreferencesInDialogWindow(boolean all)
      Shows all stored persistent data in a dialog and allows to clear the own data. Pesistency operations are for qualified users only, so MuLi is NOT supported, but LINGUA FRANCA expected.
      Parameters:
      all - whether all data and not only for this application is shown.

    • user_requests_documentation

      public void user_requests_documentation()
      Central dialog to download DEnS (documentation, examples and sources).

    • persistAllCmdLineArgs

      protected void persistAllCmdLineArgs()
      Store the state of the option model to the persistency cache. Must be called by the payload code explicitly (in case of success, or sim.)

    • persistentPutString

      protected void persistentPutString(String key, @Opt @Opt String value)
      Put the data, retrievable by the current application and the explict key used together as key.
      "this.getClass() identifies the package of the derived application, not of this class.

    • persistentGetString

      @Opt protected @Opt String persistentGetString(String key, @Opt @Opt String deflt)
      Read the data which is stored under the current application and the explicit key used as key.

    • persistentPutByteArray

      protected void persistentPutByteArray(String key, byte[] values)
      Store the data, retrievable by the current application and the explicit key used as key.

    • persistentGetByteArray

      @Opt protected @eu.bandm.tools.annotations.Opt byte[] persistentGetByteArray(String key)
      Return empty array if nothing found in preference storage.

    • persistentClear

      protected void persistentClear()
      Delete all persistency entries for this package. I.e., the package which contains the base class (derived from this class) of this.

    • dumpPreferences

      protected void dumpPreferences(boolean all)
      For debugging only, print COMPLETE current persistency tree to System.err. The format is an XML format defined by Preferences.exportSubtree(java.io.OutputStream).
      Parameters:
      all - whether all data and not only for this application is shown.

    • dumpPreferences

      protected void dumpPreferences(PrintStream stream, boolean all)
      For debugging only, print COMPLETE current persistency tree. The format is an XML format defined by Preferences.exportSubtree(java.io.OutputStream).
      Parameters:
      all - whether all data and not only for this application is shown.