| javax.print |
javax.print package
Provides the principal classes and interfaces for the
JavaTM Print Service API.
The Java Print Service API enables client and server applications to:
- Discover and select print services based on their capabilities
- Specify the format of print data
- Submit print jobs to services that support the document type to
be printed.
Print Service Discovery
An application invokes the static methods of the abstract class
{@link javax.print.PrintServiceLookup PrintServiceLookup} to locate print
services that have the capabilities to satisfy the application's print
request. For example, to print a double-sided document, the application
first needs to find printers that have the double-sided printing capability.
The JDK includes PrintServiceLookup implementations that
can locate the standard platform printers. To locate other types of printers,
such as IPP printers or JINI printers, a print-service provider can write
implementations of PrintServiceLookup. The print-service provider
can dynamically install these PrintServiceLookup implementations
using the
SPI JAR file specification.
Attribute Definitions
The {@link javax.print.attribute} and {@link javax.print.attribute.standard}
packages define print attributes, which describe the capabilities of a print
service, specify the requirements of a print job, and track the progress of
a print job.
The javax.print.attribute package describes the types of attributes and
how they can be collected into sets. The javax.print.attribute.standard
package enumerates all of the standard attributes supported by the API, most
of which are implementations of attributes specified in the IETF Specification,
RFC 2911 Internet Printing Protocol, 1.1: Model and Semantics, dated
September 2000. The attributes specified in javax.print.attribute.standard
include common capabilites, such as: resolution, copies, media sizes,
job priority, and page ranges.
Document Type Specification
The {@link javax.print.DocFlavor DocFlavor} class represents the print data
format, such as JPEG or PostScript. A DocFlavor object
consists of a MIME type, which describes the format, and a document
representation class name that indicates how the document is delivered
to the printer or output stream. An application uses the
DocFlavor and an attribute set to find printers that can
print the document type specified by the DocFlavor and have
the capabilities specified by the attribute set.
Using the API
A typical application using the Java Print Service API performs these steps
to process a print request:
- Chooses a
DocFlavor.
- Creates a set of attributes.
- Locates a print service that can handle the print request as specified
by the
DocFlavor and the attribute set.
- Creates a {@link javax.print.Doc Doc} object encapsulating the
DocFlavor
and the actual print data, which can take many forms including: a Postscript
file, a JPEG image, a URL, or plain text.
- Gets a print job, represented by {@link javax.print.DocPrintJob DocPrintJob},
from the print service.
- Calls the print method of the print job.
The following code sample demonstrates a typical use of the Java Print
Service API: locating printers that can print five double-sided copies
of a Postscript document on size A4 paper, creating a print job from
one of the returned print services, and calling print.
FileInputStream psStream;
try {
psStream = new FileInputStream("file.ps");
} catch (FileNotFoundException ffne) {
}
if (psStream == null) {
return;
}
DocFlavor psInFormat = DocFlavor.INPUT_STREAM.POSTSCRIPT;
Doc myDoc = new SimpleDoc(psStream, psInFormat, null);
PrintRequestAttributeSet aset =
new HashPrintRequestAttributeSet();
aset.add(new Copies(5));
aset.add(MediaSize.A4);
aset.add(Sides.DUPLEX);
PrintService[] services =
PrintServiceLookup.lookupPrintServices(psInFormat, aset);
if (services.length > 0) {
DocPrintJob job = services[0].createPrintJob();
try {
job.print(myDoc, aset);
} catch (PrintException pe) {}
}
Please note: In the javax.print APIs, a null reference parameter to methods
is incorrect unless explicitly documented on the method as having a meaningful
interpretation. Usage to the contrary is incorrect coding and may result
in a run time exception either immediately or at some later time.
IllegalArgumentException and NullPointerException are examples of
typical and acceptable run time exceptions for such cases.
@since 1.4
|
| javax.print.attribute |
javax.print.attribute package
Provides classes and interfaces
that describe the types of JavaTM Print
Service attributes and how they can be collected into attribute sets.
What is an Attribute?
When setting up a print job,
a client specifies two things:
print data and processing instructions.
The print data is the actual content to be printed.
The processing instructions tell the printer how to print the print data,
such as: what media to use, how many copies to print, and
whether to print on one or both sides of a sheet. The client specifies
these processing instructions with the attribute definitions of the Java
Print Service API.
The print data and the processing instructions
are separate entities. This means that:
- You can print the same print data
at different times using different processing instructions.
For example, you can print a slide presentation
on US letter-sized white paper,
double-sided, stapled, 20 copies
to make handouts for a talk;
and you could print the same slide presentation
on US letter-sized transparencies,
single-sided, one copy
to make the actual slides for the talk.
- You can use the same processing instructions
at different times to print different data.
For example, you could set your default processing
instructions to: US letter-sized paper, double sided, stapled.
Whenever you print a job, it prints with these settings,
unless you explicitly override them.
The processing instruction does not specify how the print job
processes the request; each processing instruction is only a description
of the results of a print job. The print job determines the manner in
which it achieves the results specified by the processing instructions.
Representing processing instructions as descriptive items
provides more flexibility for implementing print jobs.
Attribute Categories and Values
Each printer has a set of capabilities, such as the ability to print on
different paper sizes or the ability to print more than one copy. Each of
the capabilities has a range of values. For example, a printer's orientation
capability might have this range of values: [landscape, portrait].
For each print request, the capability is set to one of these values. The
Java Print Service API uses the term attribute category to refer to
a printer capability and the term attribute value to refer to the value
of the capability.
In the Java Print Service API, an attribute category is represented by a Java
class implementing the Attribute interface.
Attribute values are instances of such a class or
one of its subclasses. For example, to specify the number of copies, an
application constructs an instance of the
Copies class with the
number of desired copies and uses the Copies instance as part of
the print request. In this case, the Copies class represents the
attribute category, and the Copies instance represents the
attribute value.
Attribute Roles
When submitting a print job to a printer, the client provides the
attributes describing the characteristics of the print data, such as
the document name, and how the print data should be printed, such as
double-sided, five copies. If a print job consists of multiple
pieces of print data, different pieces might have different processing
instructions, such as 8 x 11 inch media for the first document, and
11 x 17 inch media for another document.
Once the printer starts processing the print job,
additional information about the job becomes available, which might include:
the job state (such as completed or queued) and
the number of pages printed so far. These pieces of information are also
attributes. Attributes can also describe the printer itself, such as:
the printer name, the printer location, and the number of jobs queued.
The Java Print Service API defines these different kinds of attributes
with five subinterfaces of Attribute:
Each attribute class
implements one or more of these tagging subinterfaces
to indicate where the attribute can be used in the API.
If an attribute class implements multiple tagging subinterfaces,
the attribute can be used in multiple contexts. For example, the media
attribute can apply to one document in a print job as a DocAttribute
or to an entire print job as a PrintRequestAttribute.
Certain low-level attributes
are never used on their own
but are always aggregated into higher-level attributes.
These low-level attribute classes only
implement interface Attribute,
not any of the tagging subinterfaces.
The Java Print Service API defines a group of
standard attribute classes modeled upon the attributes in
the Internet Printing Protocol (IPP) version 1.1. The
standard attribute classes are in the subpackage
javax.print.attribute.standard to keep the actual
attribute classes conceptually separate from the generic
apparatus defined in package javax.print.attribute.
Attribute Sets
A client usually needs to provide more than one processing
instruction when submitting a print job. For example, the client might need to
specify a media size of A4 and a landscape orientation. To send more than one
processing instruction, the client collects the attributes into an
attribute set, which the Java Print Service API represents with the
AttributeSet
interface.
The AttributeSet interface is similar to the
Map interface: it provides a map of
key to values, in which each key is unique and can contain no more than one
value. However, the AttributeSet interface is designed to
specifically support the needs of the Java Print Service API. An
AttributeSet requires that:
- Each key in an
AttributeSet corresponds to a category, and
the value of the key can only be one of the attribute values that belong
to the category represented by the key. Thus, unlike a Map, an
AttributeSet restricts the possible values of a key: an
attribute category cannot be set to an attribute value that does not belong to
that category.
- No two attributes from the same category can exist in the same set.
For example, an attribute collection
must not contain both a "one-sided" attribute and a "two-sided" attribute
because these two attributes give the printer conflicting instructions.
- Only attributes implementing the
Attribute interface can
be added to the set.
The javax.print.attribute package includes
HashAttributeSet
as a concrete implementation of the attribute set interface.
HashAttributeSet provides an attribute set based on a hash map.
You can use this implementation or provide your own implementation
of interface AttributeSet.
The Java Print Service API provides four specializations of an attribute set
that are restricted to contain just one of the four kinds of attributes,
as discussed in the Attribute Roles section:
Notice that only four kinds of attribute sets are listed here, but there are
five kinds of attributes. Interface
SupportedValuesAttribute
denotes an attribute that gives the supported values for another attribute.
Supported-values attributes are never aggregated into attribute sets,
so there is no attribute set subinterface defined for them.
In some contexts, an attribute set is read-only, which means that the
client is only allowed to examine an attribute set's
contents but not change them. In other contexts, the attribute set is read-write,
which means that the client is allowed both to examine and to change an
attribute set's contents. For a read-only attribute set, calling a mutating
operation throws an UnmodifiableSetException.
Package javax.print.attribute includes
one concrete implementation of each of the attribute set subinterfaces:
All of these classes extend HashAttributeSet
and enforce the restriction that the attribute set is only allowed to contain
the corresponding kind of attribute.
Attribute Class Design
An attribute value is a small, atomic data item,
such as an integer or an enumerated value. The Java Print Service API
does not use primitive data types, such as int, to represent attribute
values for these reasons:
- Primitive data types are not type-safe. For example, a compiler
should not allow a "copies" attribute value to
be used for a "sides" attribute.
- Some attributes must be represented as a record of several
values. One example is printer resolution, which requires two
numbers, such as 600 and 300 representing 600 x 300 dpi.
For type-safety and to represent all attributes uniformly, the Java
Print Service API defines each attribute category as a class, such as
class Copies, class Sides, and class
PrinterResolution. Each
attribute class wraps one or more primitive data items containing the
attribute's value. Attribute set operations perform frequent
comparisons between attribute category objects when adding attributes,
finding existing attributes in the same category, and looking
up an attribute given its category. Because an attribute category is
represented by a class, fast attribute-value comparisons can be performed
with the Class.equals method.
Even though the Java Print Service API includes a large number of
different attribute categories, there are only a few different types
of attribute values. Most attributes can be represented by a small
number of data types, such as: integer values, integer ranges, text,
or an enumeration of integer values. The type of the attribute value that
a category accepts is called the attribute's abstract syntax. To
provide consistency and reduce code duplication, the Java Print Service
API defines abstract syntax classes to represent each
abstract syntax, and these classes are used as the parent of standard
attributes whenever possible. The abstract syntax classes are:
- EnumSyntax
provides a type-safe enumeration in which enumerated
values are represented as singleton objects. Each enumeration
singleton is an instance of the enumeration class that wraps a hidden
int value.
- IntegerSyntax
is the abstract syntax for integer-valued attributes.
- TextSyntax is
the abstract syntax for text-valued attributes, and
includes a locale giving the text string's natural language.
- SetOfIntegerSyntax
is the abstract syntax for attributes
representing a range or set of integers
- ResolutionSyntax
is the abstract syntax for attributes representing
resolution values, such as 600x300 dpi.
- Size2DSyntax
is the abstract syntax for attributes representing a
two-dimensional size, such as a paper size of 8.5 x 11 inches.
- DateTimeSyntax
is the abstract syntax for attributes whose value is a date and time.
- URISyntax is the
abstract syntax for attributes whose value is a Uniform Resource
Indicator.
The abstract syntax classes are independent of the attributes that
use them. In fact, applications that have nothing to do with
printing can use the abstract syntax classes. Although most of the
standard attribute classes extend one of the abstract syntax classes,
no attribute class is required to extend one of these classes. The
abstract syntax classes merely provide a convenient implementation that
can be shared by many attribute classes.
Each attribute class implements the Attribute interface, either
directly or indirectly, to mark it as a printing attribute. An
attribute class that can appear in restricted attribute sets in
certain contexts also implements one or more subinterfaces of
Attribute. Most attribute classes also extend the appropriate
abstract syntax class to get the implementation. Consider the
Sides attribute class:
public class Sides
extends EnumSyntax
implements DocAttribute, PrintRequestAttribute, PrintJobAttribute
{
public final Object getCategory()
{
return Sides.class;
}
...
}
Since every attribute class implements Attribute, every attribute
class must provide an implementation for the
{@link javax.print.attribute.Attribute#getCategory() getCategory} method,
which returns the attribute category. In the case of Sides, the
getCategory method returns Sides.class. The
getCategory method is final to ensure that any vendor-defined
subclasses of a standard attribute class appear in the same category.
Every attribute object is immutable once constructed so that attribute object
references can be passed around freely. To get a different attribute
value, construct a different attribute object.
Attribute Vendors
The Java Print Service API is designed so that vendors can:
- define new vendor-specific values for any standard attribute
defined in
javax.print.attribute.standard.
- define new attribute categories representing the vendor printer's
proprietary capabilities not already supported by the standard
attributes.
To define a new value for an attribute, a client can construct
instances of such attributes with arbitrary values at runtime.
However, an enumerated attribute using an abstract syntax class
of EnumSyntax specifies all the possible attribute values
at compile time as singleton instances of the attribute class. This
means that new enumerated values cannot be constructed at run time.
To define new vendor-specific values for a standard enumerated
attribute, the vendor must define a new attribute class specifying
the new singleton instances. To ensure that the new attribute values
fall in the same category as the standard attribute values, the new
attribute class must be a subclass of the standard attribute class.
To define a new attribute category, a vendor defines a new attribute
class. This attribute class, like the standard attribute classes,
implements Attribute or one of its subinterfaces and extends an
abstract syntax class. The vendor can either use an existing
abstract syntax class or define a new one. The new vendor-defined
attribute can be used wherever an Attribute is used, such as in an
AttributeSet.
Using Attributes
A typical printing application uses the PrintRequestAttributeSet
because print-request attributes are the types of attributes that
client usually specifies. This example demonstrates creating an attribute
set of print-request attributes and locating a printer that can
print the document according to the specified attributes:
FileInputStream psStream;
try {
psstream = new FileInputStream("file.ps");
} catch (FileNotFoundException ffne) {
}
if (psstream == null) {
return;
}
//Set the document type. See the DocFlavor documentation for
//more information.
DocFlavor psInFormat = DocFlavor.INPUT_STREAM.POSTSCRIPT;
Doc myDoc = new SimpleDoc(pstream, psInFormat, null);
PrintRequestAttributeSet aset = new HashPrintRequestAttributeSet();
aset.add(new Copies(5));
aset.add(MediaSize.A4);
aset.add(Sides.DUPLEX);
PrintService[] services =
PrintServiceLookup.lookupPrintServices(psInFormat, aset);
if (services.length > 0) {
DocPrintJob job = services[0].createPrintJob();
try {
job.print(myDoc, aset);
} catch (PrintException pe) {}
}
Please note: In the javax.print APIs, a null reference parameter to methods
is incorrect unless explicitly documented on the method as having a meaningful
interpretation. Usage to the contrary is incorrect coding and may result
in a run time exception either immediately or at some later time.
IllegalArgumentException and NullPointerException are examples of
typical and acceptable run time exceptions for such cases.
@since 1.4
|
| javax.print.attribute.standard |
javax.print.attribute.standard package
Package javax.print.attribute.standard
contains classes for specific printing attributes.
The parent package,
javax.print.attribute,
provides classes and interfaces that describe the types of Java
Print Service attributes and how they can be collected into attribute
sets.
An attribute represents a printing feature
that a print service can provide.
For each attribute,
a print service either does or does not support the attribute.
For each possible value of a supported attribute,
a print service either does or does not support the value.
The API requires every print service
to support certain attributes;
other attributes are optional
and the service can choose whether or not to support them.
Each attribute has a set of values that it accepts. The API
requires every print service to support certain values for
certain attributes;
other attribute values are optional
and the service can choose whether or not to support them.
These support requirements are recorded in the documentation
for each attribute class.
Package javax.print.attribute.standard
contains standard printing attributes
and standard printing attribute values
that are widely used in the printing domain.
A print service vendor
can provide new vendor-specific printing attributes
in addition to the standard ones.
A vendor can also provide
vendor-specific extensions (subclasses)
of the standard printing attributes --
for example,
to provide additional vendor-specific values
for an existing standard attribute.
Of course,
if a vendor wants clients
to be able to use any added or extended attributes,
the vendor must publish the new attribute classes.
Many of the standard attribute classes extend one of
the abstract syntax classes of the javax.print.attribute package.
These abstract syntax classes each represent a
different type. The
EnumSyntax class, for example, represents a type-safe
enumeration. The abstract syntax class provides a wrapper for the attribute
value.
If an attribute class extends EnumSyntax, and the value of the
attribute is an IPP-compatible value, the attribute's toString
method returns the IPP string representation of the attribute value, such as
"processing-stopped" for the
JobState attribute. However, because the
EnumSyntax class is extensible, vendors can define their own
attribute values. If an attribute uses the EnumSyntax class
and is set to one of these vendor-defined values then the toString
method will not return the IPP string representation of the value.
A printing client application
will typically not need to use
all the printing attribute classes
in package javax.print.attribute.standard,
just the ones that pertain to the application.
The attribute classes in package javax.print.attribute.standard
are based on the Internet Printing Protocol (IPP) attributes
as defined in the Internet RFC document,
RFC 2911 Internet Printing Protocol/1.1: Model and Semantics
dated September 2000.
See RFC 2911
for more information.
The descriptive text for each attribute class
was taken largely from the above documents.
The above authors' contribution to the API
is gratefully acknowledged.
Attribute Organization
There are five kinds of printing attributes:
doc attributes,
print request attributes,
print job attributes,
print service attributes,
and supported-values attributes.
Doc Attributes
Doc attributes specify the characteristics of an individual doc
and the print job settings to be applied to an individual doc.
A doc attribute class implements interface
DocAttribute.
A doc attribute can appear in a
DocAttributeSet.
Print Request Attributes
Print request attributes
specify the settings to be applied to a whole print job
and to all the docs in the print job.
A print request attribute class implements interface
PrintRequestAttribute.
A print request attribute can appear in a
PrintRequestAttributeSet.
Some attributes are doc attributes
but not print request attributes
and may only be specified at the doc level.
Some attributes are print request attributes
but not doc attributes
and may only be specified at the Print Request level.
Some attributes are both doc attributes
and print request attributes
and may be specified either at the doc level
or at the Print Request level.
When specified at the doc level,
an attribute applies just to that one doc.
When specified at the Print Request level,
an attribute applies to the whole job,
including all the docs in the job.
However, an attribute specified at the doc level
overrides an attribute in the same category
specified at the Print Request level.
Print Job Attributes
Print job attributes report the status of a Print Job.
A print job attribute class implements interface
PrintJobAttribute.
A print job attribute
can appear in a
PrintJobAttributeSet.
Some attributes are both print request attributes
and print job attributes;
a client may include such attributes in a Print Request
to specify characteristics for the ensuing Print Job,
and those attributes then also appear
in the Print Job's attribute set.
Some attributes are print job attributes
but not print request attributes;
the print service itself
adds these attributes to the Print Job's attribute set.
Print Service Attributes
Print service attributes report the status
of a print service.
A print service attribute class implements interface
PrintServiceAttribute.
A print service attribute
can appear in a
PrintServiceAttributeSet.
Supported-Values Attributes
A supported-value attribute
indicates the legal values for another attribute
that a print service supports.
A supported-values attribute class implements interface
SupportedValuesAttribute.
However, supported-values attributes
never appear in attribute sets,
so there is no restricted
AttributeSet
subinterface for them.
Attribute Table
The table below lists all the printing attributes.
The table shows the tagging interfaces
each attribute class implements
in addition to interface
Attribute,
thus indicating how each attribute is used in the API.
For each doc attribute and print request attribute,
the column marked "SupportedValuesAttribute"
lists the supported-values attribute class, if any,
with which a print service
indicates the supported values for that attribute category.
Please note: In the javax.print APIs, a null reference parameter to methods
is incorrect unless explicitly documented on the method as having a meaningful
interpretation. Usage to the contrary is incorrect coding and may result
in a run time exception either immediately or at some later time.
IllegalArgumentException and NullPointerException are examples of
typical and acceptable run time exceptions for such cases.
@since 1.4
|