aboutsummaryrefslogtreecommitdiffstats
path: root/documentation/gwt/gwt-shared-state.asciidoc
blob: 6e14b6c435fcce35b856ce4ab0dc9d3f04b02b2c (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
---
title: Shared State
order: 5
layout: page
---

[[gwt.shared-state]]
= Shared State

The basic communication from a server-side component to its the client-side
widget counterpart is handled using a __shared state__. The shared state is
serialized transparently. It should be considered read-only on the client-side,
as it is not serialized back to the server-side.

A shared state object simply needs to extend the
[classname]#AbstractComponentState#. The member variables should normally be
declared as public.


----
public class MyComponentState extends AbstractComponentState {
    public String text;
}
----

A shared state should never contain any logic. If the members have private
visibility for some reason, you can also use public setters and getters, in
which case the property must not be public.

[[gwt.shared-state.location]]
== Location of Shared-State Classes

The shared-state classes are used by both server- and client-side classes, but
widget set compilation requires that they must be located in a client-side
source package. The default location is under a [filename]#client# package under
the package of the [filename]#.gwt.xml# descriptor. If you wish to organize the
shared classes separately from other client-side code, you can define separate
client-side source packages for pure client-side classes and any shared classes.
In addition to shared state classes, shared classes could include enumerations
and other classes needed by shared-state or RPC communication.

For example, you could have the following definitions in the
[filename]#.gwt.xml# descriptor:


----
    <source path="client" />
    <source path="shared" />
----

The paths are relative to the package containing the descriptor.


[[gwt.shared-state.component]]
== Accessing Shared State on Server-Side

A server-side component can access the shared state with the
[methodname]#getState()# method. It is required that you override the base
implementation with one that returns the shared state object cast to the proper
type, as follows:


----
@Override
public MyComponentState getState() {
    return (MyComponentState) super.getState();
}
----

You can then use the [methodname]#getState()# to access the shared state object
with the proper type.


----
public MyComponent() {
    getState().setText("This is the initial state");
    ....
}
----


[[gwt.shared-state.connector]]
== Handling Shared State in a Connector

A connector can access a shared state with the [methodname]#getState()# method.
The access should be read-only. It is required that you override the base
implementation with one that returns the proper shared state type, as follows:


----
@Override
public MyComponentState getState() {
    return (MyComponentState) super.getState();
}
----

State changes made on the server-side are communicated transparently to the
client-side. When a state change occurs, the [methodname]#onStateChanged()#
method in the connector is called. You should always call the superclass
method before anything else to handle changes to common component properties.


----
@Override
public void onStateChanged(StateChangeEvent stateChangeEvent) {
    super.onStateChanged(stateChangeEvent);
		
    // Copy the state properties to the widget properties
    final String text = getState().getText();
    getWidget().setText(text);
}
----

The crude [methodname]#onStateChanged()# method is called when any of the state
properties is changed, allowing you to have even complex logic in how you
manipulate the widget according to the state changes. In most cases, however,
you can handle the property changes more easily and also more efficiently by
using instead the [classname]#@OnStateChange# annotation on the handler methods
for each property, as described next in <<gwt.shared-state.onstatechange>>, or
by delegating the property value directly to the widget, as described in
<<gwt.shared-state.delegatetowidget>>.

ifdef::web[]
The processing phases of state changes are described in more detail in
<<dummy/../../../framework/gwt/gwt-advanced#gwt.advanced.phases,"Client-Side
Processing Phases">>.
endif::web[]


[[gwt.shared-state.onstatechange]]
== Handling Property State Changes with [classname]#@OnStateChange#

The [classname]#@OnStateChange# annotation can be used to mark a connector
method that handles state change on a particular property, given as parameter
for the annotation. In addition to higher clarity, this avoids handling all
property changes if a state change occurs in only one or some of them. However,
if a state change can occur in multiple properties, you can only use this
technique if the properties do not have interaction that prevents handling them
separately in arbitrary order.

We can replace the [methodname]#onStateChange()# method in the earlier connector
example with the following:


----
@OnStateChange("text")
void updateText() {
    getWidget().setText(getState().text);
}
----

If the shared state property and the widget property have same name and do not
require any type conversion, as is the case in the above example, you could
simplify this even further by using the [classname]#@DelegateToWidget#
annotation for the shared state property, as described in
<<gwt.shared-state.delegatetowidget>>.


[[gwt.shared-state.delegatetowidget]]
== Delegating State Properties to Widget

The [classname]#@DelegateToWidget# annotation for a shared state property
defines automatic delegation of the property value to the corresponding widget
property of the same name and type, by calling the respective setter for the
property in the widget.


----
public class MyComponentState extends AbstractComponentState {
    @DelegateToWidget
    public String text;
}
----

This is equivalent to handling the state change in the connector, as done in the
example in <<gwt.shared-state.onstatechange>>.

If you want to delegate a shared state property to a widget property of another
name, you can give the property name as a string parameter for the annotation.


----
public class MyComponentState extends AbstractComponentState {
    @DelegateToWidget("description")
    public String text;
}
----


[[gwt.shared-state.referring]]
== Referring to Components in Shared State

While you can pass any regular Java objects through a shared state, referring to
another component requires special handling because on the server-side you can
only refer to a server-side component, while on the client-side you only have
widgets. References to components can be made by referring to their connectors
(all server-side components implement the [interfacename]#Connector# interface).


----
public class MyComponentState extends AbstractComponentState {
    public Connector otherComponent;
}
----

You could then access the component on the server-side as follows:


----
public class MyComponent {
    public void MyComponent(Component otherComponent) {
        getState().otherComponent = otherComponent;
    }

    public Component getOtherComponent() {
        return (Component)getState().otherComponent;
    }

    // And the cast method
    @Override
    public MyComponentState getState() {
        return (MyComponentState) super.getState();
    }
}
----

On the client-side, you should cast it in a similar fashion to a
[classname]#ComponentConnector#, or possibly to the specific connector type if
it is known.


[[gwt.shared-state.resource]]
== Sharing Resources

Resources, which commonly are references to icons or other images, are another
case of objects that require special handling. A [interfacename]#Resource#
object exists only on the server-side and on the client-side you have an URL to
the resource. You need to use the [methodname]#setResource()# and
[methodname]#getResource()# on the server-side to access a resource, which is
serialized to the client-side separately.

Let us begin with the server-side API:


----
public class MyComponent extends AbstractComponent {
    ...

    public void setMyIcon(Resource myIcon) {
        setResource("myIcon", myIcon);
    }

    public Resource getMyIcon() {
        return getResource("myIcon");
    }
}
----

On the client-side, you can then get the URL of the resource with
[methodname]#getResourceUrl()#.


----
@Override
public void onStateChanged(StateChangeEvent stateChangeEvent) {
    super.onStateChanged(stateChangeEvent);
    ...
	
    // Get the resource URL for the icon
    getWidget().setMyIcon(getResourceUrl("myIcon"));
}
----

The widget could then use the URL, for example, as follows:


----
public class MyWidget extends Label {
    ...
    
    Element imgElement = null;
    
    public void setMyIcon(String url) {
        if (imgElement == null) {
            imgElement = DOM.createImg();
            getElement().appendChild(imgElement);
        }
        
        DOM.setElementAttribute(imgElement, "src", url);
    }
}
----