--- old/src/java.desktop/share/classes/javax/print/attribute/ResolutionSyntax.java 2017-07-16 16:17:40.000000000 -0700 +++ new/src/java.desktop/share/classes/javax/print/attribute/ResolutionSyntax.java 2017-07-16 16:17:40.000000000 -0700 @@ -1,5 +1,5 @@ /* - * Copyright (c) 2000, 2014, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2000, 2017, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it @@ -23,29 +23,27 @@ * questions. */ - package javax.print.attribute; import java.io.Serializable; /** - * Class ResolutionSyntax is an abstract base class providing the common + * Class {@code ResolutionSyntax} is an abstract base class providing the common * implementation of all attributes denoting a printer resolution. - *

+ *

* A resolution attribute's value consists of two items, the cross feed * direction resolution and the feed direction resolution. A resolution * attribute may be constructed by supplying the two values and indicating the * units in which the values are measured. Methods are provided to return a * resolution attribute's values, indicating the units in which the values are * to be returned. The two most common resolution units are dots per inch (dpi) - * and dots per centimeter (dpcm), and exported constants {@link #DPI - * DPI} and {@link #DPCM DPCM} are provided for - * indicating those units. - *

+ * and dots per centimeter (dpcm), and exported constants {@link #DPI DPI} and + * {@link #DPCM DPCM} are provided for indicating those units. + *

* Once constructed, a resolution attribute's value is immutable. - *

- * Design - *

+ *

+ * Design + *

* A resolution attribute's cross feed direction resolution and feed direction * resolution values are stored internally using units of dots per 100 inches * (dphi). Storing the values in dphi rather than, say, metric units allows @@ -57,43 +55,47 @@ * resolution attribute's values are created in one units and retrieved in * different units; for example, 600 dpi will be rounded to 236 dpcm, whereas * the true value (to five figures) is 236.22 dpcm. - *

+ *

* Storing the values internally in common units of dphi lets two resolution * attributes be compared without regard to the units in which they were * created; for example, 300 dpcm will compare equal to 762 dpi, as they both - * are stored as 76200 dphi. In particular, a lookup service can - * match resolution attributes based on equality of their serialized - * representations regardless of the units in which they were created. Again, - * using integers for internal storage allows precise equality comparisons to be - * done, which would not be guaranteed if a floating point representation were - * used. - *

- * The exported constant {@link #DPI DPI} is actually the - * conversion factor by which to multiply a value in dpi to get the value in - * dphi. Likewise, the exported constant {@link #DPCM DPCM} is the - * conversion factor by which to multiply a value in dpcm to get the value in - * dphi. A client can specify a resolution value in units other than dpi or dpcm - * by supplying its own conversion factor. However, since the internal units of - * dphi was chosen with supporting only the external units of dpi and dpcm in - * mind, there is no guarantee that the conversion factor for the client's units - * will be an exact integer. If the conversion factor isn't an exact integer, - * resolution values in the client's units won't be stored precisely. + * are stored as 76200 dphi. In particular, a lookup service can match + * resolution attributes based on equality of their serialized representations + * regardless of the units in which they were created. Again, using integers for + * internal storage allows precise equality comparisons to be done, which would + * not be guaranteed if a floating point representation were used. + *

+ * The exported constant {@link #DPI DPI} is actually the conversion factor by + * which to multiply a value in dpi to get the value in dphi. Likewise, the + * exported constant {@link #DPCM DPCM} is the conversion factor by which to + * multiply a value in dpcm to get the value in dphi. A client can specify a + * resolution value in units other than dpi or dpcm by supplying its own + * conversion factor. However, since the internal units of dphi was chosen with + * supporting only the external units of dpi and dpcm in mind, there is no + * guarantee that the conversion factor for the client's units will be an exact + * integer. If the conversion factor isn't an exact integer, resolution values + * in the client's units won't be stored precisely. * - * @author David Mendenhall - * @author Alan Kaminsky + * @author David Mendenhall + * @author Alan Kaminsky */ public abstract class ResolutionSyntax implements Serializable, Cloneable { + /** + * Use serialVersionUID from JDK 1.4 for interoperability. + */ private static final long serialVersionUID = 2706743076526672017L; /** * Cross feed direction resolution in units of dots per 100 inches (dphi). + * * @serial */ private int crossFeedResolution; /** * Feed direction resolution in units of dots per 100 inches (dphi). + * * @serial */ private int feedResolution; @@ -105,26 +107,20 @@ public static final int DPI = 100; /** - * Value to indicate units of dots per centimeter (dpcm). It is actually - * the conversion factor by which to multiply dpcm to yield dphi (254). + * Value to indicate units of dots per centimeter (dpcm). It is actually the + * conversion factor by which to multiply dpcm to yield dphi (254). */ public static final int DPCM = 254; - /** * Construct a new resolution attribute from the given items. * - * @param crossFeedResolution - * Cross feed direction resolution. - * @param feedResolution - * Feed direction resolution. - * @param units - * Unit conversion factor, e.g. {@link #DPI DPI} or - * {@link #DPCM DPCM}. - * - * @exception IllegalArgumentException - * (unchecked exception) Thrown if {@code crossFeedResolution < 1} - * or {@code feedResolution < 1} or {@code units < 1}. + * @param crossFeedResolution cross feed direction resolution + * @param feedResolution feed direction resolution + * @param units unit conversion factor, e.g. {@link #DPI DPI} or + * {@link #DPCM DPCM} + * @throws IllegalArgumentException if {@code crossFeedResolution < 1} or + * {@code feedResolution < 1} or {@code units < 1} */ public ResolutionSyntax(int crossFeedResolution, int feedResolution, int units) { @@ -147,16 +143,11 @@ * Convert a value from dphi to some other units. The result is rounded to * the nearest integer. * - * @param dphi - * Value (dphi) to convert. - * @param units - * Unit conversion factor, e.g. {@link #DPI DPI} or - * {@link #DPCM DPCM}. - * - * @return The value of {@code dphi} converted to the desired units. - * - * @exception IllegalArgumentException - * (unchecked exception) Thrown if {@code units} < 1. + * @param dphi value (dphi) to convert + * @param units unit conversion factor, e.g. {@link #DPI DPI} or + * {@link #DPCM DPCM} + * @return the value of {@code dphi} converted to the desired units + * @throws IllegalArgumentException if {@code units < 1} */ private static int convertFromDphi(int dphi, int units) { if (units < 1) { @@ -167,18 +158,14 @@ } /** - * Get this resolution attribute's resolution values in the given units. - * The values are rounded to the nearest integer. - * - * @param units - * Unit conversion factor, e.g. {@link #DPI DPI} or - * {@link #DPCM DPCM}. - * - * @return A two-element array with the cross feed direction resolution - * at index 0 and the feed direction resolution at index 1. + * Get this resolution attribute's resolution values in the given units. The + * values are rounded to the nearest integer. * - * @exception IllegalArgumentException - * (unchecked exception) Thrown if {@code units < 1}. + * @param units unit conversion factor, e.g. {@link #DPI DPI} or + * {@link #DPCM DPCM} + * @return a two-element array with the cross feed direction resolution at + * index 0 and the feed direction resolution at index 1 + * @throws IllegalArgumentException if {@code units < 1} */ public int[] getResolution(int units) { return new int[] { getCrossFeedResolution(units), @@ -190,14 +177,10 @@ * Returns this resolution attribute's cross feed direction resolution in * the given units. The value is rounded to the nearest integer. * - * @param units - * Unit conversion factor, e.g. {@link #DPI DPI} or - * {@link #DPCM DPCM}. - * - * @return Cross feed direction resolution. - * - * @exception IllegalArgumentException - * (unchecked exception) Thrown if {@code units < 1}. + * @param units unit conversion factor, e.g. {@link #DPI DPI} or + * {@link #DPCM DPCM} + * @return cross feed direction resolution + * @throws IllegalArgumentException if {@code units < 1} */ public int getCrossFeedResolution(int units) { return convertFromDphi (crossFeedResolution, units); @@ -207,14 +190,10 @@ * Returns this resolution attribute's feed direction resolution in the * given units. The value is rounded to the nearest integer. * - * @param units - * Unit conversion factor, e.g. {@link #DPI DPI} or {@link - * #DPCM DPCM}. - * - * @return Feed direction resolution. - * - * @exception IllegalArgumentException - * (unchecked exception) Thrown if {@code units < 1}. + * @param units unit conversion factor, e.g. {@link #DPI DPI} or + * {@link #DPCM DPCM} + * @return feed direction resolution + * @throws IllegalArgumentException if {@code units < 1} */ public int getFeedResolution(int units) { return convertFromDphi (feedResolution, units); @@ -222,22 +201,18 @@ /** * Returns a string version of this resolution attribute in the given units. - * The string takes the form "CxF U", - * where C is the cross feed direction resolution, F is the - * feed direction resolution, and U is the units name. The values are + * The string takes the form "CxF U", + * where C is the cross feed direction resolution, F is the + * feed direction resolution, and U is the units name. The values are * rounded to the nearest integer. * - * @param units - * Unit conversion factor, e.g. {@link #DPI CODE>DPI} or {@link - * #DPCM DPCM}. - * @param unitsName - * Units name string, e.g. {@code "dpi"} or {@code "dpcm"}. If - * null, no units name is appended to the result. - * - * @return String version of this resolution attribute. - * - * @exception IllegalArgumentException - * (unchecked exception) Thrown if {@code units < 1}. + * @param units unit conversion factor, e.g. {@link #DPI CODE>DPI} or + * {@link #DPCM DPCM} + * @param unitsName units name string, e.g. {@code "dpi"} or + * {@code "dpcm"}. If {@code null}, no units name is appended to the + * result. + * @return string version of this resolution attribute + * @throws IllegalArgumentException if {@code units < 1} */ public String toString(int units, String unitsName) { StringBuilder result = new StringBuilder(); @@ -251,54 +226,43 @@ return result.toString(); } - /** - * Determine whether this resolution attribute's value is less than or - * equal to the given resolution attribute's value. This is true if all - * of the following conditions are true: - *

- * - * @param other Resolution attribute to compare with. - * - * @return True if this resolution attribute is less than or equal to the - * {@code other} resolution attribute, false otherwise. - * - * @exception NullPointerException - * (unchecked exception) Thrown if {@code other} is null. + * Determine whether this resolution attribute's value is less than or equal + * to the given resolution attribute's value. This is true if all of the + * following conditions are true: + * + * + * @param other resolution attribute to compare with + * @return {@code true} if this resolution attribute is less than or equal + * to the {@code other} resolution attribute, {@code false} + * otherwise + * @throws NullPointerException if {@code other} is {@code null} */ public boolean lessThanOrEquals(ResolutionSyntax other) { return (this.crossFeedResolution <= other.crossFeedResolution && this.feedResolution <= other.feedResolution); } - /** * Returns whether this resolution attribute is equivalent to the passed in * object. To be equivalent, all of the following conditions must be true: - *
    - *
  1. - * {@code object} is not null. - *
  2. - * {@code object} is an instance of class ResolutionSyntax. - *
  3. - * This attribute's cross feed direction resolution is equal to - * {@code object}'s cross feed direction resolution. - *
  4. - * This attribute's feed direction resolution is equal to - * {@code object}'s feed direction resolution. - *
- * - * @param object Object to compare to. - * - * @return True if {@code object} is equivalent to this resolution - * attribute, false otherwise. + *
    + *
  1. {@code object} is not {@code null}. + *
  2. {@code object} is an instance of class {@code ResolutionSyntax}. + *
  3. This attribute's cross feed direction resolution is equal to + * {@code object}'s cross feed direction resolution. + *
  4. This attribute's feed direction resolution is equal to + * {@code object}'s feed direction resolution. + *
+ * + * @param object {@code Object} to compare to + * @return {@code true} if {@code object} is equivalent to this resolution + * attribute, {@code false} otherwise */ public boolean equals(Object object) { @@ -320,8 +284,8 @@ /** * Returns a string version of this resolution attribute. The string takes - * the form "CxF dphi", where C is the - * cross feed direction resolution and F is the feed direction + * the form "CxF dphi", where C is the + * cross feed direction resolution and F is the feed direction * resolution. The values are reported in the internal units of dphi. */ public String toString() { @@ -333,25 +297,23 @@ return result.toString(); } - /** * Returns this resolution attribute's cross feed direction resolution in * units of dphi. (For use in a subclass.) * - * @return Cross feed direction resolution. + * @return cross feed direction resolution */ protected int getCrossFeedResolutionDphi() { return crossFeedResolution; } /** - * Returns this resolution attribute's feed direction resolution in units - * of dphi. (For use in a subclass.) + * Returns this resolution attribute's feed direction resolution in units of + * dphi. (For use in a subclass.) * - * @return Feed direction resolution. + * @return feed direction resolution */ protected int getFeedResolutionDphi() { return feedResolution; } - }