--- 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:
- *
"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;
}
-
}