Clean up Place and RequestFactory javadoc
Specify a charset in base64 encoding/decoding in JsonRequestProcessor
Review at http://gwt-code-reviews.appspot.com/1009801
Review by: rjrjr@google.com
git-svn-id: https://google-web-toolkit.googlecode.com/svn/trunk@9076 8db76d5a-ed1c-0410-87a9-c151d255dfc7
diff --git a/user/src/com/google/gwt/app/rebind/package.html b/user/src/com/google/gwt/app/rebind/package.html
index 9eb0788..f190dd1 100644
--- a/user/src/com/google/gwt/app/rebind/package.html
+++ b/user/src/com/google/gwt/app/rebind/package.html
@@ -1,7 +1,7 @@
<html>
<body>
Code generators for the GWT application framework.
-<p><span style="color:red">Experimental API: All classes in this package are still under rapid development, and are very likely to be deleted or renamed. Use them at your own risk.
-</span></p>
+
+@since GWT 2.1
</body>
</html>
diff --git a/user/src/com/google/gwt/place/shared/PlaceChangeEvent.java b/user/src/com/google/gwt/place/shared/PlaceChangeEvent.java
index b3aa594..1c9700a 100644
--- a/user/src/com/google/gwt/place/shared/PlaceChangeEvent.java
+++ b/user/src/com/google/gwt/place/shared/PlaceChangeEvent.java
@@ -27,13 +27,26 @@
* Implemented by handlers of PlaceChangeEvent.
*/
public interface Handler extends EventHandler {
+ /**
+ * Called when a {@link PlaceChangeEvent} is fired.
+ *
+ * @param event the {@link PlaceChangeEvent}
+ */
void onPlaceChange(PlaceChangeEvent event);
}
+ /**
+ * A singleton instance of Type<Handler>.
+ */
public static final Type<Handler> TYPE = new Type<Handler>();
private final Place newPlace;
+ /**
+ * Constructs a PlaceChangeEvent for the given {@link Place}.
+ *
+ * @param newPlace a {@link Place} instance
+ */
public PlaceChangeEvent(Place newPlace) {
this.newPlace = newPlace;
}
@@ -43,6 +56,11 @@
return TYPE;
}
+ /**
+ * Return the new {@link Place}.
+ *
+ * @return a {@link Place} instance
+ */
public Place getNewPlace() {
return newPlace;
}
diff --git a/user/src/com/google/gwt/place/shared/PlaceChangeRequestEvent.java b/user/src/com/google/gwt/place/shared/PlaceChangeRequestEvent.java
index 35d63e4..d00e7c2 100644
--- a/user/src/com/google/gwt/place/shared/PlaceChangeRequestEvent.java
+++ b/user/src/com/google/gwt/place/shared/PlaceChangeRequestEvent.java
@@ -30,15 +30,28 @@
* Implemented by handlers of PlaceChangeRequestEvent.
*/
public interface Handler extends EventHandler {
+ /**
+ * Called when a {@link PlaceChangeRequestEvent} is fired.
+ *
+ * @param event the {@link PlaceChangeRequestEvent}
+ */
void onPlaceChangeRequest(PlaceChangeRequestEvent event);
}
+ /**
+ * A singleton instance of Type<Handler>.
+ */
public static final Type<Handler> TYPE = new Type<Handler>();
private String warning;
private final Place newPlace;
+ /**
+ * Constructs a PlaceChangeRequestEvent for the given {@link Place}.
+ *
+ * @param newPlace a {@link Place} instance
+ */
public PlaceChangeRequestEvent(Place newPlace) {
this.newPlace = newPlace;
}
@@ -50,6 +63,8 @@
/**
* Returns the place we may navigate to, or null on window close.
+ *
+ * @return a {@link Place} instance
*/
public Place getNewPlace() {
return newPlace;
@@ -58,6 +73,9 @@
/**
* Returns the warning message to show the user before allowing the place
* change, or null if none has been set.
+ *
+ * @return the warning message as a String
+ * @see #setWarning(String)
*/
public String getWarning() {
return warning;
@@ -73,6 +91,9 @@
* <p>
* Only the first non-null call to setWarning has any effect. That is, once
* the warning message has been set it cannot be cleared.
+ *
+ * @param warning the warning message as a String
+ * @see #getWarning()
*/
public void setWarning(String warning) {
if (this.warning == null) {
diff --git a/user/src/com/google/gwt/place/shared/PlaceController.java b/user/src/com/google/gwt/place/shared/PlaceController.java
index 4a7e497..294a963 100644
--- a/user/src/com/google/gwt/place/shared/PlaceController.java
+++ b/user/src/com/google/gwt/place/shared/PlaceController.java
@@ -42,13 +42,25 @@
}
/**
- * Optional delegate in charge of Window related events. Provides nice
+ * Optional delegate in charge of Window-related events. Provides nice
* isolation for unit testing, and allows customization of confirmation
* handling.
*/
public interface Delegate {
+ /**
+ * Adds a {@link ClosingHandler} to the Delegate.
+ *
+ * @param handler a {@link ClosingHandler} instance
+ * @return a {@link HandlerRegistration} instance
+ */
HandlerRegistration addWindowClosingHandler(ClosingHandler handler);
+ /**
+ * Called to confirm a window closing event.
+ *
+ * @param message a warning message
+ * @return true to allow the window closing
+ */
boolean confirm(String message);
}
@@ -62,8 +74,10 @@
/**
* Create a new PlaceController with a {@link DefaultDelegate}. The
* DefaultDelegate is created via a call to GWT.create(), so an alternative
- * default implementation can be provided through <replace-with> rules in a
- * gwt.xml file.
+ * default implementation can be provided through <replace-with> rules
+ * in a {@code .gwt.xml} file.
+ *
+ * @param eventBus the {@link EventBus}
*/
public PlaceController(EventBus eventBus) {
this(eventBus, (Delegate) GWT.create(DefaultDelegate.class));
@@ -71,6 +85,9 @@
/**
* Create a new PlaceController.
+ *
+ * @param eventBus the {@link EventBus}
+ * @param delegate the {@link Delegate} in charge of Window-related events
*/
public PlaceController(EventBus eventBus, Delegate delegate) {
this.eventBus = eventBus;
@@ -87,6 +104,8 @@
/**
* Returns the current place.
+ *
+ * @return a {@link Place} instance
*/
public Place getWhere() {
return where;
@@ -100,6 +119,8 @@
* typically a call to {@link Window#confirm(String)}). If she cancels, the
* current location will not change. Otherwise, the location changes and a
* {@link PlaceChangeEvent} is posted announcing the new place.
+ *
+ * @param newPlace a {@link Place} instance
*/
public void goTo(Place newPlace) {
log().fine("goTo: " + newPlace);
diff --git a/user/src/com/google/gwt/place/shared/PlaceHistoryHandler.java b/user/src/com/google/gwt/place/shared/PlaceHistoryHandler.java
index 274fd55..94fa17f 100644
--- a/user/src/com/google/gwt/place/shared/PlaceHistoryHandler.java
+++ b/user/src/com/google/gwt/place/shared/PlaceHistoryHandler.java
@@ -53,11 +53,14 @@
* isolation for unit testing, and allows pre- or post-processing of tokens.
*/
public interface Historian {
+ // TODO - document
HandlerRegistration addValueChangeHandler(
ValueChangeHandler<String> valueChangeHandler);
+ // TODO - document
String getToken();
+ // TODO - document
void newItem(String token, boolean issueEvent);
}
@@ -73,7 +76,9 @@
* Create a new PlaceHistoryHandler with a {@link DefaultHistorian}.
* The DefaultHistorian is created via a call to GWT.create(), so an
* alternative default implementation can be provided through
- * <replace-with> rules in a gwt.xml file.
+ * <replace-with> rules in a {@code gwt.xml} file.
+ *
+ * @param mapper a {@link PlaceHistoryMapper} instance
*/
public PlaceHistoryHandler(PlaceHistoryMapper mapper) {
this(mapper, (Historian) GWT.create(DefaultHistorian.class));
@@ -81,16 +86,21 @@
/**
* Create a new PlaceHistoryHandler.
+ *
+ * @param mapper a {@link PlaceHistoryMapper} instance
+ * @param historian a {@link Historian} instance
*/
public PlaceHistoryHandler(PlaceHistoryMapper mapper, Historian historian) {
this.mapper = mapper;
this.historian = historian;
}
+ // TODO - document
public void handleCurrentHistory() {
handleHistoryToken(historian.getToken());
}
+ // TODO - document
public HandlerRegistration register(PlaceController placeController,
EventBus eventBus, Place defaultPlace) {
this.placeController = placeController;
diff --git a/user/src/com/google/gwt/place/shared/PlaceHistoryMapper.java b/user/src/com/google/gwt/place/shared/PlaceHistoryMapper.java
index 145b92e..6037ffd 100644
--- a/user/src/com/google/gwt/place/shared/PlaceHistoryMapper.java
+++ b/user/src/com/google/gwt/place/shared/PlaceHistoryMapper.java
@@ -21,7 +21,19 @@
*/
public interface PlaceHistoryMapper {
+ /**
+ * Returns the {@link Place} associated with the given token.
+ *
+ * @param token a String token
+ * @return a {@link Place} instance
+ */
Place getPlace(String token);
+ /**
+ * Returns the String token associated with the given {@link Place}.
+ *
+ * @param place a {@link Place} instance
+ * @return a String token
+ */
String getToken(Place place);
}
diff --git a/user/src/com/google/gwt/place/shared/PlaceHistoryMapperWithFactory.java b/user/src/com/google/gwt/place/shared/PlaceHistoryMapperWithFactory.java
index 4d0b6b7..dd326ea 100644
--- a/user/src/com/google/gwt/place/shared/PlaceHistoryMapperWithFactory.java
+++ b/user/src/com/google/gwt/place/shared/PlaceHistoryMapperWithFactory.java
@@ -16,12 +16,17 @@
package com.google.gwt.place.shared;
/**
- * A PlaceHistoryMapper that can get its {@link PlaceTokenizer} instances from
- * a factory.
+ * A {@link PlaceHistoryMapper} that can get its {@link PlaceTokenizer}
+ * instances from a factory.
*
* @param <F> factory type
*/
public interface PlaceHistoryMapperWithFactory<F> extends PlaceHistoryMapper {
+ /**
+ * Sets the factory to be used to generate {@link PlaceTokenizer} instances.
+ *
+ * @param factory a factory of type F
+ */
void setFactory(F factory);
}
diff --git a/user/src/com/google/gwt/place/shared/PlaceTokenizer.java b/user/src/com/google/gwt/place/shared/PlaceTokenizer.java
index ebc2a71..6e04c98 100644
--- a/user/src/com/google/gwt/place/shared/PlaceTokenizer.java
+++ b/user/src/com/google/gwt/place/shared/PlaceTokenizer.java
@@ -19,10 +19,23 @@
* Implemented by objects responsible for text serialization and deserialization
* of Place objects.
*
- * @param <P>
+ * @param <P> a subtype of {@link Place}
*/
public interface PlaceTokenizer<P extends Place> {
+
+ /**
+ * Returns the {@link Place} associated with the given token.
+ *
+ * @param token a String token
+ * @return a {@link Place} of type P
+ */
P getPlace(String token);
+ /**
+ * Returns the token associated with the given {@link Place}.
+ *
+ * @param place a {@link Place} of type P
+ * @return a String token
+ */
String getToken(P place);
}
diff --git a/user/src/com/google/gwt/place/shared/package.html b/user/src/com/google/gwt/place/shared/package.html
new file mode 100644
index 0000000..96668b0
--- /dev/null
+++ b/user/src/com/google/gwt/place/shared/package.html
@@ -0,0 +1,7 @@
+<html>
+<body>
+<p>A package for managing bookmarkable locations in an application.
+
+@since GWT 2.1
+</body>
+</html>
diff --git a/user/src/com/google/gwt/requestfactory/client/DefaultRequestTransport.java b/user/src/com/google/gwt/requestfactory/client/DefaultRequestTransport.java
index 0fd2571..f8e555c 100644
--- a/user/src/com/google/gwt/requestfactory/client/DefaultRequestTransport.java
+++ b/user/src/com/google/gwt/requestfactory/client/DefaultRequestTransport.java
@@ -25,9 +25,9 @@
import com.google.gwt.http.client.RequestException;
import com.google.gwt.http.client.Response;
import com.google.gwt.requestfactory.shared.RequestEvent;
-import com.google.gwt.requestfactory.shared.RequestEvent.State;
import com.google.gwt.requestfactory.shared.RequestFactory;
import com.google.gwt.requestfactory.shared.RequestTransport;
+import com.google.gwt.requestfactory.shared.RequestEvent.State;
import com.google.gwt.user.client.Window.Location;
import java.util.logging.Level;
@@ -36,18 +36,6 @@
/**
* An implementation of {@link RequestTransport} that uses a
* {@link RequestBuilder}.
- * <p>
- * This implementation will send {@link RequestEvent} objects to the
- * {@link EventBus} passed into the constructor to provide indication of
- * transport-level activity. When an HTTP request is sent, an event with a
- * {@link State#SENT} state and a {@code null} {@link Request} will be posted.
- * When an HTTP transport completes successfully, an event will be posted with
- * state {@link State#RECEIVED} and the {@link Request} object provided to the
- * internal {@link RequestCallback#onResponseReceived()}. If an HTTP transport
- * fails (e.g. due to network malfunction), an event with state
- * {@link State#RECEIVED} and a {@code null} {@link Request} will be sent. The
- * success or failure of the HTTP transport is wholly independent from whether
- * or not the application payload was successfully executed by the server.
*/
public class DefaultRequestTransport implements RequestTransport {
@@ -86,6 +74,9 @@
/**
* Returns the current URL used by this transport.
+ *
+ * @return the URL as a String
+ * @see #setRequestUrl(String)
*/
public String getRequestUrl() {
return requestUrl;
@@ -110,6 +101,9 @@
/**
* Override the default URL used by this transport.
+ *
+ * @param url a String URL
+ * @see #getRequestUrl()
*/
public void setRequestUrl(String url) {
this.requestUrl = url;
@@ -117,6 +111,8 @@
/**
* Override to change the headers sent in the HTTP request.
+ *
+ * @param builder a {@link RequestBuilder} instance
*/
protected void configureRequestBuilder(RequestBuilder builder) {
builder.setHeader("Content-Type", RequestFactory.JSON_CONTENT_TYPE_UTF8);
@@ -125,8 +121,10 @@
}
/**
- * Constructs a RequestBuilder using the {@link RequestBuilder#POST} method
- * sent to the URL returned from {@link #getRequestUrl()}.
+ * Constructs a {@link RequestBuilder} using the {@link RequestBuilder#POST}
+ * method sent to the URL returned from {@link #getRequestUrl()}.
+ *
+ * @return a {@link RequestBuilder} instance
*/
protected RequestBuilder createRequestBuilder() {
return new RequestBuilder(RequestBuilder.POST, getRequestUrl());
@@ -136,6 +134,9 @@
* Creates a RequestCallback that maps the HTTP response onto the
* {@link com.google.gwt.requestfactory.shared.RequestTransport.TransportReceiver
* TransportReceiver} interface.
+ *
+ * @param receiver a {@link TransportReceiver}
+ * @return a {@link RequestCallback} instance
*/
protected RequestCallback createRequestCallback(
final TransportReceiver receiver) {
diff --git a/user/src/com/google/gwt/requestfactory/client/RequestFactoryEditorDriver.java b/user/src/com/google/gwt/requestfactory/client/RequestFactoryEditorDriver.java
index a98e6eb..1afa4e8 100644
--- a/user/src/com/google/gwt/requestfactory/client/RequestFactoryEditorDriver.java
+++ b/user/src/com/google/gwt/requestfactory/client/RequestFactoryEditorDriver.java
@@ -52,6 +52,8 @@
/**
* Start driving the Editor and its sub-editors with data for display-only
* mode.
+ *
+ * @param proxy a Proxy of type P
*/
void display(P proxy);
@@ -79,23 +81,34 @@
RequestContext flush();
/**
- * Returns any unconsumed EditorErrors from the last call to {@link #flush()}.
+ * Returns any unconsumed {@link EditorError EditorErrors} from the last call
+ * to {@link #flush()}.
+ *
+ * @return a List of {@link EditorError} instances
*/
List<EditorError> getErrors();
/**
- * Returns a new array.
+ * Returns a new array containing the request paths.
+ *
+ * @return an array of Strings
*/
String[] getPaths();
/**
* Indicates if the last call to {@link #flush()} resulted in any errors.
+ *
+ * @return {@code} true if errors are present
*/
boolean hasErrors();
/**
* Overload of {@link #initialize(RequestFactory, Editor)} to allow a modified
* {@link EventBus} to be monitored for subscription services.
+ *
+ * @param eventBus the {@link EventBus}
+ * @param requestFactory a {@link RequestFactory} instance
+ * @param editor an {@link Editor} of type E
*
* @see com.google.gwt.editor.client.EditorDelegate#subscribe
* @see com.google.gwt.event.shared.ResettableEventBus
@@ -105,6 +118,9 @@
/**
* Initializes a driver with the editor it will run, and a RequestFactory to
* use for subscription services.
+ *
+ * @param requestFactory a {@link RequestFactory} instance
+ * @param editor an {@link Editor} of type E
*
* @see com.google.gwt.editor.client.EditorDelegate#subscribe
*/
@@ -114,6 +130,8 @@
* Initializes a driver that will not be able to support subscriptions. Calls
* to {@link com.google.gwt.editor.client.EditorDelegate#subscribe()} will do
* nothing.
+ *
+ * @param editor an {@link Editor} of type E
*/
void initialize(E editor);
@@ -122,6 +140,8 @@
* violations will be converted into {@link EditorError} objects whose
* {@link EditorError#getUserData() getUserData()} method can be used to
* access the original Violation object.
+ *
+ * @param errors a Iterable over {@link Violation} instances
*
* @return <code>true</code> if there were any unconsumed EditorErrors which
* can be retrieved from {@link #getErrors()}
diff --git a/user/src/com/google/gwt/requestfactory/client/RequestFactoryLogHandler.java b/user/src/com/google/gwt/requestfactory/client/RequestFactoryLogHandler.java
index 0383f5d..d3f0b4f 100644
--- a/user/src/com/google/gwt/requestfactory/client/RequestFactoryLogHandler.java
+++ b/user/src/com/google/gwt/requestfactory/client/RequestFactoryLogHandler.java
@@ -34,6 +34,11 @@
* Provides a logging request.
*/
public static interface LoggingRequestProvider {
+ /**
+ * Returns the logging request.
+ *
+ * @return a {@link LoggingRequest} instance
+ */
LoggingRequest getLoggingRequest();
}
@@ -47,6 +52,10 @@
* name of the logger(s) which will be used to log acknowledgements of
* activity going accross the wire. If we did not exclude these loggers, an
* infinite loop would occur.
+ *
+ * @param requestProvider a {@link LoggingRequestProvider} instance
+ * @param level a logging {@link Level}
+ * @param ignoredLoggerNames a List of Strings
*/
public RequestFactoryLogHandler(LoggingRequestProvider requestProvider,
Level level, List<String> ignoredLoggerNames) {
diff --git a/user/src/com/google/gwt/requestfactory/client/package.html b/user/src/com/google/gwt/requestfactory/client/package.html
new file mode 100644
index 0000000..75b49b8
--- /dev/null
+++ b/user/src/com/google/gwt/requestfactory/client/package.html
@@ -0,0 +1,7 @@
+<html>
+<body>
+<p>A package for manging client-server requests.
+
+@since GWT 2.1
+</body>
+</html>
diff --git a/user/src/com/google/gwt/requestfactory/server/DeadEntityException.java b/user/src/com/google/gwt/requestfactory/server/DeadEntityException.java
index 008fe4c..84df340 100644
--- a/user/src/com/google/gwt/requestfactory/server/DeadEntityException.java
+++ b/user/src/com/google/gwt/requestfactory/server/DeadEntityException.java
@@ -17,12 +17,21 @@
/**
* Indicates the user attempted to perform an operation on an irretrievable
- * entity
+ * entity.
*/
public class DeadEntityException extends RuntimeException {
+
+ /**
+ * Contructs a new {@link DeadEntityException}.
+ */
public DeadEntityException() {
}
+ /**
+ * Contructs a new {@link DeadEntityException} with a given message.
+ *
+ * @param message a message String
+ */
public DeadEntityException(String message) {
super(message);
}
diff --git a/user/src/com/google/gwt/requestfactory/server/ExceptionHandler.java b/user/src/com/google/gwt/requestfactory/server/ExceptionHandler.java
index 9225a95..4faff11 100644
--- a/user/src/com/google/gwt/requestfactory/server/ExceptionHandler.java
+++ b/user/src/com/google/gwt/requestfactory/server/ExceptionHandler.java
@@ -25,6 +25,8 @@
* Generates a {@link ServerFailure} based on the information
* contained in the received {@code exception}.
*
+ * @param throwable a Throwable instance
+ * @return a {@link ServerFailure} instance
* @see DefaultExceptionHandler
*/
ServerFailure createServerFailure(Throwable throwable);
diff --git a/user/src/com/google/gwt/requestfactory/server/FindService.java b/user/src/com/google/gwt/requestfactory/server/FindService.java
index cd26f48..06aefd8 100644
--- a/user/src/com/google/gwt/requestfactory/server/FindService.java
+++ b/user/src/com/google/gwt/requestfactory/server/FindService.java
@@ -20,8 +20,11 @@
*/
public class FindService {
- /*
+ /**
* For now, a simple implementation of find will work.
+ *
+ * @param entityInstance an entity instance
+ * @return the passed-in entity instance
*/
public static <T> T find(T entityInstance) {
return entityInstance;
diff --git a/user/src/com/google/gwt/requestfactory/server/JsonRequestProcessor.java b/user/src/com/google/gwt/requestfactory/server/JsonRequestProcessor.java
index ce0f692..39242b4 100644
--- a/user/src/com/google/gwt/requestfactory/server/JsonRequestProcessor.java
+++ b/user/src/com/google/gwt/requestfactory/server/JsonRequestProcessor.java
@@ -30,6 +30,7 @@
import org.json.JSONObject;
import java.beans.Introspector;
+import java.io.UnsupportedEncodingException;
import java.lang.reflect.Field;
import java.lang.reflect.InvocationTargetException;
import java.lang.reflect.Method;
@@ -159,7 +160,12 @@
private static final Logger log = Logger.getLogger(JsonRequestProcessor.class.getName());
- // Decodes a string encoded as web-safe base64
+ /**
+ * Decodes a String encoded as web-safe base64.
+ *
+ * @param encoded the encoded String
+ * @return a decoded String
+ */
public static String base64Decode(String encoded) {
byte[] decodedBytes;
try {
@@ -168,15 +174,31 @@
throw new IllegalArgumentException("EntityKeyId was not Base64 encoded: "
+ encoded);
}
- return new String(decodedBytes);
+ try {
+ return new String(decodedBytes, "UTF-8");
+ } catch (UnsupportedEncodingException e) {
+ // This can't happen
+ throw new IllegalStateException(e);
+ }
}
- // Encodes a string with web-safe base64
+ /**
+ * Encodes a String as web-safe base64.
+ *
+ * @param decoded the decoded String
+ * @return an encoded String
+ */
public static String base64Encode(String decoded) {
- byte[] decodedBytes = decoded.getBytes();
- return Base64Utils.toBase64(decodedBytes);
+ try {
+ byte[] decodedBytes = decoded.getBytes("UTF-8");
+ return Base64Utils.toBase64(decodedBytes);
+ } catch (UnsupportedEncodingException e) {
+ // This can't happen
+ throw new IllegalStateException(e);
+ }
}
+ // TODO - document
@SuppressWarnings("unchecked")
public static Class<EntityProxy> getRecordFromClassToken(String recordToken) {
try {
@@ -201,6 +223,7 @@
private OperationRegistry operationRegistry;
private ExceptionHandler exceptionHandler;
+
/*
* <li>Request comes in. Construct the involvedKeys, dvsDataMap and
* beforeDataMap, using DVS and parameters.
@@ -218,12 +241,14 @@
private Map<EntityKey, EntityData> afterDvsDataMap = new HashMap<EntityKey, EntityData>();
+ // TODO - document
@SuppressWarnings("rawtypes")
public Collection<Property<?>> allProperties(
Class<? extends EntityProxy> clazz) throws IllegalArgumentException {
return getPropertiesFromRecordProxyType(clazz).values();
}
+ // TODO - document
public String decodeAndInvokeRequest(String encodedRequest)
throws RequestProcessingException {
try {
@@ -250,6 +275,7 @@
/**
* Decodes parameter value.
*/
+ // TODO - document parameters and return value
public Object decodeParameterValue(Type genericParameterType,
String parameterValue) throws SecurityException, JSONException,
IllegalAccessException, InvocationTargetException, NoSuchMethodException,
@@ -373,8 +399,11 @@
+ parameterType);
}
- /*
+ /**
* Encode a property value to be sent across the wire.
+ *
+ * @param value a value Object
+ * @return an encoded value Object
*/
public Object encodePropertyValue(Object value) {
if (value == null) {
@@ -404,6 +433,7 @@
* Returns the propertyValue in the right type, from the DataStore. The value
* is sent into the response.
*/
+ // TODO - document parameters and return value
public Object encodePropertyValueFromDataStore(Object entityElement,
Property<?> property, String propertyName, RequestProperty propertyContext)
throws SecurityException, NoSuchMethodException, IllegalAccessException,
@@ -452,6 +482,7 @@
* <p>
* If a <i>set</i> method has side-effects, we will not notice.
*/
+ // TODO - document parameters and return value
public EntityData getEntityDataForRecordWithSettersApplied(
EntityKey entityKey, JSONObject recordObject,
WriteOperation writeOperation) throws JSONException, SecurityException,
@@ -538,6 +569,7 @@
: getViolationsAsJson(violations)));
}
+ // TODO - document
public Object getEntityInstance(EntityKey entityKey)
throws NoSuchMethodException, IllegalAccessException,
InvocationTargetException, JSONException, InstantiationException {
@@ -549,6 +581,7 @@
return entityInstance;
}
+ // TODO - document
public Object getEntityInstance(WriteOperation writeOperation,
Class<?> entityType, Object idValue, Class<?> idType)
throws SecurityException, InstantiationException, IllegalAccessException,
@@ -563,6 +596,7 @@
null, decodeParameterValue(idType, idValue.toString()));
}
+ // TODO - document
@SuppressWarnings("unchecked")
public Class<Object> getEntityTypeForProxyType(
Class<? extends EntityProxy> record) {
@@ -1433,7 +1467,7 @@
private boolean hasServerVersionChanged(EntityKey entityKey,
Object entityInstanceAfterOperation) throws IllegalArgumentException,
SecurityException, IllegalAccessException, InvocationTargetException,
- NoSuchMethodException, JSONException, InstantiationException {
+ NoSuchMethodException, JSONException {
SerializedEntity beforeEntity = beforeDataMap.get(entityKey);
if (beforeEntity != null
&& hasChanged(beforeEntity.serializedEntity,
diff --git a/user/src/com/google/gwt/requestfactory/server/Logging.java b/user/src/com/google/gwt/requestfactory/server/Logging.java
index d9d806f..4bbef25 100644
--- a/user/src/com/google/gwt/requestfactory/server/Logging.java
+++ b/user/src/com/google/gwt/requestfactory/server/Logging.java
@@ -30,6 +30,12 @@
private static StackTraceDeobfuscator deobfuscator =
new StackTraceDeobfuscator("");
+ /**
+ * Logs a message.
+ *
+ * @param logRecordJson a log record in JSON format.
+ * @throws RemoteLoggingException if logging fails
+ */
public static void logMessage(String logRecordJson) throws
RemoteLoggingException {
// if the header does not exist, we pass null, which is handled gracefully
@@ -44,6 +50,8 @@
/**
* This function is only for server side use which is why it's not in the
* LoggingRequest interface.
+ *
+ * @param dir a directory, specified as a String
*/
public static void setSymbolMapsDirectory(String dir) {
deobfuscator.setSymbolMapsDirectory(dir);
@@ -53,18 +61,42 @@
private Integer version = 0;
+ /**
+ * Returns the id of this instance.
+ *
+ * @return a String id
+ * @see #setId(String)
+ */
public String getId() {
return this.id;
}
+ /**
+ * Returns the version of this instance.
+ *
+ * @return an Integer version number
+ * @see #setVersion(Integer)
+ */
public Integer getVersion() {
return this.version;
}
+ /**
+ * Sets the id on this instance.
+ *
+ * @param id a String id
+ * @see #getId()
+ */
public void setId(String id) {
this.id = id;
}
+ /**
+ * Sets the version of this instance.
+ *
+ * @param version an Integer version number
+ * @see #getVersion()
+ */
public void setVersion(Integer version) {
this.version = version;
}
diff --git a/user/src/com/google/gwt/requestfactory/server/OperationRegistry.java b/user/src/com/google/gwt/requestfactory/server/OperationRegistry.java
index c769ee0..d21e1a2 100644
--- a/user/src/com/google/gwt/requestfactory/server/OperationRegistry.java
+++ b/user/src/com/google/gwt/requestfactory/server/OperationRegistry.java
@@ -20,7 +20,19 @@
*/
public interface OperationRegistry {
+ /**
+ * Returns the {@link RequestDefinition} associated with the given operation.
+ *
+ * @param operationName the operation name as a String
+ * @return a {@link RequestDefinition} instance
+ */
RequestDefinition getOperation(String operationName);
+ /**
+ * Returns the {@link RequestSecurityProvider} associated with this
+ * {@link OperationRegistry}.
+ *
+ * @return a {@link RequestSecurityProvider} instance
+ */
RequestSecurityProvider getSecurityProvider();
}
diff --git a/user/src/com/google/gwt/requestfactory/server/ReflectionBasedOperationRegistry.java b/user/src/com/google/gwt/requestfactory/server/ReflectionBasedOperationRegistry.java
index b2c89bf..874643d 100644
--- a/user/src/com/google/gwt/requestfactory/server/ReflectionBasedOperationRegistry.java
+++ b/user/src/com/google/gwt/requestfactory/server/ReflectionBasedOperationRegistry.java
@@ -182,19 +182,30 @@
}
}
+ /**
+ * The separator used to delimit scopes.
+ */
public static final String SCOPE_SEPARATOR = "::";
private RequestSecurityProvider securityProvider;
+ /**
+ * Constructs a {@link ReflectionBasedOperationRegistry} instance
+ * with a given {@link RequestSecurityProvider}.
+ *
+ * @param securityProvider a {@link RequestSecurityProvider} instance.
+ */
public ReflectionBasedOperationRegistry(
RequestSecurityProvider securityProvider) {
this.securityProvider = securityProvider;
}
/**
-
* Turns an operation in the form of package.requestClass::method into a
* RequestDefinition via reflection.
+ *
+ * @param operationName the operation name as a String
+ * @return a {@link RequestDefinition} instance
*/
public RequestDefinition getOperation(String operationName) {
String decodedOperationName = securityProvider.mapOperation(operationName);
diff --git a/user/src/com/google/gwt/requestfactory/server/RequestDefinition.java b/user/src/com/google/gwt/requestfactory/server/RequestDefinition.java
index 1e0db57..9929659 100644
--- a/user/src/com/google/gwt/requestfactory/server/RequestDefinition.java
+++ b/user/src/com/google/gwt/requestfactory/server/RequestDefinition.java
@@ -26,33 +26,50 @@
/**
* Returns the name of the (domain) class that contains the method to be
* invoked on the server.
+ *
+ * @return the domain class name as a String
*/
String getDomainClassName();
/**
* Returns the method to be invoked on the server.
+ *
+ * @return the domain Method
*/
Method getDomainMethod();
/**
* Returns the parameter types of the method to be invoked on the server.
+ *
+ * @return an array of Class objects for each parameter type
*/
Class<?>[] getParameterTypes();
+ /**
+ * Returns the request parameter types.
+ *
+ * @return an array of Type objects for each request parameter
+ */
Type[] getRequestParameterTypes();
/**
* Returns the return type of the method to be invoked on the server.
+ *
+ * @return a Class object representing the return type
*/
Class<?> getReturnType();
/**
- * Returns true if the domain method is an instance method.
+ * Returns whether the domain method is an instance method.
+ *
+ * @return {@code true} if the domain method is an instance method
*/
boolean isInstance();
/**
* Returns the name.
+ *
+ * @return the name as a String
*/
String name();
}
\ No newline at end of file
diff --git a/user/src/com/google/gwt/requestfactory/server/RequestFactoryServlet.java b/user/src/com/google/gwt/requestfactory/server/RequestFactoryServlet.java
index 1f8eb6b..74ff36c 100644
--- a/user/src/com/google/gwt/requestfactory/server/RequestFactoryServlet.java
+++ b/user/src/com/google/gwt/requestfactory/server/RequestFactoryServlet.java
@@ -62,16 +62,30 @@
private static final ThreadLocal<HttpServletRequest> perThreadRequest = new ThreadLocal<HttpServletRequest>();
private static final ThreadLocal<HttpServletResponse> perThreadResponse = new ThreadLocal<HttpServletResponse>();
+ /**
+ * Returns the thread-local {@link HttpServletRequest}.
+ *
+ * @return an {@link HttpServletRequest} instance
+ */
public static HttpServletRequest getThreadLocalRequest() {
return perThreadRequest.get();
}
+ /**
+ * Returns the thread-local {@link HttpServletResponse}.
+ *
+ * @return an {@link HttpServletResponse} instance
+ */
public static HttpServletResponse getThreadLocalResponse() {
return perThreadResponse.get();
}
private final ExceptionHandler exceptionHandler;
+ /**
+ * Constructs a new {@link RequestFactoryServlet} with a
+ * {@code DefaultExceptionHandler}.
+ */
public RequestFactoryServlet() {
this(new DefaultExceptionHandler());
}
@@ -79,11 +93,21 @@
/**
* Use this constructor in subclasses to provide a custom
* {@link ExceptionHandler}.
+ *
+ * @param exceptionHandler an {@link ExceptionHandler} instance
*/
public RequestFactoryServlet(ExceptionHandler exceptionHandler) {
this.exceptionHandler = exceptionHandler;
}
+ /**
+ * Processes a POST to the server.
+ *
+ * @param request an {@link HttpServletRequest} instance
+ * @param response an {@link HttpServletResponse} instance
+ * @throws IOException if an internal I/O error occurs
+ * @throws ServletException if an error occurs in the servlet
+ */
@Override
protected void doPost(HttpServletRequest request, HttpServletResponse response)
throws IOException, ServletException {
diff --git a/user/src/com/google/gwt/requestfactory/server/RequestProcessingException.java b/user/src/com/google/gwt/requestfactory/server/RequestProcessingException.java
index 91485a2..e90b70c 100644
--- a/user/src/com/google/gwt/requestfactory/server/RequestProcessingException.java
+++ b/user/src/com/google/gwt/requestfactory/server/RequestProcessingException.java
@@ -24,9 +24,13 @@
private final Object response;
/**
+ * Constructs a new {@link RequestProcessingException} with a given message,
+ * Throwable cause, and response Object.
+ *
* @param message a message to display
- * @param t the cause
- * @param response a response, may be cast to T by a {@link RequestProcessor}<T>
+ * @param t the Throwable cause
+ * @param response a response Object, may be cast to T by a
+ * {@link RequestProcessor}<T>
*/
public RequestProcessingException(String message, Throwable t, Object response) {
super(message, t);
diff --git a/user/src/com/google/gwt/requestfactory/server/RequestProcessor.java b/user/src/com/google/gwt/requestfactory/server/RequestProcessor.java
index 93dd64e..42d53a1 100644
--- a/user/src/com/google/gwt/requestfactory/server/RequestProcessor.java
+++ b/user/src/com/google/gwt/requestfactory/server/RequestProcessor.java
@@ -24,6 +24,10 @@
public interface RequestProcessor<T> {
/**
* Decodes request, invokes methods, and re-encoded resulting return values.
+ *
+ * @param encodedRequest an encoded request of type T
+ * @return a decoded instance of type T
+ * @throws RequestProcessingException if an error occurs
*/
T decodeAndInvokeRequest(T encodedRequest) throws RequestProcessingException;
diff --git a/user/src/com/google/gwt/requestfactory/server/RequestProperty.java b/user/src/com/google/gwt/requestfactory/server/RequestProperty.java
index b1aeb0c..c2c1d6f 100644
--- a/user/src/com/google/gwt/requestfactory/server/RequestProperty.java
+++ b/user/src/com/google/gwt/requestfactory/server/RequestProperty.java
@@ -27,6 +27,9 @@
/**
* Merge two property chains.
+ *
+ * @param properties a list of {@link RequestProperty} instances
+ * @return a new {@link RequestProperty} instance
*/
public static RequestProperty coalesce(RequestProperty... properties) {
assert properties.length > 0;
@@ -43,6 +46,12 @@
return root;
}
+ /**
+ * Parse selectors to obtain a {@link RequestProperty}.
+ *
+ * @param selectors a String of selectors separated by commas
+ * @return a new {@link RequestProperty} instance
+ */
public static RequestProperty parse(String selectors) {
String parts[] = selectors.split("\\s*,\\s*");
RequestProperty props[] = new RequestProperty[parts.length];
@@ -61,6 +70,12 @@
this.propertyName = propertyName;
}
+ /**
+ * Add a property reference to this {@link RequestProperty}.
+ *
+ * @param propertyRef a {@link RequestProperty} instance
+ * @return this instance
+ */
public RequestProperty add(RequestProperty propertyRef) {
if (subProperties == null) {
subProperties = new HashMap<String, RequestProperty>();
@@ -69,23 +84,54 @@
return this;
}
+ /**
+ * Returns the value of a property defined as a sub-property of
+ * this instance.
+ *
+ * @param propName the property name as a String
+ * @return a {@link RequestProperty} instance or null
+ */
public RequestProperty getProperty(String propName) {
return subProperties == null ? null : subProperties.get(propName);
}
+ /**
+ * Returns the top-level property name associated with this instance.
+ *
+ * @return the property name as a String
+ */
public String getPropertyName() {
return propertyName;
}
+ /**
+ * Returns whether a given property is defined as a sub-property of this
+ * instance.
+ *
+ * @param name the property name as a String
+ * @return {@code} true if the property exists
+ */
public boolean hasProperty(String name) {
return subProperties == null ? false : subProperties.containsKey(name);
}
+ /**
+ * Returns an iterator over the properties of this instance.
+ *
+ * @return an Iterator over {@link RequestProperty} instances
+ */
public Iterator<RequestProperty> iterator() {
return subProperties == null ? emptyIterator()
: subProperties.values().iterator();
}
+ /**
+ * Merge a given property into this instance.
+ *
+ * @param property a {@link RequestProperty} instance
+ * @return the {@link RequestProperty} from this instance corresponding to the
+ * name of the given property, or {@code null}.
+ */
public RequestProperty mergeProperty(RequestProperty property) {
RequestProperty foundProp = getProperty(property.getPropertyName());
if (foundProp == null && !"".equals(property.getPropertyName())) {
diff --git a/user/src/com/google/gwt/requestfactory/server/RequestSecurityProvider.java b/user/src/com/google/gwt/requestfactory/server/RequestSecurityProvider.java
index 9a404af..55352b4 100644
--- a/user/src/com/google/gwt/requestfactory/server/RequestSecurityProvider.java
+++ b/user/src/com/google/gwt/requestfactory/server/RequestSecurityProvider.java
@@ -23,17 +23,28 @@
/**
* Throws exception if argument is not accessible via remote requests.
+ *
+ * @param clazz a Class instance
+ * @throws SecurityException if the argument is not accessible via remote
+ * requests
*/
void checkClass(Class<?> clazz) throws SecurityException;
/**
* Encode a Class type into a String token.
+ *
+ * @param type a Class instance
+ * @return an encoded String token
*/
String encodeClassType(Class<?> type);
/**
* Optionally decodes a previously encoded operation. Throws exception if
* argument is not a legal operation.
+ *
+ * @param operationName the operation name as a String
+ * @return a decoded operation name
+ * @throws SecurityException if the argument is not a legal operation
*/
String mapOperation(String operationName) throws SecurityException;
}
diff --git a/user/src/com/google/gwt/requestfactory/server/SampleDataPopulator.java b/user/src/com/google/gwt/requestfactory/server/SampleDataPopulator.java
index 2ffd72e..ec075c2 100644
--- a/user/src/com/google/gwt/requestfactory/server/SampleDataPopulator.java
+++ b/user/src/com/google/gwt/requestfactory/server/SampleDataPopulator.java
@@ -38,6 +38,11 @@
*/
public class SampleDataPopulator {
+ /**
+ * Run the sample data populator.
+ *
+ * @param args command-line arguments
+ */
public static void main(String args[]) {
// TODO: cleanup argument processing and error reporting.
if (args.length < 2) {
@@ -74,6 +79,12 @@
this.filePathName = filePathName;
}
+ /**
+ * Populate the datastore and port the resulting JSON file.
+ *
+ * @throws JSONException if the input contains bad JSON
+ * @throws IOException if an error occurs during file I/O
+ */
public void populate() throws JSONException, IOException {
JSONObject jsonObject = readAsJsonObject(readFileAsString(filePathName));
postJsonFile(jsonObject);
diff --git a/user/src/com/google/gwt/requestfactory/server/UserInformation.java b/user/src/com/google/gwt/requestfactory/server/UserInformation.java
index 472a088..27d4c4d 100644
--- a/user/src/com/google/gwt/requestfactory/server/UserInformation.java
+++ b/user/src/com/google/gwt/requestfactory/server/UserInformation.java
@@ -23,7 +23,17 @@
public abstract class UserInformation {
private static String userInformationImplClass = "";
-
+
+ /**
+ * Returns the current user information for a given redirect URL. If
+ * {@link #setUserInformationImplClass(String)} has been called with a class
+ * name, that class is used to gather the information by calling a (String)
+ * constructor. If the impl class name is "", or if the class cannont be
+ * instantiated, dummy user info is returned.
+ *
+ * @param redirectUrl the redirect URL as a String
+ * @return a {@link UserInformation} instance
+ */
public static UserInformation getCurrentUserInformation(String redirectUrl) {
UserInformation userInfo = null;
if (!"".equals(userInformationImplClass)) {
@@ -41,32 +51,100 @@
return userInfo;
}
+ /**
+ * Sets the implementation class to be used to gather user information
+ * in {@link #getCurrentUserInformation(String)}.
+ *
+ * @param clazz a class name
+ */
public static void setUserInformationImplClass(String clazz) {
userInformationImplClass = clazz;
}
+ /**
+ * The redirect URL as a String.
+ */
protected String redirectUrl = "";
private Integer version = 0;
+ /**
+ * Constructs a new {@link UserInformation} instance.
+ *
+ * @param redirectUrl the redirect URL as a String
+ */
public UserInformation(String redirectUrl) {
if (redirectUrl != null) {
this.redirectUrl = redirectUrl;
}
}
+ /**
+ * Returns the user's email address.
+ *
+ * @return the user's email address as a String
+ */
public abstract String getEmail();
+
+ /**
+ * Returns the user's id.
+ *
+ * @return the user's id as a Long
+ * @see #setId(Long)
+ */
public abstract Long getId();
+
+ /**
+ * Returns the user's login URL.
+ *
+ * @return the user's login URL as a String
+ */
public abstract String getLoginUrl();
+
+ /**
+ * Returns the user's logout URL.
+ *
+ * @return the user's logout URL as a String
+ */
public abstract String getLogoutUrl();
+
+ /**
+ * Returns the user's name.
+ *
+ * @return the user's name as a String
+ */
public abstract String getName();
+ /**
+ * Returns the version of this instance.
+ *
+ * @return an Integer version number
+ * @see #setVersion(Integer)
+ */
public Integer getVersion() {
return this.version;
}
+ /**
+ * Returns whether the user is logged in.
+ *
+ * @return {@code true} if the user is logged in
+ */
public abstract boolean isUserLoggedIn();
+
+ /**
+ * Sets the id for this user.
+ *
+ * @param id a String id
+ * @see #getId()
+ */
public abstract void setId(Long id);
+ /**
+ * Sets the version of this instance.
+ *
+ * @param version an Integer version number
+ * @see #getVersion()
+ */
public void setVersion(Integer version) {
this.version = version;
}
diff --git a/user/src/com/google/gwt/requestfactory/server/UserInformationSimpleImpl.java b/user/src/com/google/gwt/requestfactory/server/UserInformationSimpleImpl.java
index bd6e3ce..46ef176 100644
--- a/user/src/com/google/gwt/requestfactory/server/UserInformationSimpleImpl.java
+++ b/user/src/com/google/gwt/requestfactory/server/UserInformationSimpleImpl.java
@@ -23,6 +23,11 @@
private Long id = 0L;
+ /**
+ * Constructs an UserInformationSimpleImpl object.
+ *
+ * @param redirectUrl the redirect URL as a String
+ */
public UserInformationSimpleImpl(String redirectUrl) {
super(redirectUrl);
}
diff --git a/user/src/com/google/gwt/requestfactory/server/package.html b/user/src/com/google/gwt/requestfactory/server/package.html
index f650cc4..c698f61 100644
--- a/user/src/com/google/gwt/requestfactory/server/package.html
+++ b/user/src/com/google/gwt/requestfactory/server/package.html
@@ -3,7 +3,7 @@
Server side classes for mediating between the client side and the persistent datastore.
This package contains classes that can receive client side read and write requests in the JSON format, perform the necessary operations on the persistent datastore, and return the results in JSON format.
-<p><span style="color:red">Experimental API: All classes in this package are still under rapid development, and are very likely to be deleted or renamed. Use them at your own risk.
-</span></p>
+
+@since GWT 2.1
</body>
</html>
diff --git a/user/src/com/google/gwt/requestfactory/shared/EntityProxy.java b/user/src/com/google/gwt/requestfactory/shared/EntityProxy.java
index 64072ce..a4ca1ce 100644
--- a/user/src/com/google/gwt/requestfactory/shared/EntityProxy.java
+++ b/user/src/com/google/gwt/requestfactory/shared/EntityProxy.java
@@ -30,6 +30,8 @@
* Subtypes should override to declare they return a stable id of their own
* type, to allow type safe use of the request objects returned by
* {@link RequestFactory#find(EntityProxyId)}.
+ *
+ * @return an {@link EntityProxyId} instance
*/
EntityProxyId<?> stableId();
}
diff --git a/user/src/com/google/gwt/requestfactory/shared/EntityProxyChange.java b/user/src/com/google/gwt/requestfactory/shared/EntityProxyChange.java
index 3b7abde..1c59370 100644
--- a/user/src/com/google/gwt/requestfactory/shared/EntityProxyChange.java
+++ b/user/src/com/google/gwt/requestfactory/shared/EntityProxyChange.java
@@ -38,9 +38,15 @@
/**
* Implemented by methods that handle EntityProxyChange events.
+ *
* @param <P> the proxy type
*/
public interface Handler<P extends EntityProxy> extends EventHandler {
+ /**
+ * Called when an {@link EntityProxyChange} event is fired.
+ *
+ * @param event an {@link EntityProxyChange} instance
+ */
void onProxyChange(EntityProxyChange<P> event);
}
@@ -49,6 +55,11 @@
/**
* Register a handler for a EntityProxyChange events for a particular proxy
* class.
+ *
+ * @param eventBus the {@link EventBus}
+ * @param proxyType a Class instance of type P
+ * @param handler an {@link EntityProxyChange.Handler} instance of type P
+ * @return an {@link EntityProxy} instance
*/
public static <P extends EntityProxy> HandlerRegistration registerForProxyType(
EventBus eventBus, Class<P> proxyType,
@@ -60,11 +71,22 @@
private WriteOperation writeOperation;
+ /**
+ * Constructs an EntityProxyChange object.
+ *
+ * @param proxy an {@link EntityProxy} instance of type P
+ * @param writeOperation a {@link WriteOperation} instance
+ */
public EntityProxyChange(P proxy, WriteOperation writeOperation) {
this.proxy = proxy;
this.writeOperation = writeOperation;
}
+ /**
+ * Returns the type associated with this instance.
+ *
+ * @return an instance of {@link GwtEvent.Type} of type Handler<P>
+ */
@SuppressWarnings({"unchecked", "rawtypes"})
@Override
public GwtEvent.Type<Handler<P>> getAssociatedType() {
@@ -79,12 +101,19 @@
/**
* Returns an unpopulated copy of the changed proxy — all properties are
* undefined except its id.
+ *
+ * @return an instance of {@link EntityProxyId}<P>
*/
@SuppressWarnings("unchecked")
public EntityProxyId<P> getProxyId() {
return (EntityProxyId<P>) proxy.stableId();
}
+ /**
+ * Returns the {@link WriteOperation} associated with this instance.
+ *
+ * @return a {@link WriteOperation} instance
+ */
public WriteOperation getWriteOperation() {
return writeOperation;
}
diff --git a/user/src/com/google/gwt/requestfactory/shared/EntityProxyId.java b/user/src/com/google/gwt/requestfactory/shared/EntityProxyId.java
index 68a319e..af81fa7 100644
--- a/user/src/com/google/gwt/requestfactory/shared/EntityProxyId.java
+++ b/user/src/com/google/gwt/requestfactory/shared/EntityProxyId.java
@@ -28,6 +28,8 @@
/**
* Returns the class of the proxy identified.
+ *
+ * @return a Class object of type P
*/
Class<P> getProxyClass();
}
diff --git a/user/src/com/google/gwt/requestfactory/shared/InstanceRequest.java b/user/src/com/google/gwt/requestfactory/shared/InstanceRequest.java
index ea3f567..b52a001 100644
--- a/user/src/com/google/gwt/requestfactory/shared/InstanceRequest.java
+++ b/user/src/com/google/gwt/requestfactory/shared/InstanceRequest.java
@@ -24,8 +24,12 @@
* @param <T> the type eventually returned by the method invocation
*/
public interface InstanceRequest<P extends EntityProxy, T> {
+
/**
* Provide the instance on which the request will be invoked.
+ *
+ * @param instanceObject an {@link EntityProxy} instance of type P
+ * @return an instance of {@link Request}<T>
*/
Request<T> using(P instanceObject);
}
diff --git a/user/src/com/google/gwt/requestfactory/shared/LoggingRequest.java b/user/src/com/google/gwt/requestfactory/shared/LoggingRequest.java
index 3f36ce8..53d7802 100644
--- a/user/src/com/google/gwt/requestfactory/shared/LoggingRequest.java
+++ b/user/src/com/google/gwt/requestfactory/shared/LoggingRequest.java
@@ -29,6 +29,9 @@
// serialized string.
/**
* Log a message on the server.
+ *
+ * @param serializedLogRecordString a String
+ * @return a Void {@link Request}
*/
Request<Void> logMessage(String serializedLogRecordString);
}
diff --git a/user/src/com/google/gwt/requestfactory/shared/Receiver.java b/user/src/com/google/gwt/requestfactory/shared/Receiver.java
index 4f28289..33fabe2 100644
--- a/user/src/com/google/gwt/requestfactory/shared/Receiver.java
+++ b/user/src/com/google/gwt/requestfactory/shared/Receiver.java
@@ -26,6 +26,8 @@
/**
* Receives general failure notifications. The default implementation throws a
* RuntimeException with the provided error message.
+ *
+ * @param error a {@link ServerFailure} instance
*/
public void onFailure(ServerFailure error) {
throw new RuntimeException(error.getMessage());
@@ -33,6 +35,8 @@
/**
* Called when a Request has been successfully executed on the server.
+ *
+ * @param response a response of type V
*/
public abstract void onSuccess(V response);
@@ -40,6 +44,8 @@
* Called if an object sent to the server could not be validated. The default
* implementation calls {@link #onFailure(ServerFailure)} if <code>errors
* </code> is not empty.
+ *
+ * @param errors a Set of {@link Violation} instances
*/
public void onViolation(Set<Violation> errors) {
if (!errors.isEmpty()) {
diff --git a/user/src/com/google/gwt/requestfactory/shared/Request.java b/user/src/com/google/gwt/requestfactory/shared/Request.java
index 4ca7a23..d8190d0 100644
--- a/user/src/com/google/gwt/requestfactory/shared/Request.java
+++ b/user/src/com/google/gwt/requestfactory/shared/Request.java
@@ -30,16 +30,24 @@
/**
* Convenience method equivalent to calling <code>to(...).fire()</code>.
+ *
+ * @param receiver a {@link Receiver} instance
*/
void fire(Receiver<? super T> receiver);
/**
* 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);
}
diff --git a/user/src/com/google/gwt/requestfactory/shared/RequestContext.java b/user/src/com/google/gwt/requestfactory/shared/RequestContext.java
index 78279e1..495d252 100644
--- a/user/src/com/google/gwt/requestfactory/shared/RequestContext.java
+++ b/user/src/com/google/gwt/requestfactory/shared/RequestContext.java
@@ -23,6 +23,9 @@
* Returns a new mutable proxy that this request can carry to the server,
* perhaps to be persisted. If a persist does happen, a CREATE event will be
* posted including the EntityProxyId of this proxy.
+ *
+ * @param clazz a Class object of type T
+ * @return an {@link EntityProxy} instance of type T
*/
<T extends EntityProxy> T create(Class<T> clazz);
@@ -30,6 +33,9 @@
* 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} instance of type T
*/
<T extends EntityProxy> T edit(T object);
@@ -45,7 +51,8 @@
/**
* For receiving errors or validation failures only.
- *
+ *
+ * @param receiver a {@link Receiver} instance
* @throws IllegalArgumentException if <code>receiver</code> is
* <code>null</code>
*/
@@ -64,6 +71,8 @@
* bar.setName(name);
* assertFalse(context.isChanged());
* </pre>
+ *
+ * @return {@code true} if any changes have been made
*/
boolean isChanged();
}
diff --git a/user/src/com/google/gwt/requestfactory/shared/RequestEvent.java b/user/src/com/google/gwt/requestfactory/shared/RequestEvent.java
index cd9faf3..c08641d 100644
--- a/user/src/com/google/gwt/requestfactory/shared/RequestEvent.java
+++ b/user/src/com/google/gwt/requestfactory/shared/RequestEvent.java
@@ -30,6 +30,11 @@
* Implemented by handlers of this type of event.
*/
public interface Handler extends EventHandler {
+ /**
+ * Called when a {@link RequestEvent} is fired.
+ *
+ * @param requestEvent a {@link RequestEvent} instance
+ */
void onRequestEvent(RequestEvent requestEvent);
}
@@ -42,6 +47,13 @@
private static final Type<Handler> TYPE = new Type<Handler>();
+ /**
+ * Register a {@link RequestEvent.Handler} on an {@link EventBus}.
+ *
+ * @param eventBus the {@link EventBus}
+ * @param handler a {@link RequestEvent.Handler}
+ * @return a {@link HandlerRegistration} instance
+ */
public static HandlerRegistration register(EventBus eventBus,
RequestEvent.Handler handler) {
return eventBus.addHandler(TYPE, handler);
@@ -55,6 +67,12 @@
*/
private final Response response;
+ /**
+ * Constructs a new @{link RequestEvent}.
+ *
+ * @param state a {@link State} instance
+ * @param response a {@link Response} instance
+ */
public RequestEvent(State state, Response response) {
this.state = state;
this.response = response;
@@ -65,10 +83,20 @@
return TYPE;
}
+ /**
+ * Returns the {@link Response} associated with this event.
+ *
+ * @return a {@link Response} instance
+ */
public Response getResponse() {
return response;
}
+ /**
+ * Returns the {@link State} associated with this event.
+ *
+ * @return a {@link State} instance
+ */
public State getState() {
return state;
}
diff --git a/user/src/com/google/gwt/requestfactory/shared/RequestFactory.java b/user/src/com/google/gwt/requestfactory/shared/RequestFactory.java
index dc88565..0fb276e 100644
--- a/user/src/com/google/gwt/requestfactory/shared/RequestFactory.java
+++ b/user/src/com/google/gwt/requestfactory/shared/RequestFactory.java
@@ -19,45 +19,26 @@
/**
* Marker interface for the RequestFactory code generator.
- * <p>
- * A RequestFactory implementation will post {@link EntityProxyChange} events to
- * the {@link EventBus} passed into the {@link #initialize} method. The events
- * will have the following {@link WriteOperation} associated with them in the
- * following circumstances:
- * <ul>
- * <li>{@link WriteOperation#PERSIST} when an {@link EntityProxy}
- * {@link RequestContext#create(Class) created} on the client is successfully
- * persisted in the server's backing store.</li>
- * <li>{@link WriteOperation#UPDATE} when changes due to an {@link EntityProxy}
- * being {@link RequestContext#edit(EntityProxy) edited} on the client are
- * successfully persisted in the server's backing store.</li>
- * <li>{@link WriteOperation#UPDATE} when a previously-unseen
- * {@link EntityProxy} is reachable from the return value for a
- * successfully-executed {@link Request}.</li>
- * <li>{@link WriteOperation#UPDATE} when any property of an {@link EntityProxy}
- * reachable from a {@link Request Request's} arguments is seen to have changed
- * after executing the service method on the server.</li>
- * <li>{@link WriteOperation#DELETE} when an {@link EntityProxy} reachable from
- * a {@link Request Request's} arguments becomes irretrievable after executing
- * the service method on the server.</li>
- * </ul>
- * <p>
- * Other types of events may be posted to the {@link EventBus} by other services
- * used by the RequestFactory.
- *
- * @see {@link com.google.gwt.requestfactory.client.DefaultRequestTransport}
*/
public interface RequestFactory {
+ /**
+ * The JSON content type String.
+ */
String JSON_CONTENT_TYPE_UTF8 = "application/json; charset=utf-8";
/**
* 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);
/**
- * Returns the eventbus this factory's events are posted on, which was set via
+ * Returns the event bus this factory's events are posted on, which was set via
* {@link #initialize}.
+ *
+ * @return the {@link EventBus} associated with this instance
*/
EventBus getEventBus();
@@ -66,6 +47,7 @@
* represents the given class. It can be processed by
* {@link #getProxyClass(String)}
*
+ * @param clazz a Class object for an {@link EntityProxy} subclass
* @return a {@link com.google.gwt.user.client.History} compatible token
*/
String getHistoryToken(Class<? extends EntityProxy> clazz);
@@ -84,6 +66,7 @@
* as-yet-unpersisted EntityProxy is only valid for the duration of the
* RequestFactory's lifespan.
*
+ * @param proxy an {@link EntityProxyId} instance
* @return a {@link com.google.gwt.user.client.History} compatible token
*/
String getHistoryToken(EntityProxyId<?> proxy);
@@ -93,23 +76,34 @@
* type of this token, via {@link RequestContext#create}. The token may
* represent either a proxy instance (see {@link #getHistoryToken}) or a proxy
* class (see {@link #getProxyClass}).
+ *
+ * @param historyToken a String token
+ * @return a Class object for an {@link EntityProxy} subclass
*/
Class<? extends EntityProxy> getProxyClass(String historyToken);
/**
* Return the appropriate {@link EntityProxyId} using a string returned from
* {@link #getHistoryToken(EntityProxyId)}.
+ *
+ * @param historyToken a String token
+ * @return an {@link EntityProxyId}
*/
<T extends EntityProxy> EntityProxyId<T> getProxyId(String historyToken);
/**
* Start this request factory with a
* {@link com.google.gwt.requestfactory.client.DefaultRequestTransport}.
+ *
+ * @param eventBus an {@link EventBus}
*/
void initialize(EventBus eventBus);
/**
* Start this request factory with a user-provided transport.
+ *
+ * @param eventBus an {@link EventBus}
+ * @param transport aÊ{@link RequestTransport} instance
*/
void initialize(EventBus eventBus, RequestTransport transport);
}
diff --git a/user/src/com/google/gwt/requestfactory/shared/RequestTransport.java b/user/src/com/google/gwt/requestfactory/shared/RequestTransport.java
index 8cbf318..3e30f4f 100644
--- a/user/src/com/google/gwt/requestfactory/shared/RequestTransport.java
+++ b/user/src/com/google/gwt/requestfactory/shared/RequestTransport.java
@@ -26,13 +26,26 @@
* A callback interface.
*/
public interface TransportReceiver {
+ /**
+ * Called when the transmission succeeds.
+ *
+ * @param payload the String payload
+ */
void onTransportSuccess(String payload);
+ /**
+ * Called when the transmission fails.
+ *
+ * @param message the String error message
+ */
void onTransportFailure(String message);
}
/**
* Called by the RequestFactory implementation.
+ *
+ * @param payload the String payload
+ * @param receiver a {@link TransportReceiver} instance
*/
void send(String payload, TransportReceiver receiver);
}
diff --git a/user/src/com/google/gwt/requestfactory/shared/ServerFailure.java b/user/src/com/google/gwt/requestfactory/shared/ServerFailure.java
index 3175f30..d57bf53 100644
--- a/user/src/com/google/gwt/requestfactory/shared/ServerFailure.java
+++ b/user/src/com/google/gwt/requestfactory/shared/ServerFailure.java
@@ -30,6 +30,13 @@
this(null, null, null);
}
+ /**
+ * Constructs a ServerFailure object.
+ *
+ * @param message a String containing the failure message
+ * @param exceptionType a String containing the exception type
+ * @param stackTraceString a String containing the stack trace
+ */
public ServerFailure(String message, String exceptionType,
String stackTraceString) {
this.message = message;
@@ -37,14 +44,29 @@
this.stackTraceString = stackTraceString;
}
+ /**
+ * Returns the exception type.
+ *
+ * @return the exception type as a String
+ */
public String getExceptionType() {
return exceptionType;
}
+ /**
+ * Returns the failure message.
+ *
+ * @return the message as a String
+ */
public String getMessage() {
return message;
}
+ /**
+ * Returns the failure stack trace.
+ *
+ * @return the stack trace as a String
+ */
public String getStackTraceString() {
return stackTraceString;
}
diff --git a/user/src/com/google/gwt/requestfactory/shared/UserInformationProxy.java b/user/src/com/google/gwt/requestfactory/shared/UserInformationProxy.java
index 90fe1808..0dd84a0 100644
--- a/user/src/com/google/gwt/requestfactory/shared/UserInformationProxy.java
+++ b/user/src/com/google/gwt/requestfactory/shared/UserInformationProxy.java
@@ -23,9 +23,31 @@
*/
@ProxyFor(UserInformation.class)
public interface UserInformationProxy extends EntityProxy {
+ /**
+ * Returns the user's email address.
+ *
+ * @return the user's email address as a String
+ */
String getEmail();
+
+ /**
+ * Returns the user's login url.
+ *
+ * @return the user's login url as a String
+ */
String getLoginUrl();
+
+ /**
+ * Returns the user's logout url.
+ *
+ * @return the user's logout url as a String
+ */
String getLogoutUrl();
+
+ /**
+ * Returns the user's name.
+ *
+ * @return the user's name as a String
+ */
String getName();
-
}
diff --git a/user/src/com/google/gwt/requestfactory/shared/UserInformationRequest.java b/user/src/com/google/gwt/requestfactory/shared/UserInformationRequest.java
index 4e9e313..463cb36 100644
--- a/user/src/com/google/gwt/requestfactory/shared/UserInformationRequest.java
+++ b/user/src/com/google/gwt/requestfactory/shared/UserInformationRequest.java
@@ -25,5 +25,11 @@
@Service(UserInformation.class)
public interface UserInformationRequest extends RequestContext {
+ /**
+ * Returns the current user information given a redirect URL.
+ *
+ * @param redirectUrl the redirect UR as a String
+ * @return an instance of {@link Request}<{@link UserInformationProxy}>
+ */
Request<UserInformationProxy> getCurrentUserInformation(String redirectUrl);
}
diff --git a/user/src/com/google/gwt/requestfactory/shared/ValueCodex.java b/user/src/com/google/gwt/requestfactory/shared/ValueCodex.java
index 2097caa..1763759 100644
--- a/user/src/com/google/gwt/requestfactory/shared/ValueCodex.java
+++ b/user/src/com/google/gwt/requestfactory/shared/ValueCodex.java
@@ -166,6 +166,9 @@
/**
* Returns true if ValueCodex can operate on values of the given type.
+ *
+ * @param clazz a Class object
+ * @return {@code true} if the given object type can be decoded
*/
public static boolean canDecode(Class<?> clazz) {
return typesByClass.containsKey(clazz);
diff --git a/user/src/com/google/gwt/requestfactory/shared/Violation.java b/user/src/com/google/gwt/requestfactory/shared/Violation.java
index 2119c24..c4ddb96 100644
--- a/user/src/com/google/gwt/requestfactory/shared/Violation.java
+++ b/user/src/com/google/gwt/requestfactory/shared/Violation.java
@@ -20,9 +20,24 @@
* {@link javax.validation.ConstraintViolation}.
*/
public interface Violation {
+ /**
+ * Returns the message associated with this {@link Violation}.
+ *
+ * @return a String message
+ */
String getMessage();
+ /**
+ * Returns the path associated with this {@link Violation}.
+ *
+ * @return a String path
+ */
String getPath();
+ /**
+ * Returns the proxy id associated with this {@link Violation}.
+ *
+ * @return an {@link EntityProxyId} instance
+ */
EntityProxyId<?> getProxyId();
}
diff --git a/user/src/com/google/gwt/requestfactory/shared/WriteOperation.java b/user/src/com/google/gwt/requestfactory/shared/WriteOperation.java
index 34ff6fb..b1fa575 100644
--- a/user/src/com/google/gwt/requestfactory/shared/WriteOperation.java
+++ b/user/src/com/google/gwt/requestfactory/shared/WriteOperation.java
@@ -40,6 +40,12 @@
this.unObfuscatedEnumName = unObfuscatedEnumName;
}
+ /**
+ * Returns the unobfuscated name of the event associated with this
+ * {@link WriteOperation}.
+ *
+ * @return one of "PERSIST", "UPDATE", or "DELETE"
+ */
public String getUnObfuscatedEnumName() {
return this.unObfuscatedEnumName;
}
diff --git a/user/src/com/google/gwt/requestfactory/shared/package.html b/user/src/com/google/gwt/requestfactory/shared/package.html
index a846a3f..2b14e49 100644
--- a/user/src/com/google/gwt/requestfactory/shared/package.html
+++ b/user/src/com/google/gwt/requestfactory/shared/package.html
@@ -1,7 +1,7 @@
<html>
<body>
Shared classes used on both the client and the server side for transmitting data between the sever and the client in JSON format.
-<p><span style="color:red">Experimental API: All classes in this package are still under rapid development, and are very likely to be deleted or renamed. Use them at your own risk.
-</span></p>
+
+@since GWT 2.1
</body>
</html>
diff --git a/user/src/com/google/gwt/requestfactory/ui/client/EntityProxyKeyProvider.java b/user/src/com/google/gwt/requestfactory/ui/client/EntityProxyKeyProvider.java
index 669cb29..84d715f 100644
--- a/user/src/com/google/gwt/requestfactory/ui/client/EntityProxyKeyProvider.java
+++ b/user/src/com/google/gwt/requestfactory/ui/client/EntityProxyKeyProvider.java
@@ -31,6 +31,11 @@
*/
public class EntityProxyKeyProvider<P extends EntityProxy> implements
ProvidesKey<P> {
+ /**
+ * Returns the key Object for the given item.
+ *
+ * @param item an item of type P
+ */
public Object getKey(P item) {
return item == null ? null : item.stableId();
}
diff --git a/user/src/com/google/gwt/requestfactory/ui/client/LoginWidget.java b/user/src/com/google/gwt/requestfactory/ui/client/LoginWidget.java
index f78b5e31..0362693 100644
--- a/user/src/com/google/gwt/requestfactory/ui/client/LoginWidget.java
+++ b/user/src/com/google/gwt/requestfactory/ui/client/LoginWidget.java
@@ -41,6 +41,11 @@
initWidget(BINDER.createAndBindUi(this));
}
+ /**
+ * Sets the user information using a {@link UserInformationProxy}.
+ *
+ * @param info a {@link UserInformationProxy} instance
+ */
public void setUserInformation(UserInformationProxy info) {
name.setInnerText(info.getName());
logoutUrl = info.getLogoutUrl();
diff --git a/user/src/com/google/gwt/requestfactory/ui/client/ProxyRenderer.java b/user/src/com/google/gwt/requestfactory/ui/client/ProxyRenderer.java
index 375d839..2ddf49c 100644
--- a/user/src/com/google/gwt/requestfactory/ui/client/ProxyRenderer.java
+++ b/user/src/com/google/gwt/requestfactory/ui/client/ProxyRenderer.java
@@ -28,12 +28,19 @@
private final String[] paths;
- public ProxyRenderer(String[] strings) {
- this.paths = strings;
+ /**
+ * Constructs a {@link ProxyRenderer} with a given set of paths.
+ *
+ * @param paths an Array of Strings
+ */
+ public ProxyRenderer(String[] paths) {
+ this.paths = paths;
}
/**
* The properties required by this renderer.
+ *
+ * @return an Array of String paths
*/
public String[] getPaths() {
return paths;
