ResolutionSyntax


1   /*
2    * @(#)ResolutionSyntax.java    1.7 04/01/07
3    *
4    * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5    * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6    */
7   
8   
9   package javax.print.attribute;
10  
11  import java.io.Serializable  ;
12  
13  /**
14   * Class ResolutionSyntax is an abstract base class providing the common 
15   * implementation of all attributes denoting a printer resolution. 
16   * <P>
17   * A resolution attribute's value consists of two items, the cross feed 
18   * direction resolution and the feed direction resolution. A resolution 
19   * attribute may be constructed by supplying the two values and indicating the 
20   * units in which the values are measured. Methods are provided to return a 
21   * resolution attribute's values, indicating the units in which the values are 
22   * to be returned. The two most common resolution units are dots per inch (dpi) 
23   * and dots per centimeter (dpcm), and exported constants {@link #DPI 
24   * <CODE>DPI</CODE>} and {@link #DPCM <CODE>DPCM</CODE>} are provided for 
25   * indicating those units. 
26   * <P>
27   * Once constructed, a resolution attribute's value is immutable. 
28   * <P>
29   * <B>Design</B>
30   * <P>
31   * A resolution attribute's cross feed direction resolution and feed direction 
32   * resolution values are stored internally using units of dots per 100 inches 
33   * (dphi). Storing the values in dphi rather than, say, metric units allows 
34   * precise integer arithmetic conversions between dpi and dphi and between dpcm 
35   * and dphi: 1 dpi = 100 dphi, 1 dpcm = 254 dphi. Thus, the values can be stored 
36   * into and retrieved back from a resolution attribute in either units with no 
37   * loss of precision. This would not be guaranteed if a floating point 
38   * representation were used. However, roundoff error will in general occur if a 
39   * resolution attribute's values are created in one units and retrieved in 
40   * different units; for example, 600 dpi will be rounded to 236 dpcm, whereas 
41   * the true value (to five figures) is 236.22 dpcm. 
42   * <P>
43   * Storing the values internally in common units of dphi lets two resolution 
44   * attributes be compared without regard to the units in which they were 
45   * created; for example, 300 dpcm will compare equal to 762 dpi, as they both 
46   * are stored as 76200 dphi. In particular, a lookup service can 
47   * match resolution attributes based on equality of their serialized 
48   * representations regardless of the units in which they were created. Again, 
49   * using integers for internal storage allows precise equality comparisons to be 
50   * done, which would not be guaranteed if a floating point representation were 
51   * used. 
52   * <P>
53   * The exported constant {@link #DPI <CODE>DPI</CODE>} is actually the 
54   * conversion factor by which to multiply a value in dpi to get the value in 
55   * dphi. Likewise, the exported constant {@link #DPCM <CODE>DPCM</CODE>} is the 
56   * conversion factor by which to multiply a value in dpcm to get the value in 
57   * dphi. A client can specify a resolution value in units other than dpi or dpcm 
58   * by supplying its own conversion factor. However, since the internal units of 
59   * dphi was chosen with supporting only the external units of dpi and dpcm in 
60   * mind, there is no guarantee that the conversion factor for the client's units 
61   * will be an exact integer. If the conversion factor isn't an exact integer, 
62   * resolution values in the client's units won't be stored precisely. 
63   * <P>
64   *
65   * @author  David Mendenhall
66   * @author  Alan Kaminsky
67   */
68  public abstract class ResolutionSyntax implements Serializable  , Cloneable   {
69  
70      private static final long serialVersionUID = 2706743076526672017L;
71  
72      /**
73       * Cross feed direction resolution in units of dots per 100 inches (dphi).
74       * @serial
75       */
76      private int crossFeedResolution;
77  
78      /**
79       * Feed direction resolution in units of dots per 100 inches (dphi).
80       * @serial
81       */
82      private int feedResolution;
83  
84      /**
85       * Value to indicate units of dots per inch (dpi). It is actually the 
86       * conversion factor by which to multiply dpi to yield dphi (100). 
87       */
88      public static final int DPI = 100;
89  
90      /**
91       * Value to indicate units of dots per centimeter (dpcm). It is actually 
92       * the conversion factor by which to multiply dpcm to yield dphi (254). 
93       */
94      public static final int DPCM = 254;
95  
96  
97      /**
98       * Construct a new resolution attribute from the given items.
99       *
100      * @param  crossFeedResolution
101      *     Cross feed direction resolution.
102      * @param  feedResolution
103      *     Feed direction resolution.
104      * @param units
105      *     Unit conversion factor, e.g. {@link #DPI <CODE>DPI</CODE>} or
106      * {@link    #DPCM <CODE>DPCM</CODE>}. 
107      *
108      * @exception  IllegalArgumentException
109      *     (unchecked exception) Thrown if <CODE>crossFeedResolution</CODE> < 
110      *     1 or <CODE>feedResolution</CODE> < 1 or <CODE>units</CODE> < 1. 
111      */
112     public ResolutionSyntax(int crossFeedResolution, int feedResolution,
113                 int units) {
114 
115     if (crossFeedResolution < 1) {
116         throw new IllegalArgumentException  ("crossFeedResolution is < 1");
117     }
118     if (feedResolution < 1) {
119         throw new IllegalArgumentException  ("feedResolution is < 1");
120     }
121     if (units < 1) {
122         throw new IllegalArgumentException  ("units is < 1");
123     }
124 
125     this.crossFeedResolution = crossFeedResolution * units;
126     this.feedResolution = feedResolution * units;
127     }
128 
129     /**
130      * Convert a value from dphi to some other units. The result is rounded to 
131      * the nearest integer. 
132      *
133      * @param  dphi
134      *     Value (dphi) to convert.
135      * @param  units
136      *     Unit conversion factor, e.g. {@link #DPI <CODE>DPI</CODE>} or
137      * {@link     #DPCM <CODE>DPCM</CODE>}. 
138      *
139      * @return  The value of <CODE>dphi</CODE> converted to the desired units.
140      *
141      * @exception  IllegalArgumentException
142      *     (unchecked exception) Thrown if <CODE>units</CODE> < 1. 
143      */
144     private static int convertFromDphi(int dphi, int units) {
145     if (units < 1) {
146         throw new IllegalArgumentException  (": units is < 1");
147     }
148     int round = units / 2;
149     return (dphi + round) / units;
150     }
151     
152     /**
153      * Get this resolution attribute's resolution values in the given units.
154      * The values are rounded to the nearest integer. 
155      *
156      * @param  units
157      *     Unit conversion factor, e.g. {@link #DPI <CODE>DPI</CODE>} or
158      * {@link   #DPCM <CODE>DPCM</CODE>}. 
159      *
160      * @return  A two-element array with the cross feed direction resolution
161      *          at index 0 and the feed direction resolution at index 1. 
162      *
163      * @exception  IllegalArgumentException
164      *     (unchecked exception) Thrown if <CODE>units</CODE> < 1. 
165      */
166     public int[] getResolution(int units) {
167     return new int[] { getCrossFeedResolution(units),
168                    getFeedResolution(units)
169                    };
170     }
171 
172     /**
173      * Returns this resolution attribute's cross feed direction resolution in 
174      * the given units. The value is rounded to the nearest integer. 
175      *
176      * @param  units
177      *     Unit conversion factor, e.g. {@link #DPI <CODE>DPI</CODE>} or
178      * {@link  #DPCM <CODE>DPCM</CODE>}. 
179      *
180      * @return  Cross feed direction resolution.
181      *
182      * @exception  IllegalArgumentException
183      *     (unchecked exception) Thrown if <CODE>units</CODE> < 1. 
184      */
185     public int getCrossFeedResolution(int units) {
186     return convertFromDphi (crossFeedResolution, units);
187     }
188 
189     /**
190      * Returns this resolution attribute's feed direction resolution in the 
191      * given units. The value is rounded to the nearest integer. 
192      *
193      * @param  units
194      *     Unit conversion factor, e.g. {@link #DPI <CODE>DPI</CODE>} or {@link 
195      *     #DPCM <CODE>DPCM</CODE>}. 
196      *
197      * @return  Feed direction resolution.
198      *
199      * @exception  IllegalArgumentException
200      *     (unchecked exception) Thrown if <CODE>units</CODE> < 1. 
201      */
202     public int getFeedResolution(int units) {
203     return convertFromDphi (feedResolution, units);
204     }
205     
206     /**
207      * Returns a string version of this resolution attribute in the given units. 
208      * The string takes the form <CODE>"<I>C</I>x<I>F</I> <I>U</I>"</CODE>, 
209      * where <I>C</I> is the cross feed direction resolution, <I>F</I> is the 
210      * feed direction resolution, and <I>U</I> is the units name. The values are 
211      * rounded to the nearest integer. 
212      *
213      * @param  units
214      *     Unit conversion factor, e.g. {@link #DPI <CODE>DPI</CODE>} or {@link 
215      *     #DPCM <CODE>DPCM</CODE>}. 
216      * @param  unitsName
217      *     Units name string, e.g. <CODE>"dpi"</CODE> or <CODE>"dpcm"</CODE>. If 
218      *     null, no units name is appended to the result. 
219      *
220      * @return  String version of this resolution attribute.
221      *
222      * @exception  IllegalArgumentException
223      *     (unchecked exception) Thrown if <CODE>units</CODE> < 1. 
224      */
225     public String   toString(int units, String   unitsName) {
226     StringBuffer   result = new StringBuffer  ();
227     result.append(getCrossFeedResolution (units));
228     result.append('x');
229     result.append(getFeedResolution (units));
230     if (unitsName != null) {
231         result.append (' ');
232         result.append (unitsName);
233     }
234     return result.toString();
235     }
236 
237     
238     /**
239      * Determine whether this resolution attribute's value is less than or 
240      * equal to the given resolution attribute's value. This is true if all
241      * of the following conditions are true: 
242      * <UL>
243      * <LI>
244      * This attribute's cross feed direction resolution is less than or equal to 
245      * the <CODE>other</CODE> attribute's cross feed direction resolution.
246      * <LI>
247      * This attribute's feed direction resolution is less than or equal to the 
248      * <CODE>other</CODE> attribute's feed direction resolution. 
249      * </UL>
250      *
251      * @param  other  Resolution attribute to compare with.
252      *
253      * @return  True if this resolution attribute is less than or equal to the
254      *          <CODE>other</CODE> resolution attribute, false otherwise.
255      *
256      * @exception  NullPointerException
257      *     (unchecked exception) Thrown if <CODE>other</CODE> is null.
258      */
259     public boolean lessThanOrEquals(ResolutionSyntax   other) {
260     return (this.crossFeedResolution <= other.crossFeedResolution &&
261         this.feedResolution <= other.feedResolution);
262     }
263 
264 
265     /**
266      * Returns whether this resolution attribute is equivalent to the passed in 
267      * object. To be equivalent, all of the following conditions must be true: 
268      * <OL TYPE=1>
269      * <LI>
270      * <CODE>object</CODE> is not null.
271      * <LI>
272      * <CODE>object</CODE> is an instance of class ResolutionSyntax.
273      * <LI>
274      * This attribute's cross feed direction resolution is equal to 
275      * <CODE>object</CODE>'s cross feed direction resolution. 
276      * <LI>
277      * This attribute's feed direction resolution is equal to
278      * <CODE>object</CODE>'s feed direction resolution. 
279      * </OL>
280      *
281      * @param  object  Object to compare to.
282      *
283      * @return  True if <CODE>object</CODE> is equivalent to this resolution
284      *          attribute, false otherwise. 
285      */
286     public boolean equals(Object   object) {
287 
288     return(object != null &&
289            object instanceof ResolutionSyntax   &&
290            this.crossFeedResolution ==
291            ((ResolutionSyntax  ) object).crossFeedResolution &&
292            this.feedResolution == 
293            ((ResolutionSyntax  ) object).feedResolution);
294     }
295     
296     /**
297      * Returns a hash code value for this resolution attribute.
298      */
299     public int hashCode() {
300     return(((crossFeedResolution & 0x0000FFFF)) |
301            ((feedResolution      & 0x0000FFFF) << 16));
302     }
303     
304     /**
305      * Returns a string version of this resolution attribute. The string takes 
306      * the form <CODE>"<I>C</I>x<I>F</I> dphi"</CODE>, where <I>C</I> is the 
307      * cross feed direction resolution and <I>F</I> is the feed direction 
308      * resolution. The values are reported in the internal units of dphi. 
309      */
310     public String   toString() {
311     StringBuffer   result = new StringBuffer  ();
312     result.append(crossFeedResolution);
313     result.append('x');
314     result.append(feedResolution);
315     result.append(" dphi");
316     return result.toString();
317     }
318 
319 
320     /**
321      * Returns this resolution attribute's cross feed direction resolution in 
322      * units of dphi. (For use in a subclass.)
323      *
324      * @return  Cross feed direction resolution.
325      */
326     protected int getCrossFeedResolutionDphi() {
327     return crossFeedResolution;
328     }
329 
330     /**
331      * Returns this resolution attribute's feed direction resolution in units 
332      * of dphi. (For use in a subclass.) 
333      *
334      * @return  Feed direction resolution.
335      */
336     protected int getFeedResolutionDphi() {
337     return feedResolution;
338     }
339 
340 }
341
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags