Session #, Session Title1 Print APIs for Jini Connection Technology Robert Herriot Xerox Alan Kaminsky Xerox

Session #, Session Title1

Print APIs for Jini™ Connection Technology

Robert HerriotXerox

Alan KaminskyXerox


Goals of Print API

• Allow client software to– find Printers with particular features– submit Print Jobs to a Printer– make use of a Printer’s features, e.g.

• copies (multiple copies of a document)• sides (one-sided or two-sided printing)• finishing (stapling, binding, drilling, folding)

– query Printer and Job characteristics– cancel a Print Job


Source of Print Model for Print APIs

• Print APIs for Jini™ technology (“Jini Print APIs”) are based on “IPP”– a.k.a. Internet Printing Protocol

• IPP is an industry standard– IETF RFC 2565: encoding and transport – IETF RFC 2566: print model

• Many IPP implementations– more than 25 printer and system vendors


IPP Model

outputdevice or proxy

PrinterclientIPP

over network


IPP model in the context of Jini technology

outputdevice or proxy

Printer

client IPP or other protocol

Print Service

Jini look up service

Print Service

Find Print Service


IPP Concepts: Operations

• IPP Operations perform the basic tasks– Examples

• Create-Job• Send-Document• Send-URI

– printer fetches print data from a URI• Cancel-Job• Get-Job-Attributes• Get-Printer-Attributes• Get-Jobs (not in current API)


IPP Concepts: Objects

• Three object classes– Printer

• the software that provides the Print Service

– Job• what the Create-Job operation creates

– Subscription• for notification• not yet an RFC


IPP Concepts: Attributes

• IPP Attributes– act as parameters to operations, e.g.

• copies=4, sides=two-sided-long-edge

– indicate capabilities of a Printer• sides-supported= {one-sided, two-sided-long-edge}

– describe Printer• printer-state=idle

– describe Job• job-state=completed


IPP Encoding & Transport

• RFC 2565 specifies– a binary encoding

• MIME media type is “application/ipp”

– a transport• HTTP using the POST method

• Model allows for other encodings and transports, e.g.– XML– RMI


Print Services based on Java™ Technology

• In packages under javax.print– talk earlier today at JavaOne

• Common infrastructure for printing in– net.jini.print– java.awt.print

• Classes or concepts borrowed from Jini Print API work


Use of Color in this Talk

• Color is used:– specification of an API:

• DocAttributeSet getAttributes()

– code fragment:• new AttributeEntry(Sides) • { Copies(4), Sides.ONE_SIDED }

– for a class name: • PrintService


Jini Print API Overview of Topics

• Infrastructure– Attributes, AttributeSets and DocFlavors– Print Data with Docs and MultiDocs

• Printer Look-up– PrintService

• Job Submission– PrintRequest– PrintJob

• Exceptions and Events


ServiceRegistrar JLUS = // Obtain a Jini Lookup // Service (JLUS) proxyClass[] cl = {PrintService.class};ServiceTemplate tm = new ServiceTemplate(null,cl,null);

PrintService svc =(PrintService) JLUS.lookup (tm);if (svc != null){ DocPrintRequest req = svc.createDocPrintRequest(); Doc doc = new StringDoc ("Hello, world!", null); req.setDoc(doc); HashPrintRequestAttributeSet as = new HashPrintRequestAttributeSet(new Copies(10)); as.add(Sides.TWO_SIDED_LONG_EDGE); req.setAttributes(as); req.print(); }

Sample Code for a Client to Print


Infrastructure: Attributes

• Same concept as IPP Attributes– Examples

• IPP “copies” is Java™ programming language Class (“Java Class”) Copies

• IPP “sides” is Java Class Sides • IPP “printer-state” is Java Class PrinterState

– Exception• IPP “document-format” is Class DocFlavor

– DocFlavor is not an Attribute


javax.print.attribute.standard Class Copies (hierarchy)Class Copies

Class IntegerSyntax

Interface PrintJobAttribute

Interface PrintRequestAttribute

Interface Attribute

Interface Attribute

Class Object

Interface Serializable

Interface Cloneabledata type

attribute name

can be member of PrintRequest

can be member of PrintJob

is an attribute


javax.print.attribute Interface PrintJobAttribute

• Tags the attribute– attribute can be a member of a PrintJob

• provides type safety for setting values

• Other similar classes– Naming pattern: ClassNameAttribute

• DocAttribute• PrintRequestAttribute• PrintServiceAttribute


javax.print.attribute Class IntegerSyntax

• For an Attribute with an integer value• Provides access to

– integer value• int getValue()• String toString()

• Provides service– equals

• boolean equals(Object)

– hash code• int hashcode()


javax.print.attribute.standard Class Copies

• Provides access to– attribute name

• Class getCategory()

– i.e. Copies.class• String getName()

– i.e. "Copies" – integer value (inherited from IntegerSyntax)

• int getValue()– e.g. 10

• String toString()

– e.g. "10"


javax.print.attribute.standard Class PrinterState (hierarchy)

Class PrinterState

Class EnumSyntax

Interface PrintServiceAttribute

Interface Attribute

Class Object

Interface Serializable

Interface Cloneabledata type

attribute name

can be member of PrintService

is an attribute


javax.print.attribute.standard Class PrinterState

• Provides access to – attribute name

• Class getCategory()

– i.e. PrinterState.class• String getName()

– i.e. "PrinterState" – value (inherited from EnumSyntax)

• String toString()– e.g. "idle", "stopped” or "processing"

• predefined constants– e.g. PrinterState.IDLE, PrinterState.STOPPED

or PrinterState.PROCESSING X


javax.print.attributeInterface AttributeSet

• Extends Interface java.util.Map• Is a set of attributes with distinct names

– e.g. { Copies(4), Sides.ONE_SIDED }NOT {Sides.ONE_SIDED,Sides.TWO_SIDED_LONG_EDGE}

• Has subinterfaces– Naming pattern: ClassNameAttributeSet

• DocAttributeSet• PrintJobAttributeSet• PrintRequestAttributeSet• PrintServiceAttributeSet


javax.print.attributeInterface AttributeSet (services)

• Provides services– methods of java.util.Map– special get method

• Attribute get(Class);– e.g. get(Sides) -> Sides.ONE_SIDED

– special variant of put method• boolean add(Attribute);

– e.g. add(Sides.ONE_SIDED)is equivalent to Sides s = Sides.ONE_SIDED; put(s.getCategory(),s);Note: s.getCategory() == Sides.class


javax.print.attributeClass HashAttributeSet

• Extends Class java.util.HashMap• Implements Interface AttributeSet• Has subclasses

– Naming pattern: HashClassNameAttributeSet • HashDocAttributeSet• HashPrintJobAttributeSet• HashPrintRequestAttributeSet• HashPrintServiceAttributeSet


javax.print.data Class DocFlavor

• Specifies – the MIME media type of a Document, e.g.

• "text/plain"• "application/PostScript"• "image/jpeg"

– the class of Print Data object, e.g.• char[]• byte[]• java.lang.String• java.io.InputStream• java.awt.print.Printable


Infrastructure: Print Data

• E.g., if the Print Data is a PostScript File– Class DocFlavor specifies

• application/PostScript (as MIME media type)• java.io.InputStream (as Print Data class)

• Two Interfaces for Print Data– Doc wraps the Print Data

• implemented by a client application

– MultiDoc contains multiple Docs• implemented by a client application


net.jini.print.data Interface Doc

• Extends Interface javax.print.data.Doc– methods throw RemoteException

• methods in javax.print.data throw IOException

• Provides access to– Associated attributes

• DocAttributeSet getAttributes()

– Continued on next slide


net.jini.print.data Interface Doc (more access)

• Provides access to– Its DocFlavor,

• DocFlavor getFlavor()

• returns e.g. DocFlavor.INPUT_STREAM.POSTSCRIPT

– Object containing Print Data• Object getPrintData()

• returns e.g. java.io.InputStream object

– Reader or InputStream for Print Data• Reader getReaderForText()• InputStream getStreamForBytes()


net.jini.print.data Interface MultiDoc

• Extends Interface javax.print.data.MultiDoc– methods throw RemoteException

• methods in javax.print.data throw IOException• Contains data of multiple documents

– Acts like a linked list of Doc elements• Provides access to

– Doc of list element: it is accessible with• Doc getDoc()

– Remaining MultiDoc: it is accessible with• MultiDoc next()


Jini™ Technology Look-up Service (review)

• Client specifies any of– java.lang.Class[ ], e.g.

• (Class[]){ PrintService }

– net.jini.core.entry.Entry[ ], e.g.• (Entry[]){ net.jini.lookup.entry.Location (“floor 2”,“room 12”, “bldg 23”) }

• Look-up Service returns a matching service Object, e.g.

• PrintService• MultiDocPrintService


net.jini.print.lookup Class AttributeEntry

• Extends net.jini.entry.AbstractEntry– which implements Entry

• Matches Entry in Look-up service– any Attribute

• new AttributeEntry()

– any Attribute of a specified class, e.g.• new AttributeEntry(Sides)

– any Attribute with specified value (& class), e.g.• new AttributeEntry(Sides.ONE_SIDED)


net.jini.print.lookup Class FlavorEntry

• Extends net.jini.entry.AbstractEntry– which implements Entry

• Matches Entry in Look-up service– any DocFlavor

• new FlavorEntry()

– any DocFlavor with specified value, e.g.• new FlavorEntry(DocFlavor.BYTE_ARRAY.JPEG)


net.jini.print.service Interface PrintService

• Gives access to the Printer– Provides access to attributes that relate to

• Printer information• Printer capabilities for Job Creation

– Provides services of• Events• Job Creation


net.jini.print.service Interface PrintService (info)

• Provides access to Printer Information– attribute values of all Printer attributes

• PrintServiceAttributeSet getAttributes()• returns e.g. { PrinterState.PROCESSING, new PrinterName("speedy",locale), new QueuedJobCount(8),… }


net.jini.print.service Interface PrintService (Job Creation)

• Provides access to Job Creation info– attribute names supported,

• Class[] getSupportedAttributeCategories(… )• returns e.g. (Class[]){ Sides, Copies, … }

– attribute values supported• Object getSupportedAttributeValues(Class,…)• returns e.g. (with parameters (Sides, … )) (Sides[]) {Sides.ONE_SIDED,Sides.TWO_SIDED_LONG_EDGE}

• DocFlavors[] getSupportedDocFlavors()


net.jini.print.service Interface PrintService (Job Creation)

• Provides access to Job Creation info– default attribute values

• Object getDefaultAttributeValue(Class)• returns e.g. (with parameter (Sides)) Sides.TWO_SIDED_LONG_EDGE


net.jini.print.service Interface PrintService (services)

• Provides services– adds an event listener

• for changes in PrintService attribute values

– creates a PrintRequest• DocPrintRequest CreateDocPrintRequest()


net.jini.print.service Interface LocalizedPrintService

• Extends PrintService– Exists if a PrintService provides localized strings

• Provides access to – supported locales

• Locale[] getSupportedLocales()

• Provides services– localizes attribute names

• String localize(Class,Locale)

– localizes attribute and DocFlavor values• String localize(Attribute,Locale)• String localize(DocFlavor,Locale)


net.jini.print.service Interface MultiDocPrintService

• Extends PrintService– Exists if a PrintService allows jobs to contain

more than one Document

• Provides services– creates a PrintRequest

• MultiDocPrintRequest CreateMultiDocPrintRequest()


Steps in Job Submission (1)

• With PrintService– Client creates PrintRequest

• e.g.DocPrintRequest req = svc.createDocPrintRequest();

– Printer doesn’t remember PrintRequests


Steps in Job Submission (2)

• With a PrintRequest, a client– Adds Attributes and Doc’s (i.e. Print Data)

• e.g. req.setDoc(doc);HashPrintRequestAttributeSet as = new HashPrintRequestAttributeSet(new Copies(10));as.add(Sides.TWO_SIDED_LONG_EDGE);req.setAttributes(as);

– Then creates a PrintJob with the print method • e.g. req.print();

– Can track progress of a PrintJob


net.jini.print.job Interface PrintRequest

• Acts as a container for – Attributes– Doc’s (i.e. Print Data)

• Has two subinterfaces for setting Doc’s– DocPrintRequest:

• void SetDoc(Doc)

– MultiDocPrintRequest:• void SetMultiDoc(MultiDoc)


net.jini.print.job Interface PrintRequest (services)

• Provides Services– Sets Attributes requested for the Job

• void SetAttributes(PrintRequestAttributeSet)

– Adds event listeners• for changes in PrintJob attribute values

– Submits PrintRequest to Printer• void Print()• PrintJobAndLease Print(long leaseDuration)


net.jini.print.job Class PrintJobAndLease

• Extends Object• Contains two objects

– net.jini.core.lease.Lease• client must hold a lease on the PrintJob

– PrintJob


net.jini.print.job Interface PrintJob

• Represents a Job on the Printer– i.e. the Printer has knowledge of it.

• Provides access to– Attributes in the PrintJob

• PrintJobAttributeSet getAttributes()

• Provides services– Adds event listener

• for changes in PrintJob attribute values• same method and effect as for PrintRequest


net.jini.print.job Interface CancelablePrintJob

• Extends PrintJob– Exists if a PrintService allows a client to

cancel a PrintJob

• Allows client to cancel a PrintJob• void cancel()


javax.print.exception Class PrintException

• Extends java.lang.Exception• 3 subclasses classNameException

• net.jini.print.service.PrintServiceException• net.jini.print.job.PrintRequestException• net.jini.print.job.PrintJobException

• Interfaces for additional information• AttributeException• DocFlavorException• NestedException


net.jini.print.service Class PrintServiceException

• Is thrown during PrintRequest creation by– Interface PrintService for

• DocPrintRequest CreateDocPrintRequest()

– Interface MultiDocPrintService for• MultiDocPrintRequest CreateMultiDocPrintRequest()

• Provides access to– PrintService object causing exception

• PrintService getPrintService()


net.jini.print.job Class PrintRequestException

• Is thrown during PrintJob creation by– Interface PrintRequest

• void Print()• PrintJobAndLease Print(long leaseDuration)

• Provides access to– PrintRequest object causing exception

• PrintRequest getPrintRequest()

– Unsupported attributes or values (optional)• via javax.print.exception.AttributeException

– Class[] getUnsupportdAttributes()– Attribute[] getUnsupportdValues()


net.jini.print.job Class PrintJobException

• Is thrown by– Interface CancelablePrintJob

• void cancel()

• Provides access to– PrintJob object causing exception

• PrintJob getPrintJob()

– NestedException (optional)• via javax.print.exception.NestedException

– Throwable getNestedException()


Events

• can add event listeners to:– PrintService– PrintRequest– PrintJob

• can listen for change of– any attribute– any specified attribute– any attribute achieving a specified value


net.jini.print.event Class PrintEvent

• Extends Jini technology RemoteEvent– net.jini.core.remote.RemoteEvent

• Provides access to event’s PrintService• PrintService getPrintService()

• Has subclasses:– PrintServiceEvent– PrintJobEvent– PrintDataEvent– PrintJobFinishedEvent


net.jini.print.serviceClass PrintServiceEvent

• Sent when attribute value changes in– PrintService

• Provides access to– Attributes that changed

• PrintServiceAttributeSet getAttributes()

– Event’s PrintService • in superclass PrintEvent (just discussed)• PrintService getPrintService()


net.jini.print.jobClass PrintJobEvent

• Sent when attribute value changes in– PrintJob

• Provides access to– Attributes that changed in PrintJob

• PrintJobAttributeSet getAttributes()

– PrintJob in which attributes changed• PrintJob getPrintJob()


net.jini.print.jobClass PrintDataEvent

• Sent when Printer has finished obtaining a unit (Doc) of Print Data

• Provides access to– Whether the Printer was successful

• boolean succeeded()

– Exception if the Printer failed• Throwable getException()

– PrintJob intended to receive the print data• PrintJob getPrintJob()


net.jini.print.jobClass PrintJobFinishedEvent

• Sent when Printer has finished printing a PrintJob

• Provides access to– JobState of the PrintJob when it finished

• JobState getFinalState()• returns e.g. JobState.COMPLETED, orJobState.CANCELED, or JobState.ABORTED

– PrintJob that finished• PrintJob getPrintJob()


Documentation for Jini Print API

• Web page for Jini Printing Working Group– http://developer.jini.org/exchange/users/jpgwg

• Latest document is (with above prefix):– JiniPrintService/standards/

JiniPrintServiceApi20000523.zip

Documents

Session #, Session Title1 Print APIs for Jini Connection Technology Robert Herriot Xerox Alan Kaminsky Xerox