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. Some remote beans, in particular content object and workflow objects, are invalidated automatically after server-side changes.

In the class @coremedia/studio-client.client-core/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(AnyFunction), the bean is instructed to load its properties, using an asynchronous HTTP request. Note that this is transparent to the developer and you never need to manually construct an XHR.

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(AnyFunction), 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 setTimeout() are bundled in one write. You can call the method flush(AnyFunction) 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 PropertyChangeEvent#newState). Working with remote beans generally requires more attention to error conditions than working with local beans.