[SPARK-30547][SQL] Add unstable annotation to the CalendarInterval class

[yaooqinn]

What changes were proposed in this pull request?

CalendarInterval is maintained as a private class but might be used in a public way by users
e.g.

scala> spark.udf.register("getIntervalMonth", (_:org.apache.spark.unsafe.types.CalendarInterval).months)

scala> sql("select interval 2 month 1 day a").selectExpr("getIntervalMonth(a)").show
+-------------------+
|getIntervalMonth(a)|
+-------------------+
|                  2|
+-------------------+

And it exists since 1.5.0, now we go to the 3.x era，may be it's time to make it public

Why are the changes needed?

make the interval more future-proofing

Does this PR introduce any user-facing change?

doc change

How was this patch tested?

add ut.

[SparkQA]

Test build #116922 has finished for PR 27258 at commit 1a90651.

• This patch passes all tests.
• This patch merges cleanly.
• This patch adds no public classes.

[cloud-fan]

data type? how about The class representing ...

[yaooqinn]

ok

[SparkQA]

Test build #116941 has finished for PR 27258 at commit 1cf83ec.

• This patch passes all tests.
• This patch merges cleanly.
• This patch adds no public classes.

[SparkQA]

Test build #116997 has finished for PR 27258 at commit d9b85ff.

• This patch passes all tests.
• This patch merges cleanly.
• This patch adds no public classes.

[cloud-fan]

thanks, merging to master!

[dongjoon-hyun]

Just a question: @cloud-fan .
Although this is technically correct, if this is going to public in 3.00, @since 3.0.0 is better?

[dongjoon-hyun]

If this is 1.5.0, people will get confused and may try to use it 2.4.x.

[dongjoon-hyun]

cc @gatorsmile , too.

[cloud-fan]

this is a good point. Do we have a clear rule about how to decide the since version. To me 3.0 is better here, as we've changed this class a lot in 3.0.

[yaooqinn]

checked the java doc about since https://www.oracle.com/technetwork/java/javase/documentation/index-137868.html#@since

When a class (or interface) is introduced, specify one since tag in its class description and no since tags in the members. Add a since tag only to members added in a later version than the class. ...

If a member changes from protected to public in a later release, the since tag would not change, even though it is now usable by any caller, not just subclassers.

1.5.0 should be fine I guess

[cloud-fan]

... the since tag would not change ...

This is different from what we are facing here. We are adding a since tag. not changing an existing one.

[yaooqinn]

raise a followup to fix this #27299, thanks @dongjoon-hyun @cloud-fan