/*
* 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;
/**
* A Request represents a single method invocation on the server. It
* encapsulates the arguments provided to the Request factory method declared in
* a RequestContext as well as a set of object paths to return from the server.
* The returned data is provided to an optional {@link Receiver} object,
* specified by the {@link #to(Receiver)} method.
*
* @param <T> The return type of objects in the corresponding response.
* @see com.google.web.bindery.requestfactory.shared.testing.FakeRequest
*/
public interface Request<T> {
/**
* Submit this request. Failures will be reported through the global uncaught
* exception handler, if any.
*/
void fire();
/**
* Convenience method equivalent to calling <code>to(...).fire()</code>.
*
* @param receiver a {@link Receiver} instance
*/
void fire(Receiver<? super T> receiver);
/**
* Returns the RequestContext associated with the Request.
*/
RequestContext getRequestContext();
/**
* Specify the object that will receive the result of the method invocation.
*
* @param receiver a {@link Receiver} instance
* @return a {@link RequestContext} instance
*/
RequestContext to(Receiver<? super T> receiver);
/**
* Request additional reference properties to fetch with the return value.
*
* @param propertyRefs a list of reference property names as Strings
* @return a {@link Request} instance of type T
*/
Request<T> with(String... propertyRefs);
}