5

I have stumbled upon Hashing class from com.google.common.hash package. Intellij IDEA shows following warning if I am using functions of that class:

The class itself is annotated with @Beta annotation:

The description of @Beta annotation says:

Signifies that a public API (public class, method or field) is subject to incompatible changes, or even removal, in a future release. An API bearing this annotation is exempt from any compatibility guarantees made by its containing library. Note that the presence of this annotation implies nothing about the quality or performance of the API ...

  • So the implementation of the API is fine and stable?

... in question, only the fact that it is not "API-frozen." It is generally safe for applications to depend on beta APIs, at the cost of some extra work ...

  • Which kind of extra work?

... during upgrades. However it is generally inadvisable for libraries (which get included on users' CLASSPATHs, outside the library developers' control) to do so.

The question is whether it is safe / stable to use mentioned class and its functionality? What is the tradeoff while using a beta API?

Vladas Maier
  • 2,054
  • 2
  • 22
  • 34
  • 1
    Just use Java's standard crypto APIs, i.e. [java.security.MessageDigest](https://docs.oracle.com/javase/7/docs/api/java/security/MessageDigest.html), see also https://stackoverflow.com/a/5531479/1015327 – JimmyB Oct 30 '18 at 11:26

3 Answers3

7

The implementaion of the API is fine, you can rely on that since it is an extensively used library from google.

As for stability - you can do a little research here and compare a couple of versions of this API a year apart. Let's say, 23.0 versus 27.0-jre

https://google.github.io/guava/releases/23.0/api/docs/com/google/common/hash/Hashing.html

https://google.github.io/guava/releases/27.0-jre/api/docs/com/google/common/hash/Hashing.html

If you do a diff, the API's from different years (2017 versus 2018) are exactly the same.

Therefore, I would interpret the @Beta here as a heads-up that "be aware, this API may change in future", but in practise the API is both stable, reliable and heavily used.

Maybe at some point, the google developers may choose to remove the @Beta annotation. Or maybe they intend to, or have forgotten (speculative...)

The "extra work" referred to means that, if you build an application using this API, you may need to refactor your application slightly (imagine that a method signiture changes, or a method becomes deprecated and replaced) if you need to upgrade to the newest version of this API.

The degree of work there depends on how heavily and how often you use the API, and how deep the dependency on that API is (transitively, through other libraries, for example - those would also need to be rebuilt).

In summary, in this case - "dont worry, move along" :)

vikingsteve
  • 38,481
  • 23
  • 112
  • 156
1

So the implementation of the API is fine and stable?
No way to know from this annotation.
To answer that you need to know how widely used it is, and for how long.

Which kind of extra work?
The kind of extra work that you have to do when a method that required only 1 parameter and returned String now requires 3 parameters, and returns a List<String>.
i.e.: Code that uses this API might need to change due to API change.

Yoav Gur
  • 1,366
  • 9
  • 15
1

So the implementation of the API is fine and stable?

The quoted text says that the API is "subject to incompatible changes". That means that it (the API) is not stable.

Note also that the quoted text explicitly states that the annotation is saying nothing about whether or not the API's implementation works.

But also note that this is not a yes / no issue. It is actually a yes / no / maybe issue. Some questions don't have answers.

Which kind of extra work?

Rewriting some of your code ... if the API changes.

The question is whether it is safe / stable to use mentioned class and its functionality?

This requires the ability to predict the future. It is unanswerable. (Unless you ask the people who put that annotation on that API. They may be able to make a reliable prediction ...)

It is also unanswerable because it depends on what you mean by safe, and what context you intend to use the Hashing class in.

What is the tradeoff while using a beta API?

The tradeoff is self evident:

  • On the plus side, you get to use new API functionality that may be beneficial to your application in the long run. (And if there is no evidence that it may be beneficial, this whole discussion is moot!)

  • On the minus side, you may have to rewrite some of your code if the authors modify the API ... as they say they might do.

Stephen C
  • 698,415
  • 94
  • 811
  • 1,216
  • Thank you for your answer. You have addressed a few good points. I know the definition of *safe* is not clear. I want to use it for generating a `SHA256` hash value (as `Integer`) from a given `String`. – Vladas Maier Oct 30 '18 at 10:15