From 5e8ef54fb0cb9b525a39fc6cdb4617ce308d0f81 Mon Sep 17 00:00:00 2001
From: Semyon Sadetsky <ssadetsky@openjdk.org>
Date: Fri, 29 Jul 2016 11:08:34 +0300
Subject: [PATCH] 8016313: java.awt.Headless exception has no spec since its
 creation

Reviewed-by: prr
---
 .../classes/java/awt/HeadlessException.java   | 33 ++++++++++++++++---
 1 file changed, 29 insertions(+), 4 deletions(-)

diff --git a/jdk/src/java.desktop/share/classes/java/awt/HeadlessException.java b/jdk/src/java.desktop/share/classes/java/awt/HeadlessException.java
index 5809ffd9faf..55ba37b1e82 100644
--- a/jdk/src/java.desktop/share/classes/java/awt/HeadlessException.java
+++ b/jdk/src/java.desktop/share/classes/java/awt/HeadlessException.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2000, 2014, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2000, 2016, 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
@@ -28,10 +28,14 @@ package java.awt;
 /**
  * Thrown when code that is dependent on a keyboard, display, or mouse
  * is called in an environment that does not support a keyboard, display,
- * or mouse.
+ * or mouse. Any code that depends on any of those devices should firstly
+ * ensure their availability using the {@code GraphicsEnvironment.isHeadless()}
+ * method and throw {@code HeadlessException} if the latter returns
+ * {@code true}.
  *
  * @since 1.4
  * @author  Michael Martak
+ * @see GraphicsEnvironment#isHeadless
  */
 public class HeadlessException extends UnsupportedOperationException {
     /*
@@ -40,12 +44,24 @@ public class HeadlessException extends UnsupportedOperationException {
     private static final long serialVersionUID = 167183644944358563L;
 
     /**
-     * Constructs new {@code HeadlessException}
+     * Constructs new {@code HeadlessException} with empty message.
+     * For such {@code HeadlessException} the default headless error message
+     * may be auto-generated for some platforms.
+     * The text of the default headless message may depend on
+     * whether the GraphicsEnvironment is in fact headless.
+     * That is, the default headless message is both system and environmentally
+     * dependent.
      */
     public HeadlessException() {}
 
     /**
      * Create a new instance with the specified detailed error message.
+     * For some platforms the default headless error message may be
+     * added at the end of the specified message.
+     * The text of the default headless message may depend on
+     * whether the GraphicsEnvironment is in fact headless.
+     * That is, the default headless message is both system and environmentally
+     * dependent.
      *
      * @param  msg the error message
      */
@@ -54,7 +70,16 @@ public class HeadlessException extends UnsupportedOperationException {
     }
 
     /**
-     * {@inheritDoc}
+     * Returns the detail message string of this {@code HeadlessException}.
+     * Depending on the platform the message specified in the constructor may
+     * be followed by the default headless error message.
+     * The text of the default headless message may depend on
+     * whether the GraphicsEnvironment is in fact headless.
+     * That is, the default headless message is both system and environmentally
+     * dependent.
+     *
+     * @return  the detail message string of this {@code HeadlessException}
+     *          instance (which may be {@code null}).
      */
     public String getMessage() {
         String superMessage = super.getMessage();