SessionStateXml (MyTISM API Documentation)

java.lang.Object
- de.ipcon.gui.session.SessionStateXml

```
public class SessionStateXml
extends java.lang.Object
```
Wrapper around Electric XML providing a fluent, type-safe API to incrementally update and persist desktop session state XML (e.g. in user configuration records).
XML Schema Overview
```
 <Session>
   <Window x="0.0" y="0.0" w="2560.0" h="1440.0" state="6" zoom="1.0"/>
   <LRU>
     
     <Bookmark title="Alarme (Admin)" on="2026-07-31 11:53:40.542+02" id="1001" entity="Alarm"/>
     
     <Form title="Hinweis [2001] Ticket erstellt" on="2026-07-31 11:53:57.138+02" entity="Hinweis" boId="2001"/>
     
     <Bookmark title="Sitzungen" on="2026-07-31 11:54:20.297+02" entity="Sitzung"/>
     
     <Form title="Sitzung [3001] sysAdmin @Rivendell (DMId: 19ce4b...) (31.07.2026, 11:53:27 - ???)" on="2026-07-31 11:54:45.898+02" entity="Sitzung" boId="3001"/>
     
     <Form title="Hinweis [2003] Ticket eröffnet" on="2026-07-31 11:55:17.550+02" id="1002" tid="MPS_FORM_HINWEIS_VORGEBAUT" entity="Hinweis" boId="2003"/>
     
     <Form title="Sitzung (Sitzung-Formular (Automatisch generiert))" on="2026-07-31 11:56:20.657+02" id="1003" tid="MAS_STRUKTUR" entity="Struktur" boEntity="Sitzung"/>
     
     <Bookmark title="Kunden" on="2026-07-31 11:57:05.629+02" id="1004" tid="MCS_KUNDEN" entity="Kunde"/>
     
     <Form title="Person [2006] Musterfrau, Eric" on="2026-07-31 11:57:52.358+02" id="1007" tid="MCS_MITARBEITERACCOUNT" entity="Person" boId="2006"/>
     <Form title="Benutzer [2007] em (Musterfrau, Eric)" on="2026-07-31 11:58:02.170+02" id="1008" tid="MAS_BENUTZER" entity="Benutzer" boId="2007"/>
   </LRU>
 </Session>
 
```
Identity Attributes & Lookups
History entries store combination keys to ensure structures can be re-opened across environments or after database imports, including auto-generated structures:
- id: Database primary key of the structure element (Formular, Lesezeichen, or Report).
- tid: Technical Identifier string. Preserved during database imports/exports, allowing robust resolution when primary keys change.
- entity: Simple name of the target entity associated with the structure element. Required for getByTid lookups and auto-forms.
- boId: Database primary key of the displayed target BO.
- boEntity: Simple entity name of the target BO when opening auto-forms without a persistent instance.
Action Script Resolution Strategy
When generating Groovy action scripts via getLruActionsXml(), entries are resolved in order of resilience:
1. Primary Key Lookup (Primary): Attempts resolution via ctx.getBO(id, Class) wrapped in a try-catch (Throwable e) block.
2. TID Lookup (Fallback): If the ID lookup throws an exception, returns null, or resolves to an object marked as isDeleted(), the script falls back to getFormByTid, getBookmarkByTid, or getReportByTid (if both tid and entity are present).
3. Automatic Schema Lookup: If neither ID nor TID is present (e.g. auto-generated structures), the schema is queried via ctx.schema.getEntity(entity) to locate default automatic forms or views.
Core Responsibilities
- Window & Layout State: Tracks desktop coordinates, frame state and display zoom factors.
- LRU History Management: Maintains recently accessed forms, bookmarks and reports in access order.
- LRU Deduplication: Removes prior matching entries before appending. Forms match on composite key (structureId/entity + boId/boEntity); Bookmarks and Reports match on structure identity alone.
- Capacity Truncation: Restricts queue length via enforceLruCapacity(int).
- Self-Healing Sanitization: fromXml(String) validates structures on load, silently removing unrecognized nodes, duplicate root containers and corrupt numeric attributes.
See Also:

SessionBookmarkFilterValue

Field Summary

Fields
Modifier and Type	Field and Description
`static java.lang.String`	`ATTR_BO_ENTITY`
`static java.lang.String`	`ATTR_BO_ID`
`static java.lang.String`	`ATTR_ENTITY`
`static java.lang.String`	`ATTR_H`
`static java.lang.String`	`ATTR_ID`
`static java.lang.String`	`ATTR_KEY`
`static java.lang.String`	`ATTR_ON`
`static java.lang.String`	`ATTR_STATE`
`static java.lang.String`	`ATTR_TID`
`static java.lang.String`	`ATTR_TITLE`
`static java.lang.String`	`ATTR_W`
`static java.lang.String`	`ATTR_X`
`static java.lang.String`	`ATTR_Y`
`static java.lang.String`	`ATTR_ZOOM`
`static int`	`BASE_LRU_PRIORITY` Base priority offset for history menu actions (appended under SpecialMenu priority -800).
`static int`	`DEFAULT_EXT_STATE`
`static int`	`DEFAULT_EXT_STATE_MULTI_WINDOW`
`static int`	`DEFAULT_EXT_STATE_SINGLE_WINDOW`
`static double`	`DEFAULT_HEIGHT`
`static double`	`DEFAULT_HEIGHT_MULTI_WINDOW`
`static int`	`DEFAULT_MAX_LRU_CAPACITY` Default maximum capacity for the LRU history queue (50 entries).
`static double`	`DEFAULT_WIDTH`
`static double`	`DEFAULT_WIDTH_MULTI_WINDOW`
`static double`	`DEFAULT_X`
`static double`	`DEFAULT_Y`
`static float`	`DEFAULT_ZOOM_FACTOR` Default UI scale zoom factor (1.0 = 100%) fallback if unconfigured or invalid.
`static float`	`MAX_ZOOM_FACTOR` Maximum permitted UI scale zoom factor (5.0 = 500%).
`static java.lang.String`	`MENU_VERLAUF` Default menu identifier for history actions.
`static float`	`MIN_ZOOM_FACTOR` Minimum permitted UI scale zoom factor (0.25 = 25%).
`static java.lang.String`	`TAG_BOOKMARK`
`static java.lang.String`	`TAG_FILTER`
`static java.lang.String`	`TAG_FORM`
`static java.lang.String`	`TAG_LRU`
`static java.lang.String`	`TAG_OQL`
`static java.lang.String`	`TAG_REPORT`
`static java.lang.String`	`TAG_SESSION`
`static java.lang.String`	`TAG_WINDOW`

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`SessionStateXml`	`addBookmark(java.lang.Long structureId, java.lang.String structureTid, java.lang.String entityName, java.lang.String title, java.lang.String oql, java.util.Map<java.lang.String,SessionBookmarkFilterValue> filters)` Appends a Bookmark entry containing an optional OQL query and typed override filters.
`SessionStateXml`	`addForm(java.lang.Long structureId, java.lang.String structureTid, java.lang.String entityName, java.lang.Long boId, java.lang.String boEntityName, java.lang.String title)` Appends a business object Form entry to the LRU queue with full support for on-the-fly auto-generated forms, TIDs, and entity names.
`SessionStateXml`	`addReport(java.lang.Long structureId, java.lang.String structureTid, java.lang.String entityName, java.lang.String title)` Appends a Report entry for a standalone report to the LRU queue.
`static SessionStateXml`	`create()` Creates a fresh, unpopulated session state instance containing root `<Session>` and empty `<LRU>` container elements.
`SessionStateXml`	`enforceLruCapacity()` Truncates oldest entries at the head of the LRU queue using the default capacity of `DEFAULT_MAX_LRU_CAPACITY`.
`SessionStateXml`	`enforceLruCapacity(int maxEntries)` Truncates oldest entries at the head of the LRU queue until total size is within `maxEntries`.
`static SessionStateXml`	`fromXml(java.lang.String existingXml)` Restores session state from existing XML.
`java.util.List<java.lang.String>`	`getLruActionsXml()` Generates and returns a list of XML `<Action>` strings for all registered LRU history entries.
`de.ipcon.swing.WindowState`	`getWindowState()` Extracts and returns the saved mainframe window geometry and scale state.
`float`	`getZoomFactor()` Returns the saved UI scale zoom factor clamped between `MIN_ZOOM_FACTOR` and `MAX_ZOOM_FACTOR`.
`java.lang.String`	`toXml()` Serializes the document tree to XML text, e.g. for database storage.
`SessionStateXml`	`updateWindow(double x, double y, double width, double height, int extendedState, float zoomFactor)` Updates or creates the `<Window>` layout element under the root session.
`SessionStateXml`	`updateWindow(de.ipcon.swing.WindowState state, ClientStateSaveReason reason)` Updates or creates the `<Window>` layout element in the session state XML by applying reason-specific layout overrides to the provided `WindowState`.

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

- Field Detail
  - DEFAULT_ZOOM_FACTOR
```
public static final float DEFAULT_ZOOM_FACTOR
```
    Default UI scale zoom factor (1.0 = 100%) fallback if unconfigured or invalid.
    
    See Also:
    
    Constant Field Values
  - MIN_ZOOM_FACTOR
```
public static final float MIN_ZOOM_FACTOR
```
    Minimum permitted UI scale zoom factor (0.25 = 25%).
    
    See Also:
    
    Constant Field Values
  - MAX_ZOOM_FACTOR
```
public static final float MAX_ZOOM_FACTOR
```
    Maximum permitted UI scale zoom factor (5.0 = 500%).
    
    See Also:
    
    Constant Field Values
  - DEFAULT_MAX_LRU_CAPACITY
```
public static final int DEFAULT_MAX_LRU_CAPACITY
```
    Default maximum capacity for the LRU history queue (50 entries).
    
    See Also:
    
    Constant Field Values
  - BASE_LRU_PRIORITY
```
public static final int BASE_LRU_PRIORITY
```
    Base priority offset for history menu actions (appended under SpecialMenu priority -800).
    
    See Also:
    
    Constant Field Values
  - MENU_VERLAUF
```
public static final java.lang.String MENU_VERLAUF
```
    Default menu identifier for history actions.
    
    See Also:
    
    Constant Field Values
  - TAG_SESSION
```
public static final java.lang.String TAG_SESSION
```
    See Also:
    
    Constant Field Values
  - TAG_LRU
```
public static final java.lang.String TAG_LRU
```
    See Also:
    
    Constant Field Values
  - TAG_WINDOW
```
public static final java.lang.String TAG_WINDOW
```
    See Also:
    
    Constant Field Values
  - TAG_FORM
```
public static final java.lang.String TAG_FORM
```
    See Also:
    
    Constant Field Values
  - TAG_BOOKMARK
```
public static final java.lang.String TAG_BOOKMARK
```
    See Also:
    
    Constant Field Values
  - TAG_REPORT
```
public static final java.lang.String TAG_REPORT
```
    See Also:
    
    Constant Field Values
  - TAG_FILTER
```
public static final java.lang.String TAG_FILTER
```
    See Also:
    
    Constant Field Values
  - TAG_OQL
```
public static final java.lang.String TAG_OQL
```
    See Also:
    
    Constant Field Values
  - ATTR_ID
```
public static final java.lang.String ATTR_ID
```
    See Also:
    
    Constant Field Values
  - ATTR_TID
```
public static final java.lang.String ATTR_TID
```
    See Also:
    
    Constant Field Values
  - ATTR_ENTITY
```
public static final java.lang.String ATTR_ENTITY
```
    See Also:
    
    Constant Field Values
  - ATTR_TITLE
```
public static final java.lang.String ATTR_TITLE
```
    See Also:
    
    Constant Field Values
  - ATTR_ON
```
public static final java.lang.String ATTR_ON
```
    See Also:
    
    Constant Field Values
  - ATTR_BO_ID
```
public static final java.lang.String ATTR_BO_ID
```
    See Also:
    
    Constant Field Values
  - ATTR_BO_ENTITY
```
public static final java.lang.String ATTR_BO_ENTITY
```
    See Also:
    
    Constant Field Values
  - ATTR_KEY
```
public static final java.lang.String ATTR_KEY
```
    See Also:
    
    Constant Field Values
  - ATTR_X
```
public static final java.lang.String ATTR_X
```
    See Also:
    
    Constant Field Values
  - ATTR_Y
```
public static final java.lang.String ATTR_Y
```
    See Also:
    
    Constant Field Values
  - ATTR_W
```
public static final java.lang.String ATTR_W
```
    See Also:
    
    Constant Field Values
  - ATTR_H
```
public static final java.lang.String ATTR_H
```
    See Also:
    
    Constant Field Values
  - ATTR_STATE
```
public static final java.lang.String ATTR_STATE
```
    See Also:
    
    Constant Field Values
  - ATTR_ZOOM
```
public static final java.lang.String ATTR_ZOOM
```
    See Also:
    
    Constant Field Values
  - DEFAULT_X
```
public static final double DEFAULT_X
```
    See Also:
    
    Constant Field Values
  - DEFAULT_Y
```
public static final double DEFAULT_Y
```
    See Also:
    
    Constant Field Values
  - DEFAULT_WIDTH
```
public static final double DEFAULT_WIDTH
```
    See Also:
    
    Constant Field Values
  - DEFAULT_WIDTH_MULTI_WINDOW
```
public static final double DEFAULT_WIDTH_MULTI_WINDOW
```
    See Also:
    
    Constant Field Values
  - DEFAULT_HEIGHT
```
public static final double DEFAULT_HEIGHT
```
    See Also:
    
    Constant Field Values
  - DEFAULT_HEIGHT_MULTI_WINDOW
```
public static final double DEFAULT_HEIGHT_MULTI_WINDOW
```
    See Also:
    
    Constant Field Values
  - DEFAULT_EXT_STATE
```
public static final int DEFAULT_EXT_STATE
```
    See Also:
    
    Constant Field Values
  - DEFAULT_EXT_STATE_SINGLE_WINDOW
```
public static final int DEFAULT_EXT_STATE_SINGLE_WINDOW
```
    See Also:
    
    Constant Field Values
  - DEFAULT_EXT_STATE_MULTI_WINDOW
```
public static final int DEFAULT_EXT_STATE_MULTI_WINDOW
```
    See Also:
    
    Constant Field Values
- Method Detail
  - create
```
public static SessionStateXml create()
```
    Creates a fresh, unpopulated session state instance containing root <Session> and empty <LRU> container elements.
  - fromXml
```
public static SessionStateXml fromXml(java.lang.String existingXml)
```
    Restores session state from existing XML. If parsing fails or the payload lacks a valid <Session> root element, returns a fresh empty state instance.
    
    Parameters:
    
    existingXml - raw XML document string, e.g. taken from the database or null
  - getZoomFactor
```
public float getZoomFactor()
```
    Returns the saved UI scale zoom factor clamped between MIN_ZOOM_FACTOR and MAX_ZOOM_FACTOR.
    
    Returns:
    
    zoom factor (e.g. 1.25), or DEFAULT_ZOOM_FACTOR if unconfigured or invalid
  - getWindowState
```
public de.ipcon.swing.WindowState getWindowState()
```
    Extracts and returns the saved mainframe window geometry and scale state.
    If dimensions (w or h) are omitted from the XML (e.g. due to the maximization workaround), they fall back to DEFAULT_WIDTH and DEFAULT_HEIGHT.
    
    Returns:
    
    saved WindowState instance, or null if no valid window configuration exists
  - getLruActionsXml
```
public java.util.List<java.lang.String> getLruActionsXml()
```
    Generates and returns a list of XML <Action> strings for all registered LRU history entries.
    Actions are assigned unique command identifiers (openLRU-1, openLRU-2, etc.) and priority values starting at -801 descending so that the newest entry is positioned at the top of the history menu.
    
    Returns:
    
    list of formatted XML action strings ordered newest first, or an empty list if no history exists
  - updateWindow
```
public SessionStateXml updateWindow(de.ipcon.swing.WindowState state,
                                    ClientStateSaveReason reason)
```
    Updates or creates the <Window> layout element in the session state XML by applying reason-specific layout overrides to the provided WindowState.
    Lifecycle & Layout Strategy:
    - Window Manager Switch: When switching window modes, sensible defaults are enforced to prevent initial layout distortions (e.g. avoiding an oversized full-screen frame in multi-window mode or an undersized frame in single-window mode):
      
      ClientStateSaveReason.SET_SINGLE_WINDOW_MANAGER: Forces the maximized state (DEFAULT_EXT_STATE_SINGLE_WINDOW).
      
      ClientStateSaveReason.SET_MULTI_WINDOW_MANAGER: Forces default navigation sidebar dimensions (DEFAULT_WIDTH_MULTI_WINDOW, DEFAULT_HEIGHT_MULTI_WINDOW) and normal unmaximized state (DEFAULT_EXT_STATE_MULTI_WINDOW).
    - Logout without Live State: If state is null during ClientStateSaveReason.LOGOUT (e.g. because a window manager switch is pending a restart), this method acts as a no-op and preserves the existing window configuration in the XML.
    - Regular Saves & Logout: For all other reasons (or when a valid live state is present), the user’s manual window adjustments captured in state are preserved.
    Fallback & Post-Processing:
    - If state is null for reasons other than ClientStateSaveReason.LOGOUT, standard baseline parameters (DEFAULT_X, DEFAULT_Y, DEFAULT_WIDTH, DEFAULT_HEIGHT, DEFAULT_EXT_STATE, DEFAULT_ZOOM_FACTOR) serve as the starting point before evaluating reason.
    - The resulting geometry is delegated to updateWindow(double, double, double, double, int, float), which clamps the zoom factor to [MIN_ZOOM_FACTOR, MAX_ZOOM_FACTOR] and omits width and height attributes if maximized to prevent GNOME/X11 window manager lockups.
    Parameters:
    
    state - the current mainframe window geometry and UI zoom state; if null on logout, the existing XML configuration remains untouched
    
    reason - the trigger context defining mandatory window dimension and state overrides (must not be null)
    
    Returns:
    
    this instance for method chaining
    
    Throws:
    
    de.ipcon.tools.MissingArgumentException - if reason is null
    
    See Also:
    
    updateWindow(double, double, double, double, int, float)
  - updateWindow
```
public SessionStateXml updateWindow(double x,
                                    double y,
                                    double width,
                                    double height,
                                    int extendedState,
                                    float zoomFactor)
```
    Updates or creates the <Window> layout element under the root session. Clamps the zoom factor between MIN_ZOOM_FACTOR and MAX_ZOOM_FACTOR.
    GNOME/X11 Maximization Workaround: If horizontal or vertical maximization flags are active in extendedState, the respective dimension attribute (w or h) is removed from the XML. This prevents window managers from restoring with fullscreen bounds as normal bounds.
    
    Parameters:
    
    x - horizontal desktop window coordinate
    
    y - vertical desktop window coordinate
    
    width - window width in pixels (must be > 0)
    
    height - window height in pixels (must be > 0)
    
    extendedState - extended window state flags (e.g. Frame.MAXIMIZED_BOTH)
    
    zoomFactor - UI scale zoom level as a factor (e.g. 1.0 for 100%)
    
    Returns:
    
    this instance for method chaining
  - addForm
```
public SessionStateXml addForm(java.lang.Long structureId,
                               java.lang.String structureTid,
                               java.lang.String entityName,
                               java.lang.Long boId,
                               java.lang.String boEntityName,
                               java.lang.String title)
```
    Appends a business object Form entry to the LRU queue with full support for on-the-fly auto-generated forms, TIDs, and entity names.
    
    Parameters:
    
    structureId - primary key of the form BO (if positive/persistent)
    
    structureTid - tid of the form BO (if positive/persistent)
    
    entityName - entity name if structureId is negative (auto-generated form)
    
    boId - primary key of the shown business object (if positive/persistent)
    
    boEntityName - bo entity name, only if boId is negative or missing (auto-generated form BO)
    
    title - localized window title (mandatory)
  - addBookmark
```
public SessionStateXml addBookmark(java.lang.Long structureId,
                                   java.lang.String structureTid,
                                   java.lang.String entityName,
                                   java.lang.String title,
                                   java.lang.String oql,
                                   java.util.Map<java.lang.String,SessionBookmarkFilterValue> filters)
```
    Appends a Bookmark entry containing an optional OQL query and typed override filters. Deduplicates by structure identity alone (different filter variations of the same bookmark view overwrite the prior entry in LRU history).
    
    Parameters:
    
    structureId - primary key of the bookmark BO (if positive/persistent)
    
    structureTid - tid of the bookmark BO (if positive/persistent)
    
    entityName - entity name if structureId is negative (auto-generated bookmark)
    
    title - localized bookmark title (mandatory)
    
    oql - OQL query expression or null
    
    filters - map of filter key names to typed filter values or null
  - addReport
```
public SessionStateXml addReport(java.lang.Long structureId,
                                 java.lang.String structureTid,
                                 java.lang.String entityName,
                                 java.lang.String title)
```
    Appends a Report entry for a standalone report to the LRU queue.
    
    Parameters:
    
    structureId - primary key of the report BO (if positive/persistent)
    
    structureTid - tid of the report BO (if positive/persistent)
    
    entityName - entity name if structureId is negative (auto-generated report)
    
    title - localized report title (mandatory)
  - enforceLruCapacity
```
public SessionStateXml enforceLruCapacity()
```
    Truncates oldest entries at the head of the LRU queue using the default capacity of DEFAULT_MAX_LRU_CAPACITY.
    
    Returns:
    
    this instance for method chaining
  - enforceLruCapacity
```
public SessionStateXml enforceLruCapacity(int maxEntries)
```
    Truncates oldest entries at the head of the LRU queue until total size is within maxEntries.
    
    Parameters:
    
    maxEntries - maximum permitted capacity; negative bounds clamp to 0
    
    Returns:
    
    this instance for method chaining
  - toXml
```
public java.lang.String toXml()
```
    Serializes the document tree to XML text, e.g. for database storage.

Class SessionStateXml

XML Schema Overview

Identity Attributes & Lookups

Action Script Resolution Strategy

Core Responsibilities

Field Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

DEFAULT_ZOOM_FACTOR

MIN_ZOOM_FACTOR

MAX_ZOOM_FACTOR

DEFAULT_MAX_LRU_CAPACITY

BASE_LRU_PRIORITY

MENU_VERLAUF

TAG_SESSION

TAG_LRU

TAG_WINDOW

TAG_FORM

TAG_BOOKMARK

TAG_REPORT

TAG_FILTER

TAG_OQL

ATTR_ID

ATTR_TID

ATTR_ENTITY

ATTR_TITLE

ATTR_ON

ATTR_BO_ID

ATTR_BO_ENTITY

ATTR_KEY

ATTR_X

ATTR_Y

ATTR_W

ATTR_H

ATTR_STATE

ATTR_ZOOM

DEFAULT_X

DEFAULT_Y

DEFAULT_WIDTH

DEFAULT_WIDTH_MULTI_WINDOW

DEFAULT_HEIGHT

DEFAULT_HEIGHT_MULTI_WINDOW

DEFAULT_EXT_STATE

DEFAULT_EXT_STATE_SINGLE_WINDOW

DEFAULT_EXT_STATE_MULTI_WINDOW

Method Detail

create

fromXml

getZoomFactor

getWindowState

getLruActionsXml

updateWindow

updateWindow

addForm

addBookmark

addReport

enforceLruCapacity

enforceLruCapacity

toXml