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;