/*
* Copyright 2010 Google Inc.
*
* Licensed under the Apache License, Version 2.0 (the "License"); you may not
* use this file except in compliance with the License. You may obtain a copy of
* the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
* WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
* License for the specific language governing permissions and limitations under
* the License.
*/
package com.google.web.bindery.requestfactory.shared;
/**
* 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 com.google.web.bindery.requestfactory.shared.testing.FakeRequestContext
*/
public interface RequestContext {
/**
* Joins another RequestContext to this RequestContext.
*
* <pre>
* 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
* </pre>
*
* @param other a freshly-constructed RequestContext whose state should be
* bound to this RequestContext
* @return {@code other}
* @throws IllegalStateException if any methods have been called on
* {@code other} or if {@code other} was constructed by a different
* RequestFactory instance
*/
<T extends RequestContext> T append(T other);
/**
* 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.
*
* @param clazz a Class object of type T
* @return an {@link BaseProxy} instance of type T
*/
<T extends BaseProxy> T create(Class<T> clazz);
/**
* 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.
*
* @param object an instance of type T
* @return an {@link EntityProxy} or {@link ValueProxy} instance of type T
*/
<T extends BaseProxy> T edit(T object);
/**
* Return a request to find a fresh instance of the referenced proxy.
*
* @param proxyId an {@link EntityProxyId} instance of type P
* @return a {@link Request} object
*/
<P extends EntityProxy> Request<P> find(EntityProxyId<P> proxyId);
/**
* Send the accumulated changes and method invocations associated with the
* RequestContext.
* <p>
* If {@link 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.
*/
void fire();
/**
* For receiving errors or validation failures only.
*
* @param receiver a {@link Receiver} instance
* @throws IllegalArgumentException if <code>receiver</code> is
* <code>null</code>
*/
void fire(Receiver<Void> receiver);
/**
* Returns the {@link RequestFactory} that created the RequestContext.
*/
RequestFactory getRequestFactory();
/**
* 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
*
* <pre>
* String name = bar.getName();
* bar.setName("something else");
* assertTrue(context.isChanged());
* bar.setName(name);
* assertFalse(context.isChanged());
* </pre>
*
* @return {@code true} if any changes have been made
*/
boolean isChanged();
}