Blame - jdk/src/share/classes/javax/print/attribute/package.html - platform/libcore

blob: 90c14543835f2d74f1fc115ecc0626ff0f7ce302 [file] [log] [blame]

J. Duke	319a3b9	2007-12-01 00:00:00 +0000	[diff] [blame^]	1	<html>
				2	<head>
				3	<title>javax.print.attribute package</title>
				4	<!--
				5	Copyright 2000-2003 Sun Microsystems, Inc. All Rights Reserved.
				6	DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
				7
				8	This code is free software; you can redistribute it and/or modify it
				9	under the terms of the GNU General Public License version 2 only, as
				10	published by the Free Software Foundation. Sun designates this
				11	particular file as subject to the "Classpath" exception as provided
				12	by Sun in the LICENSE file that accompanied this code.
				13
				14	This code is distributed in the hope that it will be useful, but WITHOUT
				15	ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
				16	FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
				17	version 2 for more details (a copy is included in the LICENSE file that
				18	accompanied this code).
				19
				20	You should have received a copy of the GNU General Public License version
				21	2 along with this work; if not, write to the Free Software Foundation,
				22	Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
				23
				24	Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
				25	CA 95054 USA or visit www.sun.com if you need additional information or
				26	have any questions.
				27	-->
				28	</head>
				29	<body bgcolor="white">
				30	Provides classes and interfaces
				31	that describe the types of Java<sup><font size="-2">TM</font></sup> Print
				32	Service attributes and how they can be collected into attribute sets.
				33	<P>
				34	<H3>What is an Attribute?</H3>
				35	When setting up a print job,
				36	a client specifies two things:
				37	<B>print data</B> and <B>processing instructions.</B>
				38	The print data is the actual content to be printed.
				39	The processing instructions tell the printer how to print the print data,
				40	such as: what media to use, how many copies to print, and
				41	whether to print on one or both sides of a sheet. The client specifies
				42	these processing instructions with the attribute definitions of the Java
				43	Print Service API.
				44	<P>
				45	The print data and the processing instructions
				46	are separate entities. This means that:
				47	<ul>
				48	<li>You can print the same print data
				49	at different times using different processing instructions.
				50	<br>
				51	For example, you can print a slide presentation
				52	on US letter-sized white paper,
				53	double-sided, stapled, 20 copies
				54	to make handouts for a talk;
				55	and you could print the same slide presentation
				56	on US letter-sized transparencies,
				57	single-sided, one copy
				58	to make the actual slides for the talk.
				59	<li>You can use the same processing instructions
				60	at different times to print different data.
				61	For example, you could set your default processing
				62	instructions to: US letter-sized paper, double sided, stapled.
				63	Whenever you print a job, it prints with these settings,
				64	unless you explicitly override them.
				65	</ul>
				66	<P>
				67
				68	The processing instruction does not specify how the print job
				69	processes the request; each processing instruction is only a description
				70	of the results of a print job. The print job determines the manner in
				71	which it achieves the results specified by the processing instructions.
				72	Representing processing instructions as descriptive items
				73	provides more flexibility for implementing print jobs.
				74	<P>
				75	<h4>Attribute Categories and Values</h4>
				76	Each printer has a set of capabilities, such as the ability to print on
				77	different paper sizes or the ability to print more than one copy. Each of
				78	the capabilities has a range of values. For example, a printer's orientation
				79	capability might have this range of values: [landscape, portrait].
				80	For each print request, the capability is set to one of these values. The
				81	Java Print Service API uses the term <b>attribute category</b> to refer to
				82	a printer capability and the term <b>attribute value</b> to refer to the value
				83	of the capability.
				84	<p>
				85	In the Java Print Service API, an attribute category is represented by a Java
				86	class implementing the <a href="Attribute.html">Attribute</a> interface.
				87	Attribute values are instances of such a class or
				88	one of its subclasses. For example, to specify the number of copies, an
				89	application constructs an instance of the
				90	<a href="standard/Copies.html">Copies</a> class with the
				91	number of desired copies and uses the <code>Copies</code> instance as part of
				92	the print request. In this case, the <code>Copies</code> class represents the
				93	attribute category, and the <code>Copies</code> instance represents the
				94	attribute value.
				95
				96	<h4><a name="role"></a>Attribute Roles</h4>
				97
				98	When submitting a print job to a printer, the client provides the
				99	attributes describing the characteristics of the print data, such as
				100	the document name, and how the print data should be printed, such as
				101	double-sided, five copies. If a print job consists of multiple
				102	pieces of print data, different pieces might have different processing
				103	instructions, such as 8 x 11 inch media for the first document, and
				104	11 x 17 inch media for another document.
				105	<p>
				106	Once the printer starts processing the print job,
				107	additional information about the job becomes available, which might include:
				108	the job state (such as <i>completed</i> or <i>queued</i>) and
				109	the number of pages printed so far. These pieces of information are also
				110	attributes. Attributes can also describe the printer itself, such as:
				111	the printer name, the printer location, and the number of jobs queued.
				112	<p>
				113
				114	The Java Print Service API defines these different kinds of attributes
				115	with five subinterfaces of <code>Attribute</code>:
				116	<ul>
				117	<li><A HREF="DocAttribute.html">DocAttribute</A> specifies a characteristic
				118	of an individual document and the print job settings to be applied to an
				119	individual document.
				120	<li><A HREF="PrintRequestAttribute.html">PrintRequestAttribute</A> specifies
				121	a setting applied to a whole print job and to all the documents in
				122	the print job.
				123	<li><A HREF="PrintJobAttribute.html">PrintJobAttribute</A> reports the status
				124	of a print job.
				125	<li><A HREF="PrintServiceAttribute.html">PrintServiceAttribute</A> reports the
				126	status of a print service.
				127	<li><A HREF="SupportedValuesAttribute.html">SupportedValuesAttribute</A> gives
				128	the supported values for another attribute.
				129	</ul>
				130	Each attribute class
				131	implements one or more of these tagging subinterfaces
				132	to indicate where the attribute can be used in the API.
				133	If an attribute class implements multiple tagging subinterfaces,
				134	the attribute can be used in multiple contexts. For example, the media
				135	attribute can apply to one document in a print job as a <code>DocAttribute</code>
				136	or to an entire print job as a <code>PrintRequestAttribute</code>.
				137	Certain low-level attributes
				138	are never used on their own
				139	but are always aggregated into higher-level attributes.
				140	These low-level attribute classes only
				141	implement interface <A HREF="Attribute.html">Attribute</A>,
				142	not any of the tagging subinterfaces.
				143	<P>
				144	The Java Print Service API defines a group of
				145	standard attribute classes modeled upon the attributes in
				146	the Internet Printing Protocol (IPP) version 1.1. The
				147	standard attribute classes are in the subpackage
				148	javax.print.attribute.standard to keep the actual
				149	attribute classes conceptually separate from the generic
				150	apparatus defined in package javax.print.attribute.
				151
				152	<H3>Attribute Sets</H3>
				153	A client usually needs to provide more than one processing
				154	instruction when submitting a print job. For example, the client might need to
				155	specify a media size of A4 and a landscape orientation. To send more than one
				156	processing instruction, the client collects the attributes into an
				157	attribute set, which the Java Print Service API represents with the
				158	<a href="AttributeSet.html">AttributeSet</a>
				159	interface.
				160	<p>
				161	The <code>AttributeSet</code> interface is similar to the
				162	<a href="../../../java/util/Map.html">Map</a> interface: it provides a map of
				163	key to values, in which each key is unique and can contain no more than one
				164	value. However, the <code>AttributeSet</code> interface is designed to
				165	specifically support the needs of the Java Print Service API. An
				166	<code>AttributeSet</code> requires that:
				167	<OL TYPE=1>
				168	<LI>Each key in an <code>AttributeSet</code> corresponds to a category, and
				169	the value of the key can only be one of the attribute values that belong
				170	to the category represented by the key. Thus, unlike a <code>Map</code>, an
				171	<code>AttributeSet</code> restricts the possible values of a key: an
				172	attribute category cannot be set to an attribute value that does not belong to
				173	that category.
				174	<LI>No two attributes from the same category can exist in the same set.
				175	For example, an attribute collection
				176	must not contain both a "one-sided" attribute and a "two-sided" attribute
				177	because these two attributes give the printer conflicting instructions.
				178	<LI>Only attributes implementing the <code>Attribute</code> interface can
				179	be added to the set.
				180	</OL>
				181
				182	<P>
				183	The javax.print.attribute package includes
				184	<A HREF="HashAttributeSet.html">HashAttributeSet</A>
				185	as a concrete implementation of the attribute set interface.
				186	<code>HashAttributeSet</code> provides an attribute set based on a hash map.
				187	You can use this implementation or provide your own implementation
				188	of interface <code>AttributeSet</code>.
				189	<p>
				190	The Java Print Service API provides four specializations of an attribute set
				191	that are restricted to contain just one of the four kinds of attributes,
				192	as discussed in the <a href="#role">Attribute Roles</a> section:
				193	<ul>
				194	<li><A HREF="DocAttributeSet.html">DocAttributeSet</A>
				195	<li><A HREF="PrintRequestAttributeSet.html">PrintRequestAttributeSet</A>
				196	<li><A HREF="PrintJobAttributeSet.html">PrintJobAttributeSet</A>
				197	<li><A HREF="PrintServiceAttributeSet.html">PrintServiceAttributeSet</A>
				198	</ul>
				199	Notice that only four kinds of attribute sets are listed here, but there are
				200	five kinds of attributes. Interface
				201	<A HREF="SupportedValuesAttribute.html">SupportedValuesAttribute</A>
				202	denotes an attribute that gives the supported values for another attribute.
				203	Supported-values attributes are never aggregated into attribute sets,
				204	so there is no attribute set subinterface defined for them.
				205
				206	<P>
				207	In some contexts, an attribute set is read-only, which means that the
				208	client is only allowed to examine an attribute set's
				209	contents but not change them. In other contexts, the attribute set is read-write,
				210	which means that the client is allowed both to examine and to change an
				211	attribute set's contents. For a read-only attribute set, calling a mutating
				212	operation throws an <code>UnmodifiableSetException</code>.
				213	<P>
				214	Package javax.print.attribute includes
				215	one concrete implementation of each of the attribute set subinterfaces:
				216	<ul>
				217	<li><A HREF="HashDocAttributeSet.html">HashDocAttributeSet</A>
				218	<li><A HREF="HashPrintRequestAttributeSet.html">HashPrintRequestAttributeSet</A>,
				219	<li><A HREF="HashPrintJobAttributeSet.html">HashPrintJobAttributeSet</A>,
				220	<li><A HREF="HashPrintServiceAttributeSet.html">HashPrintServiceAttributeSet</A>.
				221	</ul>
				222	All of these classes extend <A HREF="HashAttributeSet.html">HashAttributeSet</A>
				223	and enforce the restriction that the attribute set is only allowed to contain
				224	the corresponding kind of attribute.
				225	<P>
				226	<H3>Attribute Class Design</H3>
				227	An attribute value is a small, atomic data item,
				228	such as an integer or an enumerated value. The Java Print Service API
				229	does not use primitive data types, such as int, to represent attribute
				230	values for these reasons:
				231	<ul>
				232	<li>Primitive data types are not type-safe. For example, a compiler
				233	should not allow a "copies" attribute value to
				234	be used for a "sides" attribute.
				235	<li>Some attributes must be represented as a record of several
				236	values. One example is printer resolution, which requires two
				237	numbers, such as 600 and 300 representing 600 x 300 dpi.
				238	</ul>
				239	For type-safety and to represent all attributes uniformly, the Java
				240	Print Service API defines each attribute category as a class, such as
				241	class <code>Copies</code>, class <a href="standard/Sides.html">Sides</a>, and class
				242	<a href="standard/PrinterResolution.html">PrinterResolution</a>. Each
				243	attribute class wraps one or more primitive data items containing the
				244	attribute's value. Attribute set operations perform frequent
				245	comparisons between attribute category objects when adding attributes,
				246	finding existing attributes in the same category, and looking
				247	up an attribute given its category. Because an attribute category is
				248	represented by a class, fast attribute-value comparisons can be performed
				249	with the <code>Class.equals</code> method.
				250	<p>
				251	Even though the Java Print Service API includes a large number of
				252	different attribute categories, there are only a few different types
				253	of attribute values. Most attributes can be represented by a small
				254	number of data types, such as: integer values, integer ranges, text,
				255	or an enumeration of integer values. The type of the attribute value that
				256	a category accepts is called the attribute's abstract syntax. To
				257	provide consistency and reduce code duplication, the Java Print Service
				258	API defines abstract syntax classes to represent each
				259	abstract syntax, and these classes are used as the parent of standard
				260	attributes whenever possible. The abstract syntax classes are:
				261	<ul>
				262	<li><a href="EnumSyntax.html">EnumSyntax</a>
				263	provides a type-safe enumeration in which enumerated
				264	values are represented as singleton objects. Each enumeration
				265	singleton is an instance of the enumeration class that wraps a hidden
				266	int value.
				267	<li><a href="IntegerSyntax.html">IntegerSyntax</a>
				268	is the abstract syntax for integer-valued attributes.
				269	<li><a href="TextSyntax.html">TextSyntax</a> is
				270	the abstract syntax for text-valued attributes, and
				271	includes a locale giving the text string's natural language.
				272	<li><a href="SetOfIntegerSyntax.html">SetOfIntegerSyntax</a>
				273	is the abstract syntax for attributes
				274	representing a range or set of integers
				275	<li><a href="ResolutionSyntax.html">ResolutionSyntax</a>
				276	is the abstract syntax for attributes representing
				277	resolution values, such as 600x300 dpi.
				278	<li><a href="Size2DSyntax.html">Size2DSyntax</a>
				279	is the abstract syntax for attributes representing a
				280	two-dimensional size, such as a paper size of 8.5 x 11 inches.
				281	<li><a href="DateTimeSyntax.html">DateTimeSyntax</a>
				282	is the abstract syntax for attributes whose value is a date and time.
				283	<li><a href="URISyntax.html">URISyntax</a> is the
				284	abstract syntax for attributes whose value is a Uniform Resource
				285	Indicator.
				286	</ul>
				287	The abstract syntax classes are independent of the attributes that
				288	use them. In fact, applications that have nothing to do with
				289	printing can use the abstract syntax classes. Although most of the
				290	standard attribute classes extend one of the abstract syntax classes,
				291	no attribute class is required to extend one of these classes. The
				292	abstract syntax classes merely provide a convenient implementation that
				293	can be shared by many attribute classes.
				294	<p>
				295	Each attribute class implements the <code>Attribute</code> interface, either
				296	directly or indirectly, to mark it as a printing attribute. An
				297	attribute class that can appear in restricted attribute sets in
				298	certain contexts also implements one or more subinterfaces of
				299	<code>Attribute</code>. Most attribute classes also extend the appropriate
				300	abstract syntax class to get the implementation. Consider the
				301	<code>Sides</code> attribute class:
				302	<pre>
				303	<blockquote>
				304	public class Sides
				305	extends EnumSyntax
				306	implements DocAttribute, PrintRequestAttribute, PrintJobAttribute
				307	{
				308	public final Object getCategory()
				309	{
				310	return Sides.class;
				311	}
				312	...
				313	}
				314	</blockquote>
				315	</pre>
				316	<p>
				317	Since every attribute class implements <code>Attribute</code>, every attribute
				318	class must provide an implementation for the
				319	{@link javax.print.attribute.Attribute#getCategory() getCategory} method,
				320	which returns the attribute category. In the case of <code>Sides</code>, the
				321	<code>getCategory</code> method returns <code>Sides.class</code>. The
				322	<code>getCategory</code> method is final to ensure that any vendor-defined
				323	subclasses of a standard attribute class appear in the same category.
				324	Every attribute object is immutable once constructed so that attribute object
				325	references can be passed around freely. To get a different attribute
				326	value, construct a different attribute object.
				327
				328	<h3>Attribute Vendors</h3>
				329
				330	The Java Print Service API is designed so that vendors can:
				331	<ul>
				332	<li>define new vendor-specific values for any standard attribute
				333	defined in <a href="standard/package-summary.html">
				334	javax.print.attribute.standard</a>.
				335	<li>define new attribute categories representing the vendor printer's
				336	proprietary capabilities not already supported by the standard
				337	attributes.
				338	</ul>
				339	To define a new value for an attribute, a client can construct
				340	instances of such attributes with arbitrary values at runtime.
				341	However, an enumerated attribute using an abstract syntax class
				342	of <code>EnumSyntax</code> specifies all the possible attribute values
				343	at compile time as singleton instances of the attribute class. This
				344	means that new enumerated values cannot be constructed at run time.
				345	To define new vendor-specific values for a standard enumerated
				346	attribute, the vendor must define a new attribute class specifying
				347	the new singleton instances. To ensure that the new attribute values
				348	fall in the same category as the standard attribute values, the new
				349	attribute class must be a subclass of the standard attribute class.
				350	<p>
				351	To define a new attribute category, a vendor defines a new attribute
				352	class. This attribute class, like the standard attribute classes,
				353	implements <code>Attribute</code> or one of its subinterfaces and extends an
				354	abstract syntax class. The vendor can either use an existing
				355	abstract syntax class or define a new one. The new vendor-defined
				356	attribute can be used wherever an <code>Attribute</code> is used, such as in an
				357	<code>AttributeSet</code>.
				358
				359	<h3>Using Attributes</h3>
				360
				361	A typical printing application uses the <code>PrintRequestAttributeSet</code>
				362	because print-request attributes are the types of attributes that
				363	client usually specifies. This example demonstrates creating an attribute
				364	set of print-request attributes and locating a printer that can
				365	print the document according to the specified attributes:
				366	<p>
				367	<pre>
				368	<blockquote>
				369
				370	FileInputStream psStream;
				371	try {
				372	psstream = new FileInputStream("file.ps");
				373	} catch (FileNotFoundException ffne) {
				374	}
				375	if (psstream == null) {
				376	return;
				377	}
				378	//Set the document type. See the DocFlavor documentation for
				379	//more information.
				380	DocFlavor psInFormat = DocFlavor.INPUT_STREAM.POSTSCRIPT;
				381	Doc myDoc = new SimpleDoc(pstream, psInFormat, null);
				382	PrintRequestAttributeSet aset = new HashPrintRequestAttributeSet();
				383	aset.add(new Copies(5));
				384	aset.add(MediaSize.A4);
				385	aset.add(Sides.DUPLEX);
				386
				387	PrintService[] services =
				388	PrintServiceLookup.lookupPrintServices(psInFormat, aset);
				389	if (services.length > 0) {
				390	DocPrintJob job = services[0].createPrintJob();
				391	try {
				392	job.print(myDoc, aset);
				393	} catch (PrintException pe) {}
				394	}
				395	</blockquote>
				396	</pre>
				397	<P>
				398	Please note: In the javax.print APIs, a null reference parameter to methods
				399	is incorrect unless explicitly documented on the method as having a meaningful
				400	interpretation. Usage to the contrary is incorrect coding and may result
				401	in a run time exception either immediately or at some later time.
				402	IllegalArgumentException and NullPointerException are examples of
				403	typical and acceptable run time exceptions for such cases.
				404	<P>
				405	@since 1.4
				406	</body>
				407	</html>