content/documentation/extensions/mod_jodatime.adoc

:jbake-type: page
:jbake-status: published

= Apache Tamaya - Extension: JodaTime

toc::[]

[[JodaTime]]
== Tamaya JodaTime (Extension Module)
Tamaya _JodaTime_ is an extension module. Refer to the link:../extensions.html[extensions documentation] for further details.

=== What functionality this module provides ?

Tamaya _JodaTime_ is an extension module to support the usage of http://www.joda.org/joda-time/[Joda-Time]
in conjunction with Tamaya. Tamaya JodaTime defines some additional property
converters to use Joda-Time types when accessing configuration.


=== Installation

To support Joda-Time types as configuration values, you only have to add the following
maven dependency to your project:

[source, xml, subs=attributes+]
-----------------------------------------------
<dependency>
  <grooupId>org.apache.tamaya.ext</groupId>
  <artifactId>tamaya-jodatime</artifactId>
  <version>{tamaya_version}</version>
</dependency>
-----------------------------------------------


=== Usage

After adding this module to your project you can retrieve
Joda-Time based values directly from a given configuration.

[source,java]
-----------------------------------------------
Configuration configuration = Configuration.current();

DateTime pit = configuration.get("pointInTime", DateTime.class)
-----------------------------------------------

Currently the following types are supported:


[width="80%",options=header]
|================================================================
| Joda-Time target type              | Supported Input Formats
.12+^.<| +org.joda.time.DateTime+ +org.joda.time.Instant+  | `yyyy-MM-dd'T'HH:mm:ss.SSSZ`
           | `yyyy-MM-dd'T'HH:mm:ss.SSSz`
                                     | `yyyy-MM-dd'T'HH:mm:ss.SSS z`
                                     | `yyyy-MM-dd'T'HH:mm:ssZ`
                                     | `yyyy-MM-dd'T'HH:mm:ssz`
                                     | `yyyy-MM-dd'T'HH:mm:ss z`
                                     | `yyyy-MM-dd'T'HH:mmZ`
                                     | `yyyy-MM-dd'T'HH:mmz`
                                     | `yyyy-MM-dd'T'HH:mm z`
                                     | `yyyy-MM-dd'T'HHZ`
                                     | `yyyy-MM-dd'T'HHz`
                                     | `yyyy-MM-dd'T'HH z`
.2+^.<| +org.joda.time.DateTimeZone+ | `[+-]hh:mm` (reg.ex.)
                                     | all _timezone ids_ known by Joda-Time.
.3+^.<| +org.joda.time.Duration+     | `PTa.bS`
                                     | `PdDThHmMsS`
                                     | `ddThh:mm:ss`
.2+^.<| +org.joda.time.Period+       | `PyYmMwWdDThHmMsS`
                                     | `Pyyyy-mm-ddThh:mm:ss`
.4+^.<| +org.joda.time.LocalDate+    | `yyyy ['-' MM ['-' dd]]`
                                     | `yyyy ['-' DDD]`
                                     | `LocalDateConverter`
                                     | `yyyy ['-' dd ['-' MM]]`
.4+^.<| +org.joda.time.LocalTime+    | `['T']` _time-element_
                                     |  _time-element_ = HH [_minute-element_] _or_ [_fraction_]
                                     |  _minute-element_ = ':' mm [_second-element_] _or_ [_fraction_]
                                     |  _second-element_ = ':' ss [_fraction_]
                                     |  _fraction_       = ('.' _or_ ',') digit+`
|================================================================