at.spardat.xma.component
Class ComponentClient

java.lang.Object
  extended byat.spardat.xma.component.Component
      extended byat.spardat.xma.component.ComponentClient
All Implemented Interfaces:
Descriptive, at.spardat.xma.boot.component.IComponent, IComponentClient, Synchronization
Direct Known Subclasses:
EmbeddableComponent

public abstract class ComponentClient
extends Component
implements IComponentClient

Implents the clients specific aspects of a Component. This includes the management of SWT-Resources like the Display and Images.


Field Summary
static org.eclipse.swt.graphics.RGB errorBackground
          color used to mark input fields containing errors
static org.eclipse.swt.graphics.RGB errorBackgroundUneditable
          color used to mark uneditable fields containing errors
static short lastResGif
          maximum Id reserved by the runtime. currently 100.
static short resErrorGif
          Id for Error-Icon
static short resInfoGif
          Id for Info-Icon
static short resWarnGif
          Id for Warning-Icon
 
Fields inherited from class at.spardat.xma.component.Component
session_
 
Constructor Summary
ComponentClient()
          Constructor just for test-purpose.
ComponentClient(XMASessionClient session, boolean isStateless)
          Constructor of the Component.
 
Method Summary
 void addEventListener(at.spardat.xma.boot.component.IComponentListener listener)
          Adds a ComponentListner to the listeners of the component.
 void addPropertyChangeListener(java.beans.PropertyChangeListener listener)
          Adds a PropertyChangeListener to the listeners of the component.
 ITask createTask(java.lang.String name)
          Creates the Task with the given name.
 void dispose()
          Frees all allocated recources of the Component.
 void externalize(XmaOutput xo, boolean forceFull)
          This method calculates the data stream necessary to update the server side component so that its state equals this client side component.
 void freePageModel(short idPageModel)
          Frees the Page with the given ID.
 org.eclipse.swt.graphics.Color getColor(int red, int green, int blue)
          Get a Color by naming its red, green and blue values.
 org.eclipse.swt.graphics.Color getColor(org.eclipse.swt.graphics.RGB rgb)
          Get a Color by naming its red-green-blue value.
 XMAContext getContext()
          Returns the global context.
 org.eclipse.swt.widgets.Display getDisplay()
          Gets the Display used by all Pages in the Component.
 org.eclipse.swt.graphics.Font getFont(java.lang.String name, int height, int style)
          Returns a font for the specified data that is owned by this component and automatically disposed if this component is disposed.
 org.eclipse.swt.graphics.Font getFontByHeight(org.eclipse.swt.graphics.Font template, int height)
          Returns a font whose name and style is taken from template and whose height is provided.
 org.eclipse.swt.graphics.Font getFontByStyle(org.eclipse.swt.graphics.Font template, int style)
          Returns a font whose name and height is taken from template and whose style is provided.
 java.lang.String getHelpUri()
          Gets the URI to the help page explaining this component.
 org.eclipse.swt.graphics.Image getImage(short id)
          Get an Image by its ID.
 org.eclipse.swt.graphics.Image getImage(java.lang.String resource)
          Get an Image by naming its resource-file.
 java.util.Properties getProperties()
          Gives all properties of the component.
 java.lang.String getProperty(java.lang.String name)
          Gives the value of a property.
 at.spardat.xma.boot.component.IRtXMASessionClient getRTSession()
          Returns the Session this belongs to (you can rely on the returned object not to be null).
 XMASessionClient getSession()
          Returns the Session this belongs to (you can rely on the returned object not to be null).
 void internalize(XmaInput in)
          This method gets the data stream after a server side event and applies the changes to this client side component.
abstract  void invoke(org.eclipse.swt.widgets.Composite parent)
          This Method is called by the Launcher to start the Component on the client side.
 boolean isOutOfSyncWithServer()
          Returns if the clients page model state is out of sync with respect to the servers state.
protected  RemoteCallClient newRemoteCall(java.lang.String namEvent)
          Constructs a RemoteCall object to execute a server side method with the provided name.
 void notifyClosed()
          Notifies all listener that this component was closed.
 void notifyEvent(java.lang.String name, java.lang.String value)
          Notifies all listeners of the named event.
protected  void notifyPropertyChange(java.lang.String name, java.lang.Object oldValue, java.lang.Object value)
          Notifies all registerd PropertyChangeListeners of a property change.
 void registerImage(short id, java.lang.String resource)
          Registers an image under the given id.
 void removeEventListener(at.spardat.xma.boot.component.IComponentListener listener)
          Remove a ComponentListener form the listners of the component.
 void removePropertyChangeListener(java.beans.PropertyChangeListener listener)
          Remove a PropertyChangeListener form the listners of the component.
 void rpcFinished(RemoteCallClient rc, RemoteReply reply)
          Is called at the end of RemoteCallClient.execute().
 void setOutOfSyncWithServer(boolean b)
          Sets the out of sync state.
 void setProperties(java.util.Properties input)
          Sets all properties of the component.
 void setProperty(java.lang.String name, java.lang.String value)
          Sets one property of the component.
 int showMessage(at.spardat.enterprise.exc.INotification notification)
          Displays the provided notification in a modal message box.
 
Methods inherited from class at.spardat.xma.component.Component
commit, describe, externalizePageSet, externalizeProperties, getId, getModelClass, getName, getNumPageModels, getPageModel, getPageModels, getPropDes, getPropDes, getSCN, incrementSCN, internalizePageSet, internalizeProperties, isPageModelAlive, isStateless, model2props, props2model, registerPageModel, removePageModel, rollback, setId, setSCN, toString
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

errorBackground

public static org.eclipse.swt.graphics.RGB errorBackground
color used to mark input fields containing errors


errorBackgroundUneditable

public static org.eclipse.swt.graphics.RGB errorBackgroundUneditable
color used to mark uneditable fields containing errors


resInfoGif

public static final short resInfoGif
Id for Info-Icon

See Also:
Constant Field Values

resWarnGif

public static final short resWarnGif
Id for Warning-Icon

See Also:
Constant Field Values

resErrorGif

public static final short resErrorGif
Id for Error-Icon

See Also:
Constant Field Values

lastResGif

public static final short lastResGif
maximum Id reserved by the runtime. currently 100. please use only ids greater than this for your own images.

See Also:
Constant Field Values
Constructor Detail

ComponentClient

public ComponentClient()
Constructor just for test-purpose. This constructor is not intended to be called from outside JUnit-Tests.


ComponentClient

public ComponentClient(XMASessionClient session,
                       boolean isStateless)
Constructor of the Component. Creates the Display if necessary. Registers this component with the session.

Parameters:
session - the XMASession this component belongs to
isStateless - defines whether this component is stateless or not.
Method Detail

addEventListener

public void addEventListener(at.spardat.xma.boot.component.IComponentListener listener)
Adds a ComponentListner to the listeners of the component. All listeners are notified of all property-changes and component-events.

Specified by:
addEventListener in interface at.spardat.xma.boot.component.IComponent
Parameters:
listener - the new listener to register

removeEventListener

public void removeEventListener(at.spardat.xma.boot.component.IComponentListener listener)
Remove a ComponentListener form the listners of the component. This ComponentListner will not be notified of propertiy-changes and component-events any more.

Specified by:
removeEventListener in interface at.spardat.xma.boot.component.IComponent
Parameters:
listener - the ComponentListener to remove

addPropertyChangeListener

public void addPropertyChangeListener(java.beans.PropertyChangeListener listener)
Adds a PropertyChangeListener to the listeners of the component. All listeners are notified of all property-changes.

Specified by:
addPropertyChangeListener in interface at.spardat.xma.boot.component.IComponent
Parameters:
listener - the new listener to register

removePropertyChangeListener

public void removePropertyChangeListener(java.beans.PropertyChangeListener listener)
Remove a PropertyChangeListener form the listners of the component. This PropertyChangeListener will not be notified of propertiy-changes any more.

Specified by:
removePropertyChangeListener in interface at.spardat.xma.boot.component.IComponent
Parameters:
listener - the PropertyChangeListener to remove

setProperties

public void setProperties(java.util.Properties input)
Sets all properties of the component. This method completly resets the set of properties of the component to the set given as input. If there are registered ComponentListeners, all ComponentListeners are notifyed of each property-change.

Specified by:
setProperties in interface at.spardat.xma.boot.component.IComponent
Parameters:
input - the new set of properties

setProperty

public void setProperty(java.lang.String name,
                        java.lang.String value)
Sets one property of the component. If there are registered ComponentListeners and the value of the property is differend from its old value, all ComponentListeners are notifyed of the property-change.

Specified by:
setProperty in interface at.spardat.xma.boot.component.IComponent
Parameters:
name - the name of the property to change
value - the new value of the property

notifyPropertyChange

protected void notifyPropertyChange(java.lang.String name,
                                    java.lang.Object oldValue,
                                    java.lang.Object value)
Notifies all registerd PropertyChangeListeners of a property change. The event is only fired if oldValue and value differ.

Parameters:
name - The name of the property which changed
oldValue - The old value of the property
value - The new value of the property

getProperty

public java.lang.String getProperty(java.lang.String name)
Gives the value of a property. If the property is not defined null is returned.

Specified by:
getProperty in interface at.spardat.xma.boot.component.IComponent
Parameters:
name - the name of the property
Returns:
the value of the named property

getProperties

public java.util.Properties getProperties()
Gives all properties of the component.

Specified by:
getProperties in interface at.spardat.xma.boot.component.IComponent
Returns:
the properties of the component.

notifyEvent

public void notifyEvent(java.lang.String name,
                        java.lang.String value)
Notifies all listeners of the named event.

Parameters:
name - the name of the event
value - an optional value passed with the event

notifyClosed

public void notifyClosed()
Notifies all listener that this component was closed.


getDisplay

public org.eclipse.swt.widgets.Display getDisplay()
Gets the Display used by all Pages in the Component. This Display allways exists and is never null.

Returns:
the Display for all Pages in the Component.

registerImage

public void registerImage(short id,
                          java.lang.String resource)
Registers an image under the given id. This image-id can be used in tables and trees.

Parameters:
id - the new id of the image.
resource - a resource-string naming the image file.

getImage

public org.eclipse.swt.graphics.Image getImage(short id)
Get an Image by its ID. The resource is loaded via the classloader which downloads the jar-file containing the resource if necessary. If the Image is allready loaded, the loaded Image will be returned. The Images are stored internally in the Component and will be disposed automatically when the Component is finished. Do not dispose the Image!

Parameters:
id - one of the static final int ids defined in this class.
Returns:
the Image or null if the resource can not be found.

getImage

public org.eclipse.swt.graphics.Image getImage(java.lang.String resource)
Get an Image by naming its resource-file. The resource is loaded via the classloader which downloads the jar-file containing the resource if necessary. If the Image is allready loaded, the loaded Image will be returned. The Images are stored internally in the Component and will be disposed automatically when the Component is finished. Do not dispose the Image!

Parameters:
resource - a resource-string naming the image file.
Returns:
the Image or null if the resource can not be found.

getColor

public org.eclipse.swt.graphics.Color getColor(int red,
                                               int green,
                                               int blue)
Get a Color by naming its red, green and blue values. The Colors are stored internally in the Component and will be disposed automatically when the Component is finished. Do not dispose the Color!

Parameters:
red - the red value of the color.
green - the green value of the color.
blue - the blue value of the color.
Returns:
the Color corresponding to this values

getColor

public org.eclipse.swt.graphics.Color getColor(org.eclipse.swt.graphics.RGB rgb)
Get a Color by naming its red-green-blue value. The Colors are stored internally in the Component and will be disposed automatically when the Component is finished. Do not dispose the Color!

Parameters:
rgb - the red, green, blue values defining the color.
Returns:
the Color corresponding to this values

getFont

public org.eclipse.swt.graphics.Font getFont(java.lang.String name,
                                             int height,
                                             int style)
Returns a font for the specified data that is owned by this component and automatically disposed if this component is disposed. Do not dispose the returned Font!

Parameters:
name - the name of the font (must not be null)
height - the font height in points
style - a bit or combination of SWT.NORMAL, SWT.BOLD, SWT.ITALIC
Returns:
a font-object. Must not be disposed by the caller.

getFontByHeight

public org.eclipse.swt.graphics.Font getFontByHeight(org.eclipse.swt.graphics.Font template,
                                                     int height)
Returns a font whose name and style is taken from template and whose height is provided. Do not dispose the returned font.

Parameters:
template - the reference font. Must not be null.
height - the height in points of the return Font.
Returns:
a font-object. Must not be disposed by the caller.

getFontByStyle

public org.eclipse.swt.graphics.Font getFontByStyle(org.eclipse.swt.graphics.Font template,
                                                    int style)
Returns a font whose name and height is taken from template and whose style is provided. Do not dispose the returned font.

Parameters:
template - the reference font. Must not be null.
style - the style of the font.
Returns:
a font object. Must not be disposed by the caller.

getHelpUri

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

Returns:
the uri of the help page.

dispose

public void dispose()
Frees all allocated recources of the Component. This includes freeing all still living statefull PageModels at the server and disposing all SWT-resources like Images.

Specified by:
dispose in interface at.spardat.xma.boot.component.IComponent

freePageModel

public void freePageModel(short idPageModel)
Frees the Page with the given ID. The Page will also be freed on the server bevor the next serverEvent is executed. If the Page does not exist or is allredy freed, nothing happens.

Parameters:
idPageModel - the ID of the Page to destroy.

invoke

public abstract void invoke(org.eclipse.swt.widgets.Composite parent)
This Method is called by the Launcher to start the Component on the client side. This Method must be implemented by the application programmer. It will typicaly create a Page and a DialogPage, copy some input data into the Page and start the DialogPage by calling DialogPage.invoke().

Specified by:
invoke in interface at.spardat.xma.boot.component.IComponent

externalize

public void externalize(XmaOutput xo,
                        boolean forceFull)
                 throws java.io.IOException
This method calculates the data stream necessary to update the server side component so that its state equals this client side component.

Specified by:
externalize in interface Synchronization
Parameters:
forceFull - the meaning here is as follows: If forceFull, we do not trust the delta mechanism. That implies that all alive pages are transmitted with all their widget models. So the server side state of the component may be deliberately inconsistent before. If forceFull is false, only changed pages or stateless pages are transmitted.
xo - the serialization destination
Throws:
java.io.IOException - on serialization errors
See Also:
Synchronization.externalize(at.spardat.xma.serializer.XmaOutput, boolean)

internalize

public void internalize(XmaInput in)
                 throws java.io.IOException,
                        java.lang.ClassNotFoundException
This method gets the data stream after a server side event and applies the changes to this client side component.

Specified by:
internalize in interface Synchronization
Parameters:
in - the XMAObjectInput. If a XMAObjectInputChangeListener is set in the object in, it will be notified after applying changes read from in.
Throws:
java.lang.ClassNotFoundException - on serialization errors
java.io.IOException - on serialization errors
See Also:
Synchronization.internalize(at.spardat.xma.serializer.XmaInput)

getContext

public XMAContext getContext()
Returns the global context.

Returns:
XMAContext

getSession

public XMASessionClient getSession()
Returns the Session this belongs to (you can rely on the returned object not to be null).


getRTSession

public at.spardat.xma.boot.component.IRtXMASessionClient getRTSession()
Returns the Session this belongs to (you can rely on the returned object not to be null).

Specified by:
getRTSession in interface at.spardat.xma.boot.component.IComponent

isOutOfSyncWithServer

public boolean isOutOfSyncWithServer()
Returns if the clients page model state is out of sync with respect to the servers state.

This method must not be called or overwritten outside the framework.


setOutOfSyncWithServer

public void setOutOfSyncWithServer(boolean b)
Sets the out of sync state.

This method must not be called or overwritten outside the framework.


newRemoteCall

protected RemoteCallClient newRemoteCall(java.lang.String namEvent)
Constructs a RemoteCall object to execute a server side method with the provided name. The corresponding server side Component 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

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.

createTask

public ITask createTask(java.lang.String name)
Creates the Task with the given name. The default implementation takes the name as the fully qualified classname of the Task.

Specified by:
createTask in interface IComponentClient
Parameters:
name - unique name for the task within the component.
Since:
1.4.0

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