diff options
Diffstat (limited to 'libjava/classpath/javax/print')
| -rw-r--r-- | libjava/classpath/javax/print/MultiDoc.java | 29 | ||||
| -rw-r--r-- | libjava/classpath/javax/print/MultiDocPrintJob.java | 27 | ||||
| -rw-r--r-- | libjava/classpath/javax/print/MultiDocPrintService.java | 11 | ||||
| -rw-r--r-- | libjava/classpath/javax/print/PrintServiceLookup.java | 243 | ||||
| -rw-r--r-- | libjava/classpath/javax/print/ServiceUI.java | 137 | ||||
| -rw-r--r-- | libjava/classpath/javax/print/attribute/package.html | 31 | ||||
| -rw-r--r-- | libjava/classpath/javax/print/attribute/standard/package.html | 18 | ||||
| -rw-r--r-- | libjava/classpath/javax/print/event/package.html | 12 | ||||
| -rw-r--r-- | libjava/classpath/javax/print/package.html | 200 |
9 files changed, 679 insertions, 29 deletions
diff --git a/libjava/classpath/javax/print/MultiDoc.java b/libjava/classpath/javax/print/MultiDoc.java index e7747bc..6e9ec84 100644 --- a/libjava/classpath/javax/print/MultiDoc.java +++ b/libjava/classpath/javax/print/MultiDoc.java @@ -1,5 +1,5 @@ /* MultiDoc.java -- - Copyright (C) 2004 Free Software Foundation, Inc. + Copyright (C) 2004, 2006 Free Software Foundation, Inc. This file is part of GNU Classpath. @@ -42,6 +42,25 @@ import java.io.IOException; /** + * <code>MultiDoc</code> defines the interface for objects providing multiple + * documents for use in a print job. + * <p> + * Implementations of this interface are used to pass multiple documents, to be + * printed as one print job, to the <code>MultiDocPrintJob</code> instance. + * </p><p> + * There exists no implementation of this interface in the Java Print Service + * API. Implementors may assume the following usage in print jobs and the needed + * behaviour for implementations: The print job fetches the single documents via + * iteration by consecutive calls of the {@link #getDoc()} method to obtain the + * current document follwing calls of the {@link #next()} method to get the next + * multidoc object for the next <code>getDoc()</code> method call (if returned + * multidoc object is not <code>null</code>). The print service will fetch the + * document object and then retrieve the print data from the document before it + * proceeds with the next call for the next MultiDoc object in the sequence. + * </p><p> + * Implementations of this interface have to be multiple thread-safe. + * </p> + * * @author Michael Koch (konqueror@gmx.de) */ public interface MultiDoc @@ -49,16 +68,18 @@ public interface MultiDoc /** * Returns the current document. * - * @return the current document + * @return The current document. * * @throws IOException if an error occurs */ Doc getDoc() throws IOException; /** - * Returns the next <code>MultiDoc</code> object. + * Returns the next <code>MultiDoc</code> object that contains the + * next document for retrieval. * - * @return the next <code>MultiDoc</code> object + * @return The next <code>MultiDoc</code> object, or <code>null</code> + * if no more documents are available. * * @throws IOException if an error occurs */ diff --git a/libjava/classpath/javax/print/MultiDocPrintJob.java b/libjava/classpath/javax/print/MultiDocPrintJob.java index b096769..36089b5 100644 --- a/libjava/classpath/javax/print/MultiDocPrintJob.java +++ b/libjava/classpath/javax/print/MultiDocPrintJob.java @@ -1,5 +1,5 @@ /* MultiDocPrintJob.java -- - Copyright (C) 2004 Free Software Foundation, Inc. + Copyright (C) 2004, 2006 Free Software Foundation, Inc. This file is part of GNU Classpath. @@ -42,17 +42,34 @@ import javax.print.attribute.PrintRequestAttributeSet; /** + * <code>MultiDocPrintJob</code> represents a print job which supports + * printing of multiple documents as one print job. + * <p> + * An instance can be obtained from every <code>MultiDocPrintService</code> + * available by calling the + * {@link javax.print.MultiDocPrintService#createMultiDocPrintJob()} method. + * A print job is bound to the print service it is created from. + * </p> + * * @author Michael Koch (konqueror@gmx.de) */ public interface MultiDocPrintJob extends DocPrintJob { /** - * Request a print of a <code>MultiDoc</code> object. + * Prints the documents supplied in the given <code>MultiDoc</code> object + * as one print job with the given printing attributes. * - * @param multiDoc the document to print - * @param attributes the printing attributes to apply + * @param multiDoc the documents to print. Every document must have a + * flavor supported by the bound print service. + * @param attributes the printing attributes to apply to the print job. If + * <code>null</code> the default attribute values will be used. * - * @throws PrintExeption if an error occurs + * @throws PrintException if an error occurs. The thrown exception may + * implement refining print exception interface to provide more detail of + * the error. + * + * @see FlavorException + * @see AttributeException */ void print(MultiDoc multiDoc, PrintRequestAttributeSet attributes) throws PrintException; diff --git a/libjava/classpath/javax/print/MultiDocPrintService.java b/libjava/classpath/javax/print/MultiDocPrintService.java index a71d23a..105e722 100644 --- a/libjava/classpath/javax/print/MultiDocPrintService.java +++ b/libjava/classpath/javax/print/MultiDocPrintService.java @@ -1,5 +1,5 @@ /* MultiDocPrintService.java -- - Copyright (C) 2004 Free Software Foundation, Inc. + Copyright (C) 2004, 2006 Free Software Foundation, Inc. This file is part of GNU Classpath. @@ -40,6 +40,13 @@ package javax.print; /** + * <code>MultiDocPrintService</code> represents print services that are + * capable of printing multiple documents as one print job. It provides an + * additional method for the creation of a print job for multiple documents. + * + * @see javax.print.MultiDoc + * @see javax.print.MultiDocPrintJob + * * @author Michael Koch (konqueror@gmx.de) */ public interface MultiDocPrintService extends PrintService @@ -47,7 +54,7 @@ public interface MultiDocPrintService extends PrintService /** * Create a job that can print a <code>MultiDoc</code> object. * - * @return the new print job + * @return The created print job. */ MultiDocPrintJob createMultiDocPrintJob(); }
\ No newline at end of file diff --git a/libjava/classpath/javax/print/PrintServiceLookup.java b/libjava/classpath/javax/print/PrintServiceLookup.java index 2add8d1..57cb8dc 100644 --- a/libjava/classpath/javax/print/PrintServiceLookup.java +++ b/libjava/classpath/javax/print/PrintServiceLookup.java @@ -1,5 +1,5 @@ /* PrintServiceLookup.java -- - Copyright (C) 2004 Free Software Foundation, Inc. + Copyright (C) 2004, 2006 Free Software Foundation, Inc. This file is part of GNU Classpath. @@ -38,39 +38,266 @@ exception statement from your version. */ package javax.print; +import gnu.classpath.ServiceFactory; +import gnu.javax.print.CupsPrintServiceLookup; + +import java.util.ArrayList; +import java.util.Arrays; +import java.util.HashSet; +import java.util.Iterator; + import javax.print.attribute.AttributeSet; /** + * <code>PrintServiceLookup</code> implementations provide a way to lookup + * print services based on different constraints. + * <p> + * Implementations are located and loaded automatically through the SPI JAR + * file specification. Therefore implementation classes must provide a default + * constructor for instantiation. Furthermore, applications are able to + * register further instances directly at runtime. + * </p><p> + * If an SecurityManager is installed implementors should call + * <code>checkPrintJobAccess()</code> to disable access for untrusted code. + * This check is to be made in every lookup service implementation for + * flexibility. Print services registered by applications through + * <code>registerService(PrintService)</code> are suppressed in the + * lookup results if a security manager is installed and disallows access. + * </p> + * * @author Michael Koch (konqueror@gmx.de) + * @author Wolfgang Baer (WBaer@gmx.de) */ public abstract class PrintServiceLookup { + + private static final CupsPrintServiceLookup systemProvider; + private static final HashSet printServices; + private static final HashSet printServiceLookups; + + static + { + systemProvider = new CupsPrintServiceLookup(); + + printServices = new HashSet(); + printServiceLookups = new HashSet(); + + // check for service providers + Iterator it = ServiceFactory.lookupProviders(PrintServiceLookup.class); + + while (it.hasNext()) + printServiceLookups.add(it.next()); + } + /** * Constructs a <code>PrintServiceLookup</code> object. */ public PrintServiceLookup() { - // Do nothing here + // nothing to do here + } + + /** + * Explicitly registers the provided print service lookup implementation. + * <p> + * The registration will silently fail (returning <code>false</code>) if + * the lookup service is already registered or the registration somehow + * else fails. + * </p> + * + * @param sp the print service lookup implementation to register. + * @return <code>true</code> if registered, <code>false</code> otherwise. + */ + public static boolean registerServiceProvider(PrintServiceLookup sp) + { + return printServiceLookups.add(sp); + } + + /** + * Explicitly registers the provided print service instance. + * <p> + * The registration will silently fail (returning <code>false</code>) if + * the print service instance is already registered or the registration + * somehow else fails. + * </p> + * @param service the single print service to register. + * @return <code>true</code> if registered, <code>false</code> otherwise. + */ + public static boolean registerService(PrintService service) + { + if (service instanceof StreamPrintService) + return false; + + // security + try + { + SecurityManager sm = System.getSecurityManager(); + if (sm != null) + sm.checkPrintJobAccess(); + + return printServices.add(service); + } + catch (SecurityException se) + { + return false; + } + } + + /** + * Searches print services capable of printing in the given document flavor + * which supports the specified printing attributes. + * + * @param flavor the document flavor to support. If <code>null</code> this + * constraint is ignored during lookup. + * @param attributes the printing attributes to support. If + * <code>null</code> this constraint is ignored during lookup. + * @return The resulting available print services, or an array of length 0 + * if none is found. + */ + public static final PrintService[] lookupPrintServices(DocFlavor flavor, + AttributeSet attributes) + { + ArrayList result = new ArrayList(); + + PrintService[] services = + systemProvider.getPrintServices(flavor, attributes); + result.addAll(Arrays.asList(services)); + + for (Iterator it = printServiceLookups.iterator(); it.hasNext(); ) + { + PrintServiceLookup lookup = (PrintServiceLookup) it.next(); + services = lookup.getPrintServices(flavor, attributes); + result.addAll(Arrays.asList(services)); + } + + for (Iterator it = printServices.iterator(); it.hasNext(); ) + { + PrintService service = (PrintService) it.next(); + if (systemProvider.checkPrintService(flavor, attributes, service)) + result.add(service); + } + + return (PrintService[]) result.toArray(new PrintService[result.size()]); + } + + /** + * Searches print services capable of multi document printing in all of the + * given document flavors and supporting the specified printing attributes. + * + * @param flavors the document flavors to support. If <code>null</code> this + * constraint is ignored during lookup. + * @param attributes the printing attributes to support. If + * <code>null</code> this constraint is ignored during lookup. + * @return The resulting available multi document print services, or an + * array of length 0 if none is found. + */ + public static final MultiDocPrintService[] lookupMultiDocPrintServices( + DocFlavor[] flavors, AttributeSet attributes) + { + ArrayList result = new ArrayList(); + + MultiDocPrintService[] services = + systemProvider.getMultiDocPrintServices(flavors, attributes); + result.addAll(Arrays.asList(services)); + + for (Iterator it = printServiceLookups.iterator(); it.hasNext(); ) + { + PrintServiceLookup lookup = (PrintServiceLookup) it.next(); + services = lookup.getMultiDocPrintServices(flavors, attributes); + result.addAll(Arrays.asList(services)); + } + + for (Iterator it = printServices.iterator(); it.hasNext(); ) + { + PrintService service = (PrintService) it.next(); + if (systemProvider.checkMultiDocPrintService(flavors, attributes, service)) + result.add(service); + } + + return (MultiDocPrintService[]) result.toArray( + new MultiDocPrintService[result.size()]); + } + + + /** + * Searches the default print service in the current environment. + * <p> + * If multiple lookup services are registered and each has a default + * print service the result is not specified. Usually the default + * print service of the native platform lookup service is returned. + * </p><p> + * The GNU classpath implementation will return the CUPS default + * printing service as the default print service, if available. + * </p><p> + * The default print service may be overriden by users through + * the property <code>javax.print.defaultPrinter</code>. A service + * specified must be found to be returned as the default. + * </p> + * + * @return The default print service, or <code>null</code> if none found. + */ + public static final PrintService lookupDefaultPrintService() + { + // TODO Find out what the property controls and use it + // String defaultPrinter = System.getProperty("javax.print.defaultPrinter"); + + // first test for platform specified default services + PrintService service = systemProvider.getDefaultPrintService(); + + if (service != null) + return service; + + // none available by systemDefaultProvider + // search in other registered ones and take first + for (Iterator it = printServiceLookups.iterator(); it.hasNext(); ) + { + service = ((PrintServiceLookup) it.next()).getDefaultPrintService(); + if (service != null) + return service; + } + + return null; } /** - * Not called direclty by applications. + * Not to be called directly by applications. + * + * @return The default lookup service of the implementing lookup service or + * <code>null</code> if there is no default one. */ public abstract PrintService getDefaultPrintService(); /** - * Not called direclty by applications. + * Not to be called directly by applications. + * + * @param flavors the document flavors which have to be supported. + * @param attributes the attributes which have to be supported. + * + * @return The multidoc print services of the implementing lookup service + * for the given parameters, or an array of length 0 if none is available. */ - public abstract MultiDocPrintService[] getMultiDocPrintServices(DocFlavor[] flavors, AttributeSet attributes); + public abstract MultiDocPrintService[] + getMultiDocPrintServices(DocFlavor[] flavors, AttributeSet attributes); /** - * Not called direclty by applications. + * Not to be called directly by applications. + * + * @return All known print services of the implementing lookup service + * regardless of supported features, or an array of length 0 if none is + * available. */ public abstract PrintService[] getPrintServices(); /** - * Not called direclty by applications. + * Not to be called directly by applications. + * + * @param flavor the document flavor which has to be supported. + * @param attributes the attributes which have to be supported. + * + * @return The print services of the implementing lookup service + * for the given parameters, or an array of length 0 if none is available. */ - public abstract PrintService[] getPrintServices(DocFlavor flavor, AttributeSet attributes); + public abstract PrintService[] + getPrintServices(DocFlavor flavor, AttributeSet attributes); } diff --git a/libjava/classpath/javax/print/ServiceUI.java b/libjava/classpath/javax/print/ServiceUI.java new file mode 100644 index 0000000..4a7b5bd --- /dev/null +++ b/libjava/classpath/javax/print/ServiceUI.java @@ -0,0 +1,137 @@ +/* ServiceUI.java -- + Copyright (C) 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. */ + + +package javax.print; + +import gnu.javax.print.PrinterDialog; + +import java.awt.GraphicsConfiguration; +import java.awt.GraphicsEnvironment; +import java.awt.HeadlessException; +import java.util.Arrays; + +import javax.print.attribute.PrintRequestAttributeSet; + +/** + * <code>ServiceUI</code> provides a method to create a graphical + * print dialog. + * <p> + * The graphical print dialog enables the user to browse the available + * print services on the system. It provides user interfaces to interact + * with the most common printing attributes likes specifying the number of + * copies to print or the page ranges. + * </p><p> + * The initial appearance of the print dialog as shown to the user may be + * specified by providing the default selected print service as well as + * initial values for the printing attributes in the user interface. + * </p> + * + * @author Wolfgang Baer (WBaer@gmx.de) + */ +public class ServiceUI +{ + + /** + * Default constructor. + */ + public ServiceUI() + { + // nothing to do here - only one static method + } + + /** + * Creates a modal graphical printing dialog at the specified location on + * the screen. + * <p> + * The dialog will return the user selected print service and the given + * attributes set will contain the modified printing attributes. If the + * user cancels the printing dialog <code>null</code> will be returned and + * the printing attributes set will be unmodified. + * </p><p> + * The values of the given attributes set (if not empty) will be displayed + * initially unless the are unsupported by the print service. If a print + * service does not support a particular value it is substituted with the + * default value of the print service. + * </p> + * + * @param gc the screen to use. <code>null</code> is default screen. + * @param x the coordinate of the upper left edge of the dialog in screen + * coordinates (not relative to the parent frame). + * @param y the coordinate of the upper left edge of the dialog in screen + * coordinates (not relative to the parent frame). + * @param services the print services to browse (not null). + * @param defaultService the default service. If <code>null</code> + * the first of the print services in the services array will be used. + * @param flavor the flavours to be printed. + * @param attributes the attributes requested. Will be updated + * by selections done by the user in the dialog. + * + * @return The selected print service or <code>null</code> if user + * has cancelled the printer dialog. + * + * @throws HeadlessException if GraphicsEnvironment is headless + * @throws IllegalArgumentException if services is <code>null</code> or an + * empty array, attributes are <code>null</code> or the given default + * <code>PrintService<code> is not part of the print service array. + */ + public static PrintService printDialog(GraphicsConfiguration gc, int x, + int y, PrintService[] services, PrintService defaultService, + DocFlavor flavor, PrintRequestAttributeSet attributes) + throws HeadlessException + { + if (GraphicsEnvironment.isHeadless()) + throw new HeadlessException("GraphicsEnvironment is headless."); + + if (services == null || services.length == 0 || attributes == null) + throw new IllegalArgumentException("Given print service array / " + + "attributes may not be null"); + + if (defaultService != null && + ! Arrays.asList(services).contains(defaultService)) + throw new IllegalArgumentException("defaultService is not contained " + + " in the print service array"); + + PrinterDialog dialog = new PrinterDialog(gc, services, defaultService, + flavor, attributes); + + dialog.setLocation(x, y); + dialog.show(); + + return dialog.getSelectedPrintService(); + } +} diff --git a/libjava/classpath/javax/print/attribute/package.html b/libjava/classpath/javax/print/attribute/package.html index 37f24d5..0ab01ab 100644 --- a/libjava/classpath/javax/print/attribute/package.html +++ b/libjava/classpath/javax/print/attribute/package.html @@ -1,6 +1,6 @@ <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> <!-- package.html - describes classes in javax.print.attribute package. - Copyright (C) 2003, 2005 Free Software Foundation, Inc. + Copyright (C) 2003, 2005, 2006 Free Software Foundation, Inc. This file is part of GNU Classpath. @@ -43,6 +43,35 @@ exception statement from your version. --> <p>Provides classes and interfaces describing the roles and syntax of attribute objects in the Java Print Service API.</p> <p> +The package contains the base attribute interface and several subinterfaces +describing the different attribute roles of printing attributes. Furthermore, +abstract classes defining the syntax of attributes are provided. For +collections of attributes based on their roles different set interfaces and +implementing classes are available. +</p><p> +Existing attribute roles are: +<ul> +<li><a href="PrintServiceAttribute.html">PrintServiceAttribute</a>s +describing the state and other informations of a PrintService.</li> +<li><a href="PrintJobAttribute.html">PrintJobAttribute</a>s describing +the state of the print job.</li> +<li><a href="PrintRequestAttribute.html">PrintRequestAttribute</a>s specifying +how a print job should be printed and are applied to a complete print job.</li> +<li><a href="PrintJobAttribute.html">PrintJobAttribute</a> s specifying +how a single document in the print job should be printed.</li> +</ul> +</p><p> +Every attribute is of a certain syntax which defines its type and the +representation of its value. The different syntax types are provided as +abstract syntax classes (e.g. <code>IntegerSyntax</code>). Concrete attribute +implementations are subclasses of these abstract syntax classes. +</p><p> +Attributes may be collected as sets of attributes. Different interfaces for +attribute collections per role and implementations based on a HashMap are +provided (for example <a href="HashPrintJobAttributeSet.html"> +HashPrintJobAttributeSet</a> for the print job attributes). +</p> +<p> <b>Since:</b> 1.4 </p> </body> diff --git a/libjava/classpath/javax/print/attribute/standard/package.html b/libjava/classpath/javax/print/attribute/standard/package.html index 4248acf..f6bec5f 100644 --- a/libjava/classpath/javax/print/attribute/standard/package.html +++ b/libjava/classpath/javax/print/attribute/standard/package.html @@ -1,7 +1,7 @@ <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<!-- package.html - describes classes in javax.print.attribute.standard +<!-- package.html - describes classes in javax.print.attribute.standard package. - Copyright (C) 2003, 2005 Free Software Foundation, Inc. + Copyright (C) 2003, 2005, 2006 Free Software Foundation, Inc. This file is part of GNU Classpath. @@ -41,8 +41,18 @@ exception statement from your version. --> <head><title>GNU Classpath - javax.print.attribute.standard</title></head> <body> -<p>Provides the printing attribute classes of the Java Print -Service API.</p> +Provides the printing attribute classes of the Java Print Service API. +<p> +The package contains the available printing attributes. Some attributes are +used by the print service implementations to inform about the state of print +services and print jobs. Other attributes are needs to be provided by the +user/program to specify how a print job or a document in a print job should +be printed. +</p><p> +<b>Note:</b> Printing attributes can implement more than one attribute role +and therefore be used to specify e.g. print request attributes as well as +document attributes. +</p> <p> <b>Since:</b> 1.4 </p> diff --git a/libjava/classpath/javax/print/event/package.html b/libjava/classpath/javax/print/event/package.html index f811013..5091a71 100644 --- a/libjava/classpath/javax/print/event/package.html +++ b/libjava/classpath/javax/print/event/package.html @@ -1,6 +1,6 @@ <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> <!-- package.html - describes classes in javax.print.event package. - Copyright (C) 2003, 2005 Free Software Foundation, Inc. + Copyright (C) 2003, 2005, 2006 Free Software Foundation, Inc. This file is part of GNU Classpath. @@ -40,7 +40,15 @@ exception statement from your version. --> <head><title>GNU Classpath - javax.print.event</title></head> <body> -<p>Provides events and listeners to be used with the Java Print Service API.</p> +Provides events and listeners to be used with the Java Print Service API. +<p> +The provided listeners are used to register with print services and/or +print jobs to receive state information or to monitor the progress of +print jobs. Print jobs don't need to be implemented synchronous and +therefore should be monitored to know if they succeed or fail. For this +common task the <a href="PrintJobAdapter.html">PrintJobAdapter</a> class +is provided. +</p> <p> <b>Since:</b> 1.4 </p> diff --git a/libjava/classpath/javax/print/package.html b/libjava/classpath/javax/print/package.html index dfa4b0f..7527432 100644 --- a/libjava/classpath/javax/print/package.html +++ b/libjava/classpath/javax/print/package.html @@ -1,6 +1,6 @@ <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> <!-- package.html - describes classes in javax.print package. - Copyright (C) 2003 Free Software Foundation, Inc. + Copyright (C) 2003, 2006 Free Software Foundation, Inc. This file is part of GNU Classpath. @@ -38,9 +38,203 @@ exception statement from your version. --> <html> <head><title>GNU Classpath - javax.print</title></head> - <body> -<p></p> +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> |