DocumentedDistribution2 (BandM metatools API doc)

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
```
public abstract class DocumentedDistribution2<M extends <any>,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 REPLACECMENT 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:

Serialized Form

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`static class`	`DocumentedDistribution2.Configuration<MM extends Model,GG extends Gui>` Auxiliary data class to define the main operation parameters by a particular instance of a particular application, realized as a subclass of `DocumentedDistribution2`.

Nested classes/interfaces inherited from class javax.swing.JFrame
JFrame.AccessibleJFrame

Nested classes/interfaces inherited from class java.awt.Frame
Frame.AccessibleAWTFrame

Nested classes/interfaces inherited from class java.awt.Window
Window.AccessibleAWTWindow, Window.Type

Nested classes/interfaces inherited from class java.awt.Container
Container.AccessibleAWTContainer

Nested classes/interfaces inherited from class java.awt.Component
Component.AccessibleAWTComponent, Component.BaselineResizeBehavior, Component.BltBufferStrategy, Component.FlipBufferStrategy

Field Summary

Fields
Modifier and Type	Field and Description
`protected Map<Component,String>`	`anyTabbedPane2textKey` Maps Swing objects to MuLi keys for dynamic language change.
`protected Map<AbstractButton,String>`	`button2textKey` Maps Swing objects to MuLi keys for dynamic language change.
`protected JPanel`	`buttonPanel` The container below the options for the "action" buttons.
`protected @Opt String`	`codePosition` Disk file position of the currently running code.
`protected List<Icon>`	`completed_user_language_icons` This is a copy of the original list of languages `Configuration.user_language_icons`, completed by `ListIcon`s when no flag icon has been provided.
`DocumentedDistribution2.Configuration<M,G>`	`configuration` The configuration object passed to the constructor call.
`protected byte[]`	`DEnS_cs` Checksum of all files in the local copy of DEnS.
`protected @Opt String`	`DEnS_dir` Common root directory's position of documentation, examples and sources on the local machine.
`static String[]`	`emptyArgs` Evident
`protected SwingMessageField<SimpleMessage<String>>`	`errorMsgField` Text label showing always the last message sent to .
`protected List<JMenuItem>`	`exampleMenuItems` Menu items initially inactive; enabled after successful DEnS download.
`protected JButton`	`executeButton` The button below the GUI option pane, for starting processing.
`protected @Opt String`	`firstSignerName` The name of the first/main signer of the code.
`Format`	`generationComment`
`protected boolean`	`guiPopulated` Flag set after all GUI elements have been created.
`static ImageIcon`	`icon_flag_Germany` An icon showing the German flag.
`static ImageIcon`	`icon_flag_romanEmpire` An icon showing the flag of the Roman Empire, for Latin translations.
`static ImageIcon`	`icon_flag_Spain` An icon showing the flag of Spain.
`static ImageIcon`	`icon_flag_USA` An icon showing the flag of the USA.
`protected boolean`	`interactiveIsRequested` Set to true if no payload task is defined on the command line (=no non-meta options), but can be set true explicitly by the payload task (by callback `requestInteraction(boolean)` for starting the GUI nevertheless.
`protected boolean`	`isInitialCall` Output to the payload task implementation whether its execution comes directly from the command lines, with no GUI interference.
`protected boolean`	`isMuli` Reflects whether more than one language has been specified.
`protected boolean`	`jarRunning` Whether this runs from a jar file.
`protected JTabbedPane`	`jTabbedPane` The top container for all tab panes (options, messages, and subclass specifics).
`static 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.
`static 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.
`static 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.
`static 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.
`protected Map<JLabel,String>`	`label2textKey` Maps Swing objects to MuLi keys for dynamic language change.
`protected ButtonGroup`	`languageButtons` The language buttons appearing in the language drop-down menu.
`protected JMenu`	`menu_lang` The language drop-down menu.
`static String`	`menu_languages_name` The name of the top-level menu entry for switching the user language.
`static char`	`menu_languages_short` The acceleration character of the top-level menu entry for switching the user language.
`protected MessageStore<SimpleMessage<String>>`	`messageStore` Must be global because one further consumers will later be added in case of "GUI" use.
`protected List<String>`	`modified_user_languages` This is a copy of the original list of languages `Configuration.user_languages`, which duplicates the first element and thus allows (by later overriding this very first position of the search list) to switch language preferences dynamically.
`MuLiMessageReceiver<String>`	`msg` The message receiver for all error messages.
`protected MessageTee<SimpleMessage<String>>`	`msgtee` Must be global because two further consumers will later be added in case of "GUI" use.
`protected M`	`optionsModel` The central instance holding the ooptions for all payload runs, GUI editing, serialization etc.
`protected static String`	`PK_DEnS_digest` Persistency key
`protected static String`	`PK_DEnS_local_dir` Persistency key.
`protected static String`	`PK_optionsLanguage` Persistency key
`protected static String`	`PK_optionsLastRun` Persistency key
`String`	`programJavaClassName`
`protected @Opt JButton`	`resetToDefaultsButton` The button below the GUI option pane, for resetting to default values.

Fields inherited from class javax.swing.JFrame
accessibleContext, EXIT_ON_CLOSE, rootPane, rootPaneCheckingEnabled

Fields inherited from class java.awt.Frame
CROSSHAIR_CURSOR, DEFAULT_CURSOR, E_RESIZE_CURSOR, HAND_CURSOR, ICONIFIED, MAXIMIZED_BOTH, MAXIMIZED_HORIZ, MAXIMIZED_VERT, MOVE_CURSOR, N_RESIZE_CURSOR, NE_RESIZE_CURSOR, NORMAL, NW_RESIZE_CURSOR, S_RESIZE_CURSOR, SE_RESIZE_CURSOR, SW_RESIZE_CURSOR, TEXT_CURSOR, W_RESIZE_CURSOR, WAIT_CURSOR

Fields inherited from class java.awt.Component
BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT

Fields inherited from interface javax.swing.WindowConstants
DISPOSE_ON_CLOSE, DO_NOTHING_ON_CLOSE, HIDE_ON_CLOSE

Fields inherited from interface java.awt.image.ImageObserver
ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH

Constructor Summary

Constructors
Constructor and Description
`DocumentedDistribution2(DocumentedDistribution2.Configuration<M,G> configuration)` Only constructor, which stores the `DocumentedDistribution2.Configuration` value and initializes `msg`, `messageStore` and `modified_user_languages`,

Method Summary

All Methods Instance Methods Abstract Methods Concrete Methods
Modifier and Type	Method and Description
`protected void`	`addMenu()` Add a new Menu, currently only with "File:quit", "Language" and "Help:about and docu" entries.
`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.
`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.
`protected abstract void`	`addUserMenuItems()` Call-back method to be overridden whenever the subclass wants to add further items to the main menu bar.
`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.
`protected void`	`clearErrorMsg()` Callback for the payload implementation to clear the message field
`String`	`closeDialogLink()` Delivers the source text of an HTML link to close a window, in the current language.
`protected void`	`compareLanguageSets(Collection<String> A, String Aname, Collection<String> B, String Bname)` Meta-analysis about the consistency of translations.
`protected void`	`compareLanguageSets2(Collection<String> A, String Aname, Collection<String> B, String Bname)` Meta-analysis about the consistency of translations.
`protected void`	`complete_icon_list(List<String> langs, List<Icon> icons)` Find the language icon at the nth position, if any.
`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.
`protected String`	`currentLanguage()` Evident
`protected void`	`dumpPreferences(boolean all)` For debugging only, print COMPLETE current persistency tree to System.err.
`protected void`	`dumpPreferences(PrintStream stream, boolean all)` For debugging only, print COMPLETE current persistency tree.
`protected void`	`executeBatchOperation_caught()` Exceptions are caught here, explicitly.
`protected abstract void`	`executeBatchOperation()` Call-back main execution method, called with all parameters entered into `optionsModel`, coming from the GUI or command line.
`int`	`getCriticalCount()` Number of critical messages (errors, failures) in the standard message channel.
`protected @Opt String`	`getFirstSignerName()` Returns the string representation of the name of the last signer in the first certificate chain.
`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();"
`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.
`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.
`protected String`	`insitu(String key, String... translations)`
`protected String`	`INSITU(String key, String... translations)` Makes an "in situ" definition using `Catalog.INSITU(Object,List)`.
`protected boolean`	`isInitialCall()` Output to the payload task implementation whether its execution comes directly from the command lines, with no GUI interference.
`protected boolean`	`isTampered()` Is only called if DEnS have been downloaded, according to perssitent storage.
`protected TextDialog`	`makeAboutDialog(String title, boolean modal)` Display a pop-up dialog window with an overall status text for the user.
`protected void`	`makeMuli_anyTabbedPane(Component p, String text)` Memorizes the component as being contained in ANY JTabbedPane for later language switch.
`protected JLabel`	`makeMuli_JLabel(String text)`
`protected <X extends AbstractButton> X`	`makeMuli(X button, String text)` Should work for JButton, JMenu, JMenuItem, JRadioButton, JCheckBox.
`protected String`	`makeStatusText()` Contructs the information text which presents status to the human user, in the current language.
`void`	`non_static_main(String[] args)` Main entry for command line and for GUI operation.
`protected void`	`persistAllCmdLineArgs()` Store the state of the option model to the persistency cache.
`protected void`	`persistentClear()` Delete all persistency entries for this package.
`protected @Opt byte[]`	`persistentGetByteArray(String key)` Return empty array if nothing found in preference storage.
`protected @Opt String`	`persistentGetString(String key, @Opt String deflt)` Read the data which is stored under the current application and the explicit key used as key.
`protected void`	`persistentPutByteArray(String key, byte[] values)` Store the data, retrievable by the current application and the explicit key used as key.
`protected void`	`persistentPutString(String key, @Opt String value)` Put the data, retrievable by the current application and the explict key used together as key.
`protected void`	`populate()` Generate all graphic panes and add them to the topmost window = this.
`protected void`	`POSIX_print_help()` Print standardized command line "--help" output.
`protected void`	`POSIX_print_version()` Print standardized and parseable command line "--version" output.
`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.
`protected void`	`selectExampleOptions(@Opt String shortName)` Is called by the framework to the derived class to let the options point to a prefactored example.
`protected void`	`setErrorMsg(String s)` Callback for the payload implementation to show a short text in the message field
`protected void`	`showPreferencesInDialogWindow(boolean all)` Shows all stored persistent data in a dialog and allows to clear the own data.
`protected String`	`stripHtml(String s)` Convert for output on stdout/stderr by stripping all HTML formatting.
`boolean`	`switchLanguage_internal(String lang)` Swith language without protocol message.
`boolean`	`switchLanguage(String lang)` Main service to switch the language of error messages, help functions, GUI labels, and many others.
`void`	`terminateApplicationDueToSevereErrors_usage(MessageCounter<?> m)` As `terminateApplicationDueToSevereErrors(MessageCounter)`, with printing of the usage information in case of error.
`void`	`terminateApplicationDueToSevereErrors()` If errors have been counted, then print a text to the terminal of the command line and exits the application.
`void`	`terminateApplicationDueToSevereErrors(MessageCounter<?> m)` If errors have been counted, then print a text to the terminal of the command line and exits the application.
`String`	`translate(String t)` Translate the input String as defined by the catalog object and the language code priority sequence, both from `msg`.
`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`.
`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.
`@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.
`protected void`	`updateLanguage_anyTabbedPane(Component p)` Switch the text and the mnemonic of the tab of the JTabbedPane, containing the component.
`protected void`	`updateStatusInformation()` Central self-reflecting data collection and analysis.
`void`	`user_requests_documentation()` Central dialog to download DEnS (documentation, examples and sources).

Methods inherited from class java.awt.Frame
addNotify, getCursorType, getExtendedState, getFrames, getIconImage, getMaximizedBounds, getMenuBar, getState, getTitle, isResizable, isUndecorated, remove, removeNotify, setBackground, setCursor, setExtendedState, setMaximizedBounds, setMenuBar, setOpacity, setResizable, setShape, setState, setTitle, setUndecorated

Methods inherited from class java.awt.Window
addPropertyChangeListener, addPropertyChangeListener, addWindowFocusListener, addWindowListener, addWindowStateListener, applyResourceBundle, applyResourceBundle, createBufferStrategy, createBufferStrategy, dispose, getBackground, getBufferStrategy, getFocusableWindowState, getFocusCycleRootAncestor, getFocusOwner, getFocusTraversalKeys, getIconImages, getInputContext, getListeners, getLocale, getModalExclusionType, getMostRecentFocusOwner, getOpacity, getOwnedWindows, getOwner, getOwnerlessWindows, getShape, getToolkit, getType, getWarningString, getWindowFocusListeners, getWindowListeners, getWindows, getWindowStateListeners, hide, isActive, isAlwaysOnTop, isAlwaysOnTopSupported, isAutoRequestFocus, isFocusableWindow, isFocusCycleRoot, isFocused, isLocationByPlatform, isOpaque, isShowing, isValidateRoot, pack, paint, postEvent, processEvent, processWindowFocusEvent, processWindowStateEvent, removeWindowFocusListener, removeWindowListener, removeWindowStateListener, reshape, setAlwaysOnTop, setAutoRequestFocus, setBounds, setBounds, setCursor, setFocusableWindowState, setFocusCycleRoot, setIconImages, setLocation, setLocation, setLocationByPlatform, setLocationRelativeTo, setMinimumSize, setModalExclusionType, setSize, setSize, setType, setVisible, show, toBack, toFront

Methods inherited from class java.awt.Container
add, add, add, add, add, addContainerListener, applyComponentOrientation, areFocusTraversalKeysSet, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getAlignmentX, getAlignmentY, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getComponentZOrder, getContainerListeners, getFocusTraversalPolicy, getInsets, getLayout, getMaximumSize, getMinimumSize, getMousePosition, getPreferredSize, insets, invalidate, isAncestorOf, isFocusCycleRoot, isFocusTraversalPolicyProvider, isFocusTraversalPolicySet, layout, list, list, locate, minimumSize, paintComponents, preferredSize, print, printComponents, processContainerEvent, remove, removeAll, removeContainerListener, setComponentZOrder, setFocusTraversalKeys, setFocusTraversalPolicy, setFocusTraversalPolicyProvider, setFont, transferFocusDownCycle, validate, validateTree

Methods inherited from class java.awt.Component
action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, bounds, checkImage, checkImage, coalesceEvents, contains, contains, createImage, createImage, createVolatileImage, createVolatileImage, disable, disableEvents, dispatchEvent, enable, enable, enableEvents, enableInputMethods, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getBaseline, getBaselineResizeBehavior, getBounds, getBounds, getColorModel, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusListeners, getFocusTraversalKeysEnabled, getFont, getFontMetrics, getForeground, getGraphicsConfiguration, getHeight, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputMethodListeners, getInputMethodRequests, getKeyListeners, getLocation, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMousePosition, getMouseWheelListeners, getName, getParent, getPeer, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getSize, getTreeLock, getWidth, getX, getY, gotFocus, handleEvent, hasFocus, imageUpdate, inside, isBackgroundSet, isCursorSet, isDisplayable, isDoubleBuffered, isEnabled, isFocusable, isFocusOwner, isFocusTraversable, isFontSet, isForegroundSet, isLightweight, isMaximumSizeSet, isMinimumSizeSet, isPreferredSizeSet, isValid, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, prepareImage, prepareImage, printAll, processComponentEvent, processFocusEvent, processHierarchyBoundsEvent, processHierarchyEvent, processInputMethodEvent, processKeyEvent, processMouseEvent, processMouseMotionEvent, processMouseWheelEvent, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, resize, resize, revalidate, setComponentOrientation, setDropTarget, setEnabled, setFocusable, setFocusTraversalKeysEnabled, setForeground, setIgnoreRepaint, setLocale, setMaximumSize, setName, setPreferredSize, show, size, toString, transferFocus, transferFocusBackward, transferFocusUpCycle

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface java.awt.MenuContainer
getFont, postEvent

- Field Detail
  - configuration
```
public final DocumentedDistribution2.Configuration<M extends <any>,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.
  - menu_languages_name
```
public static final String menu_languages_name
```
    The name of the top-level menu entry for switching the user language.
    
    See Also:
    
    Constant Field Values
  - menu_languages_short
```
public static final char menu_languages_short
```
    The acceleration character of the top-level menu entry for switching the user language.
  - 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:
    
    Constant Field Values
  - 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:
    
    Constant Field Values
  - 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:
    
    Constant Field Values
  - 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:
    
    Constant Field Values
  - 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
```
  - msg
```
public final MuLiMessageReceiver<String> msg
```
    The message receiver for all error messages. The data flow will be
```
     msg -------> msgtee -+--> messageStore  --> SwingMessageTable
      |                   +--> messagePrinter
      |                   +--> MessageDialog
      |                   +--> SwingMessageField
     (msgCounter is provided internally by MuLiMessageReceiver.getCounter())  
  
```
  - msgtee
```
protected final MessageTee<SimpleMessage<String>> msgtee
```
    Must be global because two further consumers will later be added in case of "GUI" use.
  - messageStore
```
protected final MessageStore<SimpleMessage<String>> messageStore
```
    Must be global because one further consumers will later be added in case of "GUI" use.
  - modified_user_languages
```
protected final List<String> modified_user_languages
```
    This is a copy of the original list of languages Configuration.user_languages, which duplicates the first element and thus allows (by later overriding this very first position of the search list) to switch language preferences dynamically.
  - completed_user_language_icons
```
protected final List<Icon> completed_user_language_icons
```
    This is a copy of the original list of languages Configuration.user_language_icons, completed by ListIcons 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:
    
    Constant Field Values
  - PK_DEnS_digest
```
protected static final String PK_DEnS_digest
```
    Persistency key
    
    See Also:
    
    Constant Field Values
  - PK_optionsLastRun
```
protected static final String PK_optionsLastRun
```
    Persistency key
    
    See Also:
    
    Constant Field Values
  - PK_optionsLanguage
```
protected static final String PK_optionsLanguage
```
    Persistency key
    
    See Also:
    
    Constant Field Values
  - emptyArgs
```
public static final String[] emptyArgs
```
    Evident
  - optionsModel
```
protected M extends <any> optionsModel
```
    The central instance holding the ooptions for all payload runs, GUI editing, serialization etc.
    (Please note: the corresponding instance is currently contained 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), but can be set true explicitly by the payload task (by callback requestInteraction(boolean) for starting the GUI nevertheless.
  - 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 "", 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.
  - languageButtons
```
protected final ButtonGroup languageButtons
```
    The language buttons appearing in the language drop-down menu.
  - menu_lang
```
protected JMenu menu_lang
```
    The language drop-down menu.
- Constructor Detail
  - DocumentedDistribution2
```
public DocumentedDistribution2(DocumentedDistribution2.Configuration<M,G> configuration)
```
    Only constructor, which stores the DocumentedDistribution2.Configuration value and initializes msg, messageStore and modified_user_languages,
- Method Detail
  - 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 given by msg and has been 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 given by msg and has been 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 given by msg and has been 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(String,List)
  - INSITU
```
protected String INSITU(String key,
                        String... translations)
```
    Makes an "in situ" definition using Catalog.INSITU(Object,List). It puts the definitions in to the current muli messages catalog and returns the key, so it can be used as an argument for MuLiMessageReceiver methods.
    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
  - 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(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 to the derived class to let the options point to a prefactored example. These shortNames of these examples must listed in Option#examplesShortNames and 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.
  - 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.
  - 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.
  - 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 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
  - setErrorMsg
```
protected void setErrorMsg(String s)
```
    Callback for the payload implementation to show a short text in the message field
  - clearErrorMsg
```
protected void clearErrorMsg()
```
    Callback for the payload implementation to clear the message field
  - 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,
                                   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)
```
    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)
```
    Swith language without protocol message. Only lets pass languages which are in the configuration list.
  - complete_icon_list
```
protected void complete_icon_list(List<String> langs,
                                  List<Icon> icons)
```
    Find the language icon at the nth position, if any.
  - 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. Preferences
    "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. Preferences
  - persistentPutByteArray
```
protected void persistentPutByteArray(String key,
                                      byte[] values)
```
    Store the data, retrievable by the current application and the explicit key used as key. Preferences
  - persistentGetByteArray
```
@Opt
protected @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(OutStream).
    
    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(OutStream).
    
    Parameters:
    
    all - whether all data and not only for this application is shown.

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

Nested Class Summary

Nested classes/interfaces inherited from class javax.swing.JFrame

Nested classes/interfaces inherited from class java.awt.Frame

Nested classes/interfaces inherited from class java.awt.Window

Nested classes/interfaces inherited from class java.awt.Container

Nested classes/interfaces inherited from class java.awt.Component

Field Summary

Fields inherited from class javax.swing.JFrame

Fields inherited from class java.awt.Frame

Fields inherited from class java.awt.Component

Fields inherited from interface javax.swing.WindowConstants

Fields inherited from interface java.awt.image.ImageObserver

Constructor Summary

Method Summary

Methods inherited from class javax.swing.JFrame

Methods inherited from class java.awt.Frame

Methods inherited from class java.awt.Window

Methods inherited from class java.awt.Container

Methods inherited from class java.awt.Component

Methods inherited from class java.lang.Object

Methods inherited from interface java.awt.MenuContainer

Field Detail

configuration

isMuli

menu_languages_name

menu_languages_short

KEY_PATH_local_userdocumentation

KEY_URL_web_userdocumentation

KEY_ultra_short_description

KEY_about_additional_text

icon_flag_Germany

icon_flag_USA

icon_flag_romanEmpire

icon_flag_Spain

programJavaClassName

generationComment

msg

msgtee

messageStore

modified_user_languages

completed_user_language_icons

jarRunning

codePosition

firstSignerName

DEnS_dir

DEnS_cs

PK_DEnS_local_dir

PK_DEnS_digest

PK_optionsLastRun

PK_optionsLanguage

emptyArgs

optionsModel

executeButton

resetToDefaultsButton

guiPopulated

jTabbedPane

buttonPanel

errorMsgField

interactiveIsRequested

isInitialCall

exampleMenuItems

button2textKey

label2textKey

anyTabbedPane2textKey

languageButtons

menu_lang

Constructor Detail

DocumentedDistribution2

Method Detail

closeDialogLink

translate

translateNonRobust

translate

insitu

insitu

insitu

INSITU

terminateApplicationDueToSevereErrors

terminateApplicationDueToSevereErrors