< prev index next >
src/java.desktop/share/classes/javax/print/PrintService.java
Print this page
*** 89,99 ****
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);
--- 89,99 ----
PrintServiceAttributeListener listener);
/**
* Removes the print-service listener from this print service.
* This means the listener is no longer interested in
! * {@code PrintService} events.
* @param listener a PrintServiceAttributeListener object
* @see #addPrintServiceAttributeListener
*/
public void removePrintServiceAttributeListener(
PrintServiceAttributeListener listener);
*** 101,114 ****
/**
* 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.
--- 101,114 ----
/**
* 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()} 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()} 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.
*** 124,192 ****
* 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
--- 124,192 ----
* 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} is not a
! * {@code Class} 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}. 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(..)}
* 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}. This is a convenience method to determine
! * if the {@code DocFlavor} would be a member of the result of
! * {@code getSupportedDocFlavors()}.
* <p>
* Note that some doc flavors may not be supported in combination
! * with all attributes. Use {@code getUnsupportedAttributes(..)}
* to validate specific combinations.
*
! * @param flavor the {@code DocFlavor} to query for support.
! * @return {@code true} if this print service supports the
! * specified {@code DocFlavor}; {@code false} otherwise.
* @exception NullPointerException
! * (unchecked exception) Thrown if {@code flavor} 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} 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}).
! * Use one of the methods that include a {@code DocFlavor} to
* validate the request before submitting it, such as
! * {@code getSupportedAttributeValues(..)}.
*
* @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
*** 196,236 ****
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);
--- 196,236 ----
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}
* 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}).
! * Use one of the methods which include a {@code DocFlavor} to
* validate the request before submitting it, such as
! * {@code getSupportedAttributeValues(..)}.
* <P>
* This is a convenience method to determine if the category
* would be a member of the result of
! * {@code getSupportedAttributeCategories()}.
*
* @param category Printing attribute category to test. It must be a
! * {@code Class} that implements
* interface
* {@link javax.print.attribute.Attribute Attribute}.
*
! * @return {@code true} if this print service supports
* specifying a doc-level or
! * job-level attribute in {@code category} in a Print
! * Request; {@code false} if it doesn't.
*
* @exception NullPointerException
! * (unchecked exception) Thrown if {@code category} is null.
* @exception IllegalArgumentException
! * (unchecked exception) Thrown if {@code category} is not a
! * {@code Class} that implements interface
* {@link javax.print.attribute.Attribute Attribute}.
*/
public boolean
isAttributeCategorySupported(Class<? extends Attribute> category);
*** 242,279 ****
* 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);
--- 242,279 ----
* 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}).
! * Use one of the methods that include a {@code DocFlavor} to
* validate the request before submitting it, such as
! * {@code getSupportedAttributeValues(..)}.
* <P>
* Not all attributes have a default value. For example the
! * service will not have a defaultvalue for {@code RequestingUser}
* i.e. a null return for a supported category means there is no
* service default value for that category. Use the
! * {@code isAttributeCategorySupported(Class)} 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}, or null
* if this Print Service does not support specifying a doc-level or
! * job-level attribute in {@code category} in a Print
* Request, or the service does not have a default value
* for this attribute.
*
* @exception NullPointerException
! * (unchecked exception) Thrown if {@code category} is null.
* @exception IllegalArgumentException
! * (unchecked exception) Thrown if {@code category} is not a
* {@link java.lang.Class Class} that implements interface {@link
* javax.print.attribute.Attribute Attribute}.
*/
public Object
getDefaultAttributeValue(Class<? extends Attribute> category);
*** 283,309 ****
* 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
--- 283,309 ----
* 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} is null and {@code attributes} 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} is not null or {@code attributes} 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} parameter contains an Attribute whose
! * category is the same as the {@code category} parameter, the service
* must ignore this attribute in the AttributeSet.
* <p>
! * {@code DocAttribute}s which are to be specified on the
! * {@code Doc} 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
*** 319,329 ****
* <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>
--- 319,329 ----
* <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)}.
* <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>
*** 335,356 ****
* @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);
--- 335,356 ----
* @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},
* or null if this Print Service does not support specifying a
! * doc-level or job-level attribute in {@code category} in
* a Print Request.
*
* @exception NullPointerException
! * (unchecked exception) Thrown if {@code category} is null.
* @exception IllegalArgumentException
! * (unchecked exception) Thrown if {@code category} is not a
* {@link java.lang.Class Class} that implements interface {@link
* javax.print.attribute.Attribute Attribute}, or
! * {@code DocFlavor} is not supported by this service.
*/
public Object
getSupportedAttributeValues(Class<? extends Attribute> category,
DocFlavor flavor,
AttributeSet attributes);
*** 360,400 ****
* 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,
--- 360,400 ----
* 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} is null and {@code attributes} 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} is not null or
! * {@code attributes} 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}s which are to be specified on the
! * {@code Doc} 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(...)}.
*
* @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} as a doc-level or job-level attribute in a
* Print Request, false if it doesn't.
*
* @exception NullPointerException
! * (unchecked exception) if {@code attrval} is null.
* @exception IllegalArgumentException if flavor is not supported by
* this PrintService.
*/
public boolean isAttributeValueSupported(Attribute attrval,
DocFlavor flavor,
*** 408,419 ****
* 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
--- 408,419 ----
* 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}s which are to be specified on the
! * {@code Doc} 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
*** 426,447 ****
* 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);
--- 426,447 ----
* 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()} 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} is
* not supported by this PrintService.
*/
public AttributeSet getUnsupportedAttributes(DocFlavor flavor,
AttributeSet attributes);
*** 451,461 ****
* 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();
/**
--- 451,461 ----
* 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} for more information.
* @return null or a factory for UI components.
*/
public ServiceUIFactory getServiceUIFactory();
/**
*** 478,488 ****
*/
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();
}
--- 478,488 ----
*/
public boolean equals(Object obj);
/**
* This method should be implemented consistently with
! * {@code equals(Object)}.
* @return hash code of this object.
*/
public int hashCode();
}
< prev index next >