From 8a1c712c2ed54fbd3eea14a6ee6fff24e9275812 Mon Sep 17 00:00:00 2001
From: Naoto Sato <naoto@openjdk.org>
Date: Fri, 19 Feb 2021 16:44:38 +0000
Subject: [PATCH] 8261728: SimpleDateFormat should link to DateTimeFormatter

Reviewed-by: bpb, rriggs, lancea, iris
---
 src/java.base/share/classes/java/text/DateFormat.java       | 5 ++++-
 src/java.base/share/classes/java/text/SimpleDateFormat.java | 5 ++++-
 2 files changed, 8 insertions(+), 2 deletions(-)

diff --git a/src/java.base/share/classes/java/text/DateFormat.java b/src/java.base/share/classes/java/text/DateFormat.java
index f086c76c8f9..bf40a911cd4 100644
--- a/src/java.base/share/classes/java/text/DateFormat.java
+++ b/src/java.base/share/classes/java/text/DateFormat.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1996, 2020, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1996, 2021, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -147,6 +147,8 @@ import sun.util.locale.provider.LocaleServiceProviderPool;
  * It is recommended to create separate format instances for each thread.
  * If multiple threads access a format concurrently, it must be synchronized
  * externally.
+ * @apiNote Consider using {@link java.time.format.DateTimeFormatter} as an
+ * immutable and thread-safe alternative.
  *
  * @implSpec
  * <ul><li>The {@link #format(Date, StringBuffer, FieldPosition)} and
@@ -173,6 +175,7 @@ import sun.util.locale.provider.LocaleServiceProviderPool;
  * @see          java.util.Calendar
  * @see          java.util.GregorianCalendar
  * @see          java.util.TimeZone
+ * @see          java.time.format.DateTimeFormatter
  * @author       Mark Davis, Chen-Lieh Huang, Alan Liu
  * @since 1.1
  */
diff --git a/src/java.base/share/classes/java/text/SimpleDateFormat.java b/src/java.base/share/classes/java/text/SimpleDateFormat.java
index 6205dfb479f..265bb0318d8 100644
--- a/src/java.base/share/classes/java/text/SimpleDateFormat.java
+++ b/src/java.base/share/classes/java/text/SimpleDateFormat.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1996, 2019, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1996, 2021, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -428,12 +428,15 @@ import sun.util.locale.provider.TimeZoneNameUtility;
  * It is recommended to create separate format instances for each thread.
  * If multiple threads access a format concurrently, it must be synchronized
  * externally.
+ * @apiNote Consider using {@link java.time.format.DateTimeFormatter} as an
+ * immutable and thread-safe alternative.
  *
  * @see          <a href="http://docs.oracle.com/javase/tutorial/i18n/format/simpleDateFormat.html">Java Tutorial</a>
  * @see          java.util.Calendar
  * @see          java.util.TimeZone
  * @see          DateFormat
  * @see          DateFormatSymbols
+ * @see          java.time.format.DateTimeFormatter
  * @author       Mark Davis, Chen-Lieh Huang, Alan Liu
  * @since 1.1
  */