36. Returning an identity string
So, what’s an identity string? An identity string is a string built from an object without calling the overridden toString() or hashCode(). It is equivalent to the following concatenation:
object.getClass().getName() + “@”
+ Integer.toHexString(System.identityHashCode(object))
Starting with JDK 19, this string is wrapped in Objects.toIdentityString(Object object). Consider the following class (object):
public class MyPoint {
private final int x;
private final int y;
private final int z;
…
@Override
public String toString() {
return “MyPoint{” + “x=” + x + “, y=” + y
+ “, z=” + z + ‘}’;
}
}
By calling toIdentityString() we obtain something as follows:
MyPoint p = new MyPoint(1, 2, 3);
// modern.challenge.MyPoint@76ed5528
Objects.toIdentityString(p);
Obviously, the overridden MyPoint.toString() method was not called. If we print out the hash code of p, we get 76ed5528, which is exactly what toIdentityString() returned. Now, let’s override hashCode() as well:
@Override
public int hashCode() {
int hash = 7;
hash = 23 * hash + this.x;
hash = 23 * hash + this.y;
hash = 23 * hash + this.z;
return hash;
}
This time, toIdentityString() returns the same thing, while our hashCode() returns 14ef3.
37. Adding code snippets in Java API documentation
I’m sure that you are familiar with generating Java API documentation (Javadoc) for your projects. We can do it via the javadoc tool from the command line, via IDE support, via the Maven plugin (maven-javadoc-plugin), and so on.A common case in writing the Javadoc consists of adding snippets of code to exemplify the usage of a non-trivial class or method. Before JDK 18, adding snippets of code in documentation can be done via {@code…} or <pre> tag. The added code is treated as plain text, is not validated for correctness, and is not discoverable by other tools. Let’s quickly have an example:
/**
* A telemeter with laser ranging from 0 to 60 ft including
* calculation of surfaces and volumes with high-precision
*
* <pre>{@code
* Telemeter.Calibrate.at(0.00001);
* Telemeter telemeter = new Telemeter(0.15, 2, “IP54”);
* }</pre>
*/
public class Telemeter {
…
In the bundled code you can see the full example. The Javadoc is generated at build time via the Maven plugin (maven-javadoc-plugin), so simply trigger a build.Starting with JDK 18, JEP 413 – Code Snippets in Java API Documentation, we have brand new support for adding snippets of code in documentation via the {@snippet…} tag. The code added via @snippet is can be discovered and validated by third-party tools (not by the javadoc tool itself).For instance, the previous snippet can be added via @snippet as follows:
/**
* A telemeter with laser ranging from 0 to 60 ft including
* calculation of surfaces and volumes with high-precision
*
* {@snippet :
* Telemeter.Calibrate.at(0.00001);
* Telemeter telemeter = new Telemeter(0.15, 2, “IP54”);
* }
*/
public class Telemeter {
…
A screenshot of the output is in the following figure:
Figure 2.13 – Simple output from @snippet