CVS update of carob (15 files)

    Date: Thursday, March 23, 2006 @ 17:10:04
  Author: gilles
    Path: /cvsroot/carob/carob

Modified: include/BigDecimal.hpp (1.20 -> 1.21) include/CarobException.hpp
          (1.45 -> 1.46) include/Common.hpp (1.42 -> 1.43)
          include/ConnectionParameters.hpp (1.19 -> 1.20)
          include/ControllerConnectPolicy.hpp (1.5 -> 1.6)
          include/CriticalSection.hpp (1.6 -> 1.7) include/JavaSocket.hpp
          (1.26 -> 1.27) include/SQLDataSerialization.hpp (1.14 -> 1.15)
          include/Statement.hpp (1.40 -> 1.41) include/StringCodecs.hpp
          (1.12 -> 1.13) test/01-Unit/TestStringCodecs.hpp (1.1 -> 1.2)
          test/10-Connection/TestConnect.hpp (1.1 -> 1.2)
          test/10-Connection/TestControllerConnectPolicy.hpp (1.2 -> 1.3)
          test/10-Connection/TestFailOver.hpp (1.1 -> 1.2)
          test/40-Parameter-PreparedStatement/TestParameterStatement.hpp
          (1.5 -> 1.6)

(minor changes)
Doxygen fixes


----------------------------------------------------------------+
 include/BigDecimal.hpp                                         |   20 ++
 include/CarobException.hpp                                     |    4 
 include/Common.hpp                                             |   22 ++-
 include/ConnectionParameters.hpp                               |    5 
 include/ControllerConnectPolicy.hpp                            |    7 +
 include/CriticalSection.hpp                                    |    2 
 include/JavaSocket.hpp                                         |    2 
 include/SQLDataSerialization.hpp                               |   12 +
 include/Statement.hpp                                          |    7 -
 include/StringCodecs.hpp                                       |   67 
+++++-----
 test/01-Unit/TestStringCodecs.hpp                              |    9 -
 test/10-Connection/TestConnect.hpp                             |    4 
 test/10-Connection/TestControllerConnectPolicy.hpp             |    3 
 test/10-Connection/TestFailOver.hpp                            |    3 
 test/40-Parameter-PreparedStatement/TestParameterStatement.hpp |   15 +-
 15 files changed, 125 insertions(+), 57 deletions(-)


Index: carob/include/BigDecimal.hpp
diff -u carob/include/BigDecimal.hpp:1.20 carob/include/BigDecimal.hpp:1.21
--- carob/include/BigDecimal.hpp:1.20   Thu Mar 23 15:37:04 2006
+++ carob/include/BigDecimal.hpp        Thu Mar 23 17:10:04 2006
@@ -57,23 +57,33 @@
 
   /**
    * Constructs a BigDecimal which value is parsed from the given wstring 
-   * (converted to a string) using #createFromString() function 
+   * (converted to a string) using #createFromString() function
+   * @param s wide string to parse into a BigDecimal
+   * @throw ConversionException if the given string does not represent a valid
+   *        BigDecimal
    * @see #createFromString()
    */
   BigDecimal(const std::wstring& s) throw (ConversionException, 
UnexpectedException);
   /**
    * Constructs a BigDecimal which value is parsed from the given string using
    * #createFromString() function.
+   * @param s string to parse into a BigDecimal
+   * @throw ConversionException if the given string does not represent a valid
+   *        BigDecimal
    * @see #createFromString()
    */
   BigDecimal(const std::string& s) throw (ConversionException, 
UnexpectedException);
   /**
-   * Constructs a BigDecimal which value is taken from the given argument using
-   * #createFromString() function.
-   * @see #createFromString()
+   * Constructs a BigDecimal which value is taken from the given argument
    */
   BigDecimal(const int);
+  /**
+   * Constructs a BigDecimal which value is taken from the given argument
+   */
   BigDecimal(const long);
+  /**
+   * Constructs a BigDecimal which value is taken from the given argument
+   */
   BigDecimal(const int64_t);
   //TODO:BigDecimal(const float);
   //TODO:BigDecimal(const double);
@@ -96,6 +106,8 @@
    * the controller for parameter statements. The controller uses the default
    * decimal point separator for parsing, so we have to send it the right one,
    * which is the default C one.
+   * @param os stream in which to write the string representation of this BD
+   * @param bd value to be serialized
    */
   friend std::basic_ostream<wchar_t>& operator << 
(std::basic_ostream<wchar_t>& os, 
       const BigDecimal &bd)  { return os<<bd.toString(controllerDecimalPoint); 
}
Index: carob/include/CarobException.hpp
diff -u carob/include/CarobException.hpp:1.45 
carob/include/CarobException.hpp:1.46
--- carob/include/CarobException.hpp:1.45       Thu Mar 16 15:35:39 2006
+++ carob/include/CarobException.hpp    Thu Mar 23 17:10:04 2006
@@ -35,7 +35,8 @@
 class StackTraceElement;
 class DriverSocket;
 
-  // redefine the default ctor to get the current backtrace
+/** Exceptions' backtrace consisting in a vector a trace strings */
+// redefine the default ctor to get the current backtrace
 class BackTrace : public std::vector<std::string>
 {
 public:
@@ -230,6 +231,7 @@
   /**
    * Constructs a ConversionException with the given message
    * @param s error message of the exception
+   * @param state corresponding SQL state, HYC00 if none
    */
   ConversionException(std::wstring s, std::wstring state)
     : DriverException(s, state)
Index: carob/include/Common.hpp
diff -u carob/include/Common.hpp:1.42 carob/include/Common.hpp:1.43
--- carob/include/Common.hpp:1.42       Thu Mar 23 15:32:58 2006
+++ carob/include/Common.hpp    Thu Mar 23 17:10:04 2006
@@ -54,15 +54,31 @@
   LOG_LEVEL_OFF
 };
 
+/**
+ * Utility class to convert a plain text log level into the internaly defined
+ * log level code
+ */
 class StringLogLevel : public std::string
 {
 public:
-  // we have nothing more than the derived std::string
+  /**
+   * Creation from a given string.
+   * Accepted strings are:<ul>
+   * <li><code>"DEBUG"</code>
+   * <li><code>"INFO"</code>
+   * <li><code>"WARN"</code>
+   * <li><code>"ERROR"</code>
+   * <li><code>"FATAL"</code>
+   * <li><code>"OFF"</code></ul>
+   * @param s string representing the desired log level
+   */
   StringLogLevel(const char * s)
     : std::string(s)
-  { } ;
+  { } ; // we have nothing more than the derived std::string
 
-  // converter from std::string to the enum
+  /**
+   * Converter from std::string to the log level enum
+   */
   operator LogLevel() const
     throw (std::string) // error message
   {
Index: carob/include/ConnectionParameters.hpp
diff -u carob/include/ConnectionParameters.hpp:1.19 
carob/include/ConnectionParameters.hpp:1.20
--- carob/include/ConnectionParameters.hpp:1.19 Mon Mar 13 19:33:32 2006
+++ carob/include/ConnectionParameters.hpp      Thu Mar 23 17:10:04 2006
@@ -41,6 +41,11 @@
   ROUND_ROBIN
 };
 
+/**
+ * Identifies a controller.
+ * For now a controller is identified by an hostname and a port.
+ * TODO: In the future, only its sockaddr should be kept (see CAROB-61)
+ */
 class ControllerInfo
 {
 public:
Index: carob/include/ControllerConnectPolicy.hpp
diff -u carob/include/ControllerConnectPolicy.hpp:1.5 
carob/include/ControllerConnectPolicy.hpp:1.6
--- carob/include/ControllerConnectPolicy.hpp:1.5       Thu Feb  2 18:19:18 2006
+++ carob/include/ControllerConnectPolicy.hpp   Thu Mar 23 17:10:04 2006
@@ -126,6 +126,13 @@
 class RoundRobinConnectPolicy : public AbstractControllerConnectPolicy
 {
 public:
+  /**
+   * Creates a new <code>RoundRobinConnectPolicy</code> object
+   * 
+   * @param controllerList the controller list on which the policy applies
+   * @param retryIntervalInMs IGNORED ! interval in milliseconds before 
retrying
+   *          to re-connect to a controller that has failed
+   */
   RoundRobinConnectPolicy(const std::vector<ControllerInfo>& controllerList,
     long retryIntervalInMs = 0) throw (DriverException, UnexpectedException);
   ControllerInfo              getController() throw (NoMoreControllerException,
Index: carob/include/CriticalSection.hpp
diff -u carob/include/CriticalSection.hpp:1.6 
carob/include/CriticalSection.hpp:1.7
--- carob/include/CriticalSection.hpp:1.6       Thu Jan 12 18:05:05 2006
+++ carob/include/CriticalSection.hpp   Thu Mar 23 17:10:04 2006
@@ -151,10 +151,12 @@
  *    //do what is critical
  * } //no need to do anything else, the scope locker destructor is called
  *   //automatically, releasing the lock
+ * </code>
  */
 class LockScope
 {
 public:
+  /** Locks the current scope using the given CriticalSection object */
   LockScope(CriticalSection* CSPtrPrm)
   {
     CSPtr = CSPtrPrm;
Index: carob/include/JavaSocket.hpp
diff -u carob/include/JavaSocket.hpp:1.26 carob/include/JavaSocket.hpp:1.27
--- carob/include/JavaSocket.hpp:1.26   Fri Feb 24 18:30:33 2006
+++ carob/include/JavaSocket.hpp        Thu Mar 23 17:10:04 2006
@@ -55,7 +55,7 @@
   /**
    * Gives socket validity status.
    * @return true if the socket is valid (has been created), so
-   * {@link #connectTo(const std::wstring&, in_addr_t)} can be called
+   * {@link #connectTo(const std::wstring& host, in_port_t port)} can be called
    */
   inline bool   isValid() const { return socketFd != -1; }
   /**
Index: carob/include/SQLDataSerialization.hpp
diff -u carob/include/SQLDataSerialization.hpp:1.14 
carob/include/SQLDataSerialization.hpp:1.15
--- carob/include/SQLDataSerialization.hpp:1.14 Fri Mar 17 12:46:49 2006
+++ carob/include/SQLDataSerialization.hpp      Thu Mar 23 17:10:04 2006
@@ -69,6 +69,7 @@
    * uint32_t bit representation. Does NOT swap bytes in any way, so
    * endianness of the result is arch-specific. Endianness of floats
    * is typically the same as for integer types, but not granted.
+   * @param f value to convert
    */
   static uint32_t
   floatToU32Bits(float f);
@@ -82,9 +83,10 @@
    * uint64_t bit representation. Does NOT swap bytes in any way, so
    * endianness of the result is arch-specific. Endianness of doubles
    * is typically the same as for integer types, but not granted.
+   * @param d value to convert
    */
   static uint64_t
-  doubleToU64Bits(double f);
+  doubleToU64Bits(double d);
 
   /** See doubleToU64Bits(double d) */
   static double
@@ -92,16 +94,20 @@
 
 };
 
-/** SQL TimeStamp */
+/** Hold a SQL <code>TIMESTAMP</code> value */
 typedef struct {
+  /** Integral seconds (no milliseconds) */
   int64_t time;
+  /** Fractional seconds (milliseconds) */
   int32_t nanos;
 } SQLTimeStamp;
 
 /** Large Data: byte array, blob, clob */
 typedef struct
 {
-  int32_t     length; //int32 to reflect java
+  /** Number of bytes held */
+  int32_t     length;
+  /** Actual data, as an array of bytes */
   java_byte*  data;
 } LargeData;
 
Index: carob/include/Statement.hpp
diff -u carob/include/Statement.hpp:1.40 carob/include/Statement.hpp:1.41
--- carob/include/Statement.hpp:1.40    Tue Mar 21 23:52:54 2006
+++ carob/include/Statement.hpp Thu Mar 23 17:10:04 2006
@@ -160,7 +160,7 @@
    * @return <code>true</code> if the next result is a <code>ResultSet</code>
    *         object; <code>false</code> if it is an update count or there are
    *         no more results
-   * @see #execute(std::wstring)
+   * @see #execute(const std::wstring &)
    */
   bool                    getMoreResults(int current) throw (DriverException,
                               SocketIOException, BackendException,
@@ -319,6 +319,7 @@
    * Nulls the given resultSet in the resultList. This function is called by
    * the driverResultSet destructor to inform that the give resultSet is beeing
    * destroyed, so that any reference to it is not valid anymore
+   * @param drsPtr pointer to the ResultSet that must be invalidated
    */
   void                    removeResultSetFromList(DriverResultSet* drsPtr);
   /** List of updateCount/ResultSet */
@@ -333,7 +334,7 @@
   /**
    * Convenience method for derived class ParameterStatement
    * @param skeleton SQL skeleton statement
-   * @param serializedParameters SQL parameters serialized into a string
+   * @param parameters SQL parameters serialized into a string
    * @return true if the result is a ResultSet or false if it is an integer
    */
   bool                    execute(const std::wstring &skeleton, const 
std::wstring &parameters)
@@ -344,7 +345,7 @@
   /**
    * Convenience method for derived class ParameterStatement
    * @param skeleton SQL skeleton statement
-   * @param serializedParameters SQL parameters serialized into a string
+   * @param parameters SQL parameters serialized into a string
    * @return a ResulSet pointer that contains the data produced by the query
    */
   DriverResultSet*        executeQuery(const std::wstring &skeleton, const 
std::wstring &parameters)
Index: carob/include/StringCodecs.hpp
diff -u carob/include/StringCodecs.hpp:1.12 carob/include/StringCodecs.hpp:1.13
--- carob/include/StringCodecs.hpp:1.12 Fri Mar 17 20:17:25 2006
+++ carob/include/StringCodecs.hpp      Thu Mar 23 17:10:04 2006
@@ -59,41 +59,46 @@
 
 std::locale trylocale(const char * const name) throw (CodecException);
 
+/**
+ * Multi-Byte String encoder and decoders according to a given or default 
locale
+ */
 class MBSCodec
 {
-    // TODO: replace loc by an accessor, so we could dynamically use
-    // the (possibly changing) current locale() instead of a constant
-    // one.
-
-    // Here order matters (see init below)
-    const std::locale loc; // hold our own (and cheap) copy for safety
-    const mbs_codecvt& codecvt;
+  // TODO: replace loc by an accessor, so we could dynamically use
+  // the (possibly changing) current locale() instead of a constant
+  // one.
+
+  // Here order matters (see init below)
+  const std::locale loc; // hold our own (and cheap) copy for safety
+  const mbs_codecvt& codecvt;
 
 public:
-    std::string encode(const std::wstring&) const throw (CodecException);
-    std::wstring decode(const std::string&) const throw (CodecException);
+  std::string encode(const std::wstring&) const throw (CodecException);
+  std::wstring decode(const std::string&) const throw (CodecException);
 
-    // Default constructor for the default converter, using
-    // user-defined locale (typically LANG, LC_etc).  If you want the
-    // C locale instead of this LANG-one use for instance this CTOR:
-    //   MBSCodec(locale::classic())
-    // or if you want the current (global) locale:
-    //   MBSCodec(locale())
-    MBSCodec() :
-        loc(std::locale("")),
-        codecvt (std::use_facet<mbs_codecvt>(loc))
-    { }
-    
-    MBSCodec(const std::locale& locarg) :
-        loc(locarg),
-        codecvt (std::use_facet<mbs_codecvt>(loc))
-    { }
-
-    MBSCodec(const char* locname) throw (CodecException) :
-        loc(trylocale(locname)),
-        codecvt (std::use_facet<mbs_codecvt>(loc))
-    { }
-    
+  /**
+   * Default constructor for the default converter, using
+   * user-defined locale (typically LANG, LC_etc).  If you want the
+   * C locale instead of this LANG-one use for instance this CTOR:
+   *   MBSCodec(locale::classic())
+   * or if you want the current (global) locale:
+   *   MBSCodec(locale())
+   */
+  MBSCodec() :
+      loc(std::locale("")),
+      codecvt (std::use_facet<mbs_codecvt>(loc))
+  { }
+  
+  MBSCodec(const std::locale& locarg) :
+      loc(locarg),
+      codecvt (std::use_facet<mbs_codecvt>(loc))
+  { }
+
+  MBSCodec(const char* locname) throw (CodecException) :
+      loc(trylocale(locname)),
+      codecvt (std::use_facet<mbs_codecvt>(loc))
+  { }
+  
 };
 
 /** 
@@ -115,7 +120,7 @@
   { return user_codec.encode(in); }
 private:
   static const CarobNS::MBSCodec utf8_codec;
-  // user-defined locale (typically set using LANG, LC_etc)
+  /** user-defined locale (typically set using LANG, LC_etc) */
   static const CarobNS::MBSCodec user_codec;
 };
 
Index: carob/test/01-Unit/TestStringCodecs.hpp
diff -u carob/test/01-Unit/TestStringCodecs.hpp:1.1 
carob/test/01-Unit/TestStringCodecs.hpp:1.2
--- carob/test/01-Unit/TestStringCodecs.hpp:1.1 Fri Dec 16 16:28:39 2005
+++ carob/test/01-Unit/TestStringCodecs.hpp     Thu Mar 23 17:10:04 2006
@@ -24,15 +24,16 @@
 #include <cppunit/TestFixture.h>
 #include <cppunit/TestCase.h>
 
-
+/**
+ * Tests StringCodecs class with various strings under different encodings.
+ */
 class TestStringCodecs : public CppUnit::TestFixture
 {
 public:
   /** Suite of tests to be run */
-    static CppUnit::Test* suite();
-
-    void encode_decode();
+  static CppUnit::Test* suite();
 
+  void encode_decode();
 };
 
 #endif // include only once
Index: carob/test/10-Connection/TestConnect.hpp
diff -u carob/test/10-Connection/TestConnect.hpp:1.1 
carob/test/10-Connection/TestConnect.hpp:1.2
--- carob/test/10-Connection/TestConnect.hpp:1.1        Mon Jan 23 17:17:59 2006
+++ carob/test/10-Connection/TestConnect.hpp    Thu Mar 23 17:10:04 2006
@@ -42,9 +42,9 @@
   /** Suite of tests to be run */
   static CppUnit::Test* suite();
 
-  /** Nothing to setup */
+  /** Init connectionPtr to NULL */
   void setUp();
-  /** Destroys connection pointer if applicable */
+  /** Frees connectionPtr if applicable */
   void tearDown();
   /**
    * Tries to connect to a dummy controller address and checks that there is a
Index: carob/test/10-Connection/TestControllerConnectPolicy.hpp
diff -u carob/test/10-Connection/TestControllerConnectPolicy.hpp:1.2 
carob/test/10-Connection/TestControllerConnectPolicy.hpp:1.3
--- carob/test/10-Connection/TestControllerConnectPolicy.hpp:1.2        Fri Feb 
24 12:29:04 2006
+++ carob/test/10-Connection/TestControllerConnectPolicy.hpp    Thu Mar 23 
17:10:04 2006
@@ -41,8 +41,9 @@
   /** Suite of tests to be run */
   static CppUnit::Test* suite();
 
-  /** Nothing to setup / tear down*/
+  /** Nothing to setup */
   void setUp();
+  /** Nothing to tearDown */
   void tearDown();
   /**
    * Adds 2 out of 4 controllers to the list of suspects and checks that the
Index: carob/test/10-Connection/TestFailOver.hpp
diff -u carob/test/10-Connection/TestFailOver.hpp:1.1 
carob/test/10-Connection/TestFailOver.hpp:1.2
--- carob/test/10-Connection/TestFailOver.hpp:1.1       Fri Feb 24 12:58:06 2006
+++ carob/test/10-Connection/TestFailOver.hpp   Thu Mar 23 17:10:04 2006
@@ -41,8 +41,9 @@
   /** Suite of tests to be run */
   static CppUnit::Test* suite();
 
-  /** Nothing to setup / tear down*/
+  /** Nothing to setup */
   void setUp();
+  /** Nothing to tearDown */
   void tearDown();
   /**
    * Tries to connect to 1 then 2 failing controllers (actually with dummy 
ports)
Index: carob/test/40-Parameter-PreparedStatement/TestParameterStatement.hpp
diff -u 
carob/test/40-Parameter-PreparedStatement/TestParameterStatement.hpp:1.5 
carob/test/40-Parameter-PreparedStatement/TestParameterStatement.hpp:1.6
--- carob/test/40-Parameter-PreparedStatement/TestParameterStatement.hpp:1.5    
Wed Mar 22 19:24:41 2006
+++ carob/test/40-Parameter-PreparedStatement/TestParameterStatement.hpp        
Thu Mar 23 17:10:04 2006
@@ -71,11 +71,20 @@
    * Tests execute function with an update statement
    */
   void testExecuteWithUpdate();
-
+  /**
+   * Tests setBoolean function by sending a write request within a parameter
+   * statement and checking that the value read back is the original one.
+   */
   void testBoolean();
-
+  /**
+   * Tests setString function by sending a write request within a parameter
+   * statement and checking that the value read back is the original one.
+   */
   void testStrings();
-
+  /**
+   * Tests setBigDecimal function by sending a write request within a parameter
+   * statement and checking that the value read back is the original one.
+   */
   void testBigDecimal();
 };