Summary

Add the final modifier to JavaFX properties and their corresponding setter and getter methods in the printing API and move documentation to the properties.

Problem

In the JavaFX API it is conventional to make properties and setter and getter methods final. This wasn't done in the printing API because the classes which contain them are final, but it would still be good to be consistent.

Solution

• Make all setters and getters and properties final as needed
• As needed, move documentation to the property so the setters and getters inherit it, with an exception for the special case of JobSettings.setPageRanges()

Specification

Updates in the javafx.print package are as follows :

public final class JobSettings

-    /**
-     * Get the name of a job.
-     * @return a string representing the name of a job
-     */
-    public String getJobName() {
+    public final String getJobName() {

-
-    /**
-     * Set the name of a job.
-     * @param name string representing the name of a job
-     */
-    public void setJobName(String name) {
+    public final void setJobName(String name) {


-    public String getOutputFile() {
+    public final String getOutputFile() {
         return outputFileProperty().get();
     }

-
-    public void setOutputFile(String filePath) {
+    public final void setOutputFile(String filePath) {


-    /**
-     * Get the number of copies to print.
-     * @return number of copies to print
-     */
-    public int getCopies() {
+    public final int getCopies() {


-    /**
-     * Set the number of copies to print.
-     * @param nCopies number of copies to print
-     */
     public final void setCopies(int nCopies) {


-    /**
-     * The range of pages to print. null always means all pages.
-     * See {@link pageRangesProperty} for more details.
-     * @return null or an array as specified above
-     */
-    public PageRange[] getPageRanges() {

+    public final PageRange[] getPageRanges() {


-    public void setPageRanges(PageRange... pages) {
+    public final void setPageRanges(PageRange... pages) {


-    /**
-     * If a printer supports it, then a job may be printed on
-     * both sides of the media (paper), ie duplex printing.
-     * This method returns the selected setting.
-     * @return the duplex (side) setting.
-     */
-    public PrintSides getPrintSides() {
+    public final PrintSides getPrintSides() {


-    /**
-     * Set the PrintSides property which controls
-     * duplex printing.
-     * A null value is ignored.
-     * @param sides new setting for number of sides.
-     */
-    public void setPrintSides(PrintSides sides) {
+    public final void setPrintSides(PrintSides sides) {

     /**
      * Property representing an instance of Collation.
+     * Collation determines how sheets are sorted when
+     * multiple copies of a document are printed.
+     * As such it is only relevant if 2 or more copies of
+     * a document with 2 more sheets are printed.
+     * A sheet is the physical media, so documents with 2 pages
+     * that are printed N-up, or double-sided may still have only
+     * one sheet.
+     * A collated print job produces documents with sheets
+     * of a document sorted in sequence.
+     * An uncollated job collects together the multiple copies
+     * of the same sheet.
+     * Uncollated (false) is the typical default value.
+     *
      * @return an instance of Collation
      */
     public final ObjectProperty collationProperty() {


-    /**
-     * Collation determines how sheets are sorted when
-     * multiple copies of a document are printed.
-     * As such it is only relevant if 2 or more copies of
-     * a document with 2 more sheets are printed.
-     * A sheet is the physical media, so documents with 2 pages
-     * that are printed N-up, or double-sided may still have only
-     * one sheet.
-     * A collated print job produces documents with sheets
-     * of a document sorted in sequence.
-     * An uncollated job collects together the multiple copies
-     * of the same sheet.
-     * Uncollated (false) is the typical default value.
-     *
-     * @return the collation
-     */
-    public Collation getCollation() {
+    public final Collation getCollation() {

-    /**
-     * Set the Collation property.
-     * A null value is ignored.
-     * @param collation new setting for collation
-     */
-    public void setCollation(Collation collation) {
+    public final void setCollation(Collation collation) {

     /**
      * Property representing an instance of PrintColor.
+     * If a null value is set it is ignored.
      * @return an instance of PrintColor
      */
     public final ObjectProperty printColorProperty() {


-    public PrintColor getPrintColor() {
+    public final PrintColor getPrintColor() {


-    /**
-     * Set the PrintColor property.
-     * A null value is ignored.
-     *
-     * @param color new setting for print color.
-     */
-    public void setPrintColor(PrintColor color) {
+    public final void setPrintColor(PrintColor color) {

     /**
      * Property representing an instance of PrintQuality.
+     * 

+     * Note that quality and resolution are overlapping concepts.
+     * Therefore a printer may support setting one, or the other but
+     * not both. Applications setting these programmatically should
+     * query both properties and select appropriately from the supported
+     * values. If a printer supports non-standard values, code likely
+     * cannot distinguish the printer's interpretation of these values
+     * and it is safest to stick to selecting a standard value that
+     * matches the requirement.
      * @return an instance of PrintQuality
      */
     public final ObjectProperty printQualityProperty() {


-    public PrintQuality getPrintQuality() {
+    public final PrintQuality getPrintQuality() {


-    /**
-     * Set the PrintQuality property.
-     * A null value is ignored.
-     * 

-     * Note that quality and resolution overlapping concepts.
-     * Therefore a printer may support setting one, or the other but
-     * not both. Applications setting these programmatically should
-     * query both properties and select appropriately from the supported
-     * values. If a printer supports non-standard values, code likely
-     * cannot distinguish the printer's interpretation of these values
-     * and is safest to stick to selecting from the standard value that
-     * matches the requirement.
-     * @param quality new setting for print quality.
-     */
-    public void setPrintQuality(PrintQuality quality) {
+    public final void setPrintQuality(PrintQuality quality) {

     /**
      * Property representing an instance of PrintResolution.
+     * A null value is ignored.
+     * 

+     * Note that quality and resolution are overlapping concepts.
+     * Therefore a printer may support setting one, or the other but
+     * not both. Applications setting these programmatically should
+     * query both properties and select appropriately from the supported
+     * values. If a printer supports non-standard values, code likely
+     * cannot distinguish the printer's interpretation of these values
+     * and it is safest to stick to selecting a standard value that
+     * matches the requirement.
      * @return an instance of PrintResolution
      */
     public final ObjectProperty printResolutionProperty() {

-    /**
-     *
-     * @return the print resolution
-     */
-    public PrintResolution getPrintResolution() {
+    public final PrintResolution getPrintResolution() {

-    /**
-     * Set the PrintResolution property.
-     * A null value is ignored.
-     * 

-     * Note that quality and resolution overlapping concepts.
-     * Therefore a printer may support setting one, or the other but
-     * not both. Applications setting these programmatically should
-     * query both properties and select appropriately from the supported
-     * values. If a printer supports non-standard values, code likely
-     * cannot distinguish the printer's interpretation of these values
-     * and is safest to stick to selecting from the standard value that
-     * matches the requirement.
-     * @param resolution new setting for print resolution.
-     */
-    public void setPrintResolution(PrintResolution resolution) {
+    public final void setPrintResolution(PrintResolution resolution) {

    /**
      * Property representing an instance of PaperSource.
+     * A null value is ignored.
      * @return an instance of PaperSource
      */
     public final ObjectProperty paperSourceProperty() {


-    public PaperSource getPaperSource() {
+    public final PaperSource getPaperSource() {

-    public void setPaperSource(PaperSource value) {
+    public final void setPaperSource(PaperSource value) {


     /**
      * Property representing an instance of PageLayout.
+     * Setting a null value is ignored.
      * @return an instance of PageLayout
      */
     public final ObjectProperty pageLayoutProperty() {
@
-    /**
-     * Get the current page layout for this job.
-     * @return page layout to use for the job.
-     */
-    public PageLayout getPageLayout() {
+    public final PageLayout getPageLayout() {

-    /**
-     * Set the PageLayout to use.
-     * @param pageLayout The page layout to use.
-     */
-    public void setPageLayout(PageLayout pageLayout) {
+    public final void setPageLayout(PageLayout pageLayout) {

public final class PageRange

     /**
      * IntegerProperty representing the starting
-     * page number of the range. See {@link getStartPage getStartPage()}
-     * for more information.
+     * page number of the range.
      * @return the starting page number of the range
      */
-    public ReadOnlyIntegerProperty startPageProperty() {
+    public final ReadOnlyIntegerProperty startPageProperty() {

-    /**
-     * @return the starting page of the range.
-     */
-    public int getStartPage() {
+    public final int getStartPage() {

     /**
      * IntegerProperty representing the ending
-     * page number of the range. See {@link #getEndPage getEndPage()}
-     * for more information.
+     * page number of the range.
      * @return the ending page number of the range
      */
-    public ReadOnlyIntegerProperty endPageProperty() {
+    public final ReadOnlyIntegerProperty endPageProperty() {

-    /**
-     * @return the ending page of the range.
-     */
-    public int getEndPage() {
+    public final int getEndPage() {

public final class PrinterJob

     /**
+     * Property representing the {@code Printer} for this job.
+     * When setting a printer which does not support the current job settings,
      * (for example if DUPLEX printing is requested but the new printer
      * does not support this), then the values are reset to the default
      * for the new printer, or in some cases a similar value. For example
@@ -243,9 +223,20 @@ public synchronized Printer getPrinter() {
      * 

      * Setting a null value for printer will install the default printer.
      * Setting the current printer has no effect.
+     * @return the Printer for this job 
-     */
-    public final ObjectProperty printerProperty() {
+    public final ObjectProperty printerProperty() {

-
-    /**
-     * Gets the printer currently associated with this job.
-     * @return printer for the job.
-     */
-    public synchronized Printer getPrinter() {
+    public synchronized final Printer getPrinter() {


-    public synchronized void setPrinter(Printer printer) {
+    public synchronized final void setPrinter(Printer printer) {



-    public ReadOnlyObjectProperty jobStatusProperty() {
+    public final ReadOnlyObjectProperty jobStatusProperty() {

-    /**
-     * Obtain the current status of the job.
-     * @return the current JobStatus
-     */
-    public JobStatus getJobStatus() {
+    public final JobStatus getJobStatus() {