// Path: kraken_lib/src/main/java/com/github/marcosalis/kraken/utils/http/HttpRequestsManager.java
// @Beta
// public interface HttpRequestsManager {
// 
//     /**
//      * Returns the default request factory from which you can execute HTTP requests. Base settings,
//      * such as timeouts and user agent, are already set for you within each {@link HttpRequest}
//      * created.
//      */
//     public HttpRequestFactory getRequestFactory();
// 
//     /**
//      * Returns a new request factory which uses the passed {@link HttpTransport} and whose generated
//      * {@link HttpRequest}s are initialised with default parameters.
//      *
//      * @param transport The HttpTransport to be used for this factory
//      * @return The created {@link HttpRequestFactory}
//      */
//     public HttpRequestFactory createRequestFactory(@NonNull HttpTransport transport);
// 
//     /**
//      * Shortcut method for the {@link HttpRequest} builder. See {@link
//      * HttpRequestFactory#buildRequest(String, GenericUrl, HttpContent)}.
//      *
//      * @param method    HTTP request method string as per {@link HttpMethods}
//      * @param urlString HTTP request url String
//      * @param content   HTTP request content or null
//      * @return The built HttpRequest
//      * @throws IOException              If an exception occurred while building the request
//      * @throws IllegalArgumentException If the passed url has a syntax error
//      */
//     public HttpRequest buildRequest(@NonNull String method, @NonNull String urlString,
//                                     @Nullable HttpContent content) throws IOException;
// 
// }


import android.support.annotation.NonNull;
import android.support.annotation.Nullable;
import com.github.marcosalis.kraken.utils.http.HttpRequestsManager;
import com.google.common.annotations.Beta;
import java.util.concurrent.Callable;
/*
 * Copyright 2013 Marco Salis - fast3r(at)gmail.com
 *
 * 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.github.marcosalis.kraken.cache.requests;




/**
 * Interface for an HTTP request which returns a cacheable item and can be used to compute its cache
 * key. It implements {@link Callable} so that in can be directly executed in an executor without
 * wrapping it.
 *
 * Support for use in caches: a content can be stored in a cache map by using an hashed
 * representation of its URL (or other suitable cache key) by calling {@link #hash()}.
 *
 * <b>Thread-safety:</b> Implementations must be thread-safe.
 *
 * @param <E> The response object type that this request will be returning.
 * @author Marco Salis
 * @since 1.0
 */
@Beta
public interface CacheableRequest<E> extends Callable<E> {

    /**
     * Returns the request's URL. Override this in subclasses if the request URL cannot be generated
     * at object instantiation.
     */
    @Nullable
    public abstract String getRequestUrl();

    /**
     * Synchronously executes the request.
     *
     * @return The response object if it can be retrieved or null
     * @throws Exception If something went wrong
     */
    @Nullable
    public abstract E execute() throws Exception;

    /**
     * Synchronously executes the request using the passed {@link HttpRequestsManager}
     *
     * @see {@link #execute()}
     */
    @Nullable
// Path: kraken_lib/src/main/java/com/github/marcosalis/kraken/utils/http/HttpRequestsManager.java
// @Beta
// public interface HttpRequestsManager {
// 
//     /**
//      * Returns the default request factory from which you can execute HTTP requests. Base settings,
//      * such as timeouts and user agent, are already set for you within each {@link HttpRequest}
//      * created.
//      */
//     public HttpRequestFactory getRequestFactory();
// 
//     /**
//      * Returns a new request factory which uses the passed {@link HttpTransport} and whose generated
//      * {@link HttpRequest}s are initialised with default parameters.
//      *
//      * @param transport The HttpTransport to be used for this factory
//      * @return The created {@link HttpRequestFactory}
//      */
//     public HttpRequestFactory createRequestFactory(@NonNull HttpTransport transport);
// 
//     /**
//      * Shortcut method for the {@link HttpRequest} builder. See {@link
//      * HttpRequestFactory#buildRequest(String, GenericUrl, HttpContent)}.
//      *
//      * @param method    HTTP request method string as per {@link HttpMethods}
//      * @param urlString HTTP request url String
//      * @param content   HTTP request content or null
//      * @return The built HttpRequest
//      * @throws IOException              If an exception occurred while building the request
//      * @throws IllegalArgumentException If the passed url has a syntax error
//      */
//     public HttpRequest buildRequest(@NonNull String method, @NonNull String urlString,
//                                     @Nullable HttpContent content) throws IOException;
// 
// }


// Path: kraken_lib/src/main/java/com/github/marcosalis/kraken/cache/requests/CacheableRequest.java
import android.support.annotation.NonNull;
import android.support.annotation.Nullable;
import com.github.marcosalis.kraken.utils.http.HttpRequestsManager;
import com.google.common.annotations.Beta;
import java.util.concurrent.Callable;

/*
 * Copyright 2013 Marco Salis - fast3r(at)gmail.com
 *
 * 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.github.marcosalis.kraken.cache.requests;




/**
 * Interface for an HTTP request which returns a cacheable item and can be used to compute its cache
 * key. It implements {@link Callable} so that in can be directly executed in an executor without
 * wrapping it.
 *
 * Support for use in caches: a content can be stored in a cache map by using an hashed
 * representation of its URL (or other suitable cache key) by calling {@link #hash()}.
 *
 * <b>Thread-safety:</b> Implementations must be thread-safe.
 *
 * @param <E> The response object type that this request will be returning.
 * @author Marco Salis
 * @since 1.0
 */
@Beta
public interface CacheableRequest<E> extends Callable<E> {

    /**
     * Returns the request's URL. Override this in subclasses if the request URL cannot be generated
     * at object instantiation.
     */
    @Nullable
    public abstract String getRequestUrl();

    /**
     * Synchronously executes the request.
     *
     * @return The response object if it can be retrieved or null
     * @throws Exception If something went wrong
     */
    @Nullable
    public abstract E execute() throws Exception;

    /**
     * Synchronously executes the request using the passed {@link HttpRequestsManager}
     *
     * @see {@link #execute()}
     */
    @Nullable
    public abstract E execute(@NonNull HttpRequestsManager connManager) throws Exception;