Details
-
CSR
-
Resolution: Approved
-
P4
-
None
-
binary
-
minimal
-
Java API
-
SE
Description
Summary
Some improvements to javadoc have identified a number of missing javadoc tags and comments in the desktop module.
Problem
If the class implements the Serializable interface its internal state became part of the public API, and as such should be properly specified.
Solution
Add all missing specifications.
Specification
Link for convenience:
https://openjdk.github.io/cr/?repo=jdk&pr=369&range=01
src/java.desktop/share/classes/java/applet/Applet.java
@@ -99,7 +99,10 @@ public Applet() throws HeadlessException {
/**
* Read an applet from an object input stream.
*
- * @param s an object input stream
+ * @param s the {@code ObjectInputStream} to read
+ * @throws ClassNotFoundException if the class of a serialized object could
+ * not be found
+ * @throws IOException if an I/O error occurs
* @throws HeadlessException if {@code GraphicsEnvironment.isHeadless()}
* returns {@code true}
* @serial
src/java.desktop/share/classes/java/awt/AWTEvent.java
@@ -87,6 +87,9 @@
*/
public abstract class AWTEvent extends EventObject {
+ /**
+ * The private data.
+ */
private byte[] bdata;
/**
src/java.desktop/share/classes/java/awt/AWTKeyStroke.java
@@ -77,9 +79,25 @@
//A key withing the cache
private static AWTKeyStroke APP_CONTEXT_KEYSTROKE_KEY = new AWTKeyStroke();
+ /**
+ * The character value for a keyboard key.
+ */
private char keyChar = KeyEvent.CHAR_UNDEFINED;
+
+ /**
+ * The key code for this {@code AWTKeyStroke}.
+ */
private int keyCode = KeyEvent.VK_UNDEFINED;
+
+ /**
+ * The bitwise-ored combination of any modifiers.
+ */
private int modifiers;
+
+ /**
+ * {@code true} if this {@code AWTKeyStroke} corresponds to a key release;
+ * {@code false} otherwise.
+ */
private boolean onKeyRelease;
static {
src/java.desktop/share/classes/java/awt/Button.java
@@ -428,9 +434,8 @@ protected String paramString() {
/* Serialization support.
*/
-
- /*
- * Button Serial Data Version.
+ /**
+ * Serialized data version.
* @serial
*/
private int buttonSerializedDataVersion = 1;
@@ -449,7 +454,8 @@ protected String paramString() {
* {@code actionListenerK} indicating an
* {@code ActionListener} object
*
- * @param s the {@code ObjectOutputStream} to write
+ * @param s the {@code ObjectOutputStream} to write
+ * @throws IOException if an I/O error occurs
* @see AWTEventMulticaster#save(ObjectOutputStream, String, EventListener)
* @see java.awt.Component#actionListenerK
* @see #readObject(ObjectInputStream)
@@ -469,10 +475,12 @@ private void writeObject(ObjectOutputStream s)
* receive action events fired by the button.
* Unrecognized keys or values will be ignored.
*
- * @param s the {@code ObjectInputStream} to read
- * @exception HeadlessException if
- * {@code GraphicsEnvironment.isHeadless} returns
- * {@code true}
+ * @param s the {@code ObjectInputStream} to read
+ * @throws ClassNotFoundException if the class of a serialized object could
+ * not be found
+ * @throws IOException if an I/O error occurs
+ * @throws HeadlessException if {@code GraphicsEnvironment.isHeadless()}
+ * returns {@code true}
* @serial
* @see #removeActionListener(ActionListener)
* @see #addActionListener(ActionListener)
src/java.desktop/share/classes/java/awt/CardLayout.java
@@ -68,8 +67,8 @@
*/
Vector<Card> vector = new Vector<>();
- /*
- * A pair of Component and String that represents its name.
+ /**
+ * A pair of component and string that represents its name.
*/
class Card implements Serializable {
static final long serialVersionUID = 6640330810709497518L;
@@ -110,10 +109,10 @@ public Card(String cardName, Component cardComponent) {
/**
* @serialField tab Hashtable
* deprecated, for forward compatibility only
- * @serialField hgap int
- * @serialField vgap int
- * @serialField vector Vector
- * @serialField currentCard int
+ * @serialField hgap int the horizontal Layout gap
+ * @serialField vgap int the vertical Layout gap
+ * @serialField vector Vector the pairs of components and their names
+ * @serialField currentCard int the index of Component currently displayed
*/
private static final ObjectStreamField[] serialPersistentFields = {
new ObjectStreamField("tab", Hashtable.class),
@@ -559,6 +558,11 @@ public String toString() {
/**
* Reads serializable fields from stream.
+ *
+ * @param s the {@code ObjectInputStream} to read
+ * @throws ClassNotFoundException if the class of a serialized object could
+ * not be found
+ * @throws IOException if an I/O error occurs
*/
@SuppressWarnings("unchecked")
private void readObject(ObjectInputStream s)
@@ -591,6 +595,9 @@ private void readObject(ObjectInputStream s)
/**
* Writes serializable fields to stream.
+ *
+ * @param s the {@code ObjectOutputStream} to write
+ * @throws IOException if an I/O error occurs
*/
private void writeObject(ObjectOutputStream s)
throws IOException
src/java.desktop/share/classes/java/awt/Checkbox.java
@@ -602,8 +610,8 @@ protected String paramString() {
/* Serialization support.
*/
- /*
- * Serialized data version
+ /**
+ * Serialized data version.
* @serial
*/
private int checkboxSerializedDataVersion = 1;
@@ -615,7 +623,8 @@ protected String paramString() {
* {@code ItemListeners} are detected and
* no attempt is made to serialize them.
*
- * @param s the {@code ObjectOutputStream} to write
+ * @param s the {@code ObjectOutputStream} to write
+ * @throws IOException if an I/O error occurs
* @serialData {@code null} terminated sequence of 0
* or more pairs; the pair consists of a {@code String}
* and an {@code Object}; the {@code String} indicates
@@ -642,10 +651,12 @@ private void writeObject(ObjectOutputStream s)
* item events fired by the {@code Checkbox}.
* Unrecognized keys or values will be ignored.
*
- * @param s the {@code ObjectInputStream} to read
- * @exception HeadlessException if
- * {@code GraphicsEnvironment.isHeadless} returns
- * {@code true}
+ * @param s the {@code ObjectInputStream} to read
+ * @throws ClassNotFoundException if the class of a serialized object could
+ * not be found
+ * @throws IOException if an I/O error occurs
+ * @throws HeadlessException if {@code GraphicsEnvironment.isHeadless()}
+ * returns {@code true}
* @serial
* @see #removeItemListener(ItemListener)
* @see #addItemListener(ItemListener)
src/java.desktop/share/classes/java/awt/CheckboxMenuItem.java
@@ -426,8 +427,8 @@ public String paramString() {
/* Serialization support.
*/
- /*
- * Serial Data Version
+ /**
+ * Serialized data version.
* @serial
*/
private int checkboxMenuItemSerializedDataVersion = 1;
@@ -439,7 +440,8 @@ public String paramString() {
* {@code ItemListeners} are detected and
* no attempt is made to serialize them.
*
- * @param s the {@code ObjectOutputStream} to write
+ * @param s the {@code ObjectOutputStream} to write
+ * @throws IOException if an I/O error occurs
* @serialData {@code null} terminated sequence of
* 0 or more pairs; the pair consists of a {@code String}
* and an {@code Object}; the {@code String} indicates
@@ -460,17 +462,20 @@ private void writeObject(ObjectOutputStream s)
s.writeObject(null);
}
- /*
+ /**
* Reads the {@code ObjectInputStream} and if it
* isn't {@code null} adds a listener to receive
* item events fired by the {@code Checkbox} menu item.
* Unrecognized keys or values will be ignored.
*
- * @param s the {@code ObjectInputStream} to read
+ * @param s the {@code ObjectInputStream} to read
+ * @throws ClassNotFoundException if the class of a serialized object could
+ * not be found
+ * @throws IOException if an I/O error occurs
* @serial
- * @see removeActionListener()
- * @see addActionListener()
- * @see #writeObject
+ * @see #removeActionListener(ActionListener)
+ * @see #addActionListener(ActionListener)
+ * @see #writeObject(ObjectOutputStream)
*/
private void readObject(ObjectInputStream s)
throws ClassNotFoundException, IOException
src/java.desktop/share/classes/java/awt/Choice.java
@@ -654,8 +658,8 @@ protected String paramString() {
/* Serialization support.
*/
- /*
- * Choice Serial Data Version.
+ /**
+ * Serialized data version.
* @serial
*/
private int choiceSerializedDataVersion = 1;
@@ -667,7 +671,8 @@ protected String paramString() {
* {@code ItemListeners} are detected and
* no attempt is made to serialize them.
*
- * @param s the {@code ObjectOutputStream} to write
+ * @param s the {@code ObjectOutputStream} to write
+ * @throws IOException if an I/O error occurs
* @serialData {@code null} terminated sequence of 0
* or more pairs; the pair consists of a {@code String}
* and an {@code Object}; the {@code String} indicates
@@ -694,10 +699,12 @@ private void writeObject(ObjectOutputStream s)
* item events fired by the {@code Choice} item.
* Unrecognized keys or values will be ignored.
*
- * @param s the {@code ObjectInputStream} to read
- * @exception HeadlessException if
- * {@code GraphicsEnvironment.isHeadless} returns
- * {@code true}
+ * @param s the {@code ObjectInputStream} to read
+ * @throws ClassNotFoundException if the class of a serialized object could
+ * not be found
+ * @throws IOException if an I/O error occurs
+ * @throws HeadlessException if {@code GraphicsEnvironment.isHeadless()}
+ * returns {@code true}
* @serial
* @see #removeItemListener(ItemListener)
* @see #addItemListener(ItemListener)
src/java.desktop/share/classes/java/awt/Component.java
@@ -716,6 +716,9 @@ final AccessControlContext getAccessControlContext() {
return acc;
}
+ /**
+ * Whether the component is packed or not;
+ */
boolean isPacked = false;
/**
@@ -8328,7 +8331,7 @@ public boolean isFocusOwner() {
return hasFocus();
}
- /*
+ /**
* Used to disallow auto-focus-transfer on disposal of the focus owner
* in the process of disposing its parent container.
*/
@@ -8903,7 +8906,8 @@ private void doSwingSerialization() {
* The non-serializable listeners are detected and
* no attempt is made to serialize them.
*
- * @param s the {@code ObjectOutputStream} to write
+ * @param s the {@code ObjectOutputStream} to write
+ * @throws IOException if an I/O error occurs
* @serialData {@code null} terminated sequence of
* 0 or more pairs; the pair consists of a {@code String}
* and an {@code Object}; the {@code String} indicates
@@ -8974,7 +8978,10 @@ private void writeObject(ObjectOutputStream s)
* of events fired by the component.
* Unrecognized keys or values will be ignored.
*
- * @param s the {@code ObjectInputStream} to read
+ * @param s the {@code ObjectInputStream} to read
+ * @throws ClassNotFoundException if the class of a serialized object could
+ * not be found
+ * @throws IOException if an I/O error occurs
* @see #writeObject(ObjectOutputStream)
*/
private void readObject(ObjectInputStream s)
src/java.desktop/share/classes/java/awt/ComponentOrientation.java
@@ -201,6 +201,9 @@ public static ComponentOrientation getOrientation(ResourceBundle bdl)
return result;
}
+ /**
+ * The bitwise-ored combination of flags.
+ */
private int orientation;
private ComponentOrientation(int value)
src/java.desktop/share/classes/java/awt/Container.java
@@ -43,30 +48,26 @@
/**
* A generic Abstract Window Toolkit(AWT) container object is a component
@@ -3666,7 +3667,8 @@ public void addPropertyChangeListener(String propertyName,
* is Serializable; otherwise, {@code null} is written.</li>
* </ul>
*
- * @param s the {@code ObjectOutputStream} to write
+ * @param s the {@code ObjectOutputStream} to write
+ * @throws IOException if an I/O error occurs
* @serialData {@code null} terminated sequence of 0 or more pairs;
* the pair consists of a {@code String} and {@code Object};
* the {@code String} indicates the type of object and
@@ -3713,7 +3715,10 @@ private void writeObject(ObjectOutputStream s) throws IOException {
* as optional data.</li>
* </ul>
*
- * @param s the {@code ObjectInputStream} to read
+ * @param s the {@code ObjectInputStream} to read
+ * @throws ClassNotFoundException if the class of a serialized object could
+ * not be found
+ * @throws IOException if an I/O error occurs
* @serial
* @see #addContainerListener
* @see #writeObject(ObjectOutputStream)
src/java.desktop/share/classes/java/awt/ContainerOrderFocusTraversalPolicy.java
@@ -62,7 +64,14 @@
{
private static final PlatformLogger log = PlatformLogger.getLogger("java.awt.ContainerOrderFocusTraversalPolicy");
+ /**
+ * This constant is used when the forward focus traversal order is active.
+ */
private final int FORWARD_TRAVERSAL = 0;
+
+ /**
+ * This constant is used when the backward focus traversal order is active.
+ */
private final int BACKWARD_TRAVERSAL = 1;
/*
@@ -70,6 +79,10 @@
*/
private static final long serialVersionUID = 486933713763926351L;
+ /**
+ * Whether this {@code ContainerOrderFocusTraversalPolicy} transfers focus
+ * down-cycle implicitly.
+ */
private boolean implicitDownCycleTraversal = true;
src/java.desktop/share/classes/java/awt/Dialog.java
@@ -1587,6 +1596,16 @@ private void checkModalityPermission(ModalityType mt) {
}
}
+ /**
+ * Reads serializable fields from stream.
+ *
+ * @param s the {@code ObjectInputStream} to read
+ * @throws ClassNotFoundException if the class of a serialized object could
+ * not be found
+ * @throws IOException if an I/O error occurs
+ * @throws HeadlessException if {@code GraphicsEnvironment.isHeadless()}
+ * returns {@code true}
+ */
private void readObject(ObjectInputStream s)
throws ClassNotFoundException, IOException, HeadlessException
{
src/java.desktop/share/classes/java/awt/FileDialog.java
@@ -60,38 +62,38 @@
*/
public static final int SAVE = 1;
- /*
+ /**
* There are two {@code FileDialog} modes: {@code LOAD} and
* {@code SAVE}.
* This integer will represent one or the other.
* If the mode is not specified it will default to {@code LOAD}.
*
* @serial
- * @see getMode()
- * @see setMode()
+ * @see #getMode
+ * @see #setMode
* @see java.awt.FileDialog#LOAD
* @see java.awt.FileDialog#SAVE
*/
int mode;
- /*
+ /**
* The string specifying the directory to display
* in the file dialog. This variable may be {@code null}.
*
* @serial
- * @see getDirectory()
- * @see setDirectory()
+ * @see #getDirectory
+ * @see #setDirectory
*/
String dir;
- /*
+ /**
* The string specifying the initial value of the
* filename text field in the file dialog.
* This variable may be {@code null}.
*
* @serial
- * @see getFile()
- * @see setFile()
+ * @see #getFile
+ * @see #setFile
*/
String file;
@@ -114,16 +116,16 @@
*/
private boolean multipleMode = false;
- /*
+ /**
* The filter used as the file dialog's filename filter.
* The file dialog will only be displaying files whose
* names are accepted by this filter.
* This variable may be {@code null}.
*
* @serial
- * @see #getFilenameFilter()
- * @see #setFilenameFilter()
- * @see FileNameFilter
+ * @see #getFilenameFilter
+ * @see #setFilenameFilter
+ * @see FilenameFilter
*/
@SuppressWarnings("serial") // Not statically typed as Serializable
FilenameFilter filter;
@@ -598,7 +600,10 @@ public synchronized void setFilenameFilter(FilenameFilter filter) {
* either a {@code dir} or a {@code file}
* equal to an empty string to {@code null}.
*
- * @param s the {@code ObjectInputStream} to read
+ * @param s the {@code ObjectInputStream} to read
+ * @throws ClassNotFoundException if the class of a serialized object could
+ * not be found
+ * @throws IOException if an I/O error occurs
*/
private void readObject(ObjectInputStream s)
throws ClassNotFoundException, IOException
src/java.desktop/share/classes/java/awt/FlowLayout.java
@@ -662,6 +663,11 @@ public void layoutContainer(Container target) {
* Reads this object out of a serialization stream, handling
* objects written by older versions of the class that didn't contain all
* of the fields we use now..
+ *
+ * @param stream the {@code ObjectInputStream} to read
+ * @throws ClassNotFoundException if the class of a serialized object could
+ * not be found
+ * @throws IOException if an I/O error occurs
*/
private void readObject(ObjectInputStream stream)
throws IOException, ClassNotFoundException
src/java.desktop/share/classes/java/awt/Font.java
@@ -1884,7 +1911,8 @@ public String toString() {
/**
* Writes default serializable fields to a stream.
*
- * @param s the {@code ObjectOutputStream} to write
+ * @param s the {@code ObjectOutputStream} to write
+ * @throws IOException if an I/O error occurs
* @see AWTEventMulticaster#save(ObjectOutputStream, String, EventListener)
* @see #readObject(java.io.ObjectInputStream)
*/
@@ -1907,7 +1935,10 @@ private void writeObject(java.io.ObjectOutputStream s)
* Reads the {@code ObjectInputStream}.
* Unrecognized keys or values will be ignored.
*
- * @param s the {@code ObjectInputStream} to read
+ * @param s the {@code ObjectInputStream} to read
+ * @throws ClassNotFoundException if the class of a serialized object could
+ * not be found
+ * @throws IOException if an I/O error occurs
* @serial
* @see #writeObject(java.io.ObjectOutputStream)
*/
src/java.desktop/share/classes/java/awt/Frame.java
@@ -345,11 +345,14 @@
*/
boolean mbManagement = false; /* used only by the Motif impl. */
+ /**
+ * The bitwise mask of frame state constants.
+ */
// XXX: uwe: abuse old field for now
// will need to take care of serialization
private int state = NORMAL;
- /*
+ /**
* The Windows owned by the Frame.
* Note: in 1.2 this has been superseded by Window.ownedWindowList
*
@@ -1176,7 +1179,8 @@ public int getCursorType() {
* an optional serializable icon {@code Image}, which is
* available as of 1.4.
*
- * @param s the {@code ObjectOutputStream} to write
+ * @param s the {@code ObjectOutputStream} to write
+ * @throws IOException if an I/O error occurs
* @serialData an optional icon {@code Image}
* @see java.awt.Image
* @see #getIconImage
@@ -1206,13 +1210,13 @@ private void writeObject(ObjectOutputStream s)
* will be thrown.
* Unrecognized keys or values will be ignored.
*
- * @param s the {@code ObjectInputStream} to read
- * @exception java.io.OptionalDataException if an icon {@code Image}
- * is not available, but anything other than an EOF
- * is detected
- * @exception HeadlessException if
- * {@code GraphicsEnvironment.isHeadless} returns
- * {@code true}
+ * @param s the {@code ObjectInputStream} to read
+ * @throws ClassNotFoundException if the class of a serialized object could
+ * not be found
+ * @throws java.io.OptionalDataException if an icon {@code Image} is not
+ * available, but anything other than an EOF is detected
+ * @throws HeadlessException if {@code GraphicsEnvironment.isHeadless()}
+ * returns {@code true}
* @see java.awt.GraphicsEnvironment#isHeadless()
* @see java.awt.Image
* @see #getIconImage
src/java.desktop/share/classes/java/awt/GridBagLayoutInfo.java
@@ -35,27 +35,65 @@
public class GridBagLayoutInfo implements java.io.Serializable {
- int width, height; /* number of cells: horizontal and vertical
- int startx, starty; /* starting point for layout
- int[] minWidth; /* largest minWidth in each column */
- int[]
minHeight; /* largest minHeight in each row
- double[] weightX; /* largest weight in each column
- double[]
weightY; /* largest weight in each row
- boolean hasBaseline; //* Whether or not baseline layout has been
- //* requested and one of the components
- //* has a valid baseline.
+ /**
+ * The number of cells: horizontal and vertical.
+ */
+ int width, height;
+
+ /**
+ * The starting point for layout.
+ */
+ int startx, starty;
+
+ /**
+ * The largest minWidth in each column.
+ */
+ int[] minWidth;
+
+ /**
+ * The largest minHeight in each row.
+ */
+ int[] minHeight;
+
+ /**
+ * The largest weight in each column.
+ */
+ double[] weightX;
+
+ /**
+ * The largest weight in each row.
+ */
+ double[] weightY;
+
+ /**
+ * Whether or not baseline layout has been requested and one of the
+ * components has a valid baseline.
+ */
+ boolean hasBaseline;
+
- short[] baselineType; /* The type of baseline for a particular
- row. A mix of the BaselineResizeBehavior
- //* constants (1 << ordinal())
- int[]
maxAscent; /* Max ascent (baseline).
- int[] maxDescent; /* Max descent (height - baseline)
+ /**
+ * The type of baseline for a particular row. A mix of the
+ * BaselineResizeBehavior constants
{code (1 << ordinal())}
+ */
+ short[] baselineType;
+
+ /**
+ * Max ascent (baseline).
+ */
+ int[] maxAscent;
+
+ /**
+ * Max descent (height - baseline)
+ */
+ int[] maxDescent;
src/java.desktop/share/classes/java/awt/Label.java
@@ -153,12 +157,16 @@ public Label(String text, int alignment) throws HeadlessException {
/**
* Read a label from an object input stream.
- * @exception HeadlessException if
- * {@code GraphicsEnvironment.isHeadless()} returns
- * {@code true}
+ *
+ * @param s the {@code ObjectInputStream} to read
+ * @throws ClassNotFoundException if the class of a serialized object could
+ * not be found
+ * @throws IOException if an I/O error occurs
+ * @throws HeadlessException if {@code GraphicsEnvironment.isHeadless()}
+ * returns {@code true}
* @serial
- * @since 1.4
* @see java.awt.GraphicsEnvironment#isHeadless
+ * @since 1.4
*/
private void readObject(ObjectInputStream s)
throws ClassNotFoundException, IOException, HeadlessException {
@@ -1234,7 +1244,8 @@ public synchronized void delItems(int start, int end) {
* {@code actionListenerK} indicating an
* {@code ActionListener} object
*
- * @param s the {@code ObjectOutputStream} to write
+ * @param s the {@code ObjectOutputStream} to write
+ * @throws IOException if an I/O error occurs
* @see AWTEventMulticaster#save(ObjectOutputStream, String, EventListener)
* @see java.awt.Component#itemListenerK
* @see java.awt.Component#actionListenerK
@@ -1264,10 +1275,12 @@ private void writeObject(ObjectOutputStream s)
* {@code List}.
* Unrecognized keys or values will be ignored.
*
- * @param s the {@code ObjectInputStream} to write
- * @exception HeadlessException if
- * {@code GraphicsEnvironment.isHeadless} returns
- * {@code true}
+ * @param s the {@code ObjectInputStream} to read
+ * @throws ClassNotFoundException if the class of a serialized object could
+ * not be found
+ * @throws IOException if an I/O error occurs
+ * @throws HeadlessException if {@code GraphicsEnvironment.isHeadless()}
+ * returns {@code true}
* @see #removeItemListener(ItemListener)
* @see #addItemListener(ItemListener)
* @see java.awt.GraphicsEnvironment#isHeadless
@@ -1532,8 +1545,15 @@ public void selectAllAccessibleSelection() {
// [[[FIXME]]] need to finish implementing this!!!
- private List parent;
- private int indexInParent;
+ /**
+ * The parent {@code List}.
+ */
+ private List parent;
+
+ /**
+ * The index in the parent.
+ */
+ private int indexInParent;
src/java.desktop/share/classes/java/awt/MediaTracker.java
@@ -923,6 +922,10 @@ void setStatus(int flag) {
}
}
+/**
+ * The entry of the list of {@code Images} that is being tracked by the
+ * {@code MediaTracker}.
+ */
@SuppressWarnings("serial") // MediaEntry does not have a no-arg ctor
class ImageMediaEntry extends MediaEntry implements ImageObserver,
java.io.Serializable {
src/java.desktop/share/classes/java/awt/Menu.java
@@ -526,7 +526,8 @@ void deleteShortcut(MenuShortcut s) {
/**
* Writes default serializable fields to stream.
*
- * @param s the {@code ObjectOutputStream} to write
+ * @param s the {@code ObjectOutputStream} to write
+ * @throws IOException if an I/O error occurs
* @see AWTEventMulticaster#save(ObjectOutputStream, String, EventListener)
* @see #readObject(ObjectInputStream)
*/
@@ -540,10 +541,12 @@ private void writeObject(java.io.ObjectOutputStream s)
* Reads the {@code ObjectInputStream}.
* Unrecognized keys or values will be ignored.
*
- * @param s the {@code ObjectInputStream} to read
- * @exception HeadlessException if
- * {@code GraphicsEnvironment.isHeadless} returns
- * {@code true}
+ * @param s the {@code ObjectInputStream} to read
+ * @throws ClassNotFoundException if the class of a serialized object could
+ * not be found
+ * @throws IOException if an I/O error occurs
+ * @throws HeadlessException if {@code GraphicsEnvironment.isHeadless()}
+ * returns {@code true}
* @see java.awt.GraphicsEnvironment#isHeadless
* @see #writeObject(ObjectOutputStream)
*/
src/java.desktop/share/classes/java/awt/MenuBar.java
@@ -427,7 +427,8 @@ public void deleteShortcut(MenuShortcut s) {
/**
* Writes default serializable fields to stream.
*
- * @param s the {@code ObjectOutputStream} to write
+ * @param s the {@code ObjectOutputStream} to write
+ * @throws IOException if an I/O error occurs
* @see AWTEventMulticaster#save(ObjectOutputStream, String, EventListener)
* @see #readObject(java.io.ObjectInputStream)
*/
@@ -441,10 +442,12 @@ private void writeObject(java.io.ObjectOutputStream s)
* Reads the {@code ObjectInputStream}.
* Unrecognized keys or values will be ignored.
*
- * @param s the {@code ObjectInputStream} to read
- * @exception HeadlessException if
- * {@code GraphicsEnvironment.isHeadless} returns
- * {@code true}
+ * @param s the {@code ObjectInputStream} to read
+ * @throws ClassNotFoundException if the class of a serialized object could
+ * not be found
+ * @throws IOException if an I/O error occurs
+ * @throws HeadlessException if {@code GraphicsEnvironment.isHeadless()}
+ * returns {@code true}
* @see java.awt.GraphicsEnvironment#isHeadless
* @see #writeObject(java.io.ObjectOutputStream)
*/
src/java.desktop/share/classes/java/awt/MenuComponent.java
@@ -438,10 +438,12 @@ protected final Object getTreeLock() {
/**
* Reads the menu component from an object input stream.
*
- * @param s the {@code ObjectInputStream} to read
- * @exception HeadlessException if
- * {@code GraphicsEnvironment.isHeadless} returns
- * {@code true}
+ * @param s the {@code ObjectInputStream} to read
+ * @throws ClassNotFoundException if the class of a serialized object could
+ * not be found
+ * @throws IOException if an I/O error occurs
+ * @throws HeadlessException if {@code GraphicsEnvironment.isHeadless()}
+ * returns {@code true}
* @serial
* @see java.awt.GraphicsEnvironment#isHeadless
*/
@@ -465,10 +467,11 @@ private void readObject(ObjectInputStream s)
/*
* --- Accessibility Support ---
- *
- * MenuComponent will contain all of the methods in interface Accessible,
- * though it won't actually implement the interface - that will be up
- * to the individual objects which extend MenuComponent.
+ */
+ /**
+ * MenuComponent will contain all of the methods in interface Accessible,
+ * though it won't actually implement the interface - that will be up
+ * to the individual objects which extend MenuComponent.
*/
@SuppressWarnings("serial") // Not statically typed as Serializable
AccessibleContext accessibleContext = null;
src/java.desktop/share/classes/java/awt/MenuItem.java
@@ -725,7 +725,8 @@ public String paramString() {
* as optional data. The non-serializable listeners are
* detected and no attempt is made to serialize them.
*
- * @param s the {@code ObjectOutputStream} to write
+ * @param s the {@code ObjectOutputStream} to write
+ * @throws IOException if an I/O error occurs
* @serialData {@code null} terminated sequence of 0
* or more pairs; the pair consists of a {@code String}
* and an {@code Object}; the {@code String}
@@ -751,10 +752,12 @@ private void writeObject(ObjectOutputStream s)
* action events fired by the {@code Menu} Item.
* Unrecognized keys or values will be ignored.
*
- * @param s the {@code ObjectInputStream} to read
- * @exception HeadlessException if
- * {@code GraphicsEnvironment.isHeadless} returns
- * {@code true}
+ * @param s the {@code ObjectInputStream} to read
+ * @throws ClassNotFoundException if the class of a serialized object could
+ * not be found
+ * @throws IOException if an I/O error occurs
+ * @throws HeadlessException if {@code GraphicsEnvironment.isHeadless()}
+ * returns {@code true}
* @see #removeActionListener(ActionListener)
* @see #addActionListener(ActionListener)
* @see #writeObject(ObjectOutputStream)
src/java.desktop/share/classes/java/awt/ScrollPane.java
@@ -672,6 +679,9 @@ public boolean isWheelScrollingEnabled() {
/**
* Writes default serializable fields to stream.
+ *
+ * @param s the {@code ObjectOutputStream} to write
+ * @throws IOException if an I/O error occurs
*/
private void writeObject(ObjectOutputStream s) throws IOException {
@@ -682,9 +692,13 @@ private void writeObject(ObjectOutputStream s) throws IOException {
/**
* Reads default serializable fields to stream.
- * @exception HeadlessException if
- * {@code GraphicsEnvironment.isHeadless()} returns
- * {@code true}
+ *
+ * @param s the {@code ObjectInputStream} to read
+ * @throws ClassNotFoundException if the class of a serialized object could
+ * not be found
+ * @throws IOException if an I/O error occurs
+ * @throws HeadlessException if {@code GraphicsEnvironment.isHeadless()}
+ * returns {@code true}
* @see java.awt.GraphicsEnvironment#isHeadless
*/
private void readObject(ObjectInputStream s)
@@ -719,6 +733,9 @@ private void readObject(ObjectInputStream s)
// }
}
+ /**
+ * Invoked when the value of the adjustable has changed.
+ */
class PeerFixer implements AdjustmentListener, java.io.Serializable
{
private static final long serialVersionUID = 1043664721353696630L;
src/java.desktop/share/classes/java/awt/ScrollPaneAdjustable.java
@@ -138,6 +138,10 @@
*/
private int blockIncrement = 1;
+ /**
+ * Specified adjustment listener to receive adjustment events from this
+ * {@code ScrollPaneAdjustable}.
+ */
@SuppressWarnings("serial") // Not statically typed as Serializable
private AdjustmentListener adjustmentListener;
src/java.desktop/share/classes/java/awt/Scrollbar.java
@@ -1171,7 +1178,8 @@ protected String paramString() {
* as optional data. The non-serializable listeners are
* detected and no attempt is made to serialize them.
*
- * @param s the {@code ObjectOutputStream} to write
+ * @param s the {@code ObjectOutputStream} to write
+ * @throws IOException if an I/O error occurs
* @serialData {@code null} terminated sequence of 0
* or more pairs; the pair consists of a {@code String}
* and an {@code Object}; the {@code String} indicates
@@ -1199,10 +1207,12 @@ private void writeObject(ObjectOutputStream s)
* {@code Scrollbar}.
* Unrecognized keys or values will be ignored.
*
- * @param s the {@code ObjectInputStream} to read
- * @exception HeadlessException if
- * {@code GraphicsEnvironment.isHeadless} returns
- * {@code true}
+ * @param s the {@code ObjectInputStream} to read
+ * @throws ClassNotFoundException if the class of a serialized object could
+ * not be found
+ * @throws IOException if an I/O error occurs
+ * @throws HeadlessException if {@code GraphicsEnvironment.isHeadless()}
+ * returns {@code true}
* @see java.awt.GraphicsEnvironment#isHeadless
* @see #writeObject(ObjectOutputStream)
*/
src/java.desktop/share/classes/java/awt/SystemColor.java
@@ -22,14 +22,14 @@
/**
* A class to encapsulate symbolic colors representing the color of
* native GUI objects on a system. For systems which support the dynamic
@@ -536,6 +536,8 @@ private Object readResolve() {
* each {@code SystemColor} object.
* @return a proxy {@code SystemColor} object with its value
* replaced by the corresponding system color index.
+ * @throws ObjectStreamException if a new object replacing this object could
+ * not be created
*/
private Object writeReplace() throws ObjectStreamException
{
src/java.desktop/share/classes/java/awt/TextArea.java
@@ -649,9 +650,13 @@ protected String paramString() {
/**
* Read the ObjectInputStream.
- * @exception HeadlessException if
- * {@code GraphicsEnvironment.isHeadless()} returns
- * {@code true}
+ *
+ * @param s the {@code ObjectInputStream} to read
+ * @throws ClassNotFoundException if the class of a serialized object could
+ * not be found
+ * @throws IOException if an I/O error occurs
+ * @throws HeadlessException if {@code GraphicsEnvironment.isHeadless()}
+ * returns {@code true}
* @see java.awt.GraphicsEnvironment#isHeadless
*/
private void readObject(ObjectInputStream s)
src/java.desktop/share/classes/java/awt/TextComponent.java
@@ -102,9 +111,11 @@
*/
int selectionEnd;
- // A flag used to tell whether the background has been set by
- // developer code (as opposed to AWT code). Used to determine
- // the background color of non-editable TextComponents.
+ /**
+ * A flag used to tell whether the background has been set by
+ * developer code (as opposed to AWT code). Used to determine
+ * the background color of non-editable TextComponents.
+ */
boolean backgroundSetByClientCode = false;
/**
@@ -766,6 +777,8 @@ private boolean canAccessClipboard() {
* is one of the following :
* textListenerK indicating and TextListener object.
*
+ * @param s the {@code ObjectOutputStream} to write
+ * @throws IOException if an I/O error occurs
* @see AWTEventMulticaster#save(ObjectOutputStream, String, EventListener)
* @see java.awt.Component#textListenerK
*/
@@ -794,9 +807,12 @@ private void writeObject(java.io.ObjectOutputStream s)
* TextComponent. Unrecognized keys or values will be
* ignored.
*
- * @exception HeadlessException if
- * {@code GraphicsEnvironment.isHeadless()} returns
- * {@code true}
+ * @param s the {@code ObjectInputStream} to read
+ * @throws ClassNotFoundException if the class of a serialized object could
+ * not be found
+ * @throws IOException if an I/O error occurs
+ * @throws HeadlessException if {@code GraphicsEnvironment.isHeadless()}
+ * returns {@code true}
* @see #removeTextListener
* @see #addTextListener
* @see java.awt.GraphicsEnvironment#isHeadless
@@ -1199,5 +1215,8 @@ public String getBeforeIndex(int part, int index) {
}
} // end of AccessibleAWTTextComponent
+ /**
+ * Whether support of input methods should be checked or not.
+ */
private boolean checkForEnableIM = true;
}
src/java.desktop/share/classes/java/awt/TextField.java
@@ -701,6 +705,8 @@ protected String paramString() {
* is one of the following :
* ActionListenerK indicating and ActionListener object.
*
+ * @param s the {@code ObjectOutputStream} to write
+ * @throws IOException if an I/O error occurs
* @see AWTEventMulticaster#save(ObjectOutputStream, String, EventListener)
* @see java.awt.Component#actionListenerK
*/
@@ -719,9 +725,12 @@ private void writeObject(ObjectOutputStream s)
* TextField. Unrecognized keys or values will be
* ignored.
*
- * @exception HeadlessException if
- * {@code GraphicsEnvironment.isHeadless()} returns
- * {@code true}
+ * @param s the {@code ObjectInputStream} to read
+ * @throws ClassNotFoundException if the class of a serialized object could
+ * not be found
+ * @throws IOException if an I/O error occurs
+ * @throws HeadlessException if {@code GraphicsEnvironment.isHeadless()}
+ * returns {@code true}
* @see #removeActionListener(ActionListener)
* @see #addActionListener(ActionListener)
* @see java.awt.GraphicsEnvironment#isHeadless
src/java.desktop/share/classes/java/awt/Toolkit.java
@@ -2211,6 +2211,9 @@ private static PropertyChangeSupport createPropertyChangeSupport(Toolkit toolkit
}
}
+ /**
+ * This is a utility class to support desktop properties.
+ */
@SuppressWarnings("serial")
private static class DesktopPropertyChangeSupport extends PropertyChangeSupport {
src/java.desktop/share/classes/java/awt/Window.java
@@ -241,7 +241,11 @@
private transient Component temporaryLostComponent;
static boolean systemSyncLWRequests = false;
- boolean syncLWRequests = false;
+
+ /**
+ * Focus transfers should be synchronous for lightweight component requests.
+ */
+ boolean syncLWRequests = false;
transient boolean beforeFirstShow = true;
private transient boolean disposing = false;
transient WindowDisposerRecord disposerRecord = null;
@@ -2936,7 +2940,8 @@ public Type getType() {
* Writes a list of child windows as optional data.
* Writes a list of icon images as optional data
*
- * @param s the {@code ObjectOutputStream} to write
+ * @param s the {@code ObjectOutputStream} to write
+ * @throws IOException if an I/O error occurs
* @serialData {@code null} terminated sequence of
* 0 or more pairs; the pair consists of a {@code String}
* and {@code Object}; the {@code String}
@@ -3091,10 +3096,12 @@ private void deserializeResources(ObjectInputStream s)
* (possibly {@code null}) child windows.
* Unrecognized keys or values will be ignored.
*
- * @param s the {@code ObjectInputStream} to read
- * @exception HeadlessException if
- * {@code GraphicsEnvironment.isHeadless} returns
- * {@code true}
+ * @param s the {@code ObjectInputStream} to read
+ * @throws ClassNotFoundException if the class of a serialized object could
+ * not be found
+ * @throws IOException if an I/O error occurs
+ * @throws HeadlessException if {@code GraphicsEnvironment.isHeadless()}
+ * returns {@code true}
* @see java.awt.GraphicsEnvironment#isHeadless
* @see #writeObject
*/
@@ -3427,6 +3434,10 @@ boolean canContainFocusOwner(Component focusOwnerCandidate) {
return super.canContainFocusOwner(focusOwnerCandidate) && isFocusableWindow();
}
+ /**
+ * {@code true} if this Window should appear at the default location,
+ * {@code false} if at the current location.
+ */
private volatile boolean locationByPlatform = locationByPlatformProp;
src/java.desktop/share/classes/java/awt/color/ColorSpace.java
@@ -99,7 +99,14 @@
*/
private static final long serialVersionUID = -409452704308689724L;
+ /**
+ * One of the {@code ColorSpace} type constants.
+ */
private int type;
+
+ /**
+ * The number of components in the color space.
+ */
private int numComponents;
private transient String [] compName = null;
src/java.desktop/share/classes/java/awt/color/ICC_ColorSpace.java
@@ -82,11 +84,34 @@
*/
private static final long serialVersionUID = 3455889114070431483L;
- private ICC_Profile thisProfile;
+ /**
+ * The specified {@code ICC_Profile} object.
+ */
+ private ICC_Profile thisProfile;
+
+ /**
+ * The maximum normalized component values.
+ */
private float[] minVal;
+
+ /**
+ * The minimum normalized component values.
+ */
private float[] maxVal;
+
+ /**
+ * Difference between min and max values.
+ */
private float[] diffMinMax;
+
+ /**
+ * Inverted value of the difference between min and max values.
+ */
private float[] invDiffMinMax;
+
+ /**
+ * Whether the values should be scaled or not.
+ */
private boolean needScaleInit = true;
@@ -123,7 +148,12 @@ public ICC_ColorSpace (ICC_Profile profile) {
}
/**
- * Validate an ICC_ColorSpace read from an object input stream
+ * Validate an ICC_ColorSpace read from an object input stream.
+ *
+ * @param s the {@code ObjectInputStream} to read
+ * @throws ClassNotFoundException if the class of a serialized object could
+ * not be found
+ * @throws IOException if an I/O error occurs
*/
private void readObject(java.io.ObjectInputStream s)
throws ClassNotFoundException, java.io.IOException {
src/java.desktop/share/classes/java/awt/dnd/DragGestureEvent.java
@@ -300,6 +292,8 @@ public void startDrag(Cursor dragCursor, Image dragImage, Point imageOffset, Tra
* {@code DragGestureEvent} created from the resulting deserialized
* stream will contain an empty {@code List} of gesture events.
*
+ * @param s the {@code ObjectOutputStream} to write
+ * @throws IOException if an I/O error occurs
* @serialData The default serializable fields, in alphabetical order,
* followed by either a {@code List} instance, or
* {@code null}.
@@ -323,6 +317,10 @@ private void writeObject(ObjectOutputStream s) throws IOException {
* {@code null}, this object's {@code List} of gesture events
* is set to an empty {@code List}.
*
+ * @param s the {@code ObjectInputStream} to read
+ * @throws ClassNotFoundException if the class of a serialized object could
+ * not be found
+ * @throws IOException if an I/O error occurs
* @since 1.4
*/
private void readObject(ObjectInputStream s)
src/java.desktop/share/classes/java/awt/dnd/DragGestureRecognizer.java
@@ -393,6 +390,8 @@ protected synchronized void appendEvent(InputEvent awtie) {
* {@code DragGestureListener} is written out if and only if it can be
* serialized. If not, {@code null} is written instead.
*
+ * @param s the {@code ObjectOutputStream} to write
+ * @throws IOException if an I/O error occurs
* @serialData The default serializable fields, in alphabetical order,
* followed by either a {@code DragGestureListener}, or
* {@code null}.
@@ -411,6 +410,10 @@ private void writeObject(ObjectOutputStream s) throws IOException {
* fields. This object's {@code DragGestureListener} is then
* deserialized as well by using the next object in the stream.
*
+ * @param s the {@code ObjectInputStream} to read
+ * @throws ClassNotFoundException if the class of a serialized object could
+ * not be found
+ * @throws IOException if an I/O error occurs
* @since 1.4
*/
@SuppressWarnings("unchecked")
src/java.desktop/share/classes/java/awt/dnd/DragSource.java
@@ -803,6 +802,8 @@ void processDragMouseMoved(DragSourceDragEvent dsde) {
* {@code DragSourceMotionListener} object.
* </ul>
*
+ * @param s the {@code ObjectOutputStream} to write
+ * @throws IOException if an I/O error occurs
* @serialData Either a {@code FlavorMap} instance, or
* {@code null}, followed by a {@code null}-terminated
* sequence of 0 or more pairs; the pair consists of a
@@ -849,6 +850,10 @@ private void writeObject(ObjectOutputStream s) throws IOException {
* <li>Otherwise, the key/value pair is skipped.
* </ul>
*
+ * @param s the {@code ObjectInputStream} to read
+ * @throws ClassNotFoundException if the class of a serialized object could
+ * not be found
+ * @throws IOException if an I/O error occurs
* @see java.awt.datatransfer.SystemFlavorMap#getDefaultFlavorMap
* @since 1.4
*/
src/java.desktop/share/classes/java/awt/dnd/DragSourceContext.java
@@ -544,6 +544,8 @@ private void setCursorImpl(Cursor c) {
* {@code DragSourceListener} is written out if and only if it can be
* serialized. If not, {@code null} is written instead.
*
+ * @param s the {@code ObjectOutputStream} to write
+ * @throws IOException if an I/O error occurs
* @serialData The default serializable fields, in alphabetical order,
* followed by either a {@code Transferable} instance, or
* {@code null}, followed by either a
@@ -570,6 +572,10 @@ private void writeObject(ObjectOutputStream s) throws IOException {
* {@code Transferable} is set to a dummy {@code Transferable}
* which supports no {@code DataFlavor}s.
*
+ * @param s the {@code ObjectInputStream} to read
+ * @throws ClassNotFoundException if the class of a serialized object could
+ * not be found
+ * @throws IOException if an I/O error occurs
* @since 1.4
*/
private void readObject(ObjectInputStream s)
src/java.desktop/share/classes/java/awt/dnd/DropTarget.java
@@ -576,6 +574,8 @@ protected DropTargetContext createDropTargetContext() {
* only if it can be serialized. If not, {@code null} is written
* instead.
*
+ * @param s the {@code ObjectOutputStream} to write
+ * @throws IOException if an I/O error occurs
* @serialData The default serializable fields, in alphabetical order,
* followed by either a {@code DropTargetListener}
* instance, or {@code null}.
@@ -598,6 +598,10 @@ private void writeObject(ObjectOutputStream s) throws IOException {
* {@code DropTargetListener}. If this fails, the next object in the
* stream is used instead.
*
+ * @param s the {@code ObjectInputStream} to read
+ * @throws ClassNotFoundException if the class of a serialized object could
+ * not be found
+ * @throws IOException if an I/O error occurs
* @since 1.4
*/
private void readObject(ObjectInputStream s)
src/java.desktop/share/classes/java/awt/event/FocusEvent.java
@@ -381,6 +381,9 @@ public final Cause getCause() {
* {@link Cause#UNKNOWN} and its other fields have the same values as in
* this {@code FocusEvent} instance.
*
+ * @return a newly created object from deserialized data
+ * @throws ObjectStreamException if a new object replacing this object could
+ * not be created
* @serial
* @see #cause
* @since 9
src/java.desktop/share/classes/java/awt/event/HierarchyEvent.java
@@ -162,9 +162,23 @@
*/
public static final int SHOWING_CHANGED = 0x4;
+ /**
+ * The {@code Component} at the top of the hierarchy which was changed.
+ */
Component changed;
+
+ /**
+ * The parent of the {@code changed} component. This may be the parent
+ * before or after the change, depending on the type of change.
+ */
Container changedParent;
- long changeFlags;
+
+ /**
+ * A bitmask which indicates the type(s) of the {@code HIERARCHY_CHANGED}
+ * events represented in this event object. For information on allowable
+ * values, see the class description for {@link HierarchyEvent}
+ */
+ long changeFlags;
src/java.desktop/share/classes/java/awt/event/InputMethodEvent.java
@@ -414,6 +414,11 @@ public String paramString() {
* Initializes the {@code when} field if it is not present in the
* object input stream. In that case, the field will be initialized by
* invoking {@link java.awt.EventQueue#getMostRecentEventTime()}.
+ *
+ * @param s the {@code ObjectInputStream} to read
+ * @throws ClassNotFoundException if the class of a serialized object could
+ * not be found
+ * @throws IOException if an I/O error occurs
*/
private void readObject(ObjectInputStream s) throws ClassNotFoundException, IOException {
s.defaultReadObject();
src/java.desktop/share/classes/java/awt/event/KeyEvent.java
@@ -1878,6 +1879,11 @@ private void setOldModifiers() {
/**
* Sets new modifiers by the old ones. The key modifiers
* override overlapping mouse modifiers.
+ *
+ * @param s the {@code ObjectInputStream} to read
+ * @throws ClassNotFoundException if the class of a serialized object could
+ * not be found
+ * @throws IOException if an I/O error occurs
* @serial
*/
@SuppressWarnings("deprecation")
src/java.desktop/share/classes/java/awt/event/MouseEvent.java
@@ -1188,6 +1187,11 @@ private void setOldModifiers() {
/**
* Sets new modifiers by the old ones.
+ *
+ * @param s the {@code ObjectInputStream} to read
+ * @throws ClassNotFoundException if the class of a serialized object could
+ * not be found
+ * @throws IOException if an I/O error occurs
* @serial
*/
@SuppressWarnings("deprecation")
src/java.desktop/share/classes/java/awt/event/WindowEvent.java
@@ -163,11 +164,14 @@
transient Window opposite;
/**
- * TBS
+ * Previous state of the window for window state change event.
*/
int oldState;
- int newState;
+ /**
+ * New state of the window for window state change event.
+ */
+ int newState;
/*
* JDK 1.1 serialVersionUID
src/java.desktop/share/classes/java/awt/font/TransformAttribute.java
@@ -99,6 +100,12 @@ public boolean isIdentity() {
*/
public static final TransformAttribute IDENTITY = new TransformAttribute(null);
+ /**
+ * Writes default serializable fields to stream.
+ *
+ * @param s the {@code ObjectOutputStream} to write
+ * @throws IOException if an I/O error occurs
+ */
private void writeObject(java.io.ObjectOutputStream s)
throws java.io.IOException
{
@@ -109,7 +116,12 @@ private void writeObject(java.io.ObjectOutputStream s)
s.defaultWriteObject();
}
- /*
+ /**
+ * Resolves a {@code TransformAttribute} object after serialization.
+ *
+ * @return a newly created object from deserialized data
+ * @throws ObjectStreamException if a new object replacing this object could
+ * not be created
* @since 1.6
*/
private Object readResolve() throws ObjectStreamException {
src/java.desktop/share/classes/java/awt/geom/AffineTransform.java
@@ -27,6 +27,7 @@
import java.awt.Shape;
import java.beans.ConstructorProperties;
+import java.io.IOException;
/**
* The {@code AffineTransform} class represents a 2D affine transform
@@ -3942,12 +3943,26 @@ public boolean equals(Object obj) {
*/
private static final long serialVersionUID = 1330973210523860834L;
+ /**
+ * Writes default serializable fields to stream.
+ *
+ * @param s the {@code ObjectOutputStream} to write
+ * @throws IOException if an I/O error occurs
+ */
private void writeObject(java.io.ObjectOutputStream s)
throws java.io.IOException
{
s.defaultWriteObject();
}
+ /**
+ * Reads the {@code ObjectInputStream}.
+ *
+ * @param s the {@code ObjectInputStream} to read
+ * @throws ClassNotFoundException if the class of a serialized object could
+ * not be found
+ * @throws IOException if an I/O error occurs
+ */
private void readObject(java.io.ObjectInputStream s)
throws java.lang.ClassNotFoundException, java.io.IOException
{
src/java.desktop/share/classes/java/awt/geom/Arc2D.java
@@ -330,6 +331,8 @@ protected Rectangle2D makeBounds(double x, double y,
* indicating the arc type of this {@code Arc2D}
* instance.
*
+ * @param s the {@code ObjectOutputStream} to write
+ * @throws IOException if an I/O error occurs
* @serialData
* <ol>
* <li>The default serializable fields.
@@ -352,6 +355,10 @@ private void writeObject(java.io.ObjectOutputStream s)
* indicating the arc type of this {@code Arc2D}
* instance.
*
+ * @param s the {@code ObjectInputStream} to read
+ * @throws ClassNotFoundException if the class of a serialized object
+ * could not be found
+ * @throws IOException if an I/O error occurs
* @serialData
* <ol>
* <li>The default serializable fields.
@@ -622,6 +629,8 @@ protected Rectangle2D makeBounds(double x, double y,
* indicating the arc type of this {@code Arc2D}
* instance.
*
+ * @param s the {@code ObjectOutputStream} to write
+ * @throws IOException if an I/O error occurs
* @serialData
* <ol>
* <li>The default serializable fields.
@@ -644,6 +653,10 @@ private void writeObject(java.io.ObjectOutputStream s)
* indicating the arc type of this {@code Arc2D}
* instance.
*
+ * @param s the {@code ObjectInputStream} to read
+ * @throws ClassNotFoundException if the class of a serialized object
+ * could not be found
+ * @throws IOException if an I/O error occurs
* @serialData
* <ol>
* <li>The default serializable fields.
src/java.desktop/share/classes/java/awt/geom/Path2D.java
@@ -857,6 +858,8 @@ public final Object clone() {
* serialization of the path segments stored in this
* path.
*
+ * @param s the {@code ObjectOutputStream} to write
+ * @throws IOException if an I/O error occurs
* @serialData
* <ol>
* <li>The default serializable fields.
@@ -994,6 +997,10 @@ private void writeObject(java.io.ObjectOutputStream s)
* The serial data for this object is described in the
* writeObject method.
*
+ * @param s the {@code ObjectInputStream} to read
+ * @throws ClassNotFoundException if the class of a serialized object
+ * could not be found
+ * @throws IOException if an I/O error occurs
* @since 1.6
*/
private void readObject(java.io.ObjectInputStream s)
@@ -1632,6 +1639,8 @@ public final Object clone() {
* serialization of the path segments stored in this
* path.
*
+ * @param s the {@code ObjectOutputStream} to write
+ * @throws IOException if an I/O error occurs
* @serialData
* <ol>
* <li>The default serializable fields.
@@ -1768,6 +1777,10 @@ private void writeObject(java.io.ObjectOutputStream s)
* The serial data for this object is described in the
* writeObject method.
*
+ * @param s the {@code ObjectInputStream} to read
+ * @throws ClassNotFoundException if the class of a serialized object
+ * could not be found
+ * @throws IOException if an I/O error occurs *
* @since 1.6
*/
private void readObject(java.io.ObjectInputStream s)
src/java.desktop/share/classes/java/beans/IndexedPropertyChangeEvent.java
@@ -41,8 +42,12 @@
* @author Mark Davidson
*/
public class IndexedPropertyChangeEvent extends PropertyChangeEvent {
+
private static final long serialVersionUID = -320227448495806870L;
+ /**
+ * The index of the property element that was changed.
+ */
private int index;
/**
src/java.desktop/share/classes/java/beans/PropertyChangeSupport.java
@@ -423,6 +424,10 @@ public boolean hasListeners(String propertyName) {
}
/**
+ * Writes serializable fields to stream.
+ *
+ * @param s the {@code ObjectOutputStream} to write
+ * @throws IOException if an I/O error occurs
* @serialData Null terminated list of {@code PropertyChangeListeners}.
* <p>
* At serialization time we skip non-serializable listeners and
@@ -462,6 +467,14 @@ private void writeObject(ObjectOutputStream s) throws IOException {
s.writeObject(null);
}
+ /**
+ * Reads the {@code ObjectInputStream}.
+ *
+ * @param s the {@code ObjectInputStream} to read
+ * @throws ClassNotFoundException if the class of a serialized object could
+ * not be found
+ * @throws IOException if an I/O error occurs
+ */
private void readObject(ObjectInputStream s) throws ClassNotFoundException, IOException {
this.map = new PropertyChangeListenerMap();
@@ -491,9 +504,13 @@ private void readObject(ObjectInputStream s) throws ClassNotFoundException, IOEx
private Object source;
/**
- * @serialField children Hashtable
- * @serialField source Object
+ * @serialField children Hashtable
+ * The list of {@code PropertyChangeListeners}
+ * @serialField source Object
+ * The object to be provided as the "source" for any generated
+ * events
* @serialField propertyChangeSupportSerializedDataVersion int
+ * The version
*/
private static final ObjectStreamField[] serialPersistentFields = {
new ObjectStreamField("children", Hashtable.class),
src/java.desktop/share/classes/java/beans/VetoableChangeSupport.java
@@ -412,6 +413,10 @@ public boolean hasListeners(String propertyName) {
}
/**
+ * Writes serializable fields to stream.
+ *
+ * @param s the {@code ObjectOutputStream} to write
+ * @throws IOException if an I/O error occurs
* @serialData Null terminated list of {@code VetoableChangeListeners}.
* <p>
* At serialization time we skip non-serializable listeners and
@@ -451,6 +456,14 @@ private void writeObject(ObjectOutputStream s) throws IOException {
s.writeObject(null);
}
+ /**
+ * Reads the {@code ObjectInputStream}.
+ *
+ * @param s the {@code ObjectInputStream} to read
+ * @throws ClassNotFoundException if the class of a serialized object could
+ * not be found
+ * @throws IOException if an I/O error occurs
+ */
private void readObject(ObjectInputStream s) throws ClassNotFoundException, IOException {
this.map = new VetoableChangeListenerMap();
@@ -480,9 +493,13 @@ private void readObject(ObjectInputStream s) throws ClassNotFoundException, IOEx
private Object source;
/**
- * @serialField children Hashtable
- * @serialField source Object
+ * @serialField children Hashtable
+ * The list of {@code PropertyChangeListeners}
+ * @serialField source Object
+ * The object to be provided as the "source" for any generated
+ * events
* @serialField vetoableChangeSupportSerializedDataVersion int
+ * The version
*/
private static final ObjectStreamField[] serialPersistentFields = {
new ObjectStreamField("children", Hashtable.class),
src/java.desktop/share/classes/java/beans/beancontext/BeanContextChildSupport.java
@@ -312,8 +309,10 @@ protected void initializeBeanContextResources() {
/**
* Write the persistence state of the object.
+ *
+ * @param oos the {@code ObjectOutputStream} to write
+ * @throws IOException if an I/O error occurs
*/
-
private void writeObject(ObjectOutputStream oos) throws IOException {
/*
@@ -332,10 +331,13 @@ private void writeObject(ObjectOutputStream oos) throws IOException {
/**
* Restore a persistent object, must wait for subsequent setBeanContext()
- * to fully restore any resources obtained from the new nesting
- * BeanContext
+ * to fully restore any resources obtained from the new nesting BeanContext.
+ *
+ * @param ois the {@code ObjectInputStream} to read
+ * @throws ClassNotFoundException if the class of a serialized object could
+ * not be found
+ * @throws IOException if an I/O error occurs
*/
-
private void readObject(ObjectInputStream ois) throws IOException, ClassNotFoundException {
ois.defaultReadObject();
}
src/java.desktop/share/classes/java/beans/beancontext/BeanContextServiceRevokedEvent.java
@@ -25,10 +25,6 @@
@@ -94,6 +90,10 @@ public boolean isServiceClass(Class<?> service) {
/**
* A {@code Class} reference to the service that is being revoked.
*/
- protected Class<?> serviceClass;
- private boolean invalidateRefs;
+ protected Class<?> serviceClass;
+
+ /**
+ * {@code true} if current service is being forcibly revoked.
+ */
+ private boolean invalidateRefs;
}
src/java.desktop/share/classes/java/beans/beancontext/BeanContextServicesSupport.java
@@ -1209,9 +1205,11 @@ protected synchronized void bcsPreDeserializationHook(ObjectInputStream ois) thr
}
/**
- * serialize the instance
+ * Serialize the instance.
+ *
+ * @param oos the {@code ObjectOutputStream} to write
+ * @throws IOException if an I/O error occurs
*/
-
private synchronized void writeObject(ObjectOutputStream oos) throws IOException {
oos.defaultWriteObject();
@@ -1219,9 +1217,13 @@ private synchronized void writeObject(ObjectOutputStream oos) throws IOException
}
/**
- * deserialize the instance
+ * Deserialize the instance.
+ *
+ * @param ois the {@code ObjectInputStream} to read
+ * @throws ClassNotFoundException if the class of a serialized object could
+ * not be found
+ * @throws IOException if an I/O error occurs
*/
-
private synchronized void readObject(ObjectInputStream ois) throws IOException, ClassNotFoundException {
ois.defaultReadObject();
src/java.desktop/share/classes/java/beans/beancontext/BeanContextSupport.java
@@ -338,8 +325,16 @@ public void remove() { /* do nothing */ }
*/
+ /**
+ * The child.
+ */
@SuppressWarnings("serial") // Not statically typed as Serializable
- private Object child;
+ private Object child;
+
+ /**
+ * The peer if the child and the peer are related by an implementation
+ * of BeanContextProxy
+ */
@SuppressWarnings("serial") // Not statically typed as Serializable
private Object proxyPeer;
@@ -997,9 +992,9 @@ public final void writeChildren(ObjectOutputStream oos) throws IOException {
* it should always call writeObject() followed by writeChildren() and
* readObject() followed by readChildren().
*
- * @param oos the ObjectOutputStream
+ * @param oos the {@code ObjectOutputStream} to write
+ * @throws IOException if an I/O error occurs
*/
-
private synchronized void writeObject(ObjectOutputStream oos) throws IOException {
serializing = true;
@@ -1065,8 +1060,12 @@ public final void readChildren(ObjectInputStream ois) throws IOException, ClassN
* deserialize contents ... if this instance has a distinct peer the
* children are *not* serialized here, the peer's readObject() must call
* readChildren() after deserializing this instance.
+ *
+ * @param ois the {@code ObjectInputStream} to read
+ * @throws ClassNotFoundException if the class of a serialized object could
+ * not be found
+ * @throws IOException if an I/O error occurs
*/
-
private synchronized void readObject(ObjectInputStream ois) throws IOException, ClassNotFoundException {
synchronized(BeanContext.globalHierarchyLock) {
@@ -1372,7 +1371,10 @@ protected static final boolean classEquals(Class<?> first, Class<?> second) {
*/
protected transient HashMap<Object, BCSChild> children;
- private int serializable = 0; // children serializable
+ /**
+ * Currently serializable children.
+ */
+ private int serializable = 0; // children serializable
/**
* all accesses to the {@code protected ArrayList bcmListeners} field
src/java.desktop/share/classes/javax/imageio/metadata/IIOMetadataNode.java
@@ -30,16 +30,19 @@
-
+/**
+ * An {@code IIODOMException} is thrown by the {@code IIOMetadataNode} in
+ * "exceptional" circumstances.
+ */
class IIODOMException extends DOMException {
private static final long serialVersionUID = -4369510142067447468L;
src/java.desktop/share/classes/javax/print/attribute/standard/DialogOwner.java
@@ -59,6 +61,9 @@ public long getOwnerID(DialogOwner owner) {
private static final long serialVersionUID = -1901909867156076547L;
+ /**
+ * The owner of the dialog.
+ */
private Window owner;
private transient long id;
src/java.desktop/share/classes/javax/swing/plaf/synth/SynthDesktopPaneUI.java
@@ -198,6 +219,9 @@ protected void uninstallDesktopManager() {
super.uninstallDesktopManager();
}
+ /**
+ * The {@code TaskBar} installed by the UI.
+ */
@SuppressWarnings("serial") // Same-version serialization only and
// internal anonymous classes
static class TaskBar extends JPanel implements ComponentListener, ContainerListener {
@@ -327,6 +351,9 @@ public void componentRemoved(ContainerEvent e) {
}
}
+ /**
+ * The default {@code DesktopManager} installed by the UI.
+ */
@SuppressWarnings("serial") // Same-version serialization only
class SynthDesktopManager extends DefaultDesktopManager implements UIResource {
src/java.desktop/share/classes/javax/swing/plaf/synth/SynthInternalFrameTitlePane.java
@@ -157,6 +176,9 @@ protected void uninstallDefaults() {
super.uninstallDefaults();
}
+ /**
+ * A subclass of {@code JPopupMenu} that implements {@code UIResource}.
+ */
@SuppressWarnings("serial") // Superclass is not serializable across versions
private static class JPopupMenuUIResource extends JPopupMenu implements
UIResource { }
src/java.desktop/share/classes/javax/swing/plaf/synth/SynthListUI.java
@@ -198,6 +204,9 @@ private int getComponentState(JComponent c) {
return SynthLookAndFeel.getComponentState(c);
}
+ /**
+ * The {@code DefaultListCellRenderer} installed by the UI.
+ */
@SuppressWarnings("serial") // Superclass is not serializable across versions
private class SynthListCellRenderer extends DefaultListCellRenderer.UIResource {
@Override public String getName() {
src/java.desktop/share/classes/javax/swing/plaf/synth/SynthScrollPaneUI.java
@@ -230,7 +237,9 @@ public void propertyChange(PropertyChangeEvent e) {
}
}
-
+ /**
+ * A subclass of {@code AbstractBorder} that implements {@code UIResource}.
+ */
@SuppressWarnings("serial") // Superclass is not serializable across versions
private class ViewportBorder extends AbstractBorder implements UIResource {
private Insets insets;
src/java.desktop/share/classes/javax/swing/plaf/synth/SynthTabbedPaneUI.java
@@ -912,6 +928,10 @@ public void calculateLayoutInfo() {
}
}
+ /**
+ * A subclass of {@code SynthArrowButton} that implements
+ * {@code UIResource}.
+ */
@SuppressWarnings("serial") // Superclass is not serializable across versions
private class SynthScrollableTabButton extends SynthArrowButton implements
UIResource {
src/java.desktop/share/classes/javax/swing/plaf/synth/SynthTableHeaderUI.java
@@ -217,6 +226,9 @@ public void propertyChange(PropertyChangeEvent evt) {
}
}
+ /**
+ * The {@code DefaultTableCellHeaderRenderer} installed by the UI.
+ */
@SuppressWarnings("serial") // Superclass is not serializable across versions
private class HeaderRenderer extends DefaultTableCellHeaderRenderer {
HeaderRenderer() {
src/java.desktop/share/classes/javax/swing/plaf/synth/SynthTableUI.java
@@ -706,6 +709,9 @@ public void propertyChange(PropertyChangeEvent event) {
}
}
+ /**
+ * The renderer installed by the UI to render the boolean data.
+ */
@SuppressWarnings("serial") // Superclass is not serializable across versions
private class SynthBooleanTableCellRenderer extends JCheckBox implements
TableCellRenderer {
@@ -745,6 +751,9 @@ public boolean isOpaque() {
}
}
+ /**
+ * The {@code DefaultTableCellRenderer} installed by the UI.
+ */
@SuppressWarnings("serial") // Superclass is not serializable across versions
private class SynthTableCellRenderer extends DefaultTableCellRenderer {
private Object numberFormat;
src/java.desktop/share/classes/javax/swing/plaf/synth/SynthTreeUI.java
@@ -680,6 +682,10 @@ protected int getRowX(int row, int depth) {
return super.getRowX(row, depth) + padding;
}
+ /**
+ * A subclass of {@code DefaultTreeCellRenderer} that implements
+ * {@code UIResource}.
+ */
@SuppressWarnings("serial") // Superclass is not serializable across versions
private class SynthTreeCellRenderer extends DefaultTreeCellRenderer
implements UIResource {
src/java.desktop/share/classes/javax/swing/text/GapVector.java
@@ -67,17 +66,24 @@ public GapVector(int initialLength) {
/**
* Allocate an array to store items of the type
* appropriate (which is determined by the subclass).
+ *
+ * @param len the length of the array
+ * @return the java array of some type
*/
protected abstract Object allocateArray(int len);
/**
- * Get the length of the allocated array
+ * Get the length of the allocated array.
+ *
+ * @return the length of the array
*/
protected abstract int getArrayLength();
/**
* Access to the array. The actual type
* of the array is known only by the subclass.
+ *
+ * @return the java array of some type
*/
protected final Object getArray() {
return array;
@@ -85,6 +91,8 @@ protected final Object getArray() {
/**
* Access to the start of the gap.
+ *
+ * @return the start of the gap
*/
protected final int getGapStart() {
return g0;
@@ -92,6 +100,8 @@ protected final int getGapStart() {
/**
* Access to the end of the gap.
+ *
+ * @return the end of the gap
*/
protected final int getGapEnd() {
return g1;
@@ -128,6 +138,7 @@ protected final int getGapEnd() {
* the location in the contiguous space being modeled.
* @param rmSize the number of items to remove
* @param addItems the new items to place in storage.
+ * @param addSize the number of items to add
*/
protected void replace(int position, int rmSize, Object addItems, int addSize) {
int addOffset = 0;
@@ -219,7 +230,9 @@ void resize(int nsize) {
/**
* Make the gap bigger, moving any necessary data and updating
- * the appropriate marks
+ * the appropriate marks.
+ *
+ * @param newSize the new capacity
*/
protected void shiftEnd(int newSize) {
int oldSize = getArrayLength();
@@ -251,6 +264,8 @@ int getNewArraySize(int reqSize) {
* without changing the size of the gap. This
* moves the data in the array and updates the
* marks accordingly.
+ *
+ * @param newGapStart the new start of the gap
*/
protected void shiftGap(int newGapStart) {
if (newGapStart == g0) {
@@ -280,6 +295,8 @@ protected void shiftGap(int newGapStart) {
* gap start down to the new gap start are squeezed
* to the end of the gap (their location has been
* removed).
+ *
+ * @param newGapStart the new start of the gap
*/
protected void shiftGapStartDown(int newGapStart) {
g0 = newGapStart;
@@ -292,6 +309,8 @@ protected void shiftGapStartDown(int newGapStart) {
* gap end up to the new gap end are squeezed
* to the end of the gap (their location has been
* removed).
+ *
+ * @param newGapEnd the new end of the gap
*/
protected void shiftGapEndUp(int newGapEnd) {
g1 = newGapEnd;Attachments
Issue Links
- csr of
-
JDK-8251123 doclint warnings about missing javadoc tags and comments
-
- Resolved
-