Jini Print Service Tutorial

Lesson 2. Print Data Attributes

The first shortcoming of the code in Lesson 1 is that it doesn't tell the Jini Print Service instance how we want the job to be printed -- what kind of paper to use, how many copies to print, and so on. As a consequence, the Jini Print Service instance uses implementation-dependent default values for each of these characteristics. If those defaults happen to be what we want, we're in luck. But Murphy's Law says they won't be what we want, so we have to tell the Jini Print Service instance which printing attributes to use for the job. Suppose, for this example, we want the job to print as follows:

1. The document being printed is named "Test String".
2. It must print on letter-sized (8.5 x 11 inch) pink paper.
3. It must print in landscape orientation (text running the long way on the paper).
4. The print job is named "Test Job".

Below is the example code fragment from Lesson 1 augmented to specify additional printing characteristics. The changed and added lines of code are marked in bold. We will focus our attention only on these new lines; the other lines behave just as before.

You specify the print data characteristics by associating printing attributes with the print data and/or the print job. The Jini Print Service defines many printing attributes in package javax.print.attribute.standard for the purpose of specifying print data or print job characteristics. The Jini Print Service also defines an attribute set data structure (interface AttributeSet) to hold a set of printing attributes.

You can specify printing attributes when you construct the doc object. Line 26 specifies the print data as before, the string "Hello, world!". But now, instead of specifying null, lines 27-30 supply an attribute set containing one or more printing attributes for the doc. Here we use class HashDocAttributeSet to convey the doc's attributes (later we'll say more about why we chose that particular class). The doc's attribute set contains only one attribute, a DocumentName attribute giving the document's name, "Test String". All string-valued printing attributes in the Jini Print Service API are localized, meaning they indicate the string's natural language as well as the string itself. Line 30 specifies the default locale as the document name's natural language.

You can also specify printing attributes in the Print Request object. Lines 42-43 create the Print Request as before. But now, instead of specifying null, lines 44-55 supply an attribute set -- this time, a HashPrintRequestAttributeSet -- containing printing attributes for the whole job. Line 45 supplies an array of three attributes to the HashPrintRequestAttributeSet constructor to populate the attribute set.

For the first print job attribute, lines 46-51 construct a Media attribute to specify letter-sized pink paper. The Media attribute is a collection of orthogonal media characteristics, which are themselves printing attributes. Line 47 supplies an array of four attributes to the Media constructor to populate the Media object:

• The declared constant MediaSize.NA.LETTER indicating a media size of 8.5 x 11 inches.
• The declared constant MediaColor.PINK to make sure we get pink paper instead of some other color.
• The declared constant MediaOpacity.OPAQUE to make sure we don't get transparencies.
• The declared constant MediaKind.SHEET to make sure we get a sheet of paper instead of, say, an envelope.

For the second print job attribute, line 52 specifies the declared constant OrientationRequested.LANDSCAPE to make sure we get landscape orientation instead of portrait.

For the third and final print job attribute, lines 53-55 specify a JobName attribute with the job name, "Test Job".

Thus, printing attributes can be associated with the doc -- document level attributes which pertain just to that doc. Printing attributes can also be associated with the Print Request -- job level attributes which pertain to the whole job. For a print job consisting of a single doc, it really makes no difference whether attributes are specified at the document level or the job level. But it does make a difference for a print job consisting of more than one doc. Then you can specify common attributes at the job level which apply to all the docs, and for each doc you can specify its own unique document level attributes.

However, not every printing attribute is a document level attribute, and not every printing attribute is a job level attribute. To specify how a particular printing attribute is used, the attribute class implements one or more tagging interfaces -- DocAttribute for document level attributes, PrintRequestAttribute for job level attributes. Some attributes can be used at both levels and so implement both tagging interfaces. Likewise, interfaces are defined for attribute sets restricted to contain only one kind of attribute -- DocAttributeSet for document level attribute sets, PrintRequestAttributeSet for job level attribute sets. To ensure that only document level attributes can appear in a doc's attribute set, a doc class's constructor requires an instance of the more restrictive DocAttributeSet interface rather than the general AttributeSet interface. To ensure that only job level attributes can appear in a Print Request's attribute set, the Print Service's factory method requires an instance of the more restrictive PrintRequestAttributeSet interface. The Jini Print Service provides classes HashDocAttributeSet and HashPrintRequestAttributeSet that implement the corresponding interfaces, and we used those classes to set up the doc and Print Request objects.

When the Print Request is told to submit itself on line 56, the Jini Print Service instance will extract the job level and document level attributes from the Print Request object and the doc object and will make sure the Jini Print Service instance can support the specified attributes and attribute values. If the Jini Print Service instance doesn't support one or more of the specified attributes or attribute values, the job won't print. (Such a failure is reported with an event notification -- see Lesson 5.) The Print Service object has capability methods that let you test whether a given print data attribute is supported without actually trying to create or print a job. See interface PrintService for further information. This code does not test whether the attributes are supported but just sets them unconditionally.

Having extracted the printing attributes, the Jini Print Service instance will then extract the print data from the doc object and print the job, using the specified attribute values to determine how to print the job.

DRAFT STANDARD VERSION 1.0 (23-MAY-2000)