A remote bean encapsulates the state of a server-side object in the client-side application.
Its properties are loaded on demand - most commonly by invoking the
RemoteBean#load
or RemoteBean#invalidate
methods, respectively.
The SDK provides more specialized subclasses of remote beans, for example beans of type
Content
, which represents CoreMedia CMS documents and folders.
Bean values may change when the remote bean is invalidated and reloaded. Note however that currently, there is no active event mechanism that invalidates client-side beans immediately after the data they represent changes on the server.
In the interface com.coremedia.ui.data.RemoteBean
, the method
getUri()
provides access to the URI from which its state is loaded. Its sibling
method getUriPath()
returns a URI path relative to the base URI of the remote
service from which the bean is loaded. The latter value provides a more concise and still
unique identification of the remote bean. There is only ever one remote bean for each URI
path.
By calling load(Function)
, the bean is instructed to load its properties, using
an asynchronous HTTP request. Note that this is transparent to the developer, that is, you
never need to manually construct an XHR, for example by invoking Ext
JS's Ajax#request
method.
Once the call has returned, an optional callback function is invoked, indicating the new
state of the bean. A remote bean is also loaded as soon as any of its properties are read.
However, the bean will report properties as undefined
initially and fire an
event as soon as the property is updated to a different value after loading.
To reload the bean state, call the method invalidate(Function)
, which takes an
optional callback function which is invoked after all properties have been reloaded.
Please note that computed bean properties may still be undefined
when the
callback functions are invoked. For example, the Content
bean contains a
property path
that requires all the content's parents to be loaded recursively.
Although the Content
bean itself might be completely loaded, the
path
property remains undefined
until all the content's parents
have finished loading. Listen to the change events for the computed property to find out
when the property is ready or use a ValueExpression
. See
Section 5.3.6, “Value Expressions” for details.
When properties of a remote bean are set, they are eventually written back to the server.
The remote bean may bundle any number of writes before making its update request. At least
all updates made in the same JavaScript execution without an intervening
window.setTimeout()
are bundled in one write. You can call the method
flush(Function)
to ensure that a callback function is invoked after the update
call for all previously updated properties has completed, either successfully or with an
error. The callback function can determine the success status of a flush call by its single
argument, a FlushResult
object. This object also carries a reference to the
flushed bean and, in the case of an error, to a RemoteError
object indicating
the source of the problem.
Remote beans may be unreadable or even nonexistent, which is indicated by the method
getState()
. A bean's state can be observed by usual property change listeners
(see previous section), since bean state changes trigger property change events and report
the current state (see com.coremedia.ui.data.PropertyChangeEvent#newState
).
Working with remote beans generally requires more attention to error conditions than working
with local beans.