<!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
{
&nbsp; public static void main(String[] args)
&nbsp; {
&nbsp; &nbsp; // Using the predefined doc flavor for postscript mimetype
&nbsp; &nbsp; DocFlavor flavor = DocFlavor.INPUT_STREAM.POSTSCRIPT;
<br>
&nbsp; &nbsp; // Looking for printservice supporting this doc flavor
&nbsp; &nbsp; PrintService[] services = PrintServiceLookup.lookupPrintServices(flavor, null);
<br>
&nbsp; &nbsp; // Just take the first
&nbsp; &nbsp; PrintService service = services[0];
&nbsp; &nbsp; System.out.println("Name :" + service.getName());
<br>
&nbsp; &nbsp; try
&nbsp; &nbsp; &nbsp; {
&nbsp; &nbsp; &nbsp; &nbsp; // Create a print job
&nbsp; &nbsp; &nbsp; &nbsp; DocPrintJob job = service.createPrintJob();
<br>
&nbsp; &nbsp; &nbsp; &nbsp; // We want to print a file so we construct an inputstream
&nbsp; &nbsp; &nbsp; &nbsp; // on the file to supply the print data as given in the doc flavor
&nbsp; &nbsp; &nbsp; &nbsp; File file = new File("File.ps");
&nbsp; &nbsp; &nbsp; &nbsp; InputStream stream = new FileInputStream(file);
<br>
&nbsp; &nbsp; &nbsp; &nbsp; // Build a attribute set with the wanted printing attributes
&nbsp; &nbsp; &nbsp; &nbsp; HashPrintRequestAttributeSet attr = new HashPrintRequestAttributeSet();
&nbsp; &nbsp; &nbsp; &nbsp; attr.add(new Copies(2)); // two copies
&nbsp; &nbsp; &nbsp; &nbsp; attr.add(new PageRanges(2, 7)); // only the 2-7 pages
<br>
&nbsp; &nbsp; &nbsp; &nbsp; // Construct a doc object with the provided class SimpleDoc
&nbsp; &nbsp; &nbsp; &nbsp; SimpleDoc doc = new SimpleDoc(stream, flavor, null);
<br>
&nbsp; &nbsp; &nbsp; &nbsp; // register us as the print - use the adapter class 
&nbsp; &nbsp; &nbsp; &nbsp; // and override the interesing failure condition
&nbsp; &nbsp; &nbsp; &nbsp; job.addPrintJobListener(new PrintJobAdapter()
&nbsp; &nbsp; &nbsp; &nbsp; {
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; public void printJobFailed(PrintJobEvent arg0)
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; {
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; System.out.println("The PrintJob failed.");
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; }
&nbsp; &nbsp; &nbsp; &nbsp; });
<br>
&nbsp; &nbsp; &nbsp; &nbsp; // start the printing process
&nbsp; &nbsp; &nbsp; &nbsp; job.print(doc, attr);
<br>
&nbsp; &nbsp; &nbsp; &nbsp; // lets assume we want to cancel it
&nbsp; &nbsp; &nbsp; &nbsp; if (job instanceof CancelablePrintJob)
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; {
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; CancelablePrintJob cancelJob = (CancelablePrintJob) job;
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; cancelJob.cancel();
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; }
<br>
&nbsp; &nbsp; &nbsp; }
&nbsp; &nbsp; catch (PrintException e)
&nbsp; &nbsp; {
&nbsp; &nbsp; &nbsp; e.printStackTrace();
&nbsp; &nbsp; }
&nbsp; &nbsp; catch (FileNotFoundException e)
&nbsp; &nbsp; {
&nbsp; &nbsp; &nbsp; e.printStackTrace();
&nbsp; &nbsp; }
&nbsp; }
}
</pre>
<p>
<b>Since:</b> 1.4
</p>
</body>
</html>