Jini Print Service API Revision History

Description

This draft incorporates revisions to resolve issues raised with the draft version of 24-Mar-2000 as agreed at the Jini Printing Working Group Meeting of 11-Apr-2000 and subsequently. See the Jini Print Service API Issues List for minutes of the meeting. This draft includes all the capabilities of the first product release subset identified at the Jini Printing Working Group meeting in September 1999. See the Jini Print Service Roadmap Prototyping Subset for a list of these capabilities.

Changes Since Previous Version

Attributes

• Package net.jini.print.util, containing interface CategoricalSet and implementations thereof, was eliminated.

• Interface Attribute was changed to a standalone interface rather than extending CategoricalSet.Value. Its getCategory() method was changed to return type Class (the type for an attribute category) instead of type Object.

• Tagging subinterfaces of interface Attribute were defined to denote how various printing attributes are used -- interfaces DocAttribute, PrintRequestAttribute, PrintJobAttribute, PrintServiceAttribute, and SupportedValuesAttribute. Each attribute class was tagged with one or more of the above tagging subinterfaces instead of interface Attribute.

• Interface AttributeSet was changed to extend interface java.util.Map rather than CategoricalSet.

• Subinterfaces of interface AttributeSet were defined that are restricted to contain just one kind of attribute -- classes DocAttributeSet, PrintRequestAttributeSet, PrintJobAttributeSet, and PrintServiceAttributeSet. Throughout the API, methods that had taken generic AttributeSet arguments or returned generic AttributeSet objects were changed to take or return the proper kind of restricted attribute set.

• Implementations of interface AttributeSet and its subinterfaces were changed to use class java.util.HashMap rather than CategoricalSet implementations.

• Unmodifiable and synchronized views of an attribute set are now provided in class AttributeSetViews rather than class Collections, the new class name being more descriptive.

• The Media attribute and MediaEntry service registration entry were changed to conform to recent changes in the IPP Production Printing Extensions proposal. The following abstract syntax classes were eliminated: WeightSyntax. The following media characteristics were eliminated: MediaWeight. The following media characteristics were added: MediaRecycled, MediaStock, MediaWeightEnglish, and MediaWeightMetric. Class MediaName was renamed MediaDescription. Some additional enumeration values were added to classes MediaColor, MediaKind, and MediaPrePrinted.

• The following abstract syntax classes were added: URLSyntax. The following attributes were added: ColorSupported, PagesPerMinute, PagesPerMinuteColor, PDLOverrideSupported, PrinterInfo, PrinterLocation, PrinterMakeAndModel, PrinterMoreInfo, PrinterMoreInfoManufacturer, PrinterName, ReferenceUriScheme, SheetCollate.

• Many of the individual abstract syntax classes and concrete attribute classes were changed to address issues identified at the 11-Apr-2000 Jini Printing Working Group meeting. See the Jini Print Service API Issues List for further information.

Docs

• Interface Doc was changed to clarify that the getReaderForText() and getStreamForBytes() methods are required to return a valid reader or input stream object if the doc meets the stated criteria.

• The methods in interface Doc were changed to throw an exception in two circumstances: (a) if the doc is leased and the lease object has not been obtained yet, (b) if the print data source cannot provide more than one piece of print data at a time and the printer has not yet finished obtaining a previous doc's print data.

• The documentation in interfaces Doc and LeasedDoc was expanded to clarify how the doc leasing scheme works. The description of print job processing in interface PrintJob was revised to accord with the doc leasing scheme.

• The restriction on the pattern which a Print Service uses to access the individual docs in a MultiDoc was eliminated.

• The documentation in class DocFlavor describing typical doc flavors was rewritten. Classes nested inside class DocFlavor were added to declare predefined static constant doc flavor objects for the example doc flavors.

• In class DocFlavor, support for plain text input stream print data and renderable image print data was made mandatory.

Print Jobs

• The PrintJob.getAttributes() method's documentation was rewritten to clarify which attributes appear in a Print Job's attribute set.

• The description of print job processing in interface PrintJob was expanded to clarify several points, including the treatment of multidoc print jobs in which different docs specify different attribute values for the same attribute category.

• Interfaces PrintRequest, DocPrintRequest, and MultiDocPrintRequest were changed so the only methods that throw a RemoteException are the methods for adding an event listener and submitting the Print Request. These are the only methods that might make a remote method call to the Print Service. The other methods are intended to be implemented locally and therefore no longer throw a RemoteException.

Print Services

• The PrintService.getAttributes() method's documentation was rewritten to clarify which attributes appear in a Print Service's attribute set.

• The capability methods in interface PrintService were revised. Class Settings was defined to hold the doc flavor and attributes for a supposed print job. To simplify the method signatures, and for consistency, all the capability methods were changed to take a Settings argument instead of separate doc flavor and/or attribute set arguments. The following capability methods were added: PrintService.getDefaultAttributeValues(), PrintService.getUnsupportedSettings().

• A capability method was added to interface MultiDocPrintService: getUnsupportedSettings(). Analogous to class Settings, class MultiDocSettings was defined to hold the doc flavors, document-level attributes, and job-level attributes for a supposed multidoc print job.

• Capability methods were added to interface LocalizedPrintService to determine the supported locales and the default locale. The documentation was expanded to clarify how the printer chooses a locale to use if the printer does not support the exact locale the client specifies.

Events

• The printing event class hierarchy was changed to include additional events. Abstract base classes for printing events were added in a new package. See package net.jini.print.event for details.

• The event registration methods in interfaces PrintService, PrintRequest, and PrintJob were changed to align with the new printing event scheme.

Lookup

• The PrinterDescriptionEntry was changed to consist of fields that are printer description attributes instead of generic Integers and Booleans. The Jini Print Service lookup scheme in package net.jini.print.lookup was revised accordingly.

• Class LocaleEntry was added. The Jini Print Service lookup scheme in package net.jini.print.lookup was revised to require a printer to register one LocaleEntry for each supported locale.

Exceptions

• Mixin interfaces URLInaccessibleException and URLSchemeNotSupportedException were added to report specific error conditions involving a URL address.

Doc Implementations

• The example implementations of interfaces Doc and MultiDoc in package org.jpwg.jini.print.data were changed to conform to the new contracts for those interfaces. The doc implementation class hierarchy was reorganized and class LeasedAbstractDoc was added.

Unified Printing API

• The printing attribute classes and interfaces formerly in packages net.jini.print.attribute and net.jini.print.attribute.standard are now in packages javax.print.attribute and javax.print.attribute.standard, respectively.

• The printing exception classes and interfaces formerly in package net.jini.print.exception are now in package javax.print.exception.

• Package javax.print.data was added. Class DocFlavor was moved to package javax.print.data. Interfaces Doc and MultiDoc were added to package javax.print.data. Interfaces net.jini.print.data.Doc and net.jini.print.data.MultiDoc remain in package net.jini.print.data but were changed to extend the like-named superinterfaces in package javax.print.data.

Documentation

• The Tutorial was revised to conform to the above changes.

Description

Changes Since Previous Version

Attributes

• The package summary for net.jini.print.attribute was rewritten and expanded to explain the rationale behind the design of the attribute classes.

• Attribute sets, used for document attributes, job templates, print job status, and printer status, were changed to use a new general-purpose data structure, the categorical set. The categorical set data structure, defined by interface CategoricalSet in a new package net.jini.print.util, is designed to be part of the standard Java collections framework in the core JDK package java.util. Interface AttributeSet was changed to derive from interface CategoricalSet, and the printing attribute base interface Attribute was changed to integrate with the categorical set data structure.

• The tagging interfaces AllOrNoneAttribute, RegisteredAttribute, and SpecialMatchAttribute were eliminated. These existed in the previous API draft to support service registration in the Jini Lookup Service (JLUS). This leaves the attribute classes in packages net.jini.print.attribute and net.jini.print.attribute.standard free of Jini-specific code, hence making them more suitable for use in other printing applications such as core JDK printing (package java.awt.print).

• The abstract syntax classes were renamed from "...Attribute" to "...Syntax", and they no longer implement interface Attribute, to emphasize that these classes are not themselves printing attributes, they are just information containers which in fact could possibly be used in applications besides printing. Each printing attribute class now implements interface Attribute (to mark it as a printing attribute) and extends the appropriate abstract syntax class (to obtain its implementation).

• Class ResolutionSyntax (formerly ResolutionAttribute) was changed to store its values internally in standard units. Operations are provided for converting from the internal units to external units of dots per inch (dpi) or dots per centimeter (dpcm).

• Classes DateTimeSyntax, Size2DSyntax, and WeightSyntax were added.

• The doc description attributes and job template attributes in package net.jini.print.attribute.standard were extensively revised from the previous API draft to bring them in line with the above changes. Especially noteworthy revisions: The former Finishings attribute was split into two independent attributes, FinishingsBinding and FinishingsCover. Attribute JobHoldUntil was changed to let the client specify a job hold-until time as an exact date and time. The Media attribute became a collection of several independent attributes denoting different media characteristics.

• Job description attributes and printer description attributes were added to package net.jini.print.attribute.standard, which now comprises 63 attribute classes.

Docs

• Interface Doc was changed to address issues with docs in a distributed printing system. It is now a non-remote, Serializable interface. Its methods are now defined to behave idempotently; the readPrintData() method's name was changed back to getPrintData(). The documentation was changed to clarify what print data representation object is supposed to be returned if the getPrintData() method is called more than once. The getAttributes() method was changed to return an AttributeSet object instead of an array of attributes.

• Interface LeasedDoc, an extension of interface Doc, was added to optionally convey a lease on the print data to the Print Job.

• Interface DocIterator was eliminated and interface MultiDoc was resurrected to address issues with multiple doc print jobs in a distributed printing system. Interface MultiDoc now has idempotent getDoc() and next() methods providing a "linked list view" of a sequence of docs. The pattern in which a print service proxy is required to use a MultiDoc object was documented.

• Class RemoteInputStream was moved to package net.jini.print.data. It was changed to be an abstract "tagging base class" extending class java.io.InputStream but with no implementation. Its purpose is to require certain behavior after a RemoteException occurs while reading a remote input stream that allows the consumer to recover from transient network failures; this behavior could be achieved in various ways in different concrete subclass implementations. Class RemoteReader, a similar abstract "tagging base class" extending class java.io.Reader, was added.

• The utility methods getReaderForText() and getStreamForBytes() were moved from class DocFlavor to interface Doc.

Doc Implementations

• Package net.jini.print.data.standard was renamed org.jpwg.jini.print.data to emphasize that the implementations in that package are not part of the official Jini Print Service API, but are only examples that clients are free to use or not use as they see fit.

• Package org.jpwg.jini.print.data (formerly package net.jini.print.data.standard) was reorganized. It now contains sample implementations of the Doc interface corresponding to the common print data representation classes for client formatted print data: classes StringDoc, InputStreamDoc, ReaderDoc, and URLDoc. It also contains variants of the input stream and reader docs with leases: classes LeasedInputStreamDoc and LeasedReaderDoc. Finally, it contains two sample implementations of the MultiDoc interface: class ArrayMultiDoc layered on top of an array of docs, and class IteratorMultiDoc layered on top of an Iterator over a collection of docs.

• Class RmiInputStream was rewritten to support recoverable reading of remote byte streams as specified by class RemoteInputStream.

• Class RmiReader was added to support recoverable reading of remote character streams as specified by class RemoteReader.

Print Jobs

• Package net.jini.print.job was reorganized. It now declares interfaces for two job-related objects: a Print Request representing a nascent print job being set up before being submitted to be printed, and a Print Job representing an actual print job that has been submitted to be printed.

• Interfaces PrintRequest, DocPrintRequest, and MultiDocPrintRequest were added to define the class hierarchy for Print Requests.

• Interface PrintJob was rewritten and interface CancelablePrintJob was added to define the class hierarchy for Print Jobs. Interfaces DocPrintJob and MultiDocPrintJob were eliminated (their roles were taken over by DocPrintRequest and MultiDocPrintRequest).

• Classes PrintJobEvent and PrintDataEvent (formerly called PrintJobDataEvent) were rewritten to support the new Print Request/Print Job scheme.

• The description of print job processing (in the documentation for interface PrintJob) was revised and expanded to support the new Print Request/Print Job scheme.

Print Services

• Interface PrintService was changed to create doc Print Request objects instead of Print Job objects. Methods were added to examine the Print Service's set of printer description attributes and to register an event listener for print service events notifying of changes in the printer description attributes. The methods for querying a Print Service's capabilities were augmented to test for supported combinations of doc flavors and printing attributes.

• Interface MultiDocPrintService was changed to create multidoc Print Request objects instead of Print Job objects.

• Interface LocalizedPrintService and class PrintServiceEvent were added.

Lookup

• The names of entry classes SupportedAttributeEntry and SupportedFlavorEntry were shortened to just AttributeEntry and FlavorEntry.

• Entry class AttributeEntry was rewritten to include an attribute runtime class field as well as the attribute category and value fields. The attribute category and runtime class fields were changed from a Class to a String to save space and time in the JLUS.

• Entry classes MediaEntry and PrinterDescriptionEntry were added.

• All the Entry classes now implement interface ServiceControlled.

• Class PrintServiceLookup was eliminated. Code to look up Jini Print Service instances in the JLUS does not properly belong in the core Jini Print Service API. The intention is to provide a class in a non-core package (such as org.jpwg.jini.print.lookup) that works with the Jini Service Discovery Manager to look up Jini Print Service instances.

Exceptions

• The exception classes and interfaces formerly declared in package net.jini.print were moved to package net.jini.print.exception, except for the following: PrintServiceException is in package net.jini.print.service; PrintJobException is in package net.jini.print.job.

• A new class PrintRequestException was added to package net.jini.print.job.

Documentation

• The Overview, Tutorial, and package summaries were revised and expanded to conform to the above changes.

Description

Changes Since Previous Version

• The print exception scheme was changed. It now includes just base class PrintException and subclasses PrintJobException and PrintServiceException. It also includes several mixin interfaces which a print exception subclass can optionally implement to report additional data about the error. The Print Job and Print Service methods now are declared to throw just PrintJobException and PrintServiceException, respectively.

• Two utility operations, getReaderForText() and getStreamForBytes(), were added to class DocFlavor to help a Doc's client extract client formatted print data.

• The leasing scheme was changed. The lease on the Print Service object was eliminated. The Print Job object's lease was pulled out of the Print Job itself. A Print Job object and its associated lease object are now returned together, wrapped in a PrintJobAndLease object. The lease on the Doc object was eliminated, as were the lease and landlord implementation classes in package net.jini.print.data.standard.

• Print Job events were added. Interface PrintJob now includes a method to add a remote event listener to a Print Job. The only Print Job event defined so far is class PrintJobDataEvent which a Print Job reports in response to a print() method call to indicate whether the Print Job successfully obtained the print data. The documentation for class DocPrintJob was updated to specify when Print Job events are reported.

• Interface MultiDocPrintJob was changed to obtain doc objects from a "doc iterator" (interface DocIterator) instead of a regular iterator (interface java.util.Iterator). A regular iterator is unsuitable because interface java.util.Iterator is not a remote interface. A doc iterator implementation layered on top of a regular iterator was added (class RemoteDocIterator).

• The attribute tagging interface NonRegisteredAttribute was eliminated, and RegisteredAttribute took its place. Now, every attribute class included in the service registration in the Jini Lookup Service (JLUS) is explicitly tagged as either a RegisteredAttribute, AllOrNoneAttribute, or SpecialMatchAttribute. Attribute classes not included in the service registration are not tagged.

• Attribute classes for job template attributes were added. However, job templates, job description attributes, and printer description attributes are not in the API yet.

• The Jini Print Service lookup scheme was changed. Class ServiceIDEntry was eliminated. The Print Service Lookup Utility (class PrintServiceLookup) now supports searches based on all the job template attributes, and its methods are now directly analogous to the Jini Lookup Service's lookup() methods.

Description

Changes Since Previous Version

• Interface net.jini.print.data.MultiDoc was eliminated. Instead, a multidoc print job gets its print data from an array or Iterator of doc objects. This lets the client encapsulate a group of docs to be printed using any collection class that supports an Iterator.

• The relationship between doc objects and Print Job objects was changed. Previously, a doc had been considered part of a Print Job. Now, a doc is considered to be printed by a Print Job, but not part of it. Specific consequences of this change are:
  • The Print Service's print job creation methods no longer take a doc or multidoc as an argument; they simply create a Print Job without reference to a specific doc or multidoc. Instead, the doc or multidoc is supplied as a parameter of the Print Job's print() method.
  • The Print Service's print job creation methods no longer verify whether the Jini Print Service instance can support printing the given doc or multidoc. Likewise, the Print Service's isDocSupported() and isMultiDocSupported() methods were eliminated. Instead, the Print Job's print() method does this verification.
  • The Print Job's getDoc() and getMultiDoc() methods were eliminated.
  This change was done in anticipation of a future version of the API in which a client will be able to query a Print Service for its queued Print Jobs. These Print Jobs will be able to report their status in the form of attributes but will not in general be able to report the doc object from which their print data came. Thus, considering a doc to be "part of" a Print Job would be problematic.

• Interface UniDocPrintJob was renamed DocPrintJob to eliminate confusion -- that interface is used to print a doc, not a "unidoc."

• The Print Job's print() method was split into three overloaded methods and moved into subinterfaces: DocPrintJob.print(Doc), MultiDocPrintJob.print(Doc[]), and MultiDocPrintJob.print(Iterator). Analogous changes were made to the print service lookup utility (class net.jini.print.lookup.PrintServiceLookup).

• Package net.jini.print.data.impl, containing implementations of the Doc interface, was renamed net.jini.print.data.standard.

• Leases were added to the Print Service, Print Job, and doc objects. For a Jini Print Service, the Print Service object's lease and the Print Job object's lease let the Jini Print Service detect and recover from client crashes. For a client, the doc object's lease lets the client detect and recover from Jini Print Service crashes.

• The doc implementation class hierarchy in package net.jini.print.data.standard was reorganized to add lease implementations. To manage the doc leases for a client, a landlord implementation was added also (class net.jini.print.data.standard.DocLandlord).

• Interface net.jini.print.data.Doc was changed to require the doc object implementation to function correctly whether its methods are called from the same JVM in which it was created or whether it is sent to a remote JVM and its methods are called from there. This affords greater flexibility to set up a distributed printing system.

• A remote input stream implementation was added (class net.jini.print.data.standard.RemoteInputStream). This lets a doc object supply its print data via an input stream to a Jini Print Service executing either locally or remotely.

• The fields of class net.jini.print.data.DocFlavor were changed from protected scope to private scope. Class net.jini.print.data.MimeType was changed from public scope to package scope. These changes hide implementation details from the client.

• In class net.jini.print.data.DocFlavor, the default character set for a "text/plain" MIME type was changed from US-ASCII to UTF-8.

• The implementation of class net.jini.print.attribute.EnumAttribute was simplified.

• A locale field was added to class net.jini.print.attribute.TextAttribute to let a client optionally specify the text string's natural language.

• Documentation throughout the API as well as the Tutorial were revised in accordance with the above changes.

Description

Changes Since Previous Version

• A new subpackage was added, package net.jini.print.data. Print data formats are now indicated by class DocFlavor instead of the DocumentFormat attribute (which was eliminated). A single piece of print data is encapsulated in an object that implements interface Doc. Multiple pieces of print data are encapsulated in an object that implements interface MultiDoc.

• Another new subpackage was added, package net.jini.print.data.impl, containing example implementations of interfaces Doc and MultiDoc.

• The PrintService interface was rewritten and split into a couple of subinterfaces. Interface PrintService itself contains methods for discovering a Print Service's supported doc flavors, printing attributes, and attribute values. Subinterface UniDocPrintService contains a method for creating a unidoc print job object that will print a specified Doc object, that is, a single piece of print data. Subinterface MultiDocPrintService contains a method for creating a multidoc print job object that will print a specified MultiDoc object, that is, multiple pieces of print data.

• The PrintJob interface was rewritten and split into a couple of subinterfaces. Interface PrintJob itself contains a print() method that extracts the print data from the Doc or MultiDoc object the client supplied when the Print Job was created. Subinterfaces UniDocPrintJob and MultiDocPrintJob contain methods that pertain to unidoc print jobs and multidoc print jobs, respectively.

• The print service lookup scheme in package net.jini.print.lookup was revised to let clients search for Jini Print Service instances that can print a specified Doc or MultiDoc object.

• Documentation throughout the API as well as the Tutorial were revised in accordance with the above changes.

• The getKey() method was added to interface Attribute.

Description

Changes Since Previous Version

• Changed the print exception scheme to afford more flexibility to the client writing exception handlers. There are now three tiers of exceptions: a base exception class, PrintException; exceptions for indicating particular error conditions; and exceptions for indicating particular error conditions encountered by particular methods. See "Exception Classes" in package net.jini.print for further information.

• Changed the semantics of the Print Job methods to follow a "create -- write -- close" pattern and added the ability to write multiple documents to a print job. This aligns the Print Job object's behavior with the printing model defined by the Internet Printing Protocol (IPP) in RFC 2566. See package net.jini.print.job for further information.

• Changed back to interfaces net.jini.print.job.InputStreamPrintJob and net.jini.print.job.OutputStreamPrintJob from interfaces net.jini.print.job.StreamPrintJob and net.jini.print.job.StreamPrintData. Concern was that the two-stage process (get a StreamPrintData object from the print job, then get the actual stream from the StreamPrintData object) has too much potential for client programming errors; the one-stage process (get the stream directly from the print job) is simpler and less error-prone.

• Eliminated the mixin interface SpecializedLookupAttribute and its methods in favor of adding simpler tagging interfaces. Right now just one is defined, interface NonRegisteredAttribute to indicate that a particular attribute is not registered into the Jini Lookup Service (JLUS).

Description

Changes Since Previous Version

• Got rid of the Print Service Factory and all related classes and interfaces. Philosophy is that we will not worry for the moment about client memory limitations, since the code space required to support RMI (about 1/2 a megabyte) seems much greater than the size of a Jini Print Service implementation, and since even low-end clients these days tend to have 2 MB or more of memory. Eliminating the Print Service Factory simplifies the API. But the issue of whether a Print Service Factory is needed will remain open until we get some implementation experience and see just how big Jini Print Service implementations are compared to low-end clients' memory capacities.

• Simplified the attribute scheme by eliminating methods intended to support lookups for limited-resource clients. Attribute became a tagging interface again instead of an abstract base class with methods.

• Eliminated the attribute tagging interfaces which were provided for compile-time safety to prevent attributes from being used in places where they shouldn't be. Concern was that this would limit flexibility by preventing attributes from being used in new contexts in the future. Instead, using an attribute improperly will throw an exception at run time.

• Eliminated the DocumentLocale attribute. Although defined in IPP, it's not clear what this attribute will be used for in any actual printer.

• Incorporated David Mendenhall's code of 14-Oct-1999 for interface Attribute, class EnumAttribute, and class TextAttribute.

• Added mixin interface SpecializedLookupAttribute to support some of the special cases needed when searching the Jini Lookup Service for printing attributes.

Description

Changes Since Previous Version

• Changed from interfaces net.jini.print.job.InputStreamPrintJob and net.jini.print.job.OutputStreamPrintJob to interfaces net.jini.print.job.StreamPrintJob and net.jini.print.job.StreamPrintData. The stream print job object returns a stream print data object. The stream print data object lets the client write print data to an output stream (the push model) or lets the print service read print data from an input stream (the pull model). The stream print data object acts as an adapter between the client-side Java stream and the underlying mechanism that transports the print data to the (possibly remote) print service.

• Changed the way print attributes are registered into the Jini Lookup Service (JLUS) in the service registration. Before, supported print attributes and supported print attribute values were wrapped into separate Entry objects. Now, the Entry object (class SupportedAttributeEntry) contains both items of information, a key field which is the supported print attribute class and a value field which is the supported print attribute value. This arrangement is anticipated to be needed when searching the JLUS for a Jini Print Service instance that can fulfill a given job template (a capability to be added in the next API revision).

• Made net.jini.print.attribute.Attribute an abstract base class instead of an interface. Added methods to class Attribute to support the print service lookup scheme (see package net.jini.print.lookup).

• Added a Tutorial lesson showing how a Jini Print Service instance would set up its service registration to go into the JLUS.

• Moved the specific printing attribute classes from package net.jini.print.attribute to package net.jini.print.attribute.standard. This clarifies the distinction between classes and interfaces that pertain to attributes in general (in package net.jini.print.attribute) and classes for specific attributes (in package net.jini.print.attribute.standard).

Description