com.google.web.bindery.requestfactory.shared

## Interface RequestContext

- All Known Subinterfaces:
    LoggingRequest
  All Known Implementing Classes:
    com.google.web.bindery.requestfactory.shared.impl.AbstractRequestContext, FakeRequestContext, InProcessRequestContext

      public interface RequestContext

  The base interface for RequestFactory service endpoints. Implementations of this interface are provided by the RequestFactory plumbing and this interface may be extended in the future.
  See Also:
    `FakeRequestContext`

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `<T extends RequestContext> T` | `append(T other)` Joins another RequestContext to this RequestContext.
    `<T extends BaseProxy> T` | `create(java.lang.Class<T> clazz)` Returns a new mutable proxy that this request can carry to the server, perhaps to be persisted.
    `<T extends BaseProxy> T` | `edit(T object)` Returns a mutable version of the proxy, whose mutations will accumulate in this context.
    `<P extends EntityProxy> Request<P>` | `find(EntityProxyId<P> proxyId)` Return a request to find a fresh instance of the referenced proxy.
    `void` | `fire()` Send the accumulated changes and method invocations associated with the RequestContext.
    `void` | `fire(Receiver<java.lang.Void> receiver)` For receiving errors or validation failures only.
    `RequestFactory` | `getRequestFactory()` Returns the `RequestFactory` that created the RequestContext.
    `boolean` | `isChanged()` Returns true if any changes have been made to proxies mutable under this context.

- - ### Method Detail

    - #### append

          <T extends RequestContext> T append(T other)

      Joins another RequestContext to this RequestContext.

           SomeContext ctx = myFactory.someContext();
           // Perform operations on ctx
           OtherContext other = ctx.append(myFactory.otherContext());
           // Perform operations on both other and ctx
           ctx.fire() // or other.fire() are equivalent

      Parameters:
        `other` - a freshly-constructed RequestContext whose state should be bound to this RequestContext
      Returns:
        `other`
      Throws:
        `java.lang.IllegalStateException` - if any methods have been called on `other` or if `other` was constructed by a different RequestFactory instance

    - #### create

          <T extends BaseProxy> T create(java.lang.Class<T> clazz)

      Returns a new mutable proxy that this request can carry to the server, perhaps to be persisted. If the object is succesfully persisted, a PERSIST event will be posted including the EntityProxyId of this proxy.
      Parameters:
        `clazz` - a Class object of type T
      Returns:
        an `BaseProxy` instance of type T

    - #### edit

          <T extends BaseProxy> T edit(T object)

      Returns a mutable version of the proxy, whose mutations will accumulate in this context. Proxies reached via getters on this mutable proxy will also be mutable.
      Parameters:
        `object` - an instance of type T
      Returns:
        an `EntityProxy` or `ValueProxy` instance of type T

    - #### find

          <P extends EntityProxy> Request<P> find(EntityProxyId<P> proxyId)

      Return a request to find a fresh instance of the referenced proxy.
      Parameters:
        `proxyId` - an `EntityProxyId` instance of type P
      Returns:
        a `Request` object

    - #### fire

          void fire()

      Send the accumulated changes and method invocations associated with the RequestContext.

      If `Request.to(Receiver)` has not been called, this method will install a default receiver that will throw a RuntimeException if there is a server failure.

    - #### fire

          void fire(Receiver<java.lang.Void> receiver)

      For receiving errors or validation failures only.
      Parameters:
        `receiver` - a `Receiver` instance
      Throws:
        `java.lang.IllegalArgumentException` - if `receiver` is `null`

    - #### getRequestFactory

          RequestFactory getRequestFactory()

      Returns the `RequestFactory` that created the RequestContext.

    - #### isChanged

          boolean isChanged()

      Returns true if any changes have been made to proxies mutable under this context. Note that vacuous changes — e.g. foo.setName(foo.getName() — will not trip the changed flag. Similarly, "unmaking" a change will clear the isChanged flag

           String name = bar.getName();
           bar.setName("something else");
           assertTrue(context.isChanged());
           bar.setName(name);
           assertFalse(context.isChanged());

      Returns:
        `true` if any changes have been made