libjava/classpath/javax/print/package.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
   2 <!-- package.html - describes classes in javax.print package.
   3    Copyright (C) 2003, 2006 Free Software Foundation, Inc.
   4
   5 This file is part of GNU Classpath.
   6
   7 GNU Classpath is free software; you can redistribute it and/or modify
   8 it under the terms of the GNU General Public License as published by
   9 the Free Software Foundation; either version 2, or (at your option)
  10 any later version.
  11
  12 GNU Classpath is distributed in the hope that it will be useful, but
  13 WITHOUT ANY WARRANTY; without even the implied warranty of
  14 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  15 General Public License for more details.
  16
  17 You should have received a copy of the GNU General Public License
  18 along with GNU Classpath; see the file COPYING.  If not, write to the
  19 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
  20 02110-1301 USA.
  21
  22 Linking this library statically or dynamically with other modules is
  23 making a combined work based on this library.  Thus, the terms and
  24 conditions of the GNU General Public License cover the whole
  25 combination.
  26
  27 As a special exception, the copyright holders of this library give you
  28 permission to link this library with independent modules to produce an
  29 executable, regardless of the license terms of these independent
  30 modules, and to copy and distribute the resulting executable under
  31 terms of your choice, provided that you also meet, for each linked
  32 independent module, the terms and conditions of the license of that
  33 module.  An independent module is a module which is not derived from
  34 or based on this library.  If you modify this library, you may extend
  35 this exception to your version of the library, but you are not
  36 obligated to do so.  If you do not wish to do so, delete this
  37 exception statement from your version. -->
  38
  39 <html>
  40 <head><title>GNU Classpath - javax.print</title></head>
  41 <body>
  42 Provides the basic interfaces and classes of the Java Print Service API.
  43 <p>
  44 The Java Print Service API enables programmers to:
  45 <ul>
  46 <li>Discover print services for printing to printer devices and to output
  47 streams. The discovery process can be constrained to return only print
  48 services supporting specific document formats or printing attributes.</li>
  49 <li>Print client-formatted print data like Postscript, PDF or various
  50 image formats and service-formatted print data from Java.</li>
  51 <li>Submit, cancel and monitor single and multi document print jobs.</li>
  52 <li>Provide users a graphical print service browser with printing attribute
  53 selection.</li>
  54 </ul>
  55 </p>
  56 <p>
  57 <h2>Print Service Discovery</h2>
  58
  59 Print service types in the JPS API:
  60 <ul>
  61 <li><a href="PrintService.html">PrintService</a>:<br>The base interface
  62 describing a print service capable of printing a supplied document for a
  63 given document format to the printer device it is representing.</li><br>
  64 <li><a href="MultiDocPrintService.html">MultiDocPrintService</a>:<br>Extends
  65 the PrintService interface and provides a print service which is capable of
  66 printing multiple documents as one print job to its printer device.</li><br>
  67 <li><a href="StreamPrintService.html">StreamPrintService</a>:<br>Extends the
  68 PrintService interface and provides a print service which is capable of
  69 printing into a supplied output stream instead of to a physical printer
  70 device.</li>
  71 </ul>
  72 </p>
  73 <p>
  74 <h4>PrintService, MultiDocPrintService</h4>
  75 Discovery is done by the use of the static methods in the
  76 <a href="PrintServiceLookup.html">PrintServiceLookup</a> class. The discovery
  77 process can be constrained by supplying the document formats and printing
  78 attributes that need to be supported by the returned print service. Furthermore
  79 the <a href="PrintServiceLookup.html#lookupDefaultPrintService()">
  80 lookupDefaultPrintService()</a> method enables to lookup the default print
  81 service of the platforms printing system.
  82 </p>
  83 <p>
  84 <h4>StreamPrintService</h4>
  85 StreamPrintService provides the same functionality as a print service for output
  86 to a supplied <code>OutputStream</code>. Available stream print services are
  87 discovered via the static methods in the <a href="StreamPrintServiceFactory.html">
  88 StreamPrintServiceFactory</a> factory. The query can be constrained by supplying
  89 the the requested document format support and the needed output format.
  90 </p>
  91
  92 <h2>Document formats</h2>
  93
  94 The format of the printing documents are specified by the
  95 <a href="DocFlavor.html">DocFlavor</a> class in the JPS API. It provides the
  96 description of the format in which the print data will be supplied in a print
  97 job to the print service and consists of two parts:
  98 <ul>
  99 <li>The MIME type (Multipurpose Internet Mail Extensions types as described in
 100 RFC 2045/2046) specifying the media format of the print data.</li>
 101 <br>
 102 <li>The representation class name which is the fully qualified name of the
 103 class providing the print data to the print job. For example if the print data
 104 is supplied as a byte array the representation class name will be "[B" or for
 105 an input stream "java.io.InputStream".</li>
 106 </ul>
 107 The Java Print Service API differentiates between two types of print data,
 108 client-formatted and service-formatted. Client-formatted print data is already
 109 provided in a formatted representation by the client e.g. in an image format
 110 or as postscript. For service-formatted print data, the Java Print Service
 111 implementation produces the formatted print data. Here the doc flavor's
 112 representation class name does specify an interface instead of the actual
 113 print data source. The print service will call the methods of the given
 114 implementation of this interface with a special Graphics object capable of
 115 producing formatted print data from the graphics routines inside the
 116 interface methods.
 117 </ul>
 118 <h2>Printing attributes</h2>
 119
 120 Print services as well as print jobs report their state and capabilities
 121 by the way of supplying printing attributes. Also the behaviour of print
 122 jobs (like how many copies should be printed) is controlled via printing
 123 attributes. For these requirements the JPS API defines different roles
 124 of attributes and common syntax classes in the package
 125 <code>javax.print.attribute</code>. The actual available printing attributes
 126 are implemented in the <code>javax.print.attribute.standard</code> package.
 127 <ul>
 128
 129 <li>Print service attributes:<br>
 130 These printing attributes of role
 131 <a href="attribute/PrintServiceAttribute.html">PrintServiceAttribute</a> report
 132 the status and other informations of a PrintService. Example for informations
 133 available in the print services attributes are the attribute
 134 <code>PagesPerMinute</code> providing the number of pages a printer can print
 135 per minute. Status attributes like the <code>PrinterState</code> attribute
 136 gives the current state (e.g. printer currently processes or is idle) of the
 137 printer.</li>
 138 <br>
 139 <li>Print job attributes:<br>
 140 Print job attributes of role <a href="attribute/PrintJobAttribute.html">
 141 PrintJobAttribute</a> inform about the status of given print job. For example
 142 the <code>NumberOfInterveningJobs</code> attribute provides the number of jobs
 143 ahead in the print service queue before this job. Status attributes like the
 144 <code>JobState</code> attribute gives the current state of the print job (like
 145 pending, processing or canceled).</li>
 146 <br>
 147 <li>Print request attributes:<br>
 148 The attributes of role <a href="attribute/PrintRequestAttribute.html">
 149 PrintRequestAttribute</a> specify the behaviour of a complete print job.
 150 The print request attributes apply to all documents in a print job, whereas
 151 the doc attributes only apply to the specific document in a print job.
 152 Most of the print request attributes are also doc attributes and therefore
 153 implementing both attribute role interfaces.
 154 </li>
 155 <br>
 156 <li>Doc attributes:<br>
 157 As described above the <a href="attribute/PrintJobAttribute.html">
 158 PrintJobAttribute</a> attributes are specific to a single document in the
 159 print job.
 160 </li>
 161 </ul>
 162
 163 <h2>Example of using the API</h2>
 164 <pre>
 165 import java.io.*;
 166 <br>
 167 import javax.print.*;
 168 import javax.print.attribute.*;
 169 import javax.print.attribute.standard.*;
 170 import javax.print.event.*;
 171 <br>
 172 public class Beispiel
 173 {
 174 &nbsp; public static void main(String[] args)
 175 &nbsp; {
 176 &nbsp; &nbsp; // Using the predefined doc flavor for postscript mimetype
 177 &nbsp; &nbsp; DocFlavor flavor = DocFlavor.INPUT_STREAM.POSTSCRIPT;
 178 <br>
 179 &nbsp; &nbsp; // Looking for printservice supporting this doc flavor
 180 &nbsp; &nbsp; PrintService[] services = PrintServiceLookup.lookupPrintServices(flavor, null);
 181 <br>
 182 &nbsp; &nbsp; // Just take the first
 183 &nbsp; &nbsp; PrintService service = services[0];
 184 &nbsp; &nbsp; System.out.println("Name :" + service.getName());
 185 <br>
 186 &nbsp; &nbsp; try
 187 &nbsp; &nbsp; &nbsp; {
 188 &nbsp; &nbsp; &nbsp; &nbsp; // Create a print job
 189 &nbsp; &nbsp; &nbsp; &nbsp; DocPrintJob job = service.createPrintJob();
 190 <br>
 191 &nbsp; &nbsp; &nbsp; &nbsp; // We want to print a file so we construct an inputstream
 192 &nbsp; &nbsp; &nbsp; &nbsp; // on the file to supply the print data as given in the doc flavor
 193 &nbsp; &nbsp; &nbsp; &nbsp; File file = new File("File.ps");
 194 &nbsp; &nbsp; &nbsp; &nbsp; InputStream stream = new FileInputStream(file);
 195 <br>
 196 &nbsp; &nbsp; &nbsp; &nbsp; // Build a attribute set with the wanted printing attributes
 197 &nbsp; &nbsp; &nbsp; &nbsp; HashPrintRequestAttributeSet attr = new HashPrintRequestAttributeSet();
 198 &nbsp; &nbsp; &nbsp; &nbsp; attr.add(new Copies(2)); // two copies
 199 &nbsp; &nbsp; &nbsp; &nbsp; attr.add(new PageRanges(2, 7)); // only the 2-7 pages
 200 <br>
 201 &nbsp; &nbsp; &nbsp; &nbsp; // Construct a doc object with the provided class SimpleDoc
 202 &nbsp; &nbsp; &nbsp; &nbsp; SimpleDoc doc = new SimpleDoc(stream, flavor, null);
 203 <br>
 204 &nbsp; &nbsp; &nbsp; &nbsp; // register us as the print - use the adapter class
 205 &nbsp; &nbsp; &nbsp; &nbsp; // and override the interesing failure condition
 206 &nbsp; &nbsp; &nbsp; &nbsp; job.addPrintJobListener(new PrintJobAdapter()
 207 &nbsp; &nbsp; &nbsp; &nbsp; {
 208 &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; public void printJobFailed(PrintJobEvent arg0)
 209 &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; {
 210 &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; System.out.println("The PrintJob failed.");
 211 &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; }
 212 &nbsp; &nbsp; &nbsp; &nbsp; });
 213 <br>
 214 &nbsp; &nbsp; &nbsp; &nbsp; // start the printing process
 215 &nbsp; &nbsp; &nbsp; &nbsp; job.print(doc, attr);
 216 <br>
 217 &nbsp; &nbsp; &nbsp; &nbsp; // lets assume we want to cancel it
 218 &nbsp; &nbsp; &nbsp; &nbsp; if (job instanceof CancelablePrintJob)
 219 &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; {
 220 &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; CancelablePrintJob cancelJob = (CancelablePrintJob) job;
 221 &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; cancelJob.cancel();
 222 &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; }
 223 <br>
 224 &nbsp; &nbsp; &nbsp; }
 225 &nbsp; &nbsp; catch (PrintException e)
 226 &nbsp; &nbsp; {
 227 &nbsp; &nbsp; &nbsp; e.printStackTrace();
 228 &nbsp; &nbsp; }
 229 &nbsp; &nbsp; catch (FileNotFoundException e)
 230 &nbsp; &nbsp; {
 231 &nbsp; &nbsp; &nbsp; e.printStackTrace();
 232 &nbsp; &nbsp; }
 233 &nbsp; }
 234 }
 235 </pre>
 236 <p>
 237 <b>Since:</b> 1.4
 238 </p>
 239 </body>
 240 </html>