Download and installation

Table Of Contents

Where to download?
Standard installation procedures
About the module dependency tree
Starting in an OSGi-environment
Special notes for Android platform
Historical notes on earlier versions

Where to download?

There are two sources where you can download Time4J: GitHub and Maven. The latest versions can be found on GitHub. Another source is Maven Central (just use the search word "Time4J").

It is strongly recommended to use the latest versions where possible. Starting with the version line v5.x - Time4J can be considered as stable. No backwards incompatible breaks should be expected unless any class might be marked as experimental. It works from Java 8+ onwards. Note: The tzdata-module uses the version number scheme "5.x-2###{letter}" where the qualifier part 2###{letter} is identical to the TZDB-version of IANA (example: 2018g).

Standard installation procedures

Either you just drop the downloaded jar-files (one jar-file exists for every module) into your classpath, or you use Apache Maven inside your IDE with following dependency section (example): 

	<dependency>
		<groupId>net.time4j<groupId>
		<artifactId>time4j-base<artifactId>
		<version>5.9.1<version>
	</dependency>

Every module of Time4J has an artifactId in this form: time4j-{module-identifier}. Following modules are offered:

A "module-info.java" for the usage in Java 9+ might look like:

	module my.app {
		requires net.time4j.base;
		requires net.time4j.tzdb;
	}

About the module dependency tree

The base-module is always obligatory. However, if you use Maven then it is not necessary to specify the whole tree. For example, if you need the JDBC-adapter of Time4J, too, then you can just point to the sqlxml-module and can leave out the explicit reference to the parent module base. 

 {base}
 |
 +---{sqlxml}
 +---{tzdata}
 +---{ui}

Starting in an OSGi-environment

OSGi-based applications should define the system property "net.time4j.base.useClassloaderOnly" for the sake of performant and successful resource loading. So the strong recommendation is to start the Java process with: "-Dnet.time4j.base.useClassloaderOnly=true"

Special notes for the Android platform

  1. The sister project Time4A manages and yields the Android version of Time4J.
  2. It is licensed under Apache 2.0 which fits better the underlying Android platform.
  3. Time4A delivers the stand-alone time4j-android-artifact as AAR-library. It contains a subset of Time4J (without the range-package and some other classes like WindowsZone). The minimum version should be v4.0 or later. The best available timezone data are already included and indicated by an extra classifier behind the version (for example: 4.7-2020a).
  4. Time4A is capable of observing any settings of the system timezone on mobile devices. This is done by registering a specialized BroadcastReceiver.
  5. The Android version of TickProvider deploys the best available clock using android.os.SystemClock.elapsedRealtimeNanos().
  6. Time-specific format patterns are aware of the user-preference for 12/24-hour-format if the system locale is chosen.
  7. Using Proguard (with "minifiyEnabled=true") will help to shrink the size of Time4A to an acceptable size.
  8. The standard service provider infrastructure of Time4J does not work well. Time4A instead uses assets for managing its own resources.
  9. It is recommended to develop the time-apps in Android Studio. Then you just need following section within your build.gradle-file (example): 
    dependencies {
    compile group: 'net.time4j', name: 'time4j-android', version: '4.7-2020a'
}
  10. Finally you should initialize your time-app as follows: Either you write an extra Application-class which inherits from the Time4A-class net.time4j.android.TimeApplication - or you manually initialize your application like this: 
      public class MyApplication extends Application {
    @Override
    public void onCreate() {
      super.onCreate();
      ApplicationStarter.initialize(this, true);
    }
  }

Historical notes on earlier versions

Outdated versions of Time4J or Time4A can still be found on Maven Central. See the detailed instructions for downloading, structure and usage.