| <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> | |
| <!-- package.html - describes classes in javax.print package. | |
| Copyright (C) 2003, 2006 Free Software Foundation, Inc. | |
| This file is part of GNU Classpath. | |
| GNU Classpath is free software; you can redistribute it and/or modify | |
| it under the terms of the GNU General Public License as published by | |
| the Free Software Foundation; either version 2, or (at your option) | |
| any later version. | |
| GNU Classpath is distributed in the hope that it will be useful, but | |
| WITHOUT ANY WARRANTY; without even the implied warranty of | |
| MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU | |
| General Public License for more details. | |
| You should have received a copy of the GNU General Public License | |
| along with GNU Classpath; see the file COPYING. If not, write to the | |
| Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA | |
| 02110-1301 USA. | |
| Linking this library statically or dynamically with other modules is | |
| making a combined work based on this library. Thus, the terms and | |
| conditions of the GNU General Public License cover the whole | |
| combination. | |
| As a special exception, the copyright holders of this library give you | |
| permission to link this library with independent modules to produce an | |
| executable, regardless of the license terms of these independent | |
| modules, and to copy and distribute the resulting executable under | |
| terms of your choice, provided that you also meet, for each linked | |
| independent module, the terms and conditions of the license of that | |
| module. An independent module is a module which is not derived from | |
| or based on this library. If you modify this library, you may extend | |
| this exception to your version of the library, but you are not | |
| obligated to do so. If you do not wish to do so, delete this | |
| exception statement from your version. --> | |
| <html> | |
| <head><title>GNU Classpath - javax.print</title></head> | |
| <body> | |
| Provides the basic interfaces and classes of the Java Print Service API. | |
| <p> | |
| The Java Print Service API enables programmers to: | |
| <ul> | |
| <li>Discover print services for printing to printer devices and to output | |
| streams. The discovery process can be constrained to return only print | |
| services supporting specific document formats or printing attributes.</li> | |
| <li>Print client-formatted print data like Postscript, PDF or various | |
| image formats and service-formatted print data from Java.</li> | |
| <li>Submit, cancel and monitor single and multi document print jobs.</li> | |
| <li>Provide users a graphical print service browser with printing attribute | |
| selection.</li> | |
| </ul> | |
| </p> | |
| <p> | |
| <h2>Print Service Discovery</h2> | |
| Print service types in the JPS API: | |
| <ul> | |
| <li><a href="PrintService.html">PrintService</a>:<br>The base interface | |
| describing a print service capable of printing a supplied document for a | |
| given document format to the printer device it is representing.</li><br> | |
| <li><a href="MultiDocPrintService.html">MultiDocPrintService</a>:<br>Extends | |
| the PrintService interface and provides a print service which is capable of | |
| printing multiple documents as one print job to its printer device.</li><br> | |
| <li><a href="StreamPrintService.html">StreamPrintService</a>:<br>Extends the | |
| PrintService interface and provides a print service which is capable of | |
| printing into a supplied output stream instead of to a physical printer | |
| device.</li> | |
| </ul> | |
| </p> | |
| <p> | |
| <h4>PrintService, MultiDocPrintService</h4> | |
| Discovery is done by the use of the static methods in the | |
| <a href="PrintServiceLookup.html">PrintServiceLookup</a> class. The discovery | |
| process can be constrained by supplying the document formats and printing | |
| attributes that need to be supported by the returned print service. Furthermore | |
| the <a href="PrintServiceLookup.html#lookupDefaultPrintService()"> | |
| lookupDefaultPrintService()</a> method enables to lookup the default print | |
| service of the platforms printing system. | |
| </p> | |
| <p> | |
| <h4>StreamPrintService</h4> | |
| StreamPrintService provides the same functionality as a print service for output | |
| to a supplied <code>OutputStream</code>. Available stream print services are | |
| discovered via the static methods in the <a href="StreamPrintServiceFactory.html"> | |
| StreamPrintServiceFactory</a> factory. The query can be constrained by supplying | |
| the the requested document format support and the needed output format. | |
| </p> | |
| <h2>Document formats</h2> | |
| The format of the printing documents are specified by the | |
| <a href="DocFlavor.html">DocFlavor</a> class in the JPS API. It provides the | |
| description of the format in which the print data will be supplied in a print | |
| job to the print service and consists of two parts: | |
| <ul> | |
| <li>The MIME type (Multipurpose Internet Mail Extensions types as described in | |
| RFC 2045/2046) specifying the media format of the print data.</li> | |
| <br> | |
| <li>The representation class name which is the fully qualified name of the | |
| class providing the print data to the print job. For example if the print data | |
| is supplied as a byte array the representation class name will be "[B" or for | |
| an input stream "java.io.InputStream".</li> | |
| </ul> | |
| The Java Print Service API differentiates between two types of print data, | |
| client-formatted and service-formatted. Client-formatted print data is already | |
| provided in a formatted representation by the client e.g. in an image format | |
| or as postscript. For service-formatted print data, the Java Print Service | |
| implementation produces the formatted print data. Here the doc flavor's | |
| representation class name does specify an interface instead of the actual | |
| print data source. The print service will call the methods of the given | |
| implementation of this interface with a special Graphics object capable of | |
| producing formatted print data from the graphics routines inside the | |
| interface methods. | |
| </ul> | |
| <h2>Printing attributes</h2> | |
| Print services as well as print jobs report their state and capabilities | |
| by the way of supplying printing attributes. Also the behaviour of print | |
| jobs (like how many copies should be printed) is controlled via printing | |
| attributes. For these requirements the JPS API defines different roles | |
| of attributes and common syntax classes in the package | |
| <code>javax.print.attribute</code>. The actual available printing attributes | |
| are implemented in the <code>javax.print.attribute.standard</code> package. | |
| <ul> | |
| <li>Print service attributes:<br> | |
| These printing attributes of role | |
| <a href="attribute/PrintServiceAttribute.html">PrintServiceAttribute</a> report | |
| the status and other informations of a PrintService. Example for informations | |
| available in the print services attributes are the attribute | |
| <code>PagesPerMinute</code> providing the number of pages a printer can print | |
| per minute. Status attributes like the <code>PrinterState</code> attribute | |
| gives the current state (e.g. printer currently processes or is idle) of the | |
| printer.</li> | |
| <br> | |
| <li>Print job attributes:<br> | |
| Print job attributes of role <a href="attribute/PrintJobAttribute.html"> | |
| PrintJobAttribute</a> inform about the status of given print job. For example | |
| the <code>NumberOfInterveningJobs</code> attribute provides the number of jobs | |
| ahead in the print service queue before this job. Status attributes like the | |
| <code>JobState</code> attribute gives the current state of the print job (like | |
| pending, processing or canceled).</li> | |
| <br> | |
| <li>Print request attributes:<br> | |
| The attributes of role <a href="attribute/PrintRequestAttribute.html"> | |
| PrintRequestAttribute</a> specify the behaviour of a complete print job. | |
| The print request attributes apply to all documents in a print job, whereas | |
| the doc attributes only apply to the specific document in a print job. | |
| Most of the print request attributes are also doc attributes and therefore | |
| implementing both attribute role interfaces. | |
| </li> | |
| <br> | |
| <li>Doc attributes:<br> | |
| As described above the <a href="attribute/PrintJobAttribute.html"> | |
| PrintJobAttribute</a> attributes are specific to a single document in the | |
| print job. | |
| </li> | |
| </ul> | |
| <h2>Example of using the API</h2> | |
| <pre> | |
| import java.io.*; | |
| <br> | |
| import javax.print.*; | |
| import javax.print.attribute.*; | |
| import javax.print.attribute.standard.*; | |
| import javax.print.event.*; | |
| <br> | |
| public class Beispiel | |
| { | |
| public static void main(String[] args) | |
| { | |
| // Using the predefined doc flavor for postscript mimetype | |
| DocFlavor flavor = DocFlavor.INPUT_STREAM.POSTSCRIPT; | |
| <br> | |
| // Looking for printservice supporting this doc flavor | |
| PrintService[] services = PrintServiceLookup.lookupPrintServices(flavor, null); | |
| <br> | |
| // Just take the first | |
| PrintService service = services[0]; | |
| System.out.println("Name :" + service.getName()); | |
| <br> | |
| try | |
| { | |
| // Create a print job | |
| DocPrintJob job = service.createPrintJob(); | |
| <br> | |
| // We want to print a file so we construct an inputstream | |
| // on the file to supply the print data as given in the doc flavor | |
| File file = new File("File.ps"); | |
| InputStream stream = new FileInputStream(file); | |
| <br> | |
| // Build a attribute set with the wanted printing attributes | |
| HashPrintRequestAttributeSet attr = new HashPrintRequestAttributeSet(); | |
| attr.add(new Copies(2)); // two copies | |
| attr.add(new PageRanges(2, 7)); // only the 2-7 pages | |
| <br> | |
| // Construct a doc object with the provided class SimpleDoc | |
| SimpleDoc doc = new SimpleDoc(stream, flavor, null); | |
| <br> | |
| // register us as the print - use the adapter class | |
| // and override the interesing failure condition | |
| job.addPrintJobListener(new PrintJobAdapter() | |
| { | |
| public void printJobFailed(PrintJobEvent arg0) | |
| { | |
| System.out.println("The PrintJob failed."); | |
| } | |
| }); | |
| <br> | |
| // start the printing process | |
| job.print(doc, attr); | |
| <br> | |
| // lets assume we want to cancel it | |
| if (job instanceof CancelablePrintJob) | |
| { | |
| CancelablePrintJob cancelJob = (CancelablePrintJob) job; | |
| cancelJob.cancel(); | |
| } | |
| <br> | |
| } | |
| catch (PrintException e) | |
| { | |
| e.printStackTrace(); | |
| } | |
| catch (FileNotFoundException e) | |
| { | |
| e.printStackTrace(); | |
| } | |
| } | |
| } | |
| </pre> | |
| <p> | |
| <b>Since:</b> 1.4 | |
| </p> | |
| </body> | |
| </html> |