001package co.codewizards.cloudstore.rest.client.request; 002 003import co.codewizards.cloudstore.rest.client.CloudStoreRestClient; 004 005/** 006 * REST request sending data to / querying data from / invoking logic on the server. 007 * <p> 008 * Every REST request should be a separate class implementing this interface. It should be instantiated for 009 * an individual invocation, parameterised (usually directly via the constructor) and passed to 010 * {@link CloudStoreRestClient#execute(Request)}. 011 * <p> 012 * Objects of this type are therefore short-lived: They normally are only used for one single invocation and 013 * forgotten afterwards. In most cases, anonymous instances are directly passed to the 014 * {@code CloudStoreRestClient.execute(...)} method as shown in this example: 015 * <p> 016 * <pre>return getCloudStoreRestClient().execute(new DoThisAndThatOnServer(param1, param2));</pre> 017 * <p> 018 * Implementations of this interface are <i>not</i> thread-safe. 019 * <p> 020 * <b>Important:</b> Please do <i>not</i> directly implement this interface! If the REST request queries a 021 * response from the server, it is recommended to sub-class {@link AbstractRequest}. If there is no response, 022 * implementors should sub-class {@link VoidRequest} instead. 023 * 024 * @author Marco หงุ่ยตระกูล-Schulze - marco at codewizards dot co 025 * 026 * @param <R> the response type, i.e. the type of the object sent from the server back to the client. 027 */ 028public interface Request<R> { 029 030 /** 031 * Gets the {@code CloudStoreRestClient}. 032 * <p> 033 * {@link CloudStoreRestClient#execute(Request)} assigns this property, before invoking 034 * {@link #execute()}. After the invocation, this property is cleared, again. 035 * @return the {@code CloudStoreRestClient}. Never <code>null</code> during 036 * {@linkplain #execute() execution} (but otherwise it normally is <code>null</code>). 037 * @see #setCloudStoreRestClient(CloudStoreRestClient) 038 */ 039 CloudStoreRestClient getCloudStoreRestClient(); 040 041 /** 042 * Sets the {@code CloudStoreRestClient}. 043 * @param cloudStoreRestClient the {@code CloudStoreRestClient}. May be <code>null</code>. 044 * @see #getCloudStoreRestClient() 045 */ 046 void setCloudStoreRestClient(CloudStoreRestClient cloudStoreRestClient); 047 048 /** 049 * Execute the actual request. 050 * <p> 051 * <b>Important:</b> You should never invoke this method directly! Instead, pass the {@code Request} to 052 * {@link CloudStoreRestClient#execute(Request)}. 053 * @return the response from the server. May be <code>null</code>. Depending on 054 * {@link #isResultNullable()} a <code>null</code> result is considered an error and causes an exception. 055 */ 056 R execute(); 057 058 /** 059 * Indicates, if the result of the invocation can be <code>null</code>. 060 * <p> 061 * If the server <i>must</i> send a response, i.e. the invocation must not return empty-handed, this 062 * should be <code>false</code>. In case, the server still does not send a reply, it is considered an 063 * error causing an exception. 064 * <p> 065 * Please note: If a request <i>never</i> returns a response (like a Java void method), it is recommended 066 * that you sub-class {@link VoidRequest}. 067 * @return <code>true</code> if <code>null</code> as response is allowed; <code>false</code> otherwise. 068 */ 069 boolean isResultNullable(); 070 071}