A PushBuilder can be customised by chained calls to mutator methods before the
* {@link #push()} method is called to initiate a push request with the current state
* of the builder. After the call to {@link #push()}, the builder may be reused for
* another push, however the {@link #path(String)}, {@link #etag(String)} and
* {@link #lastModified(String)} values will have been nulled. All other
* values are retained over calls to {@link #push()}.
*/
public interface PushBuilder
{
/** Set the method to be used for the push.
* Defaults to GET.
* @param method the method to be used for the push.
* @return this builder.
*/
public abstract PushBuilder method(String method);
/** Set the query string to be used for the push.
* Defaults to the requests query string.
* Will be appended to any query String included in a call to {@link #path(String)}. This
* method should be used instead of a query in {@link #path(String)} when multiple
* {@link #push()} calls are to be made with the same query string, or to remove a
* query string obtained from the associated request.
* @param queryString the query string to be used for the push.
* @return this builder.
*/
public abstract PushBuilder queryString(String queryString);
/** Set the SessionID to be used for the push.
* The session ID will be set in the same way it was on the associated request (ie
* as a cookie if the associated request used a cookie, or as a url parameter if
* the associated request used a url parameter).
* Defaults to the requested session ID or any newly assigned session id from
* a newly created session.
* @param sessionId the SessionID to be used for the push.
* @return this builder.
*/
public abstract PushBuilder sessionId(String sessionId);
/** Set if the request is to be conditional.
* If the request is conditional, any available values from {@link #etag(String)} or
* {@link #lastModified(String)} will be set in the appropriate headers. If the request
* is not conditional, then etag and lastModified values are ignored.
* Defaults to true if the associated request was conditional.
* @param conditional true if the push request is conditional
* @return this builder.
*/
public abstract PushBuilder conditional(boolean conditional);
/** Set a header to be used for the push.
* @param name The header name to set
* @param value The header value to set
* @return this builder.
*/
public abstract PushBuilder setHeader(String name, String value);
/** Add a header to be used for the push.
* @param name The header name to add
* @param value The header value to add
* @return this builder.
*/
public abstract PushBuilder addHeader(String name, String value);
/** Set the URI path to be used for the push.
* The path may start with "/" in which case it is treated as an
* absolute path, otherwise it is relative to the context path of
* the associated request.
* There is no path default and {@link #path(String)} must be called
* before every call to {@link #push()}
* @param the URI path to be used for the push, which may include a
* query string.
* @return this builder.
*/
public abstract PushBuilder path(String path);
/** Set the etag to be used for conditional pushes.
* The etag will be used only if {@link #isConditional()} is true.
* Defaults to no etag. The value is nulled after every call to
* {@link #push()}
* @param the etag to be used for the push.
* @return this builder.
*/
public abstract PushBuilder etag(String etag);
/** Set the last modified date to be used for conditional pushes.
* The last modified date will be used only if {@link #isConditional()} is true.
* Defaults to no date. The value is nulled after every call to
* {@link #push()}
* @param the last modified date to be used for the push.
* @return this builder.
* */
public abstract PushBuilder lastModified(String lastModified);
/** Push a resource.
* Push a resource based on the current state of the PushBuilder. If {@link #isConditional()}
* is true and an etag or lastModified value is provided, then an appropriate conditional header
* will be generated. If both an etag and lastModified value are provided only an If-None-Match header
* will be generated. If the builder has a session ID, then the pushed request
* will include the session ID either as a Cookie or as a URI parameter as appropriate. The builders
* query string is merged with any passed query string.
* After initiating the push, the builder has its path, etag and lastModified fields nulled. All
* other fields are left as is for possible reuse in another push.
* @throws IllegalArgumentException if the method set expects a request body (eg POST)
*/
public abstract void push();
public abstract String getMethod();
public abstract String getQueryString();
public abstract String getSessionId();
public abstract boolean isConditional();
public abstract Set