| <!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> |
