123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296 |
- ---
- 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);
- }
- }
- ----
-
-
-
|