You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
489 lines
22 KiB
489 lines
22 KiB
/*
|
|
* Copyright (c) 2000, 2013, Oracle and/or its affiliates. All rights reserved.
|
|
* ORACLE PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
|
|
*
|
|
*
|
|
*
|
|
*
|
|
*
|
|
*
|
|
*
|
|
*
|
|
*
|
|
*
|
|
*
|
|
*
|
|
*
|
|
*
|
|
*
|
|
*
|
|
*
|
|
*
|
|
*
|
|
*
|
|
*/
|
|
|
|
package javax.print;
|
|
|
|
import java.util.Locale;
|
|
|
|
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;
|
|
|
|
|
|
/**
|
|
* Interface 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.
|
|
* <P>
|
|
* Example:
|
|
* <PRE>{@code
|
|
* 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) {
|
|
* }
|
|
* }
|
|
* }</PRE>
|
|
*/
|
|
public interface PrintService {
|
|
|
|
/** 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 the
|
|
* {@link javax.print.attribute.standard.PrinterName PrinterName}
|
|
* attribute.
|
|
* @return name of the service.
|
|
*/
|
|
public String getName();
|
|
|
|
/**
|
|
* Creates and returns a PrintJob capable of handling data from
|
|
* any of the supported document flavors.
|
|
* @return a DocPrintJob object
|
|
*/
|
|
public DocPrintJob createPrintJob();
|
|
|
|
/**
|
|
* Registers a listener for events on this PrintService.
|
|
* @param listener a PrintServiceAttributeListener, which
|
|
* monitors the status of a print service
|
|
* @see #removePrintServiceAttributeListener
|
|
*/
|
|
public void addPrintServiceAttributeListener(
|
|
PrintServiceAttributeListener listener);
|
|
|
|
/**
|
|
* Removes the print-service listener from this print service.
|
|
* This means the listener is no longer interested in
|
|
* <code>PrintService</code> events.
|
|
* @param listener a PrintServiceAttributeListener object
|
|
* @see #addPrintServiceAttributeListener
|
|
*/
|
|
public void removePrintServiceAttributeListener(
|
|
PrintServiceAttributeListener listener);
|
|
|
|
/**
|
|
* 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 the
|
|
* <CODE>getAttributes()</CODE> method call: that is, the returned
|
|
* attribute set's contents will <I>not</I> be updated if this print
|
|
* service's attribute set's contents change in the future. To detect
|
|
* changes in attribute values, call <CODE>getAttributes()</CODE> again
|
|
* and compare the new attribute set to the previous attribute set;
|
|
* alternatively, register a listener for print service events.
|
|
*
|
|
* @return Unmodifiable snapshot of this Print Service's attribute set.
|
|
* May be empty, but not null.
|
|
*/
|
|
public PrintServiceAttributeSet getAttributes();
|
|
|
|
/**
|
|
* 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.
|
|
* @param category the category of a PrintServiceAttribute supported
|
|
* by this service - may not be null.
|
|
* @return the value of the supported attribute or null if the
|
|
* attribute is not supported by this service.
|
|
* @exception NullPointerException if the category is null.
|
|
* @exception IllegalArgumentException
|
|
* (unchecked exception) if <CODE>category</CODE> is not a
|
|
* <code>Class</code> that implements interface
|
|
*{@link javax.print.attribute.PrintServiceAttribute PrintServiceAttribute}.
|
|
*/
|
|
public <T extends PrintServiceAttribute>
|
|
T getAttribute(Class<T> category);
|
|
|
|
/**
|
|
* Determines the print data formats a client can specify when setting
|
|
* up a job for this <code>PrintService</code>. A print data format is
|
|
* designated by a "doc
|
|
* flavor" (class {@link javax.print.DocFlavor DocFlavor})
|
|
* consisting of a MIME type plus a print data representation class.
|
|
* <P>
|
|
* Note that some doc flavors may not be supported in combination
|
|
* with all attributes. Use <code>getUnsupportedAttributes(..)</code>
|
|
* to validate specific combinations.
|
|
*
|
|
* @return Array of supported doc flavors, should have at least
|
|
* one element.
|
|
*
|
|
*/
|
|
public DocFlavor[] getSupportedDocFlavors();
|
|
|
|
/**
|
|
* Determines if this print service supports a specific
|
|
* <code>DocFlavor</code>. This is a convenience method to determine
|
|
* if the <code>DocFlavor</code> would be a member of the result of
|
|
* <code>getSupportedDocFlavors()</code>.
|
|
* <p>
|
|
* Note that some doc flavors may not be supported in combination
|
|
* with all attributes. Use <code>getUnsupportedAttributes(..)</code>
|
|
* to validate specific combinations.
|
|
*
|
|
* @param flavor the <code>DocFlavor</code>to query for support.
|
|
* @return <code>true</code> if this print service supports the
|
|
* specified <code>DocFlavor</code>; <code>false</code> otherwise.
|
|
* @exception NullPointerException
|
|
* (unchecked exception) Thrown if <CODE>flavor</CODE> is null.
|
|
*/
|
|
public boolean isDocFlavorSupported(DocFlavor flavor);
|
|
|
|
|
|
/**
|
|
* 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 a <code>Class</code> that implements interface
|
|
* {@link javax.print.attribute.Attribute Attribute}. This method returns
|
|
* just the attribute <I>categories</I> that are supported; it does not
|
|
* return the particular attribute <I>values</I> that are supported.
|
|
* <P>
|
|
* 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 <code>DocFlavor</code>).
|
|
* Use one of the methods that include a <code>DocFlavor</code> to
|
|
* validate the request before submitting it, such as
|
|
* <code>getSupportedAttributeValues(..)</code>.
|
|
*
|
|
* @return Array of printing attribute categories that the client can
|
|
* specify as a doc-level or job-level attribute in a Print
|
|
* Request. Each element in the array is a {@link java.lang.Class
|
|
* Class} that implements interface {@link
|
|
* javax.print.attribute.Attribute Attribute}.
|
|
* The array is empty if no categories are supported.
|
|
*/
|
|
public Class<?>[] getSupportedAttributeCategories();
|
|
|
|
/**
|
|
* 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 a <code>Class</code>
|
|
* that implements interface {@link javax.print.attribute.Attribute
|
|
* Attribute}. This method tells whether the attribute <I>category</I> is
|
|
* supported; it does not tell whether a particular attribute <I>value</I>
|
|
* is supported.
|
|
* <p>
|
|
* Some categories may not be supported in a particular context (ie
|
|
* for a particular <code>DocFlavor</code>).
|
|
* Use one of the methods which include a <code>DocFlavor</code> to
|
|
* validate the request before submitting it, such as
|
|
* <code>getSupportedAttributeValues(..)</code>.
|
|
* <P>
|
|
* This is a convenience method to determine if the category
|
|
* would be a member of the result of
|
|
* <code>getSupportedAttributeCategories()</code>.
|
|
*
|
|
* @param category Printing attribute category to test. It must be a
|
|
* <code>Class</code> that implements
|
|
* interface
|
|
* {@link javax.print.attribute.Attribute Attribute}.
|
|
*
|
|
* @return <code>true</code> if this print service supports
|
|
* specifying a doc-level or
|
|
* job-level attribute in <CODE>category</CODE> in a Print
|
|
* Request; <code>false</code> if it doesn't.
|
|
*
|
|
* @exception NullPointerException
|
|
* (unchecked exception) Thrown if <CODE>category</CODE> is null.
|
|
* @exception IllegalArgumentException
|
|
* (unchecked exception) Thrown if <CODE>category</CODE> is not a
|
|
* <code>Class</code> that implements interface
|
|
* {@link javax.print.attribute.Attribute Attribute}.
|
|
*/
|
|
public boolean
|
|
isAttributeCategorySupported(Class<? extends Attribute> category);
|
|
|
|
/**
|
|
* 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 interface
|
|
* {@link javax.print.attribute.Attribute Attribute}. 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.
|
|
* <p>
|
|
* Some attributes may not be supported in a particular context (ie
|
|
* for a particular <code>DocFlavor</code>).
|
|
* Use one of the methods that include a <code>DocFlavor</code> to
|
|
* validate the request before submitting it, such as
|
|
* <code>getSupportedAttributeValues(..)</code>.
|
|
* <P>
|
|
* Not all attributes have a default value. For example the
|
|
* service will not have a defaultvalue for <code>RequestingUser</code>
|
|
* i.e. a null return for a supported category means there is no
|
|
* service default value for that category. Use the
|
|
* <code>isAttributeCategorySupported(Class)</code> method to
|
|
* distinguish these cases.
|
|
*
|
|
* @param category Printing attribute category for which the default
|
|
* attribute value is requested. It must be a {@link
|
|
* java.lang.Class Class} that implements interface
|
|
* {@link javax.print.attribute.Attribute
|
|
* Attribute}.
|
|
*
|
|
* @return Default attribute value for <CODE>category</CODE>, or null
|
|
* if this Print Service does not support specifying a doc-level or
|
|
* job-level attribute in <CODE>category</CODE> in a Print
|
|
* Request, or the service does not have a default value
|
|
* for this attribute.
|
|
*
|
|
* @exception NullPointerException
|
|
* (unchecked exception) Thrown if <CODE>category</CODE> is null.
|
|
* @exception IllegalArgumentException
|
|
* (unchecked exception) Thrown if <CODE>category</CODE> is not a
|
|
* {@link java.lang.Class Class} that implements interface {@link
|
|
* javax.print.attribute.Attribute Attribute}.
|
|
*/
|
|
public Object
|
|
getDefaultAttributeValue(Class<? extends Attribute> category);
|
|
|
|
/**
|
|
* 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 interface
|
|
* {@link javax.print.attribute.Attribute Attribute}.
|
|
* <P>
|
|
* If <CODE>flavor</CODE> is null and <CODE>attributes</CODE> is null
|
|
* or is an empty set, this method returns all the printing attribute
|
|
* values this Print Service supports for any possible job. If
|
|
* <CODE>flavor</CODE> is not null or <CODE>attributes</CODE> 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, a null return value may indicate that specifying this attribute
|
|
* is incompatible with the specified DocFlavor.
|
|
* Also if DocFlavor is not null it must be a flavor supported by this
|
|
* PrintService, else IllegalArgumentException will be thrown.
|
|
* <P>
|
|
* If the <code>attributes</code> parameter contains an Attribute whose
|
|
* category is the same as the <code>category</code> parameter, the service
|
|
* must ignore this attribute in the AttributeSet.
|
|
* <p>
|
|
* <code>DocAttribute</code>s which are to be specified on the
|
|
* <code>Doc</code> must be included in this set to accurately
|
|
* represent the context.
|
|
* <p>
|
|
* 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 package {@link
|
|
* javax.print.attribute.standard javax.print.attribute.standard}
|
|
* describes how each attribute indicates its supported values. Possible
|
|
* ways of indicating support include:
|
|
* <UL>
|
|
* <LI>
|
|
* 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.)
|
|
* <LI>
|
|
* 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
|
|
* <code>getCategory(Class)</code>.
|
|
* <LI>
|
|
* 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.
|
|
* </UL>
|
|
* <P>
|
|
*
|
|
* @param category Printing attribute category to test. It must be a
|
|
* {@link java.lang.Class Class} that implements
|
|
* interface {@link
|
|
* javax.print.attribute.Attribute Attribute}.
|
|
* @param flavor Doc flavor for a supposed job, or null.
|
|
* @param attributes Set of printing attributes for a supposed job
|
|
* (both job-level attributes and document-level
|
|
* attributes), or null.
|
|
*
|
|
* @return Object indicating supported values for <CODE>category</CODE>,
|
|
* or null if this Print Service does not support specifying a
|
|
* doc-level or job-level attribute in <CODE>category</CODE> in
|
|
* a Print Request.
|
|
*
|
|
* @exception NullPointerException
|
|
* (unchecked exception) Thrown if <CODE>category</CODE> is null.
|
|
* @exception IllegalArgumentException
|
|
* (unchecked exception) Thrown if <CODE>category</CODE> is not a
|
|
* {@link java.lang.Class Class} that implements interface {@link
|
|
* javax.print.attribute.Attribute Attribute}, or
|
|
* <code>DocFlavor</code> is not supported by this service.
|
|
*/
|
|
public Object
|
|
getSupportedAttributeValues(Class<? extends Attribute> category,
|
|
DocFlavor flavor,
|
|
AttributeSet attributes);
|
|
|
|
/**
|
|
* 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 interface
|
|
* {@link javax.print.attribute.Attribute Attribute}.
|
|
* <P>
|
|
* If <CODE>flavor</CODE> is null and <CODE>attributes</CODE> is null 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. If <CODE>flavor</CODE> is not null or
|
|
* <CODE>attributes</CODE> 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.
|
|
* <p>
|
|
* Also if DocFlavor is not null it must be a flavor supported by this
|
|
* PrintService, else IllegalArgumentException will be thrown.
|
|
* <p>
|
|
* <code>DocAttribute</code>s which are to be specified on the
|
|
* <code>Doc</code> must be included in this set to accurately
|
|
* represent the context.
|
|
* <p>
|
|
* This is a convenience method to determine if the value
|
|
* would be a member of the result of
|
|
* <code>getSupportedAttributeValues(...)</code>.
|
|
*
|
|
* @param attrval Printing attribute value to test.
|
|
* @param flavor Doc flavor for a supposed job, or null.
|
|
* @param attributes Set of printing attributes for a supposed job
|
|
* (both job-level attributes and document-level
|
|
* attributes), or null.
|
|
*
|
|
* @return True if this Print Service supports specifying
|
|
* <CODE>attrval</CODE> as a doc-level or job-level attribute in a
|
|
* Print Request, false if it doesn't.
|
|
*
|
|
* @exception NullPointerException
|
|
* (unchecked exception) if <CODE>attrval</CODE> is null.
|
|
* @exception IllegalArgumentException if flavor is not supported by
|
|
* this PrintService.
|
|
*/
|
|
public boolean isAttributeValueSupported(Attribute attrval,
|
|
DocFlavor flavor,
|
|
AttributeSet attributes);
|
|
|
|
|
|
/**
|
|
* Identifies the attributes that are unsupported for a print request
|
|
* in the context of a particular DocFlavor.
|
|
* 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 supported DocFlavor or an
|
|
* IllegalArgumentException will be thrown. If the
|
|
* return value from this method is null, all attributes are supported.
|
|
* <p>
|
|
* <code>DocAttribute</code>s which are to be specified on the
|
|
* <code>Doc</code> must be included in this set to accurately
|
|
* represent the context.
|
|
* <p>
|
|
* If the return value is non-null, all attributes in the returned
|
|
* set are unsupported with this DocFlavor. The returned set does not
|
|
* distinguish attribute categories that are unsupported from
|
|
* unsupported attribute values.
|
|
* <p>
|
|
* 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.
|
|
* <p>
|
|
* 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.
|
|
* <p>
|
|
* Use <code>isDocFlavorSupported()</code> to verify that a DocFlavor
|
|
* is supported before calling this method.
|
|
*
|
|
* @param flavor Doc flavor to test, or null
|
|
* @param attributes Set of printing attributes for a supposed job
|
|
* (both job-level attributes and document-level
|
|
* attributes), or null.
|
|
*
|
|
* @return null if this Print Service supports the print request
|
|
* specification, else the unsupported attributes.
|
|
*
|
|
* @exception IllegalArgumentException if<CODE>flavor</CODE> is
|
|
* not supported by this PrintService.
|
|
*/
|
|
public AttributeSet getUnsupportedAttributes(DocFlavor flavor,
|
|
AttributeSet attributes);
|
|
|
|
/**
|
|
* 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 return null.
|
|
* 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.
|
|
* See <code>ServiceUIFactory</code> for more information.
|
|
* @return null or a factory for UI components.
|
|
*/
|
|
public ServiceUIFactory getServiceUIFactory();
|
|
|
|
/**
|
|
* 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.
|
|
* <p>
|
|
* Clients should call this method to determine if two services are
|
|
* referring to the same underlying service.
|
|
* <p>
|
|
* 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.
|
|
* @param obj the reference object with which to compare.
|
|
* @return true if this service is the same as the obj argument,
|
|
* false otherwise.
|
|
*/
|
|
public boolean equals(Object obj);
|
|
|
|
/**
|
|
* This method should be implemented consistently with
|
|
* <code>equals(Object)</code>.
|
|
* @return hash code of this object.
|
|
*/
|
|
public int hashCode();
|
|
|
|
}
|