at.spardat.xma.page
Class PageClient

java.lang.Object
  extended byat.spardat.xma.page.Page
      extended byat.spardat.xma.page.PageClient
All Implemented Interfaces:
Descriptive, IEmbeddable, at.spardat.xma.boot.component.IXMAControl, Synchronization, Transactional
Direct Known Subclasses:
AssistentPage, DialogPage, EmbeddedPage, NotebookPage

public abstract class PageClient
extends Page
implements IEmbeddable

Base class of all client side pages. A PageClient contains Widgets and Models.


Field Summary
protected  org.eclipse.swt.widgets.Composite composite
          The SWT-Composite corresponding to this PageClient.
 
Constructor Summary
PageClient(ComponentClient component, boolean stateless)
          Constructor of the PageClient.
PageClient(PageClient parent, boolean stateless)
          Constructor of the PageClient.
 
Method Summary
 void activatePage()
          Brings the window representing this page to the foreground.
protected  void addChild(at.spardat.xma.boot.component.IXMAControl child)
          Adds a Subpage to this PageClient.
 void attachUI()
          Responsible for attaching a UI to all WidgetModels of this page.
abstract  void attachUIImpl()
          Must be implemented by subclass.
 void clearError(org.eclipse.swt.widgets.Widget widget)
          Removes the error for the given widget.
 void clearValidationErrorImpl(org.eclipse.swt.widgets.Widget widget)
          Removes a validation error for a particular widget model.
protected  void clientEvent(org.eclipse.swt.events.SelectionEvent event, int type)
          Calls the clientevent configured for the widget of the event.
protected  void clientEventBase(org.eclipse.swt.events.SelectionEvent event, int type)
          Calls the clientevent configured for the widget of the event by calling clientEvent(SelectionEvent,int).
protected abstract  void createModels()
          This Method will be implemented in the generated Class for each PageClient, to create the WidgetModels.
protected abstract  void createWidgets()
          This Method will be implemented in the generated Class for each PageClient, to create and initialize all SWT-Widgets of the PageClient.
 void detachUI()
          Detaches the UI-page from this Page.
 void determineState()
          This method is called every time the content of any WizardModel of the Page may have been changed.
 void determineStateBase()
          Calls determineState() on the PageClient and all subpages
protected  void enter()
          This method will be called every time the PageClient becomes visible.
 void enterBase()
          Notify the PageClient and all Subpages, that the PageClient is becoming visible by calling enter() on the PageClient and all Subpages.
 ComponentClient getComponent()
          Returns the Component this belongs to.
 org.eclipse.swt.widgets.Composite getComposite()
          Get the SWT-Composite of the PageClient.
 java.lang.String getContextString()
           
 org.eclipse.swt.events.TypedEvent getCurrentEvent()
          Get the current SWT-Event.
 at.spardat.xma.boot.component.IDialog getDialog()
          Get the DialogPage of the PageClient.
 IDialogPage getDialogPage()
          Get the DialogPage of the PageClient.
 IPageExtender getExtend()
          Gets the extention object of the page.
 java.lang.String getHelpUri()
          Gets the URI to the help page explaining this page.
 java.lang.String getHelpUriBase()
          Gets the URI to the help page explaining this page.
 PageClient getParent()
          Get the Parent of the PageClient, if any.
abstract  org.eclipse.swt.widgets.Control[] getWidgets()
          Returns an array of all Widgets of this page.
abstract  boolean hasModels()
          This Method will be implemented in the generated Class for each PageClient, to indicate if the WidgetModels are allready created.
 boolean hasValidationError(org.eclipse.swt.widgets.Widget widget)
          Determines if a validation error currently exists for a given widget.
 void helpEvent()
          Shows the help-uri of the page in a browser window.
 void initGUI()
          Creates the Widgets of the PageClient and all Subpages by calling createWidgets() on the PageClient and all Subpages.
static java.lang.String insertLangInFilename(java.lang.String uri, java.util.Locale locale)
          Places the language code of the given locale into the file-part of the given uri just before the extention.
 boolean isEventsEnabled()
          Determine if this page currently responds to UI-Events
 boolean isNew()
          Yields true if this Page has been created since the last server side event.
 boolean isUIAttached()
          Yields true, if every WidgetModel in this page has a UI attached.
 void launch(EmbeddableComponent comp)
          Calls a modal component.
 java.util.Properties launchExtern(java.lang.String componentUri, java.util.Properties input)
          Calls a modal component of an other application.
 java.util.Properties launchRelative(java.lang.String componentName, java.util.Properties input)
          Calls a modal component of the same application.
protected  void leave()
          This method will be called every time the PageClient becomes invisible.
 void leaveBase()
          Notify the PageClient and all Subpages, that the PageClient no longer is visible by calling leave() on all Subpages and the PageClient.
 RemoteCallClient newRemoteCall(java.lang.String namEvent)
          Constructs a RemoteCall object to execute a server side method with the provided name.
protected  void removeChild(at.spardat.xma.boot.component.IXMAControl child)
          Removes a Subpage of this PageClient.
 void removeModel()
          Notify the PageClient and all Subpages, to remove alle WidgetModles by calling removeWidgetModels() on all Subpages and the PageClient.
protected abstract  void removeWidgetModels()
          This Method will be implemented in the generated Class for each PageClient, to remove alle WidgetModels.
protected abstract  void removeWidgets()
          This Method will be implemented in the generated Class for each PageClient, to remove all Widgets after the Widgets have been disposed.
 void removeWidgetsBase()
          Notify the PageClient and all Subpages, that the Widgets are disposed by calling removeWidgets() on all Subpages and the PageClient.
 void rpcFinished(RemoteCallClient rc, RemoteReply reply)
          Is called at the end of RemoteCallClient.execute().
 void serverEvent(java.lang.String event)
          Calls the named eventMethod on the Server.
 void setContextString(java.lang.String text)
          Sets the context String and notifies the containing AppShell or dialog if there exists one.
 void setDialog(at.spardat.xma.boot.component.IDialog dialog)
          Sets the containing dialog of the PageClient.
 void setEditable(boolean what)
          Sets the editable-state of all model's widgets.
 void setError(ValidationErrorClient error)
          Sets an error for the given widget.
 void setEventsEnabled(boolean enabled)
          Enables/disables GUI-events on the page and all its subpages.
 void setExtend(IPageExtender extend)
          Sets an extention object, which can add behavior to the page.
 void setId(short id)
          Assigns an id to this Page.
 void setNew(boolean what)
          Sets the new state.
 void setValidationErrorImpl(ValidationErrorClient error)
          Sets a validation error for a particular widget model.
 void showException(java.lang.Exception exc)
          Shows an Exception in a MessageBox.
 int showMessage(at.spardat.enterprise.exc.INotification notification)
          Displays the provided notification in a modal message box.
 void stateChanged()
          This method is called every time the content of any WizardModel of the Page may have been changed.
 void stateChangedBase()
          Notify the PageClient and all Subpages of a possible Change in the PageModels by calling determineState() and stateChanged() on the PageClient and all Subpages.
 void stateChangedBaseImpl()
          Calls stateChanged() on the PageClient and all subpages
 void stateChangedExtend()
          Calls IPageExtender.stateChanged() on the IPageExtender of the PageClient and all subpages
 java.lang.String toLocalizedHelpUri(java.lang.String helpUri, java.util.Locale locale)
          Overwrite this method to convert the given helpUri to the uri of the tranlation of the help page to the language given in the locale.
 
Methods inherited from class at.spardat.xma.page.Page
changed, commit, describe, display, equalsCS, externalize, getId, getNumWModels, getTypeId, getWModel, getWModels, internalize, isAtServer, isStateless, randomlyChange, rollback, toString
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 
Methods inherited from interface at.spardat.xma.boot.component.IXMAControl
createComposite
 

Field Detail

composite

protected org.eclipse.swt.widgets.Composite composite
The SWT-Composite corresponding to this PageClient.

Constructor Detail

PageClient

public PageClient(ComponentClient component,
                  boolean stateless)
Constructor of the PageClient.

Parameters:
component - the component containing this page.
stateless - indicating if this page is stateless on the server.

PageClient

public PageClient(PageClient parent,
                  boolean stateless)
Constructor of the PageClient.

Parameters:
parent - the parentpage of this page. parent must not be null.
stateless - indicating if this page is stateless on the server.
Method Detail

addChild

protected void addChild(at.spardat.xma.boot.component.IXMAControl child)
Adds a Subpage to this PageClient. This may be a Notebook with its NotebookPages, an EmbeddableComponent, or an AssistentPage in an Assistent. Any Object implementing the IXMAControl-Interface my be added. The methods createWidgets() and enter() will be called on the Subpage at the right time.

Parameters:
child - the IXMAControl to add.

removeChild

protected void removeChild(at.spardat.xma.boot.component.IXMAControl child)
Removes a Subpage of this PageClient. The methods leave() and removeWidgets() will be called on the Subpage if not allready called.

Parameters:
child - the IXMAControl to remove.

getComposite

public org.eclipse.swt.widgets.Composite getComposite()
Get the SWT-Composite of the PageClient. All SWT-Widgets of this PageClient are children of this Composite (directly or indirectly).

Specified by:
getComposite in interface at.spardat.xma.boot.component.IXMAControl
Returns:
the SWT-Composite corresponding to this PageClient

getParent

public PageClient getParent()
Get the Parent of the PageClient, if any.

Returns:
the Parent of this PageClient or null if it is a top-level DialogPage.

setDialog

public void setDialog(at.spardat.xma.boot.component.IDialog dialog)
Sets the containing dialog of the PageClient.

Specified by:
setDialog in interface IEmbeddable
Parameters:
dialog -

getDialog

public at.spardat.xma.boot.component.IDialog getDialog()
Get the DialogPage of the PageClient.

Specified by:
getDialog in interface IEmbeddable
Returns:
the DialogPage containing this page or this if this page is a DialogPage.

getDialogPage

public IDialogPage getDialogPage()
Get the DialogPage of the PageClient.

Returns:
the DialogPage containing this page or this if this page is a DialogPage.

getWidgets

public abstract org.eclipse.swt.widgets.Control[] getWidgets()
Returns an array of all Widgets of this page.

Returns:
array of Widgets or null if the widgets are not allready created.

initGUI

public void initGUI()
Creates the Widgets of the PageClient and all Subpages by calling createWidgets() on the PageClient and all Subpages.

Specified by:
initGUI in interface at.spardat.xma.boot.component.IXMAControl

createModels

protected abstract void createModels()
This Method will be implemented in the generated Class for each PageClient, to create the WidgetModels. It will also create all Subpages which are not lazy.


hasModels

public abstract boolean hasModels()
This Method will be implemented in the generated Class for each PageClient, to indicate if the WidgetModels are allready created.

Returns:
true if the WidgetModels exist.

createWidgets

protected abstract void createWidgets()
This Method will be implemented in the generated Class for each PageClient, to create and initialize all SWT-Widgets of the PageClient. It will


enterBase

public void enterBase()
Notify the PageClient and all Subpages, that the PageClient is becoming visible by calling enter() on the PageClient and all Subpages.

Specified by:
enterBase in interface at.spardat.xma.boot.component.IXMAControl

enter

protected void enter()
This method will be called every time the PageClient becomes visible. For DialogPages this method is called exactly once. For NotebookPages and WizardPages this method is called every time the user navigates to this PageClient.
It is intended to be implemented by the application programmer if he wants to react on this event.


leaveBase

public void leaveBase()
Notify the PageClient and all Subpages, that the PageClient no longer is visible by calling leave() on all Subpages and the PageClient.

Specified by:
leaveBase in interface at.spardat.xma.boot.component.IXMAControl

leave

protected void leave()
This method will be called every time the PageClient becomes invisible. For DialogPages this method is called exactly once. For NotebookPages and WizardPages this method is called every time the user navigates off this PageClient.
It is intended to be implemented by the application programmer if he wants to react on this event.


removeModel

public void removeModel()
Notify the PageClient and all Subpages, to remove alle WidgetModles by calling removeWidgetModels() on all Subpages and the PageClient.

Specified by:
removeModel in interface at.spardat.xma.boot.component.IXMAControl

removeWidgetModels

protected abstract void removeWidgetModels()
This Method will be implemented in the generated Class for each PageClient, to remove alle WidgetModels.


removeWidgetsBase

public void removeWidgetsBase()
Notify the PageClient and all Subpages, that the Widgets are disposed by calling removeWidgets() on all Subpages and the PageClient.

Specified by:
removeWidgetsBase in interface at.spardat.xma.boot.component.IXMAControl

removeWidgets

protected abstract void removeWidgets()
This Method will be implemented in the generated Class for each PageClient, to remove all Widgets after the Widgets have been disposed.


stateChangedBase

public void stateChangedBase()
Notify the PageClient and all Subpages of a possible Change in the PageModels by calling determineState() and stateChanged() on the PageClient and all Subpages.

Specified by:
stateChangedBase in interface at.spardat.xma.boot.component.IXMAControl

determineStateBase

public void determineStateBase()
Calls determineState() on the PageClient and all subpages

Specified by:
determineStateBase in interface IEmbeddable

determineState

public void determineState()
This method is called every time the content of any WizardModel of the Page may have been changed.
It is intended to be implemented by the application programmer, to set some state variables to simplify the implementation of stateChanged(). This method is called imidiatly befor stateChanged().


stateChangedExtend

public void stateChangedExtend()
Calls IPageExtender.stateChanged() on the IPageExtender of the PageClient and all subpages

Specified by:
stateChangedExtend in interface IEmbeddable

stateChangedBaseImpl

public void stateChangedBaseImpl()
Calls stateChanged() on the PageClient and all subpages

Specified by:
stateChangedBaseImpl in interface IEmbeddable

stateChanged

public void stateChanged()
This method is called every time the content of any WizardModel of the Page may have been changed.
It is intended to be implemented by the application programmer, to enable or disable Controls. This method is called emediatly after determineState().


setEventsEnabled

public void setEventsEnabled(boolean enabled)
Enables/disables GUI-events on the page and all its subpages.

Specified by:
setEventsEnabled in interface IEmbeddable
Parameters:
enabled -

isEventsEnabled

public boolean isEventsEnabled()
Determine if this page currently responds to UI-Events

Returns:
true if UI-Events are enabled.

showException

public void showException(java.lang.Exception exc)
Shows an Exception in a MessageBox. This method is called every time the xma-runtime catches an Exception from an clientevent-method of this page. It can be overriden to customize the exception-handling.

Parameters:
exc - the catched Exception

showMessage

public int showMessage(at.spardat.enterprise.exc.INotification notification)
Displays the provided notification in a modal message box.

Returns:
A reaction constant of the class INotification, this is one of the constants starting with praefix R_ and indicates the pressed push button on the message dialogue.

helpEvent

public void helpEvent()
Shows the help-uri of the page in a browser window.


getHelpUriBase

public java.lang.String getHelpUriBase()
Gets the URI to the help page explaining this page. If there is none, first the enclosing pages within the same component and at last the component are searched for a help URI.

Returns:
the help URI of this page or an enclosing page or component.

getHelpUri

public java.lang.String getHelpUri()
Gets the URI to the help page explaining this page. The help page must be showable inside a web browser. This method is implemented in the generated Class for each PageClient.

Returns:
the uri of the help page or null if none is defined.

toLocalizedHelpUri

public java.lang.String toLocalizedHelpUri(java.lang.String helpUri,
                                           java.util.Locale locale)
Overwrite this method to convert the given helpUri to the uri of the tranlation of the help page to the language given in the locale. The default implementation just returns the helpUri unchanged.

Parameters:
helpUri - as returned by getHelpUri()
locale - the locale from the XMAContext
Returns:
the uri of the localized help page

insertLangInFilename

public static java.lang.String insertLangInFilename(java.lang.String uri,
                                                    java.util.Locale locale)
Places the language code of the given locale into the file-part of the given uri just before the extention. If the file-part has no extention, the language code is appended at the end.
E.g. insertLangInFilename("http://server.lan.at/help/Help.html",Locale.US) returns http://server.lan.at/help/Help_en.html
If the parameter uri is null, null is returned.


clientEventBase

protected void clientEventBase(org.eclipse.swt.events.SelectionEvent event,
                               int type)
Calls the clientevent configured for the widget of the event by calling clientEvent(SelectionEvent,int).

Parameters:
event - the SWT-Event that happened.
type - the type of the Event, as defined by the event type constants in class SWT.
Since:
1.4.0

clientEvent

protected void clientEvent(org.eclipse.swt.events.SelectionEvent event,
                           int type)
Calls the clientevent configured for the widget of the event. This method is implemented in the generated Class for each PageClient.

Parameters:
event - the SWT-Event that happened.
type - the type of the Event, as defined by the event type constants in class SWT.

serverEvent

public void serverEvent(java.lang.String event)
Calls the named eventMethod on the Server. Bevor calling the eventMethod on the Server, all PageModels are synchronized to the server. After the eventMethod is finished, all PageModels are synchronized to the client.

Parameters:
event - a String identifieing the event.

isUIAttached

public boolean isUIAttached()
Yields true, if every WidgetModel in this page has a UI attached.

Returns:
true if attached.

getComponent

public ComponentClient getComponent()
Returns the Component this belongs to.

Returns:
The Component. Never null.

attachUI

public void attachUI()
              throws AttachmentExceptionClient
Responsible for attaching a UI to all WidgetModels of this page. The possible outcome of this method is either that all WidgetModels are successfully attached or none is attached.

Throws:
AttachementException - if some of the WidgetModels could not be attached. In this case, all successfully attached widgets are detached and !isUIAttached holds after this method returns.
java.lang.IllegalStateException - if already attached.
AttachmentExceptionClient

attachUIImpl

public abstract void attachUIImpl()
                           throws AttachmentExceptionClient
Must be implemented by subclass. The subclass must call attachUI on every WidgetModels UIDelegateClient of this page. It must not catch the AttachmentException if it gets attachement errors from IWModelC.attach.

Throws:
AttachmentExceptionClient

detachUI

public void detachUI()
Detaches the UI-page from this Page. All UI-controls are reset to an empty status. This method does nothing if !isUIAttached().


clearError

public void clearError(org.eclipse.swt.widgets.Widget widget)
Removes the error for the given widget.

Parameters:
widget - the widget where to clear the error state.

setError

public void setError(ValidationErrorClient error)
Sets an error for the given widget. The error is shown in the status line. Only one error can be shown at a time. The precedence rules are: 1) the validation error of the widget owning the focus 2) the error of the widget owning the focus set with this method 3) the error of the next widget in the tab order containing an error 4) the error set for the null-widget.


clearValidationErrorImpl

public void clearValidationErrorImpl(org.eclipse.swt.widgets.Widget widget)
Removes a validation error for a particular widget model. This method is for internal use only. Calling it causes undefined behaviour!

Parameters:
widget - the widget where to clear the error state.

setValidationErrorImpl

public void setValidationErrorImpl(ValidationErrorClient error)
Sets a validation error for a particular widget model. This method is for internal use only. Calling it causes undefined behaviour!

Parameters:
error - indicates the error

hasValidationError

public boolean hasValidationError(org.eclipse.swt.widgets.Widget widget)
Determines if a validation error currently exists for a given widget. Note that validation is disabled automatically for readonly widgets, so readonly widgets never have validation errors.

Parameters:
widget - to search for validation errors
Returns:
true if the validator reported an error for the given widget. false otherwise.

isNew

public boolean isNew()
Yields true if this Page has been created since the last server side event.

Returns:
true if new.

setNew

public void setNew(boolean what)
Sets the new state.

Parameters:
what - true if this should be marked as new.

setId

public void setId(short id)
Assigns an id to this Page. This method may only be called by the Component.

Overrides:
setId in class Page
Parameters:
id - the assigned id for this Page

newRemoteCall

public RemoteCallClient newRemoteCall(java.lang.String namEvent)
Constructs a RemoteCall object to execute a server side method with the provided name. The corresponding server side Page class must have a method with the signature
 void <namEvent> (RemoteCall call, RemoteReply reply)
 
This method will be called if you call execute on the RemoteCall object returned by this.

Parameters:
namEvent - the name of the server side method to call
Returns:
a RemoteCall object

setEditable

public void setEditable(boolean what)
Sets the editable-state of all model's widgets. May be used to move the whole page into (or out of) a read-only mode.

Parameters:
what - the value to set.

launchRelative

public java.util.Properties launchRelative(java.lang.String componentName,
                                           java.util.Properties input)
Calls a modal component of the same application. If this page is directly or indirectly embedded in an IAppShell, the called component is pushed on the client area of the IAppShell. In all other cases, the component is called as a dialog.

Parameters:
componentName - name of the component within the application
input - input properties for the component
Returns:
Properties output properties of the component

launchExtern

public java.util.Properties launchExtern(java.lang.String componentUri,
                                         java.util.Properties input)
Calls a modal component of an other application. If this page is directly or indirectly embedded in an IAppShell, the called component is pushed on the client area of the IAppShell. In all other cases, the component is called as a dialog.

Parameters:
componentUri - absolute URI of the component
input - input properties for the component
Returns:
Properties output properties of the component

launch

public void launch(EmbeddableComponent comp)
Calls a modal component. If this page is directly or indirectly embedded in an IAppShell, the called component is pushed on the client area of the IAppShell. In all other cases, the component is called as a dialog.

Parameters:
comp - the component to call.

setExtend

public void setExtend(IPageExtender extend)
Sets an extention object, which can add behavior to the page. The event-methods defined in IPageExtender are called on the extend-object before they are called on the page itself.


getExtend

public IPageExtender getExtend()
Gets the extention object of the page. The event-methods defined in IPageExtender are called on the extend-object before they are called on the page itself.

Returns:
the extention object. It may be null.

getContextString

public java.lang.String getContextString()
Specified by:
getContextString in interface IEmbeddable
Returns:
the string to show as context in the enclosing AppShell or dialog.

setContextString

public void setContextString(java.lang.String text)
Sets the context String and notifies the containing AppShell or dialog if there exists one.

Parameters:
text - the new contextString

activatePage

public void activatePage()
Brings the window representing this page to the foreground.

Since:
version_number

rpcFinished

public void rpcFinished(RemoteCallClient rc,
                        RemoteReply reply)
Is called at the end of RemoteCallClient.execute(). May be overwritten by subclasses to implement some RPC-post processing. Is not called, if the RPC terminates with exceptions.

Parameters:
rc - the RemoteCallClient whose execute method is about to end
reply - the RemoteReply object that execute will return

getCurrentEvent

public final org.eclipse.swt.events.TypedEvent getCurrentEvent()
Get the current SWT-Event. This Event only exists vor the duration of the event execution.

Returns:
the current SWT-Event or null if called outside an event method.
Since:
1.7.1