mirror of git://gcc.gnu.org/git/gcc.git
297 lines
11 KiB
Java
297 lines
11 KiB
Java
/* PrintService.java --
|
|
Copyright (C) 2004, 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 javax.print.attribute.Attribute;
|
|
import javax.print.attribute.AttributeSet;
|
|
import javax.print.attribute.PrintServiceAttribute;
|
|
import javax.print.attribute.PrintServiceAttributeSet;
|
|
import javax.print.event.PrintServiceAttributeListener;
|
|
|
|
/**
|
|
* A <code>PrintService</code> represents a printer available for printing.
|
|
* <p>
|
|
* The print service hereby may be a real physical printer device, a printer
|
|
* group with same capabilities or a logical print service (like for example
|
|
* a PDF writer). The print service is used to query the capabilities of the
|
|
* represented printer instance. If a suitable print service is found it is
|
|
* used to create a print job for the actual printing process.
|
|
* </p>
|
|
* @see javax.print.DocPrintJob
|
|
*
|
|
* @author Michael Koch (konqueror@gmx.de)
|
|
*/
|
|
public interface PrintService
|
|
{
|
|
/**
|
|
* Creates and returns a new print job which is capable to handle all
|
|
* the document flavors supported by this print service.
|
|
*
|
|
* @return The created print job object.
|
|
*/
|
|
DocPrintJob createPrintJob();
|
|
|
|
/**
|
|
* Determines if two services refer to the same underlying service.
|
|
*
|
|
* @param obj the service to check against
|
|
*
|
|
* @return <code>true</code> if both services refer to the same underlying
|
|
* service, <code>false</code> otherwise.
|
|
*/
|
|
boolean equals(Object obj);
|
|
|
|
/**
|
|
* Returns the value of the single specified attribute.
|
|
*
|
|
* @param category the category of a <code>PrintServiceAttribute</code>
|
|
*
|
|
* @return The value of the attribute, or <code>null</code> if the attribute
|
|
* category is not supported by this print service implementation.
|
|
*
|
|
* @throws NullPointerException if category is <code>null</code>.
|
|
* @throws IllegalArgumentException if category is not a class that
|
|
* implements <code>PrintServiceAttribute</code>.
|
|
*/
|
|
<T extends PrintServiceAttribute> T getAttribute(Class<T> category);
|
|
|
|
/**
|
|
* Returns the attributes describing this print service. The returned
|
|
* attributes set is unmodifiable and represents the current state of
|
|
* the print service. As some print service attributes may change
|
|
* (depends on the print service implementation) a subsequent call to
|
|
* this method may return a different set. To monitor changes a
|
|
* <code>PrintServiceAttributeListener</code> may be registered.
|
|
*
|
|
* @return All the description attributes of this print service.
|
|
* @see #addPrintServiceAttributeListener(PrintServiceAttributeListener)
|
|
*/
|
|
PrintServiceAttributeSet getAttributes();
|
|
|
|
/**
|
|
* Determines and returns the default value for a given attribute category
|
|
* of this print service.
|
|
* <p>
|
|
* A return value of <code>null</code> means either that the print service
|
|
* does not support the attribute category or there is no default value
|
|
* available for this category. To distinguish these two case one can test
|
|
* with {@link #isAttributeCategorySupported(Class)} if the category is
|
|
* supported.
|
|
* </p>
|
|
*
|
|
* @param category the category of the attribute
|
|
*
|
|
* @return The default value, or <code>null</code>.
|
|
*
|
|
* @throws NullPointerException if <code>category</code> is <code>null</code>
|
|
* @throws IllegalArgumentException if <code>category</code> is a class
|
|
* not implementing <code>Attribute</code>
|
|
*/
|
|
Object getDefaultAttributeValue(Class<? extends Attribute> category);
|
|
|
|
/**
|
|
* Returns the name of this print service.
|
|
* This may be the value of the <code>PrinterName</code> attribute.
|
|
*
|
|
* @return The print service name.
|
|
*/
|
|
String getName();
|
|
|
|
/**
|
|
* Returns a factory for UI components if supported by the print service.
|
|
*
|
|
* @return A factory for UI components or <code>null</code>.
|
|
*/
|
|
ServiceUIFactory getServiceUIFactory();
|
|
|
|
/**
|
|
* Returns all supported attribute categories.
|
|
*
|
|
* @return The class array of all supported attribute categories.
|
|
*/
|
|
Class<?>[] getSupportedAttributeCategories();
|
|
|
|
/**
|
|
* Determines and returns all supported attribute values of a given
|
|
* attribute category a client can use when setting up a print job
|
|
* for this print service.
|
|
* <p>
|
|
* The returned object may be one of the following types:
|
|
* <ul>
|
|
* <li>A single instance of the attribute category to indicate that any
|
|
* value will be supported.</li>
|
|
* <li>An array of the same type as the attribute category to test,
|
|
* containing all the supported values for this category.</li>
|
|
* <li>A single object (of any other type than the attribute category)
|
|
* which indicates bounds on the supported values.</li>
|
|
* </ul>
|
|
* </p>
|
|
*
|
|
* @param category the attribute category to test
|
|
* @param flavor the document flavor to use, or <code>null</code>
|
|
* @param attributes set of attributes for a supposed job,
|
|
* or <code>null</code>
|
|
*
|
|
* @return A object (as defined above) indicating the supported values
|
|
* for the given attribute category, or <code>null</code> if this print
|
|
* service doesn't support the given attribute category at all.
|
|
*
|
|
* @throws NullPointerException if <code>category</code> is null
|
|
* @throws IllegalArgumentException if <code>category</code> is a class not
|
|
* implementing <code>Attribute</code>, or if <code>flavor</code> is not
|
|
* supported
|
|
*/
|
|
Object getSupportedAttributeValues(Class<? extends Attribute> category,
|
|
DocFlavor flavor,
|
|
AttributeSet attributes);
|
|
|
|
/**
|
|
* Determines and returns an array of all supported document flavors which
|
|
* can be used to supply print data to this print service.
|
|
* <p>
|
|
* The supported attribute categories may differ between the supported
|
|
* document flavors. To test for supported attributes one can use the
|
|
* {@link #getUnsupportedAttributes(DocFlavor, AttributeSet)} method with
|
|
* the specific doc flavor and attributes set.
|
|
* </p>
|
|
*
|
|
* @return the supported document flavors
|
|
*/
|
|
DocFlavor[] getSupportedDocFlavors();
|
|
|
|
/**
|
|
* Identifies all the unsupported attributes of the given set of attributes
|
|
* in the context of the specified document flavor.
|
|
* <p>
|
|
* The given flavor has to be supported by the print service (use
|
|
* {@link #isDocFlavorSupported(DocFlavor)} to verify). The method will
|
|
* return <code>null</code> if all given attributes are supported. Otherwise
|
|
* a set of unsupported attributes are returned. The attributes in the
|
|
* returned set may be completely unsupported or only the specific requested
|
|
* value. If flavor is <code>null</code> the default document flavor of the
|
|
* print service is used in the identification process.
|
|
* </p>
|
|
*
|
|
* @param flavor document flavor to test, or <code>null</code>.
|
|
* @param attributes set of printing attributes for a supposed job
|
|
*
|
|
* @return <code>null</code> if this print service supports all the given
|
|
* attributes for the specified doc flavor. Otherwise the set of unsupported
|
|
* attributes are returned.
|
|
*
|
|
* @throws IllegalArgumentException if <code>flavor</code> is unsupported
|
|
*/
|
|
AttributeSet getUnsupportedAttributes(DocFlavor flavor, AttributeSet attributes);
|
|
|
|
|
|
/**
|
|
* Returns a hashcode for this print service.
|
|
*
|
|
* @return The hashcode.
|
|
*/
|
|
int hashCode();
|
|
|
|
/**
|
|
* Determines a given attribute category is supported by this
|
|
* print service implementation. This only tests for the category
|
|
* not for any specific values of this category nor in the context
|
|
* of a specific document flavor.
|
|
*
|
|
* @param category the category to check
|
|
*
|
|
* @return <code>true</code> if <code>category</code> is supported,
|
|
* <code>false</code> otherwise.
|
|
*
|
|
* @throws NullPointerException if <code>category</code> is <code>null</code>
|
|
* @throws IllegalArgumentException if <code>category</code> is a class not
|
|
* implementing <code>Attribute</code>.
|
|
*/
|
|
boolean isAttributeCategorySupported(Class<? extends Attribute> category);
|
|
|
|
/**
|
|
* Determines if a given attribute value is supported when creating a print
|
|
* job for this print service.
|
|
* <p>
|
|
* If either the document flavor or the provided attributes are
|
|
* <code>null</code> it is determined if the given attribute value is
|
|
* supported in some combination of the available document flavors and
|
|
* attributes of the print service. Otherwise it is checked for the
|
|
* specific context of the given document flavor/attributes set.
|
|
* </p>
|
|
*
|
|
* @param attrval the attribute value to check
|
|
* @param flavor the document flavor to use, or <code>null</code>.
|
|
* @param attributes set of attributes to use, or <code>null</code>.
|
|
*
|
|
* @return <code>true</code> if the attribute value is supported in the
|
|
* requested context, <code>false</code> otherwise.
|
|
*
|
|
* @throws NullPointerException if <code>attrval</code> is <code>null</code>.
|
|
* @throws IllegalArgumentException if <code>flavor</code> is not supported
|
|
* by this print service
|
|
*/
|
|
boolean isAttributeValueSupported(Attribute attrval, DocFlavor flavor, AttributeSet attributes);
|
|
|
|
/**
|
|
* Determines if a given document flavor is supported or not.
|
|
*
|
|
* @param flavor the document flavor to check
|
|
*
|
|
* @return <code>true</code> if <code>flavor</code> is supported,
|
|
* <code>false</code> otherwise.
|
|
*
|
|
* @throws NullPointerException if <code>flavor</code> is null.
|
|
*/
|
|
boolean isDocFlavorSupported(DocFlavor flavor);
|
|
|
|
/**
|
|
* Registers a print service attribute listener to this print service.
|
|
*
|
|
* @param listener the listener to add
|
|
*/
|
|
void addPrintServiceAttributeListener(PrintServiceAttributeListener listener);
|
|
|
|
/**
|
|
* De-registers a print service attribute listener from this print service.
|
|
*
|
|
* @param listener the listener to remove
|
|
*/
|
|
void removePrintServiceAttributeListener(PrintServiceAttributeListener listener);
|
|
}
|