javax.print

Interface PrintService

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:

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

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.

Parameters: obj the service to check against

Returns: true if both services refer to the same underlying service, false otherwise.

getAttribute

public <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

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(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 {@link #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(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:

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 {@link #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 {@link #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.

Returns: The hashcode.

isAttributeCategorySupported

public 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

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