Jini Print Service Tutorial -- Lesson 3. Lookup

## Jini Print Service Tutorial

Introduction Lesson 1. The Very Basics Lesson 2. Print Data Attributes Lesson 3. Lookup Lesson 4. Print Job Status | Lesson 5. Print Job Events Lesson 6. File Print Jobs Lesson 7. URL Print Jobs Lesson 8. Service Registration

## Lesson 3. Lookup

The second shortcoming of the code in Lesson 1 is that it asks the Jini Lookup Service (JLUS) to find any old Jini Print Service instance. There's no guarantee that the Jini Print Service instance it finds will be able to do what we need it to do -- that is, print in landscape orientation, on 8.5 x 11 inch pink paper, and so on. If the Jini Print Service instance doesn't support those printing attributes, it will report an error and the job won't print. However, it would be far better to find a Jini Print Service instance that supported those printing attributes in the first place than to report an error after picking a Jini Print Service instance that happened not to support those attributes.

To tell the JLUS to find a print service that supports the features needed, include service attributes in the service template used for lookup. Below is the example code fragment from Lesson 2 with an augmented service template.

First, lines 28-33 construct and save the Media attribute we want. We will use this Media attribute in two places later.

One characteristic of a doc object is its "doc flavor." The doc flavor specifies the format of the print data obtained from the doc. The print data format consists of two things, a MIME type and a print data representation class. The doc flavor of the doc class we're using, class StringDoc, uses a MIME type of `"text/plain; charset=unicode"` and a print data representation class name of `"java.lang.String"`. When the Jini Print Service instance asks the doc object for the print data, the doc object returns an instance of the print data representation class -- String in this case. The Jini Print Service instance knows how to extract the actual print data from the print data representation object (as specified in interface PrintJob). When the Jini Print Service instance gets the print data, it interprets the print data based on the MIME type -- in this case, plain text in the Unicode character set.

A Jini Print Service instance typically supports several doc flavors with various combinations of various MIME types and various print data representation classes. See class DocFlavor for a list of typical doc flavors that may be supported. Furthermore, a Jini Print Service instance advertises the doc flavors it supports by including FlavorEntry service attributes in its service registration in the JLUS.

In addition, a Jini Print Service instance advertises the printing attribute values it supports by including AttributeEntry service attributes in its service registration in the JLUS. Support for Media attributes is advertised with another service attribute, MediaEntry.

The fact that a Jini Print Service instance advertises the doc flavors and printing attribute values it supports in its service registration means that we can search the JLUS for Jini Print Service instances that are guaranteed to be able to print our job. We do it by setting up a different service template on lines 43-49. The service ID is still null (wildcard) and the service object's type is still PrintService. But now we will also specify some service attributes as an array of class net.jini.core.entry.Entry. (Keep in mind that there is a distinction between a service attribute used when calling JLUS methods and a printing attribute used when calling Jini Print Service methods.)

The service attributes are of three kinds:

- Service attributes that denote doc flavors we are going to use, which we need the Jini Print Service instance to support.
- Service attributes that denote printing attributes we are going to specify, which we need the Jini Print Service instance to support.
- Service attributes that denote general characteristics like printer name, location, manufacturer, and so on.

To specify a needed doc flavor in the service template, wrap the doc flavor inside a service attribute of class FlavorEntry. Line 47 gets the doc flavor from our doc object and wraps it inside a FlavorEntry.

To specify a needed Media attribute value in the service template, wrap the Media attribute value inside a service attribute of class MediaEntry. Line 48 wraps the required Media attribute (created back on line 28) inside a MediaEntry.

To specify a needed printing attribute value (other than Media) in the service template, wrap the printing attribute value inside a service attribute of class AttributeEntry. Line 49 wraps the required orientation attribute, `OrientationRequested.LANDSCAPE`, inside an AttributeEntry.

The DocumentName and JobName attributes are not used for searching the JLUS and should not be included in the service template. Since all printers let you specify any document name or job name for a print job, there's no point in searching for a printer based on whether it supports the document name or job name attributes.

To specify a general characteristic in the service template, include a service attribute of class PrinterDescriptionEntry with the required fields filled in and the other fields set to null. The example code doesn't put any general characteristics in the service template. But if, for example, we had wanted to find a Jini Print Service instance that could print our job and that was named `"Bill Clinton's Printer"`, we might have added something like this to the service template after line 49:

        new PrinterDescriptionEntry
            (new PrinterName ("Bill Clinton's Printer", Locale.getDefault()),
             null, null, null, null, null, null, null, null, null)});

Line 51 calls the JLUS's `lookup()` method to get the service object. With this more specific service template, the JLUS will only find a Jini Print Service instance (a service that has registered a service object of class PrintService) that supports printing plain text strings in landscape orientation on 8.5 x 11 inch pink paper (a service that has registered service attributes equal to those on lines 47-49). The Jini Print Service API has detailed requirements for the service attributes a Jini Print Service instance must include in its service registration. These service attributes describe the Jini Print Service instance's capabilities and permit the JLUS to perform searches like the one coded here. See package net.jini.print.lookup for further information on the service attribute scheme.

It should be noted that in this example, the JLUS's search algorithm, which matches attributes for equality, did the right thing for the attributes we specified. This would not be the case for all attributes. For some attributes, equality is not the right criterion to decide whether the attribute in the Jini Print Service instance's service registration matches the attribute the client specified in the service template. Later Lessons will give examples of such attributes.

DRAFT STANDARD VERSION 1.0 (23-MAY-2000)