/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You 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.
 */

#ifndef _DECAF_NET_URLCONNECTION_H_
#define _DECAF_NET_URLCONNECTION_H_

#include <decaf/util/Config.h>

#include <decaf/io/InputStream.h>
#include <decaf/io/OutputStream.h>
#include <decaf/net/URL.h>
#include <decaf/net/UnknownServiceException.h>

namespace decaf {
namespace net {

    class URLConnectionImpl;

    /**
     * Concrete implementations of the abstract {@code URLConnection} class provide
     * a communication link to a URL for exchanging data with a specific protocol
     * type. A {@code URLConnection} can only be set up after the instantiation but
     * before connecting to the remote resource.
     *
     * @since 1.0
     */
    class DECAF_API URLConnection {
    private:

        URLConnectionImpl* impl;

        static bool defaultAllowUserInteraction;

        static bool defaultUseCaches;

    protected:

        URL url;

        /**
         * The data must be modified more recently than this time in milliseconds
         * since January 1, 1970, GMT to be transmitted.
         */
        long long ifModifiedSince;

        /**
         * Specifies whether the using of caches is enabled or the data has to be
         * recent for every request.
         */
        bool useCaches;

        /**
         * Specifies whether this {@code URLConnection} is already connected to the
         * remote resource. If this field is set to {@code true} the flags for
         * setting up the connection are not changeable anymore.
         */
        bool connected;

        /**
         * Specifies whether this {@code URLConnection} allows sending data.
         */
        bool doOutput;

        /**
         * Specifies whether this {@code URLConnection} allows receiving data.
         */
        bool doInput;

        /**
         * Specifies whether this {@code URLConnection} allows user interaction as
         * it is needed for authentication purposes.
         */
        bool allowUserInteraction;

    private:

        URLConnection(const URLConnection&);
        URLConnection& operator= (const URLConnection&);

    protected:

        URLConnection(const URL& url);

    public:

        virtual ~URLConnection();

        /**
         * Establishes the connection to the earlier configured resource. The
         * connection can only be set up before this method has been called.
         *
         * @throws IOException if an error occurs while connecting to the resource.
         */
        virtual void connect() = 0;

    public:

        /**
         * Gets the option value which indicates whether user interaction is allowed
         * on this URLConnection.
         *
         * @return the value of the option allowUserInteraction.
         */
        bool getAllowUserInteraction() const {
            return allowUserInteraction;
        }

        /**
         * Sets the flag indicating whether this connection allows user interaction
         * or not. This method can only be called prior to the connection
         * establishment.
         *
         * @param newValue
         *      the value of the flag to be set.
         * @throws IllegalStateException
         *      if this method attempts to change the flag after the connection has been established.
         */
        void setAllowUserInteraction(bool newValue);

        /**
         * Gets the content encoding type specified by the response header field
         * content-encoding or empty string if this field is not set.
         *
         * @return the value of the response header field 'content-encoding'.
         */
        std::string getContentEncoding() const {
            return getHeaderField("Content-Encoding");
        }

        /**
         * Gets the content length in bytes specified by the response header field
         * 'content-length' or '-1' if this field is not set.
         *
         * @return the value of the response header field 'content-length'.
         */
        int getContentLength() const {
            return getHeaderFieldInt("Content-Length", -1);
        }

        /**
         * Gets the MIME-type of the content specified by the response header field
         * 'content-type' or empty string if type is unknown.
         *
         * @return the value of the response header field 'content-type'.
         */
        std::string getContentType() const {
            return getHeaderField("Content-Type");
        }

        /**
         * Gets the timestamp when this response has been sent as a date in
         * milliseconds since January 1, 1970 GMT or '0' if this timestamp is
         * unknown.
         *
         * @return the sending timestamp of the current response.
         */
        long long getDate() const {
            return getHeaderFieldDate("Date", 0);
        }

        /**
         * Gets the default setting whether this connection allows using caches.
         *
         * @return the value of the default setting defaultUseCaches.
         */
        bool getDefaultUseCaches() const {
            return defaultUseCaches;
        }

        /**
         * Sets the default value for the flag indicating whether this connection
         * allows to use caches. Existing URLConnections are unaffected.
         *
         * @param newValue
         *      the default value of the flag to be used for new connections.
         */
        void setDefaultUseCaches(bool newValue);

        /**
         * Gets the value of the option {@code doInput} which specifies whether this
         * connection allows to receive data.
         *
         * @return true if this connection allows input, false otherwise.
         */
        bool getDoInput() const {
            return doInput;
        }

        /**
         * Sets the flag indicating whether this URLConnection allows input.
         * It cannot be set after the connection is established.
         *
         * @param newValue
         *      the new value for the flag to be set.
         * @throws IllegalAccessError
         *      if this method attempts to change the value after the
         *      connection has been already established.
         */
        void setDoInput(bool newValue);

        /**
         * Gets the value of the option doOutput which specifies whether
         * this connection allows to send data.
         *
         * @return true if this connection allows output, false otherwise.
         */
        bool getDoOutput() const {
            return doOutput;
        }

        /**
         * Sets the flag indicating whether this URLConnection allows
         * output. It cannot be set after the connection is established.
         *
         * @param newValue
         *      the new value for the flag to be set.
         * @throws IllegalAccessError
         *      if this method attempts to change the value after the
         *      connection has been already established.
         */
        void setDoOutput(bool newValue);

        /**
         * Gets the timestamp when this response will be expired in milliseconds
         * since January 1, 1970 GMT or 0 if this timestamp is unknown.
         *
         * @return the value of the response header field expires.
         */
        long getExpiration() const {
            return getHeaderFieldDate("Expires", 0);
        }

        /**
         * Gets the URL represented by this URLConnection.
         *
         * @return the URL of this connection.
         */
        URL getURL() const {
            return url;
        }

        /**
         * Gets the value of the flag which specifies whether this URLConnection
         * allows to use caches.
         *
         * @return true if using caches is allowed, false otherwise.
         */
        bool getUseCaches() const {
            return useCaches;
        }

        /**
         * Sets the flag indicating whether this connection allows to use caches or
         * not. This method can only be called prior to the connection
         * establishment.
         *
         * @param newValue
         *      the value of the flag to be set.
         * @throws IllegalStateException
         *      if this method attempts to change the flag after the connection has been established.
         */
        void setUseCaches(bool newValue);

        /**
         * Gets the configured connecting timeout.
         *
         * @return the connecting timeout value in milliseconds.
         */
        int getConnectTimeout() const;

        /**
         * Sets the timeout value in milliseconds for establishing the connection to
         * the resource pointed by this URLConnection instance. A  SocketTimeoutException
         * is thrown if the connection could not be established in this time. Default is
         * 0 which stands for an infinite timeout.
         *
         * @param timeout
         *      the connecting timeout in milliseconds.
         * @throws IllegalArgumentException
         *      if the parameter timeout is less than zero.
         */
        void setConnectTimeout(int timeout);

        /**
         * Gets the configured timeout for reading from the input stream of an
         * established connection to the resource.
         *
         * @return the reading timeout value in milliseconds.
         */
        int getReadTimeout() const;

        /**
         * Sets the timeout value in milliseconds for reading from the input stream
         * of an established connection to the resource. A SocketTimeoutException
         * is thrown if the connection could not be established in this time. Default
         * is code 0 which stands for an infinite timeout.
         *
         * @param timeout
         *      the reading timeout in milliseconds.
         * @throws IllegalArgumentException
         *      if the parameter timeout is less than zero.
         */
        void setReadTimeout(int timeout);

        /**
         * Returns the string representation containing the name of this class and
         * the URL.
         *
         * @return the string representation of this URLConnection instance.
         */
        virtual std::string toString() const {
            return std::string("URLConnection:") + url.toString();
        }

        /**
         * Gets the header value at the field position pos or empty string
         * if the header has fewer than pos fields. The current implementation
         * of this method returns always empty string.
         *
         * @param pos
         *      the field position of the response header.
         *
         * @return the value of the field at position pos.
         */
        virtual std::string getHeaderField(int pos DECAF_UNUSED) const {
            return "";
        }

        /**
         * Gets the value of the header field specified by key or empty string
         * if there is no field with this name. The current implementation of
         * this method returns always empty string.
         *
         * @param key
         *      the name of the header field.
         *
         * @return the value of the header field.
         */
        virtual std::string getHeaderField(const std::string& key DECAF_UNUSED) const {
            return "";
        }

        /**
         * Gets the specified header value as a date in milliseconds since January
         * 1, 1970 GMT. Returns the defaultValue if no such header field could be found.
         *
         * @param field
         *      the header field name whose value is needed.
         * @param defaultValue
         *      the default value if no field has been found.
         *
         * @return the value of the specified header field as a date in milliseconds.
         */
        long long getHeaderFieldDate(const std::string& field, long long defaultValue) const;

        /**
         * Gets the specified header value as a number. Returns the defaultValue} if no
         * such header field could be found or the value could not be parsed as an Integer.
         *
         * @param field
         *      the header field name whose value is needed.
         * @param defaultValue
         *      the default value if no field has been found.
         *
         * @return the value of the specified header field as a number.
         */
        int getHeaderFieldInt(const std::string& field, int defaultValue) const;

        /**
         * Gets the value of the response header field 'last-modified' or zero if
         * this value is not set.
         *
         * @return the value of the 'last-modified' header field.
         */
        long long getLastModified() const;

        /**
         * Gets an InputStream for reading data from the resource pointed by this
         * URLConnection.  It throws an UnknownServiceException by default. This method
         * must be overridden by its subclasses.
         *
         * @return the InputStream to read data from.
         *
         * @throws IOException if no InputStream could be created.
         */
        virtual decaf::io::InputStream* getInputStream() {
            throw UnknownServiceException(
                __FILE__, __LINE__, "Does not support writing to the input stream");
        }

        /**
         * Gets an OutputStream for writing data to this URLConnection. It throws an
         * UnknownServiceException by default. This method must be overridden by its
         * subclasses.
         *
         * @return the OutputStream to write data.
         *
         * @throws IOException if no OutputStream could be created.
         */
        virtual decaf::io::OutputStream* getOutputStream() {
            throw UnknownServiceException(
                __FILE__, __LINE__, "Does not support writing to the output stream");
        }

        /**
         * Gets the point of time since when the data must be modified to be
         * transmitted. Some protocols transmit data only if it has been modified
         * more recently than a particular time.
         *
         * @return the time in milliseconds since January 1, 1970 GMT.
         */
        long long getIfModifiedSince() const {
            return ifModifiedSince;
        }

        /**
         * Sets the point of time since when the data must be modified to be
         * transmitted. Some protocols transmit data only if it has been modified
         * more recently than a particular time. The data will be transmitted
         * regardless of its timestamp if this option is set to 0.
         *
         * @param newValue
         *      the time in milliseconds since January 1, 1970 GMT.
         * @throws IllegalStateException
         *      if this URLConnection has already been connected.
         */
        void setIfModifiedSince(long long newValue);

    public:

        /**
         * Gets the default setting whether this connection allows user interaction.
         *
         * @return the value of the default setting defaultAllowUserInteraction.
         */
        static bool getDefaultAllowUserInteraction() {
            return defaultAllowUserInteraction;
        }

        /**
         * Sets the default value for the flag indicating whether this connection
         * allows user interaction or not. Existing URLConnections are unaffected.
         *
         * @param allows
         *      the default value of the flag to be used for new connections.
         */
        static void setDefaultAllowUserInteraction(bool allows) {
            defaultAllowUserInteraction = allows;
        }

    };

}}

#endif /* _DECAF_NET_URLCONNECTION_H_ */