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}