javax.print
Interface PrintService

All Known Subinterfaces:
MultiDocPrintService
All 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.
<T extends PrintServiceAttribute>
T
getAttribute(Class<T> category)
          Returns the value of the single specified attribute.
 PrintServiceAttributeSet getAttributes()
          Returns the attributes describing this print service.
 Object getDefaultAttributeValue(Class<? extends 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(Class<? extends 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(Class<? extends 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 Detail

createPrintJob

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

boolean equals(Object obj)
Determines if two services refer to the same underlying service.

Overrides:
equals in class Object
Parameters:
obj - the service to check against
Returns:
true if both services refer to the same underlying service, false otherwise.
See Also:
Object.hashCode()

getAttribute

<T extends PrintServiceAttribute> T getAttribute(Class<T> 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

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.
See Also:
addPrintServiceAttributeListener(PrintServiceAttributeListener)

getDefaultAttributeValue

Object getDefaultAttributeValue(Class<? extends 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

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

Returns:
The print service name.

getServiceUIFactory

ServiceUIFactory getServiceUIFactory()
Returns a factory for UI components if supported by the print service.

Returns:
A factory for UI components or null.

getSupportedAttributeCategories

Class<?>[] getSupportedAttributeCategories()
Returns all supported attribute categories.

Returns:
The class array of all supported attribute categories.

getSupportedAttributeValues

Object getSupportedAttributeValues(Class<? extends 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:

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

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

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

int hashCode()
Returns a hashcode for this print service.

Overrides:
hashCode in class Object
Returns:
The hashcode.
See Also:
Object.equals(Object), System.identityHashCode(Object)

isAttributeCategorySupported

boolean isAttributeCategorySupported(Class<? extends 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

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

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.

addPrintServiceAttributeListener

void addPrintServiceAttributeListener(PrintServiceAttributeListener listener)
Registers a print service attribute listener to this print service.

Parameters:
listener - the listener to add

removePrintServiceAttributeListener

void removePrintServiceAttributeListener(PrintServiceAttributeListener listener)
De-registers a print service attribute listener from this print service.

Parameters:
listener - the listener to remove