activemq-cpp/src/main/decaf/net/URLConnection.h - activemq-cpp - Git at Google

 /*
  * 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_ */
	/*
	* 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_ */