Package com.iizix.prop.vs

Class VSComponent

java.lang.Object
com.iizix.prop.GProp<GProp<?>[]>
com.iizix.prop.PropCnr
com.iizix.prop.vs.VSComponent
All Implemented Interfaces:
EventListener, IFocusComp, IMessageBox, ICustomDataProvider, IGProp<GProp<?>[]>, IPropCnr, IVSComponent, IVSComponentListener, IVSComponentState, Cloneable
Direct Known Subclasses:
VSAction, VSColumnHeader, VSField, VSGroup, VSRow, VSTable
public abstract class VSComponent extends PropCnr implements IVSComponent
Base VS class used by VirtualSpace elements: VSField, VSTable, VSRow, VSColumnHeader, VSAction, VirtualSpace.
Author:
Christopher Mindus

  • Field Details

  • Constructor Details

    • VSComponent

      protected VSComponent()
      Creates a VirtualSpace Field property with the specified name with a null value.

    • VSComponent

      protected VSComponent(Atom propertyAtom)
      Creates a VirtualSpace Field property with the specified name with a null value.
      Parameters:
      propertyAtom - the property atom.

    • VSComponent

      protected VSComponent(Atom propertyAtom, VSComponent[] properties) throws PropException
      Creates a property container with the specified name and properties.
      Parameters:
      propertyAtom - the property atom.
      properties - the property array value for the property.
      Throws:
      PropException - as structural changes in containers on client is prohibited.

  • Method Details

    • initPropCnr

      protected final void initPropCnr()
      Method called at the earliest possible stage in the constructor of a container property or it's extending classes, before possible initialization of other properties, etc.

      VS components use the named property hash map for lookup of properties fast.

      Overrides:
      initPropCnr in class PropCnr

    • convertLoadedProp

      protected GProp<?> convertLoadedProp(GProp<?> childProp) throws PropException
      Enables conversion or omission of a property loaded from XML.

      This method is typically used to process changes of e.g. property types, e.g. from IntProp to NumberProp, in case of a change of property definitions.

      Overrides:
      convertLoadedProp in class PropCnr
      Parameters:
      childProp - The child property that is about to be added.
      Returns:
      The property to add, null to omit it. The default processing is to return the same property, i.e. childProp.
      Throws:
      PropException - for property errors.

    • getClientSessionGyro

      public IClientSessionGyro getClientSessionGyro()
      Returns the Client Session Gyro instance.

      This method calls IClientSessionGyro.getSessionInstance() to retrieve the instance from the current thread.

      Specified by:
      getClientSessionGyro in interface IGProp<GProp<?>[]>
      Overrides:
      getClientSessionGyro in class GProp<GProp<?>[]>
      Returns:
      The Client Session Gyro if found for the current thread, null otherwise.

    • forbiddenGetCustomDataMap

      @Deprecated public Map<String,Object> forbiddenGetCustomDataMap(boolean doCreate)
      Deprecated.
      Gets or creates the provider map. This method is not intended to be called by user code, it is used by the system.

      Do not call this method!

      Specified by:
      forbiddenGetCustomDataMap in interface ICustomDataProvider
      Parameters:
      doCreate - Creates the map if required.
      Returns:
      The map or newly created map, null if not created.

      Note: the map returned is NOT synchronized thus not thread safe. It is up to the caller to synchronize on it to ensure thread safety.

      Throws:
      SecurityException - If called from other than system.

    • clone

      public VSComponent clone()
      Clones the VirtualSpace component. The runtime method instances (onVSChange and onVSFocus) are kept for the clone, so they do not need to be looked up again.
      Overrides:
      clone in class PropCnr

    • virtualize

      protected final VSComponent virtualize(IAppSessionGyro appGyro, IClientSessionGyro clientGyro, VirtualSpace virtualSpace) throws CloneNotSupportedException, PropException
      Call this method to "virtualize" a property tree. This method is used at runtime in the Server for the application session of virtual instances of VirtualSpace, but also virtual instances of panels, for the individual client session. The VirtualSpace is virtualized once for the application session and is shared for parallel client sessions.

      This method is similar to cloning, but enables references that are already resolved to remain if they point to a shared instance, e.g. the VirtualSpace pointing to its participants in the application property container shared instance, or a panel with references to text IDs, assets, etc.

      It is up to the property class to handle this by overriding this method.

      Overrides:
      virtualize in class PropCnr
      Parameters:
      appGyro - The application gyro instance performing the virtualization.
      clientGyro - The client gyro session, can be null if not initialized from the client gyro.
      virtualSpace - The virtualized VirtualSpace.
      Returns:
      The virtualized property.
      Throws:
      CloneNotSupportedException - If a subclass doesn't allow cloning, e.g. the client properties.
      PropException - For property errors during the virtualization.
      IllegalStateException - IllegalStateException if the property is in an invalid state, e.g. in virtualizing state or if in

    • getDescription

      public String getDescription()
      Gets the description of the component.
      Specified by:
      getDescription in interface IVSComponent
      Returns:
      The description, or null for none.

    • paramString

      protected String paramString()
      Returns the parameter string representing the state of this event. This string is useful for debugging. Subclasses adds extra information to the string by preceding it with a comma followed by the extra information.
      Overrides:
      paramString in class PropCnr
      Returns:
      the parameter string of this event.

    • getVirtualSpace

      public VirtualSpace getVirtualSpace()
      Gets the VirtualSpace instance.
      Specified by:
      getVirtualSpace in interface IVSComponent
      Returns:
      The VirtualSpace instance (an ancestor of this property or itself), or null if not found (i.e. property is not yet attached to a VirtualSpace).

    • onEventSelf

      public void onEventSelf(GEvent event)
      Checks for state change events and fires it to listeners.
      Specified by:
      onEventSelf in interface IGProp<GProp<?>[]>
      Overrides:
      onEventSelf in class GProp<GProp<?>[]>
      Parameters:
      event - The property event.

    • addListener

      public boolean addListener(IVSGenericComponentListener listener)
      Adds a new listener to the VS component.
      Parameters:
      listener - The listener for VS component events.
      Returns:
      true for success, false if the listener already is added.

    • removeListener

      public boolean removeListener(IVSGenericComponentListener listener)
      Removes a listener from the VS component.
      Parameters:
      listener - The existing listener for VS component events.
      Returns:
      true for success, false if the listener has not been added.

    • onListenerChanged

      protected void onListenerChanged(IVSGenericComponentListener listener)
      Called when a listener is added or removed. This method is overridden by the Designer to update connections.

    • getComponentListeners

      public IVSGenericComponentListener[] getComponentListeners()
      Gets the listeners of the VS component events.
      Returns:
      A cached array of listeners for the value, retrieved without synchronization if possible.

    • isFree

      public boolean isFree()
      Verifies if this component is included in a work unit currently in progress in the VirtualSpace.
      Returns:
      true if it's OK to process, false means the component is included in this work unit.

    • isFree

      public boolean isFree(Runnable callback, boolean callbackIfFree)
      Verifies if this component is included in a work unit currently in progress in the VirtualSpace.
      Parameters:
      callback - The callback to call when work completes, or null for none.
      callbackIfFree - Performs a call to the callback if free when true.
      Returns:
      true if it's OK to process, false means the component is included in this work unit and if callback is non-null, it will be called. The callback is called if free and the flag callbackIfFree is true.

    • areFree

      public boolean areFree(Runnable callback, boolean callbackIfFree, VSComponent component)
      Verifies if this component and another are included in a work unit currently in progress in the VirtualSpace.
      Parameters:
      callback - The callback to call when work completes, or null for none.
      callbackIfFree - Performs a call to the callback if free when true.
      component - The component to verify.
      Returns:
      true if it's OK to process, false means the component is included in this work unit and if callback is non-null, it will be called. The callback is called if free and the flag callbackIfFree is true.

    • areFree

      public boolean areFree(Runnable callback, boolean callbackIfFree, VSComponent... components)
      Verifies if this component and other component(s) are included in a work unit currently in progress in the VirtualSpace.
      Parameters:
      callback - The callback to call when work completes, or null for none.
      callbackIfFree - Performs a call to the callback if free when true.
      components - The components to verify.
      Returns:
      true if it's OK to process, false means the component is included in this work unit and if callback is non-null, it will be called. The callback is called if free and the flag callbackIfFree is true.

    • onPrepare

      protected void onPrepare(IAppOwner appOwner, IModuleOwner moduleOwner, boolean isPostCall, List<Throwable> errors) throws PropException
      Called when the application is being prepared. The order of onPrepare calls is always parent first, the children. The method is called twice, first time with isPostCall set to false, then a second time with true.
      Overrides:
      onPrepare in class GProp<GProp<?>[]>
      Parameters:
      appOwner - The application owner.
      moduleOwner - The Module owner.
      isPostCall - Flag indicating this is a post-call.
      errors - A list of errors that occurred but did not cause an abort.
      Throws:
      PropException - For property errors during the application preparation to need to abort.

    • onVirtualContainerCreated

      protected final void onVirtualContainerCreated()
      Called when a property container has been virtualized because it was added into another property container that was virtualized, and this container was not. Typically, UI and VS will issue a onUICreate or onVSCreate.
      Overrides:
      onVirtualContainerCreated in class PropCnr

    • invokeOnVSCreateTree

      protected void invokeOnVSCreateTree(VirtualSpace vs)
      Invokes the onVSCreate method for the component if a VirtualSpace is present. This method should only be invoked when a component is resolved during the post-resolve virtualization process, or when a component is added into an already virtualized VS component tree.

      The OnVSCreate method is called first for the parents, then its children recursively.

      Parameters:
      vs - The VirtualSpace instance.
      Throws:
      NullPointerException - If the vs is null.

    • onPropDispose

      protected void onPropDispose()
      Called when a property is disposed of by delete/remove in a container, or by the dispose method.

      The Property Container clears the structure of unsent communication requests to clear memory.

      This call is done just at the end of the delete/remove routine in the container, without synchronization.

      During this call, whatever components that e.g. the client needs to disposed of is done.

      Subclasses needing to perform some intelligent operations upon deletion should do it by overloading this method and always call the super.onPropDispose() method.

      Overrides:
      onPropDispose in class PropCnr

    • getNonVirtualized

      public VSComponent getNonVirtualized()
      Gets the non-virtualized instance of this component, if it exists.

      The non-virtualized counterpart may not exist in case the component has been programmatically created or is e.g. a row or cell in a table that has been filled by a data connector.

      Specified by:
      getNonVirtualized in interface IVSComponent
      Returns:
      The non-virtualized component, null if not found.

    • getComponentIsHidden

      public abstract String getComponentIsHidden()
      Gets the focus message for "Component is hidden" but for the component in question.

    • getComponentIsDisabled

      public abstract String getComponentIsDisabled()
      Gets the focus message for "Component is disabled" but for the component in question.

    • canRequestFocus

      public String canRequestFocus()
      Returns if this component can receive focus. Focus capable components may override to return null for success, or other error message.

      Default processing is to return "Component not focusable" if the component doesn't implement the IFocusComp interface, "Not virtualized" if the component is not in a virtualized state, "Component is hidden" if IVSComponent.isVisible() is false or "Component is disabled" if IVSComponent.isEnabled() is false.

      Specified by:
      canRequestFocus in interface IPropCnr
      Returns:
      null focus is possible to this component, or an error message describing why focus cannot be requested.

    • couldRequestFocusIfVirtualized

      public String couldRequestFocusIfVirtualized(boolean ignoreStates)
      Returns if this component could receive focus if it would be virtualized. Focus capable components may override to return null for success, or other error message.

      Default processing is to return "Component not focusable" if the component doesn't implement the IFocusComp interface, "Component is hidden" if IVSComponent.isVisible() is false or "Component is disabled" if IVSComponent.isEnabled() is false.

      Specified by:
      couldRequestFocusIfVirtualized in interface IPropCnr
      Parameters:
      ignoreStates - Flag indicating that states should be ignored, such as visible or enabled. If false, hidden or disabled components return an error message.
      Returns:
      null focus is possible to this component, or an error message describing why focus cannot be requested.

    • onFocusGained

      public void onFocusGained(IFocusComp opposite, IGProp<?> trigger, boolean isRemoteInduced)
      Called to the component when it receives focus.

      Focus components override this method if they need to process focus lost.

      Specified by:
      onFocusGained in interface IFocusComp
      Parameters:
      opposite - Component losing focus, null for none.
      trigger - The trigger property, null for none.
      isRemoteInduced - Flag indicating this event is due to a remote event.

    • onFocusLost

      public void onFocusLost(IFocusComp focusComp, IGProp<?> trigger, boolean isRemoteInduced)
      Called to the focused component when it loses focus.

      Focus components override this method if they need to process focus lost.

      Specified by:
      onFocusLost in interface IFocusComp
      Parameters:
      focusComp - Component receiving focus, null for none.
      trigger - The trigger property, null for none.
      isRemoteInduced - Flag indicating this event is due to a remote event.

    • onRemoteEvent

      public void onRemoteEvent(RemoteEvent event)
      Called when a remote property event should be processed by this property.

      A subclass can override this method to perform appropriate processing and is not required to call super.onRemoteEvent(e).

      The onRemoteEvent is NOT called when in a proxied property container, but rather the normal onEventSelf method.

      Specified by:
      onRemoteEvent in interface IGProp<GProp<?>[]>
      Overrides:
      onRemoteEvent in class GProp<GProp<?>[]>
      Parameters:
      event - The remote event.