--- old/src/java.desktop/share/classes/javax/print/attribute/standard/MediaPrintableArea.java 2017-08-11 15:12:47.000000000 -0700 +++ new/src/java.desktop/share/classes/javax/print/attribute/standard/MediaPrintableArea.java 2017-08-11 15:12:47.000000000 -0700 @@ -22,9 +22,11 @@ * or visit www.oracle.com if you need additional information or have any * questions. */ + package javax.print.attribute.standard; import javax.print.DocFlavor; +import javax.print.PrintService; import javax.print.attribute.Attribute; import javax.print.attribute.AttributeSet; import javax.print.attribute.DocAttribute; @@ -32,60 +34,67 @@ import javax.print.attribute.PrintRequestAttribute; /** - * Class MediaPrintableArea is a printing attribute used to distinguish + * Class {@code MediaPrintableArea} is a printing attribute used to distinguish * the printable and non-printable areas of media. *

* The printable area is specified to be a rectangle, within the overall * dimensions of a media. *

- * Most printers cannot print on the entire surface of the media, due - * to printer hardware limitations. This class can be used to query - * the acceptable values for a supposed print job, and to request an area - * within the constraints of the printable area to be used in a print job. + * Most printers cannot print on the entire surface of the media, due to printer + * hardware limitations. This class can be used to query the acceptable values + * for a supposed print job, and to request an area within the constraints of + * the printable area to be used in a print job. *

* To query for the printable area, a client must supply a suitable context. - * Without specifying at the very least the size of the media being used - * no meaningful value for printable area can be obtained. + * Without specifying at the very least the size of the media being used no + * meaningful value for printable area can be obtained. *

- * The attribute is not described in terms of the distance from the edge - * of the paper, in part to emphasise that this attribute is not independent - * of a particular media, but must be described within the context of a - * choice of other attributes. Additionally it is usually more convenient - * for a client to use the printable area. + * The attribute is not described in terms of the distance from the edge of the + * paper, in part to emphasise that this attribute is not independent of a + * particular media, but must be described within the context of a choice of + * other attributes. Additionally it is usually more convenient for a client to + * use the printable area. *

- * The hardware's minimum margins is not just a property of the printer, - * but may be a function of the media size, orientation, media type, and - * any specified finishings. - * {@code PrintService} provides the method to query the supported - * values of an attribute in a suitable context : - * See {@link javax.print.PrintService#getSupportedAttributeValues(Class,DocFlavor, AttributeSet) PrintService.getSupportedAttributeValues()} + * The hardware's minimum margins is not just a property of the printer, but may + * be a function of the media size, orientation, media type, and any specified + * finishings. {@code PrintService} provides the method to query the supported + * values of an attribute in a suitable context : See + * {@link PrintService#getSupportedAttributeValues(Class, DocFlavor, AttributeSet) + * PrintService.getSupportedAttributeValues()} *

- * The rectangular printable area is defined thus: - * The (x,y) origin is positioned at the top-left of the paper in portrait - * mode regardless of the orientation specified in the requesting context. - * For example a printable area for A4 paper in portrait or landscape - * orientation will have height {@literal >} width. + * The rectangular printable area is defined thus: The (x,y) origin is + * positioned at the top-left of the paper in portrait mode regardless of the + * orientation specified in the requesting context. For example a printable area + * for A4 paper in portrait or landscape orientation will have height + * {@literal >} width. *

- * A printable area attribute's values are stored - * internally as integers in units of micrometers (µm), where 1 micrometer - * = 10-6 meter = 1/1000 millimeter = 1/25400 inch. This permits - * dimensions to be represented exactly to a precision of 1/1000 mm (= 1 - * µm) or 1/100 inch (= 254 µm). If fractional inches are expressed in - - * negative powers of two, this permits dimensions to be represented exactly to - * a precision of 1/8 inch (= 3175 µm) but not 1/16 inch (because 1/16 inch - - * does not equal an integral number of µm). + * A printable area attribute's values are stored internally as integers in + * units of micrometers (µm), where 1 micrometer = 10-6 meter = + * 1/1000 millimeter = 1/25400 inch. This permits dimensions to be represented + * exactly to a precision of 1/1000 mm (= 1 µm) or 1/100 inch (= 254 + * µm). If fractional inches are expressed in negative powers of two, this + * permits dimensions to be represented exactly to a precision of 1/8 inch + * (= 3175 µm) but not 1/16 inch (because 1/16 inch does not equal an + * integral number of µm). *

- * IPP Compatibility: MediaPrintableArea is not an IPP attribute. + * IPP Compatibility: MediaPrintableArea is not an IPP attribute. */ - public final class MediaPrintableArea implements DocAttribute, PrintRequestAttribute, PrintJobAttribute { + /** + * Printable {@code x}, {@code y}, {@code width} and {@code height}. + */ private int x, y, w, h; + + /** + * The units in which the values are expressed. + */ private int units; + /** + * Use serialVersionUID from JDK 1.4 for interoperability. + */ private static final long serialVersionUID = -1597171464050795793L; /** @@ -101,18 +110,17 @@ public static final int MM = 1000; /** - * Constructs a MediaPrintableArea object from floating point values. - * @param x printable x - * @param y printable y - * @param w printable width - * @param h printable height - * @param units in which the values are expressed. - * - * @exception IllegalArgumentException - * Thrown if {@code x < 0} or {@code y < 0} - * or {@code w <= 0} or {@code h <= 0} or - * {@code units < 1}. - */ + * Constructs a {@code MediaPrintableArea} object from floating point + * values. + * + * @param x printable x + * @param y printable y + * @param w printable width + * @param h printable height + * @param units in which the values are expressed + * @throws IllegalArgumentException if {@code x < 0} or {@code y < 0} or + * {@code w <= 0} or {@code h <= 0} or {@code units < 1} + */ public MediaPrintableArea(float x, float y, float w, float h, int units) { if ((x < 0.0) || (y < 0.0) || (w <= 0.0) || (h <= 0.0) || (units < 1)) { @@ -127,18 +135,16 @@ } /** - * Constructs a MediaPrintableArea object from integer values. - * @param x printable x - * @param y printable y - * @param w printable width - * @param h printable height - * @param units in which the values are expressed. - * - * @exception IllegalArgumentException - * Thrown if {@code x < 0} or {@code y < 0} - * or {@code w <= 0} or {@code h <= 0} or - * {@code units < 1}. - */ + * Constructs a {@code MediaPrintableArea} object from integer values. + * + * @param x printable x + * @param y printable y + * @param w printable width + * @param h printable height + * @param units in which the values are expressed + * @throws IllegalArgumentException if {@code x < 0} or {@code y < 0} or + * {@code w <= 0} or {@code h <= 0} or {@code units < 1} + */ public MediaPrintableArea(int x, int y, int w, int h, int units) { if ((x < 0) || (y < 0) || (w <= 0) || (h <= 0) || (units < 1)) { @@ -153,15 +159,13 @@ /** * Get the printable area as an array of 4 values in the order - * x, y, w, h. The values returned are in the given units. - * @param units - * Unit conversion factor, e.g. {@link #INCH INCH} or - * {@link #MM MM}. + * {@code x, y, w, h}. The values returned are in the given units. * - * @return printable area as array of x, y, w, h in the specified units. - * - * @exception IllegalArgumentException - * (unchecked exception) Thrown if {@code units < 1}. + * @param units unit conversion factor, e.g. {@link #INCH INCH} or + * {@link #MM MM} + * @return printable area as array of {@code x, y, w, h} in the specified + * units + * @throws IllegalArgumentException if {@code units < 1} */ public float[] getPrintableArea(int units) { return new float[] { getX(units), getY(units), @@ -169,86 +173,70 @@ } /** - * Get the x location of the origin of the printable area in the + * Get the {@code x} location of the origin of the printable area in the * specified units. - * @param units - * Unit conversion factor, e.g. {@link #INCH INCH} or - * {@link #MM MM}. * - * @return x location of the origin of the printable area in the - * specified units. - * - * @exception IllegalArgumentException - * (unchecked exception) Thrown if {@code units < 1}. + * @param units unit conversion factor, e.g. {@link #INCH INCH} or + * {@link #MM MM} + * @return {@code x} location of the origin of the printable area in the + * specified units + * @throws IllegalArgumentException if {@code units < 1} */ - public float getX(int units) { + public float getX(int units) { return convertFromMicrometers(x, units); - } + } /** - * Get the y location of the origin of the printable area in the - * specified units. - * @param units - * Unit conversion factor, e.g. {@link #INCH INCH} or - * {@link #MM MM}. - * - * @return y location of the origin of the printable area in the + * Get the {@code y} location of the origin of the printable area in the * specified units. * - * @exception IllegalArgumentException - * (unchecked exception) Thrown if {@code units < 1}. + * @param units unit conversion factor, e.g. {@link #INCH INCH} or + * {@link #MM MM} + * @return {@code y} location of the origin of the printable area in the + * specified units + * @throws IllegalArgumentException if {@code units < 1} */ - public float getY(int units) { + public float getY(int units) { return convertFromMicrometers(y, units); - } + } /** - * Get the width of the printable area in the specified units. - * @param units - * Unit conversion factor, e.g. {@link #INCH INCH} or - * {@link #MM MM}. - * - * @return width of the printable area in the specified units. + * Get the {@code width} of the printable area in the specified units. * - * @exception IllegalArgumentException - * (unchecked exception) Thrown if {@code units < 1}. + * @param units unit conversion factor, e.g. {@link #INCH INCH} or + * {@link #MM MM} + * @return {@code width} of the printable area in the specified units + * @throws IllegalArgumentException if {@code units < 1} */ - public float getWidth(int units) { + public float getWidth(int units) { return convertFromMicrometers(w, units); - } + } /** - * Get the height of the printable area in the specified units. - * @param units - * Unit conversion factor, e.g. {@link #INCH INCH} or - * {@link #MM MM}. - * - * @return height of the printable area in the specified units. + * Get the {@code height} of the printable area in the specified units. * - * @exception IllegalArgumentException - * (unchecked exception) Thrown if {@code units < 1}. + * @param units unit conversion factor, e.g. {@link #INCH INCH} or + * {@link #MM MM} + * @return {@code height} of the printable area in the specified units + * @throws IllegalArgumentException if {@code units < 1} */ - public float getHeight(int units) { + public float getHeight(int units) { return convertFromMicrometers(h, units); - } + } /** * Returns whether this media margins 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 MediaPrintableArea. - *
  3. - * The origin and dimensions are the same. - *
- * - * @param object Object to compare to. - * - * @return True if {@code object} is equivalent to this media margins - * attribute, false otherwise. + * in object. To be equivalent, all of the following conditions must be + * true: + *
    + *
  1. {@code object} is not {@code null}. + *
  2. {@code object} is an instance of class {@code MediaPrintableArea}. + *
  3. The origin and dimensions are the same. + *
+ * + * @param object {@code Object} to compare to + * @return {@code true} if {@code object} is equivalent to this media + * margins attribute, {@code false} otherwise */ public boolean equals(Object object) { boolean ret = false; @@ -264,12 +252,12 @@ /** * Get the printing attribute class which is to be used as the "category" * for this printing attribute value. - *

- * For class MediaPrintableArea, the category is - * class MediaPrintableArea itself. + *

+ * For class {@code MediaPrintableArea}, the category is class + * {@code MediaPrintableArea} itself. * - * @return Printing attribute class (category), an instance of class - * {@link java.lang.Class java.lang.Class}. + * @return printing attribute class (category), an instance of class + * {@link Class java.lang.Class} */ public final Class getCategory() { return MediaPrintableArea.class; @@ -278,32 +266,28 @@ /** * Get the name of the category of which this attribute value is an * instance. - *

- * For class MediaPrintableArea, - * the category name is {@code "media-printable-area"}. - *

This is not an IPP V1.1 attribute. + *

+ * For class {@code MediaPrintableArea}, the category name is + * {@code "media-printable-area"}. + *

+ * This is not an IPP V1.1 attribute. * - * @return Attribute category name. + * @return attribute category name */ public final String getName() { return "media-printable-area"; } /** - * Returns a string version of this rectangular size attribute in the - * given units. - * - * @param units - * Unit conversion factor, e.g. {@link #INCH INCH} or - * {@link #MM MM}. - * @param unitsName - * Units name string, e.g. {@code "in"} or {@code "mm"}. If - * null, no units name is appended to the result. + * Returns a string version of this rectangular size attribute in the given + * units. * - * @return String version of this two-dimensional size attribute. - * - * @exception IllegalArgumentException - * (unchecked exception) Thrown if {@code units < 1}. + * @param units unit conversion factor, e.g. {@link #INCH INCH} or + * {@link #MM MM} + * @param unitsName units name string, e.g. {@code "in"} or {@code "mm"}. + * If {@code null}, no units name is appended to the result + * @return string version of this two-dimensional size attribute + * @throws IllegalArgumentException if {@code units < 1} */ public String toString(int units, String unitsName) { if (unitsName == null) { @@ -328,6 +312,14 @@ return x + 37*y + 43*w + 47*h; } + /** + * Converts the {@code x} from micrometers to {@code units}. + * + * @param x the value + * @param units unit conversion factor, e.g. {@link #INCH INCH} or + * {@link #MM MM} + * @return the value of {@code x} in the specified units + */ private static float convertFromMicrometers(int x, int units) { if (units < 1) { throw new IllegalArgumentException("units is < 1");