0N/A/*
2362N/A * Copyright (c) 2000, 2004, Oracle and/or its affiliates. All rights reserved.
0N/A * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
0N/A *
0N/A * This code is free software; you can redistribute it and/or modify it
0N/A * under the terms of the GNU General Public License version 2 only, as
2362N/A * published by the Free Software Foundation. Oracle designates this
0N/A * particular file as subject to the "Classpath" exception as provided
2362N/A * by Oracle in the LICENSE file that accompanied this code.
0N/A *
0N/A * This code is distributed in the hope that it will be useful, but WITHOUT
0N/A * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
0N/A * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
0N/A * version 2 for more details (a copy is included in the LICENSE file that
0N/A * accompanied this code).
0N/A *
0N/A * You should have received a copy of the GNU General Public License version
0N/A * 2 along with this work; if not, write to the Free Software Foundation,
0N/A * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
0N/A *
2362N/A * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
2362N/A * or visit www.oracle.com if you need additional information or have any
2362N/A * questions.
0N/A */
0N/A
0N/A
0N/Apackage javax.print.attribute;
0N/A
0N/Aimport java.io.Serializable;
0N/A
0N/A/**
0N/A * Class ResolutionSyntax is an abstract base class providing the common
0N/A * implementation of all attributes denoting a printer resolution.
0N/A * <P>
0N/A * A resolution attribute's value consists of two items, the cross feed
0N/A * direction resolution and the feed direction resolution. A resolution
0N/A * attribute may be constructed by supplying the two values and indicating the
0N/A * units in which the values are measured. Methods are provided to return a
0N/A * resolution attribute's values, indicating the units in which the values are
0N/A * to be returned. The two most common resolution units are dots per inch (dpi)
0N/A * and dots per centimeter (dpcm), and exported constants {@link #DPI
0N/A * <CODE>DPI</CODE>} and {@link #DPCM <CODE>DPCM</CODE>} are provided for
0N/A * indicating those units.
0N/A * <P>
0N/A * Once constructed, a resolution attribute's value is immutable.
0N/A * <P>
0N/A * <B>Design</B>
0N/A * <P>
0N/A * A resolution attribute's cross feed direction resolution and feed direction
0N/A * resolution values are stored internally using units of dots per 100 inches
0N/A * (dphi). Storing the values in dphi rather than, say, metric units allows
0N/A * precise integer arithmetic conversions between dpi and dphi and between dpcm
0N/A * and dphi: 1 dpi = 100 dphi, 1 dpcm = 254 dphi. Thus, the values can be stored
0N/A * into and retrieved back from a resolution attribute in either units with no
0N/A * loss of precision. This would not be guaranteed if a floating point
0N/A * representation were used. However, roundoff error will in general occur if a
0N/A * resolution attribute's values are created in one units and retrieved in
0N/A * different units; for example, 600 dpi will be rounded to 236 dpcm, whereas
0N/A * the true value (to five figures) is 236.22 dpcm.
0N/A * <P>
0N/A * Storing the values internally in common units of dphi lets two resolution
0N/A * attributes be compared without regard to the units in which they were
0N/A * created; for example, 300 dpcm will compare equal to 762 dpi, as they both
0N/A * are stored as 76200 dphi. In particular, a lookup service can
0N/A * match resolution attributes based on equality of their serialized
0N/A * representations regardless of the units in which they were created. Again,
0N/A * using integers for internal storage allows precise equality comparisons to be
0N/A * done, which would not be guaranteed if a floating point representation were
0N/A * used.
0N/A * <P>
0N/A * The exported constant {@link #DPI <CODE>DPI</CODE>} is actually the
0N/A * conversion factor by which to multiply a value in dpi to get the value in
0N/A * dphi. Likewise, the exported constant {@link #DPCM <CODE>DPCM</CODE>} is the
0N/A * conversion factor by which to multiply a value in dpcm to get the value in
0N/A * dphi. A client can specify a resolution value in units other than dpi or dpcm
0N/A * by supplying its own conversion factor. However, since the internal units of
0N/A * dphi was chosen with supporting only the external units of dpi and dpcm in
0N/A * mind, there is no guarantee that the conversion factor for the client's units
0N/A * will be an exact integer. If the conversion factor isn't an exact integer,
0N/A * resolution values in the client's units won't be stored precisely.
0N/A * <P>
0N/A *
0N/A * @author David Mendenhall
0N/A * @author Alan Kaminsky
0N/A */
0N/Apublic abstract class ResolutionSyntax implements Serializable, Cloneable {
0N/A
0N/A private static final long serialVersionUID = 2706743076526672017L;
0N/A
0N/A /**
0N/A * Cross feed direction resolution in units of dots per 100 inches (dphi).
0N/A * @serial
0N/A */
0N/A private int crossFeedResolution;
0N/A
0N/A /**
0N/A * Feed direction resolution in units of dots per 100 inches (dphi).
0N/A * @serial
0N/A */
0N/A private int feedResolution;
0N/A
0N/A /**
0N/A * Value to indicate units of dots per inch (dpi). It is actually the
0N/A * conversion factor by which to multiply dpi to yield dphi (100).
0N/A */
0N/A public static final int DPI = 100;
0N/A
0N/A /**
0N/A * Value to indicate units of dots per centimeter (dpcm). It is actually
0N/A * the conversion factor by which to multiply dpcm to yield dphi (254).
0N/A */
0N/A public static final int DPCM = 254;
0N/A
0N/A
0N/A /**
0N/A * Construct a new resolution attribute from the given items.
0N/A *
0N/A * @param crossFeedResolution
0N/A * Cross feed direction resolution.
0N/A * @param feedResolution
0N/A * Feed direction resolution.
0N/A * @param units
0N/A * Unit conversion factor, e.g. {@link #DPI <CODE>DPI</CODE>} or
0N/A * {@link #DPCM <CODE>DPCM</CODE>}.
0N/A *
0N/A * @exception IllegalArgumentException
0N/A * (unchecked exception) Thrown if <CODE>crossFeedResolution</CODE> <
0N/A * 1 or <CODE>feedResolution</CODE> < 1 or <CODE>units</CODE> < 1.
0N/A */
0N/A public ResolutionSyntax(int crossFeedResolution, int feedResolution,
0N/A int units) {
0N/A
0N/A if (crossFeedResolution < 1) {
0N/A throw new IllegalArgumentException("crossFeedResolution is < 1");
0N/A }
0N/A if (feedResolution < 1) {
0N/A throw new IllegalArgumentException("feedResolution is < 1");
0N/A }
0N/A if (units < 1) {
0N/A throw new IllegalArgumentException("units is < 1");
0N/A }
0N/A
0N/A this.crossFeedResolution = crossFeedResolution * units;
0N/A this.feedResolution = feedResolution * units;
0N/A }
0N/A
0N/A /**
0N/A * Convert a value from dphi to some other units. The result is rounded to
0N/A * the nearest integer.
0N/A *
0N/A * @param dphi
0N/A * Value (dphi) to convert.
0N/A * @param units
0N/A * Unit conversion factor, e.g. {@link #DPI <CODE>DPI</CODE>} or
0N/A * {@link #DPCM <CODE>DPCM</CODE>}.
0N/A *
0N/A * @return The value of <CODE>dphi</CODE> converted to the desired units.
0N/A *
0N/A * @exception IllegalArgumentException
0N/A * (unchecked exception) Thrown if <CODE>units</CODE> < 1.
0N/A */
0N/A private static int convertFromDphi(int dphi, int units) {
0N/A if (units < 1) {
0N/A throw new IllegalArgumentException(": units is < 1");
0N/A }
0N/A int round = units / 2;
0N/A return (dphi + round) / units;
0N/A }
0N/A
0N/A /**
0N/A * Get this resolution attribute's resolution values in the given units.
0N/A * The values are rounded to the nearest integer.
0N/A *
0N/A * @param units
0N/A * Unit conversion factor, e.g. {@link #DPI <CODE>DPI</CODE>} or
0N/A * {@link #DPCM <CODE>DPCM</CODE>}.
0N/A *
0N/A * @return A two-element array with the cross feed direction resolution
0N/A * at index 0 and the feed direction resolution at index 1.
0N/A *
0N/A * @exception IllegalArgumentException
0N/A * (unchecked exception) Thrown if <CODE>units</CODE> < 1.
0N/A */
0N/A public int[] getResolution(int units) {
0N/A return new int[] { getCrossFeedResolution(units),
0N/A getFeedResolution(units)
0N/A };
0N/A }
0N/A
0N/A /**
0N/A * Returns this resolution attribute's cross feed direction resolution in
0N/A * the given units. The value is rounded to the nearest integer.
0N/A *
0N/A * @param units
0N/A * Unit conversion factor, e.g. {@link #DPI <CODE>DPI</CODE>} or
0N/A * {@link #DPCM <CODE>DPCM</CODE>}.
0N/A *
0N/A * @return Cross feed direction resolution.
0N/A *
0N/A * @exception IllegalArgumentException
0N/A * (unchecked exception) Thrown if <CODE>units</CODE> < 1.
0N/A */
0N/A public int getCrossFeedResolution(int units) {
0N/A return convertFromDphi (crossFeedResolution, units);
0N/A }
0N/A
0N/A /**
0N/A * Returns this resolution attribute's feed direction resolution in the
0N/A * given units. The value is rounded to the nearest integer.
0N/A *
0N/A * @param units
0N/A * Unit conversion factor, e.g. {@link #DPI <CODE>DPI</CODE>} or {@link
0N/A * #DPCM <CODE>DPCM</CODE>}.
0N/A *
0N/A * @return Feed direction resolution.
0N/A *
0N/A * @exception IllegalArgumentException
0N/A * (unchecked exception) Thrown if <CODE>units</CODE> < 1.
0N/A */
0N/A public int getFeedResolution(int units) {
0N/A return convertFromDphi (feedResolution, units);
0N/A }
0N/A
0N/A /**
0N/A * Returns a string version of this resolution attribute in the given units.
0N/A * The string takes the form <CODE>"<I>C</I>x<I>F</I> <I>U</I>"</CODE>,
0N/A * where <I>C</I> is the cross feed direction resolution, <I>F</I> is the
0N/A * feed direction resolution, and <I>U</I> is the units name. The values are
0N/A * rounded to the nearest integer.
0N/A *
0N/A * @param units
0N/A * Unit conversion factor, e.g. {@link #DPI <CODE>DPI</CODE>} or {@link
0N/A * #DPCM <CODE>DPCM</CODE>}.
0N/A * @param unitsName
0N/A * Units name string, e.g. <CODE>"dpi"</CODE> or <CODE>"dpcm"</CODE>. If
0N/A * null, no units name is appended to the result.
0N/A *
0N/A * @return String version of this resolution attribute.
0N/A *
0N/A * @exception IllegalArgumentException
0N/A * (unchecked exception) Thrown if <CODE>units</CODE> < 1.
0N/A */
0N/A public String toString(int units, String unitsName) {
0N/A StringBuffer result = new StringBuffer();
0N/A result.append(getCrossFeedResolution (units));
0N/A result.append('x');
0N/A result.append(getFeedResolution (units));
0N/A if (unitsName != null) {
0N/A result.append (' ');
0N/A result.append (unitsName);
0N/A }
0N/A return result.toString();
0N/A }
0N/A
0N/A
0N/A /**
0N/A * Determine whether this resolution attribute's value is less than or
0N/A * equal to the given resolution attribute's value. This is true if all
0N/A * of the following conditions are true:
0N/A * <UL>
0N/A * <LI>
0N/A * This attribute's cross feed direction resolution is less than or equal to
0N/A * the <CODE>other</CODE> attribute's cross feed direction resolution.
0N/A * <LI>
0N/A * This attribute's feed direction resolution is less than or equal to the
0N/A * <CODE>other</CODE> attribute's feed direction resolution.
0N/A * </UL>
0N/A *
0N/A * @param other Resolution attribute to compare with.
0N/A *
0N/A * @return True if this resolution attribute is less than or equal to the
0N/A * <CODE>other</CODE> resolution attribute, false otherwise.
0N/A *
0N/A * @exception NullPointerException
0N/A * (unchecked exception) Thrown if <CODE>other</CODE> is null.
0N/A */
0N/A public boolean lessThanOrEquals(ResolutionSyntax other) {
0N/A return (this.crossFeedResolution <= other.crossFeedResolution &&
0N/A this.feedResolution <= other.feedResolution);
0N/A }
0N/A
0N/A
0N/A /**
0N/A * Returns whether this resolution attribute is equivalent to the passed in
0N/A * object. To be equivalent, all of the following conditions must be true:
0N/A * <OL TYPE=1>
0N/A * <LI>
0N/A * <CODE>object</CODE> is not null.
0N/A * <LI>
0N/A * <CODE>object</CODE> is an instance of class ResolutionSyntax.
0N/A * <LI>
0N/A * This attribute's cross feed direction resolution is equal to
0N/A * <CODE>object</CODE>'s cross feed direction resolution.
0N/A * <LI>
0N/A * This attribute's feed direction resolution is equal to
0N/A * <CODE>object</CODE>'s feed direction resolution.
0N/A * </OL>
0N/A *
0N/A * @param object Object to compare to.
0N/A *
0N/A * @return True if <CODE>object</CODE> is equivalent to this resolution
0N/A * attribute, false otherwise.
0N/A */
0N/A public boolean equals(Object object) {
0N/A
0N/A return(object != null &&
0N/A object instanceof ResolutionSyntax &&
0N/A this.crossFeedResolution ==
0N/A ((ResolutionSyntax) object).crossFeedResolution &&
0N/A this.feedResolution ==
0N/A ((ResolutionSyntax) object).feedResolution);
0N/A }
0N/A
0N/A /**
0N/A * Returns a hash code value for this resolution attribute.
0N/A */
0N/A public int hashCode() {
0N/A return(((crossFeedResolution & 0x0000FFFF)) |
0N/A ((feedResolution & 0x0000FFFF) << 16));
0N/A }
0N/A
0N/A /**
0N/A * Returns a string version of this resolution attribute. The string takes
0N/A * the form <CODE>"<I>C</I>x<I>F</I> dphi"</CODE>, where <I>C</I> is the
0N/A * cross feed direction resolution and <I>F</I> is the feed direction
0N/A * resolution. The values are reported in the internal units of dphi.
0N/A */
0N/A public String toString() {
0N/A StringBuffer result = new StringBuffer();
0N/A result.append(crossFeedResolution);
0N/A result.append('x');
0N/A result.append(feedResolution);
0N/A result.append(" dphi");
0N/A return result.toString();
0N/A }
0N/A
0N/A
0N/A /**
0N/A * Returns this resolution attribute's cross feed direction resolution in
0N/A * units of dphi. (For use in a subclass.)
0N/A *
0N/A * @return Cross feed direction resolution.
0N/A */
0N/A protected int getCrossFeedResolutionDphi() {
0N/A return crossFeedResolution;
0N/A }
0N/A
0N/A /**
0N/A * Returns this resolution attribute's feed direction resolution in units
0N/A * of dphi. (For use in a subclass.)
0N/A *
0N/A * @return Feed direction resolution.
0N/A */
0N/A protected int getFeedResolutionDphi() {
0N/A return feedResolution;
0N/A }
0N/A
0N/A}