- All Known Subinterfaces:
MultiDocPrintService
- All Known Implementing Classes:
StreamPrintService
PrintService
is the factory for a DocPrintJob
. A
PrintService
describes the capabilities of a printer and can be
queried regarding a printer's supported attributes.
Example:
DocFlavor flavor = DocFlavor.INPUT_STREAM.POSTSCRIPT;
PrintRequestAttributeSet aset = new HashPrintRequestAttributeSet();
aset.add(MediaSizeName.ISO_A4);
PrintService[] pservices =
PrintServiceLookup.lookupPrintServices(flavor, aset);
if (pservices.length > 0) {
DocPrintJob pj = pservices[0].createPrintJob();
try {
FileInputStream fis = new FileInputStream("test.ps");
Doc doc = new SimpleDoc(fis, flavor, null);
pj.print(doc, aset);
} catch (FileNotFoundException fe) {
} catch (PrintException e) {
}
}
-
Method Summary
Modifier and TypeMethodDescriptionvoid
Registers a listener for events on thisPrintService
.Creates and returns aPrintJob
capable of handling data from any of the supported document flavors.boolean
Determines if two services are referring to the same underlying service.<T extends PrintServiceAttribute>
TgetAttribute
(Class<T> category) Gets the value of the single specified service attribute.Obtains this print service's set of printer description attributes giving this Print Service's status.getDefaultAttributeValue
(Class<? extends Attribute> category) Determines this print service's default printing attribute value in the given category.getName()
Returns a string name for this print service which may be used by applications to request a particular print service.Returns a factory for UI components which allow users to interact with the service in various roles.Class<?>[]
Determines the printing attribute categories a client can specify when setting up a job for this print service.getSupportedAttributeValues
(Class<? extends Attribute> category, DocFlavor flavor, AttributeSet attributes) Determines the printing attribute values a client can specify in the given category when setting up a job for this print service.Determines the print data formats a client can specify when setting up a job for thisPrintService
.getUnsupportedAttributes
(DocFlavor flavor, AttributeSet attributes) Identifies the attributes that are unsupported for a print request in the context of a particularDocFlavor
.int
hashCode()
This method should be implemented consistently withequals(Object)
.boolean
isAttributeCategorySupported
(Class<? extends Attribute> category) Determines whether a client can specify the given printing attribute category when setting up a job for this print service.boolean
isAttributeValueSupported
(Attribute attrval, DocFlavor flavor, AttributeSet attributes) Determines whether a client can specify the given printing attribute value when setting up a job for this Print Service.boolean
isDocFlavorSupported
(DocFlavor flavor) Determines if this print service supports a specificDocFlavor
.void
Removes the print-service listener from this print service.
-
Method Details
-
getName
String getName()Returns a string name for this print service which may be used by applications to request a particular print service. In a suitable context, such as a name service, this name must be unique. In some environments this unique name may be the same as the user friendly printer name defined as thePrinterName
attribute.- Returns:
- name of the service
-
createPrintJob
DocPrintJob createPrintJob()Creates and returns aPrintJob
capable of handling data from any of the supported document flavors.- Returns:
- a
DocPrintJob
object
-
addPrintServiceAttributeListener
Registers a listener for events on thisPrintService
.- Parameters:
listener
- a PrintServiceAttributeListener, which monitors the status of a print service- See Also:
-
removePrintServiceAttributeListener
Removes the print-service listener from this print service. This means the listener is no longer interested inPrintService
events.- Parameters:
listener
- aPrintServiceAttributeListener
object- See Also:
-
getAttributes
PrintServiceAttributeSet getAttributes()Obtains this print service's set of printer description attributes giving this Print Service's status. The returned attribute set object is unmodifiable. The returned attribute set object is a "snapshot" of this Print Service's attribute set at the time of thegetAttributes()
method call: that is, the returned attribute set's contents will not be updated if this print service's attribute set's contents change in the future. To detect changes in attribute values, callgetAttributes()
again and compare the new attribute set to the previous attribute set; alternatively, register a listener for print service events.- Returns:
- unmodifiable snapshot of this Print Service's attribute set. May
be empty, but not
null
.
-
getAttribute
Gets the value of the single specified service attribute. This may be useful to clients which only need the value of one attribute and want to minimize overhead.- Type Parameters:
T
- the type of the specified service attribute- Parameters:
category
- the category of aPrintServiceAttribute
supported by this service - may not benull
- Returns:
- the value of the supported attribute or
null
if the attribute is not supported by this service - Throws:
NullPointerException
- if the category isnull
IllegalArgumentException
- ifcategory
is not aClass
that implements interfacePrintServiceAttribute
-
getSupportedDocFlavors
DocFlavor[] getSupportedDocFlavors()Determines the print data formats a client can specify when setting up a job for thisPrintService
. A print data format is designated by a "doc flavor" (classDocFlavor
) consisting of a MIME type plus a print data representation class.Note that some doc flavors may not be supported in combination with all attributes. Use
getUnsupportedAttributes(..)
to validate specific combinations.- Returns:
- array of supported doc flavors, should have at least one element
-
isDocFlavorSupported
Determines if this print service supports a specificDocFlavor
. This is a convenience method to determine if theDocFlavor
would be a member of the result ofgetSupportedDocFlavors()
.Note that some doc flavors may not be supported in combination with all attributes. Use
getUnsupportedAttributes(..)
to validate specific combinations.- Parameters:
flavor
- theDocFlavor
to query for support- Returns:
true
if this print service supports the specifiedDocFlavor
;false
otherwise- Throws:
NullPointerException
- ifflavor
isnull
-
getSupportedAttributeCategories
Class<?>[] getSupportedAttributeCategories()Determines the printing attribute categories a client can specify when setting up a job for this print service. A printing attribute category is designated by aClass
that implements interfaceAttribute
. This method returns just the attribute categories that are supported; it does not return the particular attribute values that are supported.This method returns all the printing attribute categories this print service supports for any possible job. Some categories may not be supported in a particular context (ie for a particular
DocFlavor
). Use one of the methods that include aDocFlavor
to validate the request before submitting it, such asgetSupportedAttributeValues(..)
. -
isAttributeCategorySupported
Determines whether a client can specify the given printing attribute category when setting up a job for this print service. A printing attribute category is designated by aClass
that implements interfaceAttribute
. This method tells whether the attribute category is supported; it does not tell whether a particular attribute value is supported.Some categories may not be supported in a particular context (ie for a particular
DocFlavor
). Use one of the methods which include aDocFlavor
to validate the request before submitting it, such asgetSupportedAttributeValues(..)
.This is a convenience method to determine if the category would be a member of the result of
getSupportedAttributeCategories()
.- Parameters:
category
- printing attribute category to test. It must be aClass
that implements interfaceAttribute
.- Returns:
true
if this print service supports specifying a doc-level or job-level attribute incategory
in a Print Request;false
if it doesn't- Throws:
NullPointerException
- ifcategory
isnull
IllegalArgumentException
- ifcategory
is not aClass
that implements interfaceAttribute
-
getDefaultAttributeValue
Determines this print service's default printing attribute value in the given category. A printing attribute value is an instance of a class that implements interfaceAttribute
. If a client sets up a print job and does not specify any attribute value in the given category, this Print Service will use the default attribute value instead.Some attributes may not be supported in a particular context (ie for a particular
DocFlavor
). Use one of the methods that include aDocFlavor
to validate the request before submitting it, such asgetSupportedAttributeValues(..)
.Not all attributes have a default value. For example the service will not have a default value for
RequestingUser
i.e. anull
return for a supported category means there is no service default value for that category. Use theisAttributeCategorySupported(Class)
method to distinguish these cases.- Parameters:
category
- printing attribute category for which the default attribute value is requested. It must be aClass
that implements interfaceAttribute
.- Returns:
- default attribute value for
category
, ornull
if this Print Service does not support specifying a doc-level or job-level attribute incategory
in a Print Request, or the service does not have a default value for this attribute - Throws:
NullPointerException
- ifcategory
isnull
IllegalArgumentException
- ifcategory
is not aClass
that implements interfaceAttribute
-
getSupportedAttributeValues
Object getSupportedAttributeValues(Class<? extends Attribute> category, DocFlavor flavor, AttributeSet attributes) Determines the printing attribute values a client can specify in the given category when setting up a job for this print service. A printing attribute value is an instance of a class that implements interfaceAttribute
.If
flavor
isnull
andattributes
isnull
or is an empty set, this method returns all the printing attribute values this Print Service supports for any possible job. Ifflavor
is notnull
orattributes
is not an empty set, this method returns just the printing attribute values that are compatible with the given doc flavor and/or set of attributes. That is, anull
return value may indicate that specifying this attribute is incompatible with the specified DocFlavor. Also ifDocFlavor
is notnull
it must be a flavor supported by thisPrintService
, elseIllegalArgumentException
will be thrown.If the
attributes
parameter contains anAttribute
whose category is the same as thecategory
parameter, the service must ignore this attribute in theAttributeSet
.DocAttribute
s which are to be specified on theDoc
must be included in this set to accurately represent the context.This method returns an
Object
because different printing attribute categories indicate the supported attribute values in different ways. The documentation for each printing attribute in packagejavax.print.attribute.standard
describes how each attribute indicates its supported values. Possible ways of indicating support include:- Return a single instance of the attribute category to indicate that any value is legal -- used, for example, by an attribute whose value is an arbitrary text string. (The value of the returned attribute object is irrelevant.)
- Return an array of one or more instances of the attribute category,
containing the legal values -- used, for example, by an attribute with
a list of enumerated values. The type of the array is an array of the
specified attribute category type as returned by its
getCategory(Class)
. - Return a single object (of some class other than the attribute category) that indicates bounds on the legal values -- used, for example, by an integer-valued attribute that must lie within a certain range.
- Parameters:
category
- printing attribute category to test. It must be aClass
that implements interfaceAttribute
.flavor
- doc flavor for a supposed job, ornull
attributes
- set of printing attributes for a supposed job (both job-level attributes and document-level attributes), ornull
- Returns:
- object indicating supported values for
category
, ornull
if this Print Service does not support specifying a doc-level or job-level attribute incategory
in a Print Request - Throws:
NullPointerException
- ifcategory
isnull
IllegalArgumentException
- ifcategory
is not aClass
that implements interfaceAttribute
, orDocFlavor
is not supported by this service
-
isAttributeValueSupported
Determines whether a client can specify the given printing attribute value when setting up a job for this Print Service. A printing attribute value is an instance of a class that implements interfaceAttribute
.If
flavor
isnull
andattributes
isnull
or is an empty set, this method tells whether this Print Service supports the given printing attribute value for some possible combination of doc flavor and set of attributes. Ifflavor
is notnull
orattributes
is not an empty set, this method tells whether this Print Service supports the given printing attribute value in combination with the given doc flavor and/or set of attributes.Also if
DocFlavor
is notnull
it must be a flavor supported by thisPrintService
, elseIllegalArgumentException
will be thrown.DocAttribute
s which are to be specified on theDoc
must be included in this set to accurately represent the context.This is a convenience method to determine if the value would be a member of the result of
getSupportedAttributeValues(...)
.- Parameters:
attrval
- printing attribute value to testflavor
- doc flavor for a supposed job, ornull
attributes
- set of printing attributes for a supposed job (both job-level attributes and document-level attributes), ornull
- Returns:
true
if this Print Service supports specifyingattrval
as a doc-level or job-level attribute in a Print Request,false
if it doesn't- Throws:
NullPointerException
- ifattrval
isnull
IllegalArgumentException
- if flavor is not supported by thisPrintService
-
getUnsupportedAttributes
Identifies the attributes that are unsupported for a print request in the context of a particularDocFlavor
. This method is useful for validating a potential print job and identifying the specific attributes which cannot be supported. It is important to supply only a supportedDocFlavor
or anIllegalArgumentException
will be thrown. If the return value from this method isnull
, all attributes are supported.DocAttribute
s which are to be specified on theDoc
must be included in this set to accurately represent the context.If the return value is
non-null
, all attributes in the returned set are unsupported with thisDocFlavor
. The returned set does not distinguish attribute categories that are unsupported from unsupported attribute values.A supported print request can then be created by removing all unsupported attributes from the original attribute set, except in the case that the
DocFlavor
is unsupported.If any attributes are unsupported only because they are in conflict with other attributes then it is at the discretion of the service to select the attribute(s) to be identified as the cause of the conflict.
Use
isDocFlavorSupported()
to verify that aDocFlavor
is supported before calling this method.- Parameters:
flavor
- doc flavor to test, ornull
attributes
- set of printing attributes for a supposed job (both job-level attributes and document-level attributes), ornull
- Returns:
null
if this Print Service supports the print request specification, else the unsupported attributes- Throws:
IllegalArgumentException
- ifflavor
is not supported by thisPrintService
-
getServiceUIFactory
ServiceUIFactory getServiceUIFactory()Returns a factory for UI components which allow users to interact with the service in various roles. Services which do not provide any UI should returnnull
. Print Services which do provide UI but want to be supported in an environment with no UI support should ensure that the factory is not initialised unless the application calls this method to obtain the factory. SeeServiceUIFactory
for more information.- Returns:
null
or a factory for UI components
-
equals
Determines if two services are referring to the same underlying service. Objects encapsulating a print service may not exhibit equality of reference even though they refer to the same underlying service.Clients should call this method to determine if two services are referring to the same underlying service.
Services must implement this method and return
true
only if the service objects being compared may be used interchangeably by the client. Services are free to return the same object reference to an underlying service if that, but clients must not depend on equality of reference. -
hashCode
int hashCode()This method should be implemented consistently withequals(Object)
.
-