javax.print

Interface PrintService

Known Subinterfaces:
MultiDocPrintService
Known Implementing Classes:
StreamPrintService

public interface PrintService

A PrintService represents a printer available for printing.

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.

See Also:
DocPrintJob

Method Summary

void
addPrintServiceAttributeListener(PrintServiceAttributeListener listener)
Registers a print service attribute listener to this print service.
DocPrintJob
createPrintJob()
Creates and returns a new print job which is capable to handle all the document flavors supported by this print service.
boolean
equals(Object obj)
Determines if two services refer to the same underlying service.
extends PrintServiceAttribute> T getAttribute(Class category)
Returns the value of the single specified attribute.
PrintServiceAttributeSet
getAttributes()
Returns the attributes describing this print service.
Object
getDefaultAttributeValue(Attribute> category)
Determines and returns the default value for a given attribute category of this print service.
String
getName()
Returns the name of this print service.
ServiceUIFactory
getServiceUIFactory()
Returns a factory for UI components if supported by the print service.
Class[]
getSupportedAttributeCategories()
Returns all supported attribute categories.
Object
getSupportedAttributeValues(Attribute> category, DocFlavor flavor, AttributeSet attributes)
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.
DocFlavor[]
getSupportedDocFlavors()
Determines and returns an array of all supported document flavors which can be used to supply print data to this print service.
AttributeSet
getUnsupportedAttributes(DocFlavor flavor, AttributeSet attributes)
Identifies all the unsupported attributes of the given set of attributes in the context of the specified document flavor.
int
hashCode()
Returns a hashcode for this print service.
boolean
isAttributeCategorySupported(Attribute> category)
Determines a given attribute category is supported by this print service implementation.
boolean
isAttributeValueSupported(Attribute attrval, DocFlavor flavor, AttributeSet attributes)
Determines if a given attribute value is supported when creating a print job for this print service.
boolean
isDocFlavorSupported(DocFlavor flavor)
Determines if a given document flavor is supported or not.
void
removePrintServiceAttributeListener(PrintServiceAttributeListener listener)
De-registers a print service attribute listener from this print service.

Method Details

addPrintServiceAttributeListener

public void addPrintServiceAttributeListener(PrintServiceAttributeListener listener)
Registers a print service attribute listener to this print service.
Parameters:
listener - the listener to add

createPrintJob

public DocPrintJob createPrintJob()
Creates and returns a new print job which is capable to handle all the document flavors supported by this print service.
Returns:
The created print job object.

equals

public boolean equals(Object obj)
Determines if two services refer to the same underlying service.
Overrides:
equals in interface Object
Parameters:
obj - the service to check against
Returns:
true if both services refer to the same underlying service, false otherwise.

extends PrintServiceAttribute> T getAttribute

public extends PrintServiceAttribute> T getAttribute(Class category)
Returns the value of the single specified attribute.
Parameters:
category - the category of a PrintServiceAttribute
Returns:
The value of the attribute, or null if the attribute category is not supported by this print service implementation.
Throws:
NullPointerException - if category is null.
IllegalArgumentException - if category is not a class that implements PrintServiceAttribute.

getAttributes

public PrintServiceAttributeSet getAttributes()
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 PrintServiceAttributeListener may be registered.
Returns:
All the description attributes of this print service.

getDefaultAttributeValue

public Object getDefaultAttributeValue(Attribute> category)
Determines and returns the default value for a given attribute category of this print service.

A return value of null 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 isAttributeCategorySupported(Class) if the category is supported.

Parameters:
category - the category of the attribute
Returns:
The default value, or null.
Throws:
NullPointerException - if category is null
IllegalArgumentException - if category is a class not implementing Attribute

getName

public String getName()
Returns the name of this print service. This may be the value of the PrinterName attribute.
Returns:
The print service name.

getServiceUIFactory

public ServiceUIFactory getServiceUIFactory()
Returns a factory for UI components if supported by the print service.
Returns:
A factory for UI components or null.

getSupportedAttributeCategories

public Class[] getSupportedAttributeCategories()
Returns all supported attribute categories.
Returns:
The class array of all supported attribute categories.

getSupportedAttributeValues

public Object getSupportedAttributeValues(Attribute> category,
                                          DocFlavor flavor,
                                          AttributeSet attributes)
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.

The returned object may be one of the following types:

  • A single instance of the attribute category to indicate that any value will be supported.
  • An array of the same type as the attribute category to test, containing all the supported values for this category.
  • A single object (of any other type than the attribute category) which indicates bounds on the supported values.
Parameters:
category - the attribute category to test
flavor - the document flavor to use, or null
attributes - set of attributes for a supposed job, or null
Returns:
A object (as defined above) indicating the supported values for the given attribute category, or null if this print service doesn't support the given attribute category at all.
Throws:
NullPointerException - if category is null
IllegalArgumentException - if category is a class not implementing Attribute, or if flavor is not supported

getSupportedDocFlavors

public DocFlavor[] getSupportedDocFlavors()
Determines and returns an array of all supported document flavors which can be used to supply print data to this print service.

The supported attribute categories may differ between the supported document flavors. To test for supported attributes one can use the getUnsupportedAttributes(DocFlavor,AttributeSet) method with the specific doc flavor and attributes set.

Returns:
the supported document flavors

getUnsupportedAttributes

public AttributeSet getUnsupportedAttributes(DocFlavor flavor,
                                             AttributeSet attributes)
Identifies all the unsupported attributes of the given set of attributes in the context of the specified document flavor.

The given flavor has to be supported by the print service (use isDocFlavorSupported(DocFlavor) to verify). The method will return null 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 null the default document flavor of the print service is used in the identification process.

Parameters:
flavor - document flavor to test, or null.
attributes - set of printing attributes for a supposed job
Returns:
null 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 flavor is unsupported

hashCode

public int hashCode()
Returns a hashcode for this print service.
Overrides:
hashCode in interface Object
Returns:
The hashcode.

isAttributeCategorySupported

public boolean isAttributeCategorySupported(Attribute> category)
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.
Parameters:
category - the category to check
Returns:
true if category is supported, false otherwise.
Throws:
NullPointerException - if category is null
IllegalArgumentException - if category is a class not implementing Attribute.

isAttributeValueSupported

public boolean isAttributeValueSupported(Attribute attrval,
                                         DocFlavor flavor,
                                         AttributeSet attributes)
Determines if a given attribute value is supported when creating a print job for this print service.

If either the document flavor or the provided attributes are null 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.

Parameters:
attrval - the attribute value to check
flavor - the document flavor to use, or null.
attributes - set of attributes to use, or null.
Returns:
true if the attribute value is supported in the requested context, false otherwise.
Throws:
NullPointerException - if attrval is null.
IllegalArgumentException - if flavor is not supported by this print service

isDocFlavorSupported

public boolean isDocFlavorSupported(DocFlavor flavor)
Determines if a given document flavor is supported or not.
Parameters:
flavor - the document flavor to check
Returns:
true if flavor is supported, false otherwise.
Throws:
NullPointerException - if flavor is null.

removePrintServiceAttributeListener

public void removePrintServiceAttributeListener(PrintServiceAttributeListener listener)
De-registers a print service attribute listener from this print service.
Parameters:
listener - the listener to remove

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.