dm3#5, 0.3.0 bump, legacy java type conversions

Author: Vadim Platonov

CHANGELOG.md

@@ -1,9 +1,22 @@
 ## 0.3.0
 
-### Fixed
+### Breaking changes
+
+* `to-sql-date` converts anything convertible to `LocalDate` into a `java.sql.Date`.
+  Previously `to-sql-date` returned a `java.util.Date` (bug).
+
+### New Features
+
+Please see a new section within README - [Legacy Date-Time
+Types](https://github.com/dm3/clojure.java-time#legacy-date-time-types)
 
-* *Breaking*: `to-sql-date` converts anything convertible to `LocalDate` into a `java.sql.Date`.
-  Previously `to-sql-date` worked the same as `to-java-date`.
+* `java-date`, `sql-date`, `sql-timestamp`, `sql-time` - functions which
+  product the `java.util.*` date-time objects.
+* [#5](https://github.com/dm3/clojure.java-time/issues/5) automatic conversions:
+    - `java.sql.Date` -> `java.time.LocalDate`
+    - `java.sql.Timestamp` -> `java.time.LocalDateTime`
+    - `java.sql.Time` -> `java.time.LocalTime`
+* deprecated `to-java-date`/`to-sql-date`/`to-sql-timestamp`
 
 ## 0.2.2
 

README.md

@@ -312,18 +312,59 @@ less information, e.g. (assuming we're in UTC timezone):
 => #object[java.time.LocalTime 0x3a3cd6d5 "01:00"]
 ```
 
-Any date which can be converted to an instant, can also be converted to pre-Java
-8 date types:
+#### Legacy Date-Time Types
 
-```clj
-(to-java-date (zoned-date-time 2015 9 28))
+Any date which can be converted to an instant, can also be converted to a
+`java.util.Date`:
+
+```clojure
+(java-date (zoned-date-time 2015 9 28))
 => #inst "2015-09-27T22:00:00.000-00:00"
 
-(to-sql-date (zoned-date-time 2015 9 28))
+(java-date 50000)
+=> #inst "1970-01-01T00:00:50.000-00:00"
+```
+
+An instance of `java.util.Date` serves the same purpose as the new
+`java.time.Instant`. It's a machine timestamp which isn't aware of the
+timezone. Please, do not get confused by the way it is printed by the Clojure
+printer - the UTC timezone is applied during formatting.
+
+Sometimes you'll have to work with the legacy `java.sql.Date/Time/Timestamp`
+types. The correspondence between the legacy types and the new Date-Time
+entities is as follows:
+
+  * `java.time.LocalDate` - `java.sql.Date`
+  * `java.time.LocalDateTime` - `java.sql.Timestamp`
+  * `java.time.LocalTime` - `java.sql.Time`
+
+```clojure
+(sql-date 2015 9 28)
 => #inst "2015-09-27T22:00:00.000-00:00"
 
-(to-sql-timestamp (zoned-date-time 2015 9 28))
-=> #inst "2015-09-27T22:00:00.000000000-00:00"
+(sql-timestamp 2015 9 28 10 20 30 4000000)
+=> #inst "2015-09-28T09:20:30.004-00:00"
+
+(sql-time 10 20 30)
+=> #inst "1970-01-01T09:20:30.000-00:00"
+```
+
+The results of the above calls get printed as `#inst` because all of the
+`java.sql.Date/Time/Timestamp` are subtypes of `java.util.Date`.
+Coincidentally, this makes it impossible to plug the `java.sql.*` types into
+the Clojure.Java-Time conversion graph.
+
+Conversions to the legacy types also go the other way around:
+
+```clojure
+(j/local-date (j/sql-date 2015 9 28))
+#object[java.time.LocalDate "2015-09-28"]
+
+(j/local-date-time (j/sql-timestamp 2015 9 28 10 20 30 4000000))
+#object[java.time.LocalDateTime "2015-09-28T10:20:30.004"]
+
+(j/local-time (j/sql-time 10 20 30))
+#object[java.time.LocalTime "10:20:30"]
 ```
 
 #### Three-Ten Extra
@@ -335,7 +376,7 @@ project, you will get an `Interval`, `AmPm`, `DayOfMonth`, `DayOfYear`,
 An interval can be constructed from two entities that can be converted to
 instants:
 
-```clj
+```clojure
 (interval (offset-date-time 2015 1 1) (zoned-date-time 2016 1 1))
 => #<org.threeten.extra.Interval 2015-01-01T00:00:00Z/2016-01-01T00:00:00Z>
 
@@ -354,7 +395,7 @@ instants:
 Bonus! if you have Joda Time on the classpath (either directly, or via
 `clj-time`), you can seamlessly convert from Joda Time to Java Time types:
 
-```clj
+```clojure
 (java-time.repl/show-path org.joda.time.DateTime java.time.OffsetTime)
 => {:cost 2.0,
     :path [[#<java_time.graph.Types@15e43c24 [org.joda.time.DateTime]>
@@ -374,7 +415,7 @@ you to influence the date-times create using default constructors ala Joda's
 `DateTimeUtils/setCurrentMillisSystem`. Clojure.Java-Time tries to fix that with
 the `with-clock` macro and the corresponding `with-clock-fn` function:
 
-```clj
+```clojure
 (zone-id)
 => #<java.time.ZoneRegion Europe/London>
 
@@ -391,7 +432,7 @@ Date-Time entities are composed of date fields, while Duration entities are
 composed of time units. You can see all of the predefined fields and units
 via the `java-time.repl` ns:
 
-```clj
+```clojure
 (java-time.repl/show-fields)
 => (:aligned-day-of-week-in-month
     :aligned-day-of-week-in-year
@@ -402,7 +443,7 @@ via the `java-time.repl` ns:
     ...)
 ```
 
-```clj
+```clojure
 (java-time.repl/show-units)
 => (:centuries
     :days
@@ -415,7 +456,7 @@ via the `java-time.repl` ns:
 
 You can obtain any field/unit like this:
 
-```clj
+```clojure
 (field :year)
 => #object[java.time.temporal.ChronoField "Year"]
 
@@ -428,7 +469,7 @@ You can obtain any field/unit like this:
 
 You can obtain all of the fields/units of the temporal entity:
 
-```clj
+```clojure
 (fields (local-date))
 => {:proleptic-month #object[java.time.temporal.ChronoField ...}
 
@@ -441,7 +482,7 @@ By themselves the fields and units aren't very interesting. You can get the
 range of valid values for a field and a duration between two dates, but that's
 about it:
 
-```clj
+```clojure
 (range (field :year))
 => #object[java.time.temporal.ValueRange "-999999999 - 999999999"]
 
@@ -458,7 +499,7 @@ are reasons for that which I feel are only valid in a statically-typed API like
 Java's. In Clojure, properties allow expressing time entity modifications and
 queries uniformly across all of the entity types.
 
-```clj
+```clojure
 (def prop (property (local-date 2015 2 28) :day-of-month))
 => #java_time.temporal.TemporalFieldProperty{...}
 
@@ -496,7 +537,7 @@ Hopefully, the performance issue will be resolved in the future...
 
 You can play with the conversion graph using the following helpers:
 
-```clj
+```clojure
 (java-time.repl/show-path org.joda.time.DateTime java.time.OffsetTime)
 => {:cost 2.0,
     :path [[#<java_time.graph.Types@15e43c24 [org.joda.time.DateTime]>

project.clj

@@ -1,4 +1,4 @@
-(defproject clojure.java-time "0.2.3-SNAPSHOT"
+(defproject clojure.java-time "0.3.0-SNAPSHOT"
   :description "Clojure wrapper for Java 8 Time API"
   :url "http://github.com/dm3/clojure.java-time"
   :license {:name "MIT License"

src/java_time.clj

@@ -3,7 +3,7 @@
   (:require [java-time.potemkin.namespaces :as potemkin]
             [java-time.util :as jt.u]
             [java-time core properties temporal amount zone single-field local chrono
-             convert sugar seqs adjuster interval format joda clock]))
+             convert sugar seqs adjuster interval format joda clock pre-java8]))
 
 (potemkin/import-vars
   [java-time.clock
@@ -60,6 +60,9 @@
   [java-time.format
    format formatter]
 
+  [java-time.pre-java8
+   java-date sql-date sql-timestamp sql-time]
+
   [java-time.interval
    move-start-to move-end-to move-start-by move-end-by
    start end contains? overlaps? abuts? overlap gap])

src/java_time/pre_java8.clj

@@ -0,0 +1,73 @@
+(ns java-time.pre-java8
+  (:require [java-time
+             [local :as jt.l]
+             [temporal :as jt.t]
+             [defconversion :refer [conversion!]]]))
+
+(defn ^java.util.Date java-date
+  "Creates a `java.util.Date` out of any combination of arguments valid for
+  `java-time/instant` or the Instant itself.
+
+  A `java.util.Date` represents an instant in time. It's a direct analog of the
+  `java.time.Instant` type introduced in the JSR-310. Please consider using the
+  `java.time.Instant` (through `java-time/instant`) directly."
+  ([] (java.util.Date/from (jt.t/instant)))
+  ([a] (java.util.Date/from (jt.t/instant a)))
+  ([a b] (java.util.Date/from (jt.t/instant a b))))
+
+(defn- arities [type ctor n-args]
+  (for [i (range (inc n-args))]
+    (let [arg-vec (vec (take i (repeatedly gensym)))
+          type-ctor (symbol (name type) "valueOf")]
+      `(~arg-vec (~type-ctor (~ctor ~@arg-vec))))))
+
+(defmacro defsqldate [type name ctor n-args doc]
+  (let [fn-name (with-meta name {:tag type})]
+    `(defn ~fn-name ~doc
+       ~@(arities type ctor n-args))))
+
+(conversion! java.sql.Date java.time.LocalDate
+  (fn [^java.sql.Date dt]
+    (.toLocalDate dt)))
+
+(conversion! java.sql.Timestamp java.time.LocalDateTime
+  (fn [^java.sql.Timestamp dt]
+    (.toLocalDateTime dt)))
+
+(conversion! java.sql.Time java.time.LocalTime
+  (fn [^java.sql.Time dt]
+    (.toLocalTime dt)))
+
+(defsqldate java.sql.Date sql-date jt.l/local-date 3
+  "Creates a `java.sql.Date` out of any combination of arguments valid for
+  `java-time/local-date` or the LocalDate itself.
+
+  Please consider using the JSR-310 Java Time types instead of `java.sql.Date`
+  if your drivers support them.
+
+  Even though `java.sql.Date` extends a `java.util.Date`, it's supposed to be
+  used as a local date (no time component or timezone) for the purposes of
+  conversion from/to native JDBC driver DATE types.")
+
+(defsqldate java.sql.Timestamp sql-timestamp jt.l/local-date-time 7
+  "Creates a `java.sql.Timestamp` out of any combination of arguments valid for
+  `java-time/local-date-time` or the LocalDateTime itself.
+
+  Please consider using the JSR-310 Java Time types instead of
+  `java.sql.Timestamp` if your drivers support them.
+
+  `java.sql.Timestamp` is a version of a `java.util.Date` supposed to be used
+  as a local date-time (no timezone) for the purposes of conversion from/to native
+  JDBC driver TIMESTAMP types.")
+
+(defsqldate java.sql.Time sql-time jt.l/local-time 3
+  "Creates a `java.sql.Time` out of any combination of arguments valid for
+  `java-time/local-time` (except the nanos constructor) or the LocalTime
+  itself.
+
+  Please consider using the JSR-310 Java Time types instead of `java.sql.Time`
+  if your drivers support them.
+
+  Even though `java.sql.Time` extends a `java.util.Date`, it's supposed to be
+  used as a local time (no date component or timezone) for the purposes of
+  conversion from/to native JDBC driver TIME types.")

test/java_time_test.clj

@@ -617,6 +617,24 @@
       (is (= (java.util.Date. 1000) (j/to-java-date (j/instant 1000))))
       (is (= (java.sql.Date/valueOf (j/local-date 2016)) (j/to-sql-date (j/local-date 2016))))))
 
+  (testing "pre-java8"
+    (is (= (j/java-date (j/instant 1000))
+           (java.util.Date. 1000)
+           (j/java-date 1000)))
+    (is (= (java.sql.Date/valueOf (j/local-date 2000 10 5))
+           (j/sql-date 2000 10 5)
+           (j/sql-date (j/local-date 2000 10 5))))
+    (is (= (java.sql.Timestamp/valueOf (j/local-date-time 2000 10 5 20 30 40))
+           (j/sql-timestamp 2000 10 5 20 30 40)
+           (j/sql-timestamp (j/local-date-time 2000 10 5 20 30 40))))
+    (is (= (java.sql.Time/valueOf (j/local-time 20 30 40))
+           (j/sql-time 20 30 40)
+           (j/sql-time (j/local-time 20 30 40))))
+
+    (is (= (j/local-date 2000 10 5) (j/local-date (j/sql-date 2000 10 5))))
+    (is (= (j/local-date-time 2000 10 5 20 30 40 1000)
+           (j/local-date-time (j/sql-timestamp 2000 10 5 20 30 40 1000))))
+    (is (= (j/local-time 20 30 40) (j/local-time (j/sql-time 20 30 40)))))
 
   (testing "from java.util Date types"
     (is (= (j/zone-id "UTC") (j/zone-id (java.util.TimeZone/getTimeZone "UTC"))))))